%RX_START_REMOTE

Initiate xfServerPlus session for Synergy client

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.

(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.

1. xfNetLink time-outs.

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)

4 = Use protocols TLS 1.3 and higher

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.

%RX_START_REMOTE Status Codes
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.	Contact Synergy/DE Developer Support.
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.	Contact Synergy/DE Developer Support.
12313	RX_INVHDL	Internal “invalid memory handle” on server start-up.	Contact Synergy/DE Developer Support.
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	Secure 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