%RX_START_REMOTE
Initiate xfServerPlus session for Synergy client
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
status = %RX_START_REMOTE(netid, [ip], [port], [call_timeout], & [sess_timeout], [secure_status][, scl])
Return value
status
A status code indicating the result of the request for a remote session. Status codes are defined in the file DBLDIR:rxapi.def, which you should .INCLUDE in programs that use xfNetLink Synergy. See the %RX_START_REMOTE Status Codes table for explanations of the status codes and what you can do to resolve the problems they represent. (n)
If %RX_START_REMOTE returns RX_SUCCESS, execution is ready to proceed.
Arguments
netid
Returned with the network connection ID. The net ID is a handle to a memory structure containing information that describes the location and state of the xfServerPlus session that was created. (n)
This value is set by %RX_START_REMOTE and should be passed to all subsequent xfNetLink calls directed at the xfServerPlus session that it represents. If %RX_START_REMOTE does not return RX_SUCCESS, netid is set to 0.
ip
(optional) Host name or IP address of the machine where xfServerPlus is running. (a)
If an IP is passed, it is used. Otherwise, synergy.ini (or the corresponding environment variable on UNIX and OpenVMS) is checked for the value XF_REMOTE_HOST. If no IP is specified there, the connection errors out.
port
(optional) The port number xfServerPlus is running on. The default is 2356. (n)
If port is passed, it is used. Otherwise, synergy.ini (or the corresponding environment variable on UNIX and OpenVMS) is checked for the value XF_REMOTE_PORT. If no port is specified there, the default is used.
call_timeout
(optional) The length of time (in seconds) that the remote session request should wait for the results of a remote routine call. The default is 1800 seconds (30 minutes). (n)
This time-out is measured for each send–receive request between xfNetLink and xfServerPlus. (This is ‘C’ in figure 1.)
If a call time-out is passed, it is used. Otherwise, synergy.ini (or the corresponding environment variable on UNIX and OpenVMS) is checked for the value XF_RMT_TIMOUT.
If no time-out is specified there or if the value is ≤ 0, the default time-out is used. This value is associated with the network connection ID and may be changed at runtime with %RX_RMT_TIMOUT.
For more information on setting time-outs for xfNetLink Synergy, see Specifying time-out values. |
sess_timeout
(optional) The length of time (in seconds) that the remote session request should wait for a session connection from xfServerPlus. The default is 120 seconds (2 minutes). (n)
This time is measured from the time that xfNetLink receives the connection request acknowledgment from the connection monitor to the time it receives an acknowledgment from the session started by the logic server. (This is ‘B’ in figure 1.) Note that the time-out for the request for session from the connection monitor is 2 minutes (‘A’ in figure 1): if no acknowledgment is received from the connection monitor within 2 minutes of making the call, a time-out will occur no matter how sess_timeout is set.
If a session time-out is passed, it is used. Otherwise, synergy.ini (or the corresponding environment variable on UNIX and OpenVMS) is checked for the value XF_RMTCONN_TIMOUT. If no time-out is specified there or if the value is ≤ 0, the default time-out is used.
|
secure_status
(optional) Returns the encryption status of the server machine. (n)
0 = Encryption not enabled
1 = (deprecated in Synergy/DE 11; previously indicated slave encryption)
2 = Encryption is enabled
scl
(optional) The security compliance level. Indicates the available protocols to use for encrypted data. (n)
0 = Always use the current Synergy default
1 = (No longer valid; removed in Synergy/DE 11.1 )
2 = Use protocols TLS 1.1, TLS 1.2, and higher
3 = Use protocols TLS 1.2 and higher (default)
Discussion
% RX_START_REMOTE initiates a request for an xfServerPlus session. It handles the creation of a socket connection between the Synergy client and a dedicated xfServerPlus session running on the server. This routine returns a status code (see table below) that indicates the success or failure of the call. If the call is successful, a network connection ID is returned in the netid argument.
Examples
See Appendix D: xfNetLink Synergy Sample Code.
Number |
Status code |
Meaning |
What to do |
---|---|---|---|
0 |
RX_SUCCESS |
Session started. |
N/A |
12301 |
RX_INVLOGIN |
Remote session log-in failed. |
Make sure the username and password you specified when registering the xfServerPlus service are valid. |
12302 |
RX_NOTLICENSED |
xfServerPlus not licensed. |
Contact Synergex Customer Service to request an XFPL license. |
12303 |
RX_LICENSELMT |
Too many consecutive xfServerPlus sessions running. |
Increase your connection licenses or make sure your application disconnects in an appropriate fashion when it no longer needs the remote session. |
12304 |
RX_LICENSEEXP |
Extended demo period expired. |
Contact Synergex Customer Service for new licenses. |
12305 |
RX_RSYNDTIMEOUT |
Client timed out waiting to start remote session. |
Adjust the session time-out argument in the %RX_START_REMOTE call or change the value for the session time-out in the synergy.ini file (or change the environment variable on UNIX and OpenVMS). If the problem persists, check with your system administrator. |
12306 |
RX_NOSTART |
OS level problem in spawning or forking the remote session. |
Verify that the xfServerPlus account has read/write permission to the DBLDIR directory. Check with your system administrator. |
12307 |
RX_INVRESULT |
Unexpected error returned by xfServerPlus. |
|
12308 |
RX_NODBLDIR |
The DBLDIR environment variable is not set for the registered service. |
See Setting the XFPL_SMCPATH environment variable for xfServerPlus. Follow the instructions for setting XFPL_SMCPATH for a specific instance of xfServerPlus, but substitute DBLDIR for XFPL_SMCPATH. |
12309 |
RX_NOXFSPL |
xfServerPlus not running on the port specified. |
Verify that xfServerPlus is running on the port specified with XF_REMOTE_HOST. |
12310 |
RX_XFSPLINCOMPAT |
xfNetLink client version incompatible with server version. |
Upgrade either your client or your server to the higher version. Running a newer client with an older server is not a supported configuration. |
12311 |
RX_NOMEM |
Insufficient memory on server during start-up. |
Upgrade memory or decrease number of running processes. |
12312 |
RX_OUTRNG |
Internal “out of range” error in server start-up. |
|
12313 |
RX_INVHDL |
Internal “invalid memory handle” on server start-up. |
|
12314 |
RX_NOHOSTSPEC |
No host specified. |
Add host name or IP address of remote server to your start-up call or specify it in synergy.ini (or as an environment variable on UNIX and OpenVMS). |
12315 |
RX_BADPORTNO |
Port number not numeric. |
Change the port argument or check that a valid port was specified in synergy.ini (or as an environment variable on UNIX and OpenVMS). |
12316 |
RX_BADTIMSPEC |
Time not numeric. |
Correct time-out argument(s) to pass number of seconds. |
12317 |
RX_BADLOCALHOST |
Cannot get local host name (machine where xfNetLink Synergy is running). |
Check with your system administrator. |
12318 |
RX_BADHOSTNAME |
Cannot get host name (machine where xfServerPlus is running). |
Check with your system administrator. |
12319 |
RX_NOUSRBATPRV |
No batch privilege for username. |
(Windows) The user account used to start xfServerPlus does not have the “log on as a batch job” user right set. This error can occur only if you are using xfServerPlus version 7.1.5 or earlier. Using a version of the server that predates your client version is not a supported configuration. Upgrade xfServerPlus to the current version. |
12320 |
RX_NORUNLICENSE |
No Runtime license. |
Verify that there is a Runtime license on the server machine. |
12322 |
RX_LICENSEACCESS |
Cannot access License Manager (synd). |
Check with your system administrator. |
12323 |
RX_SSLCONNECTERR |
OpenSSL connection failed. Usually this means the client and server were unable to negotiate a protocol. |
Verify that the security compliance level is the same on both client and server. Check your encryption configuration; see Using xfServerPlus encryption. |
12324 |
RX_BADSCLVALUE |
Invalid value passed for scl (security compliance level) argument. |
Correct the scl argument to pass 0, 2, 3, or 4. |
10000 level errors |
N/A |
Socket errors. |
N/A |