Skip to main content

Running a Gateway Server

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.ServiceOpens in a new tab methods are available to start the server:

  • StartGateway() — Start the .NET Gateway server specified by a Gateway name.

  • StartGatewayObject() — Start the .NET Gateway server specified by a Gateway definition object.

  • OpenGateway() — Get the Gateway definition object for a given Gateway name.

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.GatewayOpens in a new tab 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:

  • Caché Basic or ObjectScript code sends a connection request.

  • Upon receiving the request, the .NET Gateway server starts a worker thread in which the .NET class methods subsequently run.

  • The connection between this .NET Gateway worker thread and the corresponding Caché session remains established until it is explicitly disconnected.

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.GatewayOpens in a new tab object.

  • The %Disconnect() method closes a connection to the .NET Gateway server.

The following %Net.Remote.ServiceOpens in a new tab methods are available to stop the Gateway server:

  • StopGateway() — Stop the .NET Gateway server specified by the Gateway name passed to this method.

  • StopGatewayObject() — Stop the .NET Gateway server specified by the Gateway definition object passed to this method.

  • ShutdownGateway() — Shutdown the Gateway server.

Monitoring and Debugging the Gateway

The following %Net.Remote.ServiceOpens in a new tab methods are available to monitor a Gateway server:

  • CheckMonitor() — Check if Gateway is being monitored and return the monitor job number.

  • GatewayMonitor() — The Gateway server is monitored with PING requests, according to the time interval specified by the HeartbeatInterval property of the Gateway server. Hourly, a record of type "Info" is logged.

  • StartMonitor() — If the Gateway server has the HeartbeatInterval property set to a value greater than 0, then job off a background process to monitor the Gateway server.

  • StopMonitor() — Terminate process currently monitoring a Gateway server.

  • PingGateway() — "Ping" the Gateway server to check if it's alive.

Error Checking

The .NET Gateway provides error checking as follows:

  • When an error occurs while executing Caché proxy methods, the error is, in most cases, a .NET exception, coming either from the original .NET method itself, or from the .NET Gateway engine. When this happens, an error is trapped.

  • The .NET Gateway API methods like %Import() or %Connect() return a typical Caché %StatusOpens in a new tab variable.

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:

  • Activate logging

    Should you encounter problems while using the .NET 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 Gateway Server Properties ”) when you start the .NET Gateway.

  • Terminal session problems

    Sometimes, while using the .NET 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 .NET 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:

     Close "|TCP|port"

    Where port is the port number to close.

    Alternatively, you can attempt to reconnect Caché to the Object Gateway server without closing the port by calling the %LostConnectionCleanup() method and %Reconnect() method of the gateway connection objectOpens in a new tab in succession.

    If you prefer to automate the process of reconnecting to the Object Gateway server in the event of a disconnection, set the AttemptReconnect property for the gateway connection object to true.

  • 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 .NET 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:

    HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Windows\GDIProcessHandleQuota

    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.

    See the following Microsoft MDSN article for more information on this subject: in a new tab

FeedbackOpens in a new tab