Each Gateway server session consists of the following components:
Start the .NET Gateway server specified by a Gateway name.
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:
||Port number on which to listen for the incoming requests.
||Optional Contains the IP address or hostname where the 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.
||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
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
method establishes a connection with the .NET Gateway engine. It accepts the following arguments:
||Identifies the machine on which the .NET Gateway server is running.
||Port number over which the proxy classes communicate with the .NET classes.
||Number of seconds to wait before timing out, the default is 5.
||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
method closes a connection to the .NET Gateway server.
Stop the .NET Gateway server specified by the Gateway name passed to this method.
Stop the .NET Gateway server specified by the Gateway definition object passed to this method.
Monitoring and Debugging the Gateway
Check if Gateway is being monitored and return the monitor job number.
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.
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.
Terminate process currently monitoring a Gateway server.
"Ping" the Gateway server to check if it's alive.
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.
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
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: