%RXSUBR

Call remote xfServerPlus routine from Synergy client

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
result = %RXSUBR(netid, method_id[/encrypt][, arg, ...])

or

xcall RXSUBR(netid, method_id[/encrypt], result[, arg, ...])

or

xcall RXSUBR(netid, method_id[/encrypt][, arg, ...])

result

A function call return value.

netid

Network connection ID corresponding to the value set by %RX_START_REMOTE. (n)

method_id

The unique identifier (in the SMC) of the routine being called. (a)

Note

The method ID is case sensitive.

/encrypt

(optional) This method requires encryption.

arg

(optional) The argument list. A routine may be called with no arguments. The maximum number permitted is 253.

This routine is the primary means of calling remote Synergy routines, given an existing connection to an xfServerPlus session created with %RX_START_REMOTE.

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

Note

You cannot pass ^REF and ^VAL arguments to %RXSUBR. If a routine expects to receive a ^VAL or ^REF, the arguments must be defined as such in the SMC (see Defining parameters). Pass the arguments normally to %RXSUBR; xfServerPlus will convert them to the correct type based on how they are defined in the SMC.

result = %RXSUBR(netid, method_id [, args])
xcall RXSUBR(netid, method_id, result [, args])
xcall RXSUBR(netid, method_id [, args])

The /encrypt switch is optional. When encryption is enabled on the xfServerPlus machine, all parameter and return value data for all methods is encrypted. You can further safeguard data on specific method calls by including the /encrypt switch on the %RXSUBR call. If you pass /encrypt and encryption is not enabled on the xfServerPlus machine, the error $ERR_XFSERVNOSEC, “Encryption not enabled on server,” will be returned. See Using xfServerPlus encryption for more information on encryption.

When %RXSUBR is called, the following validations take place:

If any of these items are not validated, a Synergy runtime error is signaled (see the Synergy Runtime Errors Signaled by %RXSUBR table) and processing ceases. If all items are validated, %RXSUBR calls the specified Synergy routine.

If the call to the routine is successful, %RXSUBR returns any updated arguments or results as indicated in the Synergy Method Catalog.

If the call is not successful, a Synergy runtime error is signaled (see the Synergy Runtime Errors Signaled by %RXSUBR table). To get more detailed information about a particular error, call RX_GET_ERRINFO or RX_GET_HALTINFO, as indicated in the table.

status = %rxsubr(netid, "cust_info", name, SSN)
.
.
.
function cust_info   ,^val
     a_name           ,a
     a_ssn            ,n
proc
.
.
.
endfunction
xcall rxsubr(netid, "cust_info", status, name, SSN)
.
.
.
function cust_info
     a_name      ,a
     a_ssn       ,n
proc
.
.
.
end
xcall rxsubr(netid, "cust_info", name, SSN)
.
.
.
subroutine cust_info
     a_name      ,a
     a_ssn       ,n
proc
.
.
.
end

See Appendix D: xfNetLink Synergy Sample Code for additional code samples.

Synergy Runtime Errors Signaled by %RXSUBR

Number

Runtime error

Caused by

What to do

111

$ERR_TIMOUT

Client timed out after waiting specified length of time for call results.

Extend the call time-out (see Specifying time-out values) or optimize the called routine. If the problem persists, check with your system administrator.

You can use %RX_CONTINUE to continue processing after a remote call has timed out.

320

$ERR_NETPROB

Tried to make a call on a disconnected socket or lost socket connection during call.

Try again.

550

$ERR_XFBADPKTID

Error occurred parsing returned response.

Contact Synergy/DE Developer Support. See RX_GET_ERRINFO for more information.

551

$ERR_XFBADMTHID

Method ID is too long.

Correct the method ID; the limit is 31 characters. See RX_GET_ERRINFO for more information.

552

$ERR_XFNUMPARMS

Invalid number of arguments sent.

Check routine call against definition in the SMC.

553

$ERR_XFBADPKT

Error occurred parsing returned response.

Contact Synergy/DE Developer Support. See RX_GET_ERRINFO for more information.

554

$ERR_XFBADTYPE

Argument type didn’t correspond to the definition in the SMC.

Check routine call against definition in the SMC. See RX_GET_ERRINFO for more information.

555

$ERR_XFREQPARM

Required argument not sent.

Check routine call against definition in the SMC.

556

$ERR_XFBADARRAY

Error occurred mapping array element.

Contact Synergy/DE Developer Support. See RX_GET_ERRINFO for more information.

557

$ERR_XFIOERR

File I/O error occurred on server.

See RX_GET_ERRINFO for more information.

558

$ERR_XFMETHKNF

Method ID (key) is not found in the SMC.

Check routine call against definition in the SMC. Remember that the method ID is case sensitive. See RX_GET_ERRINFO for more information.

559

$ERR_XFRTNNF

Method not found in specified ELB or shared image.

Make sure the correct ELB is specified in the SMC and that logicals are set correctly in the xfpl.ini file to point to the ELB (see Defining logicals).

560

$ERR_XFNOCONN

Connection to host was lost.

Restart session. If transaction was midstream, you may need to restore the system to a valid state before restarting.

561

$ERR_XFHALT

Fatal untrapped error in Synergy routine.

Check routine for untrapped errors. Make corrections to your code. Be sure to check the number and type of parameters. Restore system as required and restart session. See RX_GET_HALTINFO for more information.

563

$ERR_SRVNOTSUP

Feature not supported on server.

Upgrade xfServerPlus to the current version.

564

$ERR_XFUNKERR

Unknown error reported by xfServerPlus.

The server returned an error that was not recognized by the client. Check the xfpl.log file, which records the error even though the client is unable to receive it. This error usually happens when an older xfNetLink client is communicating with a newer xfServerPlus server. To solve this problem, update your client version. If your versions already match, contact Synergy/DE Developer Support.

569

$ERR_SYNSOCK

Socket error.

See RX_GET_ERRINFO for more information.

571

$ERR_INVNETHND

Network connection ID is not a valid memory handle.

Correct the netid argument.

581

$ERR_NOTNETHND

Network connection ID is a valid memory handle but not a net ID.

Correct the netid argument.

592

$ERR_XFINCALL

Remote call already in progress

Use %RX_CONTINUE to complete the timed-out %RXSUBR call before making another remote call. Or, shut down the session with RX_SHUTDOWN_REMOTE. See RX_GET_ERRINFO for more information.

596

$ERR_XFMETHCRYPT

Method requires encryption. The method is marked for encryption in the SMC, but encryption is not enabled on the server.

Start rsynd with the -encrypt option. See %RXSUBR for information on /encrypt and Using xfServerPlus encryption for information on encryption in general.

597

$ERR_XFSERVNOSEC

Encryption not enabled on server. The client has sent encrypted data, but encryption is not enabled on the server.

Start rsynd with the -encrypt option. See %RXSUBR for information on /encrypt and Using xfServerPlus encryption for information on encryption in general.