%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])

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.

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.

Note

For more information on setting time‑outs for xfNetLink, 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 = slave encryption enabled

2 = master encryption enabled

scl

(optional) The security compliance level. Indicates the available protocols to use for encrypted data. (n)

0 = Always use whatever the current Synergy default is

1 = use protocols TLS 1.0, TLS 1.1, TLS 1.2 (default)

2 = use protocols TLS 1.1 and TLS 1.2

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

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 user name and password you specified when registering the xfServerPlus service are valid.

12302

RX_NOTLICENSED

xfServerPlus not licensed.

Call your Synergy/DE customer service representative 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.

Call your Synergy/DE customer service representative 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.

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

Call Synergy/DE Developer Support.

12313

RX_INVHDL

Internal “invalid memory handle” on server start‑up.

Call 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 user name.

(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, 1, or 2.

10000 level errors

N/A

Socket errors.