.NET/Link API Version 1.5 USE FRAMES

StdLink.RequestTransaction Method 

Must always be called before calling into Mathematica from a .NET user-interface action.

[Visual Basic]
Public Shared Sub RequestTransaction()
[C#]
public static void RequestTransaction();

Remarks

You should always call RequestTransaction whenever you are preparing to call into Mathematica from a .NET user-interface action, like clicking a button. This only applies for code executing in a .NET runtime launched from Mathematica by InstallNET[], not if you are launching and controlling the kernel from a standalone .NET program.

The only time you do not need to call RequestTransaction before calling into Mathematica is when the call is being made during the handling of a call from Mathematica into .NET. In other words, when Mathematica is currently in the middle of a call into .NET, it is always safe for calls to be made from .NET back into Mathematica (and RequestTransaction does nothing in this circumstance). You need RequestTransaction to guard calls that originate in .NET. User interface actions are typical examples of such calls, as Mathematica might not currently be ready to accept incoming requests from .NET.

It is safe to call RequestTransaction whenever you call back into Mathematica--if it is not necessary then RequestTransaction will simply return immediately. In other words, if you do not understand the exact circumstances in which it is necessary, you can err on the side of caution and call it more often than needed.

What RequestTransaction does is check whether it is safe to call into Mathematica. If it is safe, it returns immediately. If it is not safe, a MathematicaNotReadyException is thrown. You can typically ignore this exception and let it propagate up into the .NET event-dispatching mechanism, where it will be caught by the internals of .NET/Link and cause a MessageBox to be displayed.

It is safe to call into Mathematica in several circumstances. The first is if the Mathematica functions DoNETModal or DoNETModeless are currently running. This is the normal situation when user interface actions that call Mathematica are being executed. It is also safe to call into Mathematica when Mathematica is in the middle of calling .NET. Finally, it is safe to call into Mathematica if you have launched the kernel from your own program instead of running in the .NET runtime launched from Mathematica by InstallNET[].

Many programmers will never use this method, because they will use the Mathematica function AddEventHandler to establish callbacks from .NET into Mathematica. Event handlers created by AddEventHandler handle all details of the communication with Mathematica for you (and of course they call RequestTransaction internally).

Here is an example of .NET code that is intended to be executed as a result of a user interface action.
IKernelLink ml = StdLink.Link;
if (ml != null) {
    StdLink.RequestTransaction();
    // Always lock the link before using it.
    lock (ml) {
        ml.Print("You clicked a button");
    }    
}

Note again that this is not the "normal" way you would wire up a Print action to a button click. Instead, you would just write something like this in Mathematica:

(* Mathematica code *)
AddEventHandler[myButton@Click, Print["You clicked a button"]&];
This discussion about RequestTransaction only applies to programmers who are writing their own custom .NET code.

Exceptions

Exception Type Condition
MathematicaNotReadyException If the kernel is not in a state where it is receptive to calls originating in .NET, as described above.

See Also

StdLink Class | Wolfram.NETLink Namespace