%RXSUBR

Call remote xfServerPlus routine from Synergy client

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

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

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

Return value

result

A function call return value.

If the remote Synergy routine is a function that returns a ^VAL value, the value is returned as the ^VAL result of %RXSUBR. (n)
If the remote Synergy routine is a function that returns a non-^VAL value, the value must be passed as an extra argument at the beginning of the argument list. (a or n)
If the remote Synergy routine is a subroutine, no value is returned.

Arguments

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)

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.

Discussion

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.

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.

To call an external function that returns a ^VAL, use

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

To call an external function that returns a type other than ^VAL, use

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

To call a subroutine, use

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:

The network connection ID is valid.
The method ID is passed.
The data is of a supported type.
The number of arguments does not exceed 253.

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.

Examples

This example calls a function that returns a ^VAL.

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

This example calls a function that returns a non-^VAL.

xcall rxsubr(netid, "cust_info", status, name, SSN)
.
.
.
function cust_info
     a_name      ,a
     a_ssn       ,n
proc
.
.
.
end

This example calls a subroutine.

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.