Running an Object Gateway Server
Each Object Gateway server session consists of the following components:
an Object Gateway Server instance (see “Object Gateway Server Versions”) running in the .NET CLR
a %Net.Remote.Service object running in an InterSystems IRIS® namespace
a unique TCP port over which the two objects communicate
one or more connections, where each connection links an InterSystems IRIS %Net.Remote.Gateway object to a thread within the server instance
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:
StartGateway() — Start the Object Gateway server specified by an Object Gateway name.
StartGatewayObject() — Start the Object Gateway server specified by an Object Gateway definition object.
OpenGateway() — Get the Object Gateway definition object for a given Object Gateway name.
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.
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:
InterSystems.Data.Gateway.exe port host logfile
InterSystems.Data.Gateway.exe 55000 "" ./gatewaySS.log
|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:
ObjectScript code sends a connection request.
Upon receiving the request, the Object Gateway server starts a worker thread in which the .NET class methods subsequently run.
The connection between this Object Gateway worker thread and the corresponding InterSystems IRIS session remains established until it is explicitly disconnected.
The Gateway.%Connect() Method
The %Connect() method establishes a connection with the Object Gateway engine. It accepts the following arguments:
|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 %Disconnect() method closes a connection to the Object Gateway server.
The following %Net.Remote.Service methods are available to stop the Object Gateway server:
StopGateway() — Stop the Object Gateway server specified by the Object Gateway name passed to this method.
StopGatewayObject() — Stop the Object Gateway server specified by the Object Gateway definition object passed to this method.
ShutdownGateway() — Shutdown the Object Gateway server.
Monitoring and Debugging the Object Gateway
The following %Net.Remote.Service methods are available to monitor an Object Gateway server:
CheckMonitor() — Check if Object Gateway is being monitored and return the monitor job number.
GatewayMonitor() — The Object Gateway server is monitored with PING requests, according to the time interval specified by the HeartbeatInterval property of the Object Gateway server. Hourly, a record of type "Info" is logged.
StartMonitor() — If the Object Gateway server has the HeartbeatInterval property set to a value greater than 0, then job off a background process to monitor the Object Gateway server.
StopMonitor() — Terminate process currently monitoring an Object Gateway server.
PingGateway() — "Ping" the Object Gateway server to check if it's alive.
The Object Gateway provides error checking as follows:
When an error occurs while executing InterSystems IRIS proxy methods, the error is, in most cases, a .NET exception, coming either from the original .NET method itself, or from the Object Gateway engine. When this happens, an error is trapped.
The Object Gateway API methods like %Import() or %Connect() return a typical InterSystems IRIS %Status variable.
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:
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.
The following suggestions may help in certain situations:
Should you encounter problems while using the Object Gateway it is always a good idea to turn logging on. This will also aid InterSystems staff in helping you troubleshoot problems. To activate logging, just define the logfile argument for the Object Gateway definition you are using (see the chapter on “Setting Object Gateway Server Properties ”) when you start the Object Gateway.
Terminal session problems
Sometimes, while using the Object Gateway in a debugging or test situation, you may encounter problems with a Terminal session becoming unusable, or with write errors in the Terminal window. It is possible that a Object Gateway connection terminated without properly disconnecting. In this case, the port used for that connection may be left open.
If you suspect this is the case, to close the port, type the following command at the Terminal prompt:
Where port is the port number to close.
Connection timeout errors
When writing a query, a .NET application may encounter an <ALARM> error due to a connection timeout error. The default timeout parameter can be overridden with the following command (assuming you have a command CMD):
Out of Memory errors
Handling large amounts of data over the Object Gateway may cause System.OutOfMemoryException errors. In this situation, raising the numbers of GDI Handles may help. You can raise the number of handles by changing the following registry entry:
The default is 10000 (2710 in Hex). It may help to set it to 20000 (4E20 in Hex). Larger Values like 25000 or 30000 are also possible.