Using the Caché Gateway for .NET
Running a Gateway Server
[Home] [Back] [Next]
InterSystems: The power behind what matters   

Each Gateway server session consists of the following components:

See 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 Caché and the .NET Gateway server run on different machines, you may find it useful to start the Gateway server from a command prompt.
The Gateway server executable will normally be located in a default directory (see 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 Gateway server listens. Specify "",, or default to listen on all IP adapters on the machine (, 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 .NET Gateway server is running, each Caché session that needs to invoke .NET class methods must create its own connection to the .NET Gateway server:
The Gateway.%Connect() Method
The %Connect() method establishes a connection with the .NET Gateway engine. It accepts the following arguments:
Argument Description
host Identifies the machine on which the .NET Gateway server is running.
port Port number over which the proxy classes communicate with the .NET classes.
namespace Caché 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 .NET Gateway. See the Import Arguments section for details using this argument.
Disconnecting and Stopping the Server
Caché Basic or ObjectScript code that establishes a .NET 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 Gateway server:
Monitoring and Debugging the Gateway
The following %Net.Remote.Service methods are available to monitor a Gateway server:
Error Checking
The .NET Gateway provides error checking as follows:
In both cases, Caché 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.
The following suggestions may help in certain situations:

Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA