The primary method of calling a remote routine is by using %RXSUBR and the related RX_xxx routines. This approach enables you to make remote routine calls in a way that is very much like using XSUBR. (You can also make remote calls by directly manipulating a routine call block (RCB) with the RCB_xxx routines. See Making remote calls using a routine call block.)
For a complete code sample, see Appendix D: xfNetLink Synergy Sample Code. For details on the RX_xxx routines, see xfNetLink Synergy API.
| 1. | .INCLUDE these two files in your program: |
- DBLDIR:rxerr.def
- DBLDIR:rxapi.def
| 2. | Use %RX_START_REMOTE to initiate a request for a remote session. You can pass the host IP and port in the call, or specify them in the synergy.ini file (or as environment variables on UNIX and OpenVMS). (See Configuring xfNetLink Synergy.) For example: |
status = %rx_start_remote(netid, ip, port)
If the call is successful, %RX_START_REMOTE returns the status code RX_SUCCESS and a network connection ID (net ID), which you’ll need to make the remote call. The net ID is a handle to an internal memory structure that describes the network connection and its current state.
If the %RX_START_REMOTE call is not successful, it returns a status code indicating why the call failed.
When you make a connection to xfServerPlus, the xfServerPlus process creates a dbs (or dbr if XFPL_DBR is set). Once created, this dbs continues to run and process requests from the client until the connection is closed, and then the dbs is closed by the xfServerPlus process.
| 3. | Use %RXSUBR to call the remote routine, which then executes in a specified remote session. Pass the network connection ID returned by %RX_START_REMOTE, the method ID of the routine you want to call (as defined in the SMC), and up to 253 arguments: |
xcall rxsubr(netid, "methodid", arg1, arg2)
%RXSUBR supports passing integer, decimal, implied-decimal, and alpha data types. Packed data is supported on the client side. Arrays of up to nine dimensions are also supported. %RXSUBR supports the usual Synergy conventions for returning results from function calls.
|
You cannot pass ^VAL and ^REF arguments to %RXSUBR. If a remote routine expects to receive a ^VAL or ^REF argument, the arguments must be defined as such in the Synergy Method Catalog. Pass the arguments normally (i.e., by descriptor) to %RXSUBR; xfServerPlus will convert them to the correct type based on how they are defined in the SMC. |
If the call is successful, arguments and results will be updated. If the call fails, a Synergy runtime error will be signaled, and you can retrieve error information. (See Handling xfNetLink Synergy errors.)
| 4. | Close the session with RX_SHUTDOWN_REMOTE: |
xcall rx_shutdown_remote(netid)
|
Failure to close the session with RX_SHUTDOWN_REMOTE wastes system resources. |
