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