docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the Object Gateway for .NET  /  Running an Object Gateway Server


Using the Object Gateway for .NET
Running an Object Gateway Server
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Each Object Gateway server session consists of the following components:
See Object Gateway Architecture for a detailed description and several diagrams showing how these components interact.
Starting the Server
These %Net.Remote.Service methods are available to start the server:
Starting a Server from the Command Prompt
During development or debugging, or when InterSystems IRIS and the Object Gateway server run on different machines, you may find it useful to start the Object Gateway server from a command prompt.
Note:
The Object Gateway server executable will normally be located in a default directory (see Object Gateway Server Versions). If you are using classes in local side-by-side assemblies (assemblies not installed into the GAC), copy the executable to the same directory as those assemblies and run it from there to resolve their dependencies.
Run the program as follows:
DotNetGatewaySS port host logfile
For example:
DotNetGatewaySS 55000 "" ./gatewaySS.log
Argument Description
port Port number on which to listen for the incoming requests.
host Optional — Contains the IP address or hostname where the Object Gateway server listens. Specify "", 0.0.0.0, or default to listen on all IP adapters on the machine (127.0.0.1, VPNs, etc.) rather than just one adapter.
logfile Optional — If specified, the command procedure creates a log file of that name. You must specify the full pathname in the string.
Connecting to a Server Thread
Connecting creates a %Net.Remote.Gateway object.
Once the Object Gateway server is running, each InterSystems IRIS session that needs to invoke .NET class methods must create its own connection to the Object Gateway server:
The Gateway.%Connect() Method
The %Connect() method establishes a connection with the Object Gateway engine. It accepts the following arguments:
Argument Description
host Identifies the machine on which the Object Gateway server is running.
port Port number over which the proxy classes communicate with the .NET classes.
namespace InterSystems IRIS namespace.
timeout Number of seconds to wait before timing out, the default is 5.
additionalClassPaths Optional — use this argument to supply additional class paths, such as the names of additional assembly DLLs that contain the classes you are importing via the Object Gateway. See the Import Arguments section for details using this argument.
Disconnecting and Stopping the Server
ObjectScript code that establishes an Object Gateway worker thread must explicitly disconnect before exiting; otherwise, the assigned port for the connection stays “in use” and is unavailable for use in other connections. A worker thread can be disconnected by calling the %Disconnect() method of the %Net.Remote.Gateway object.
The following %Net.Remote.Service methods are available to stop the Object Gateway server:
Monitoring and Debugging the Object Gateway
The following %Net.Remote.Service methods are available to monitor an Object Gateway server:
Error Checking
The Object Gateway provides error checking as follows:
In both cases, InterSystems IRIS records the last error value returned from a .NET class (which in many cases is the actual .NET exception thrown) in the local variable %objlasterror.
You can retrieve the complete text of the error message by calling $system.OBJ.DisplayError, as follows:
 Do $system.OBJ.DisplayError(%objlasterror)
Note that %objlasterror should be used as a debug resource only (for example, in development code that does not yet report errors properly), so that the underlying problem can be diagnosed and the offending code's error reporting can be corrected. It is appropriate for such code to kill %objlasterror whenever it uses an error status that is an expected condition and not a reportable error.
Troubleshooting
The following suggestions may help in certain situations: