SRVCALL()

CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › SRVCALL()

SRVCALL()

Use the SRVCALL() function to execute an IMOD as a subroutine in another ISERVE address space. SRVCALL() operates like a standard REXX CALL instruction. An argument string can be passed, a result string returned, and the current stack can be passed to the called routine. The modified stack is returned to the caller.

SRVCALL is TSO/E REXX-compatible and can also be used under SRVBATCH. It should not be used in an IMOD already running in an ISERVE address space.

Syntax

The SRVCALL() function has this syntax:

result = SRVCALL([node],[ssid],imod,[{PASS|NONE}],[args])

Arguments

The SRVCALL() function takes these arguments:

result	If the operation was successful, this is the value specified by the last-executed REXX RETURN or EXIT instruction in the called routine. Otherwise, error text is returned. The returned text is always padded on the left with one extra character. If no system-related errors occurred, this character is a blank. If the returned string is an error message indicating that linkage to the requested IMOD was not performed, this character is an asterisk (*).
node	Name of the GoalNet node where the IMOD is to be executed. Default: Current node.
ssid	Subsystem ID that identifies the CA-GSS that is to execute the IMOD. If ssid is specified without node, the request is routed to the appropriate CA-GSS on the same z/OS system. If ssid is specified with node, the request is first routed to the CA-GSS identified by ssid on the same system as the requester. That CA-GSS system then routes the request to the CA-GSS at node.
imod	Name of the IMOD that is to be executed as an external routine. This argument is required.
PASS	Passes the contents of the current stack (up to the NEWSTACK marker) to the called routine. When the information is passed, it is deleted from the caller's stack. Upon return, any records left on the stack by the called IMOD are returned to the caller. These records become the new stack contents.
NONE	Specifies that no stack information is to be passed to the called routine. This is the default. Any returned stack data is appended to the current stack contents. Select this option whenever records exist on the current stack and the called IMOD is not going to process them.
args	String passed to the called routine as an argument string.

Usage Notes

Only a single argument can be passed, although this argument can have many fields.
Only the passed stack can be referenced by the called IMOD. If the called IMOD creates additional stacks using SWAPSTAK() or NEWSTACK(), only the current stack is returned to the caller at the conclusion of the called IMOD.
Do not use this function from the ISERVE address space. It was designed for use in a single-user environment (SRVBATCH or TSO/E REXX). Other use could create severe processing bottlenecks.
To use this function from SRVBATCH, you must provide a FUNCTION control card in the PARMLIB file.
To use this function from TSO/E REXX, the SRVCALL load module must be accessible using the JOBLIB, STEPLIB or LINKLIST concatenation.
Do not pass stack records to an IMOD if they are not required. Although unread records are passed back to the caller's stack, this results in considerable (and avoidable) overhead.
SRVCALL() should not be executed from CA OPS/MVS Event Management and Automation. Instead, use the SRVOPS() function.

Return Codes

TSO/E REXX has no provision for the setting of return codes by functions. All error text generated by SRVCALL and its associated components set an asterisk in the first position. All non-error text (that returned by a successfully executed IMOD) has a single blank as the first character.

Example

x = srvcall('node2',,'status',,args)
                                /* Run "status" IMOD at node2 */
if substr(x,1,1) == '*' then signal error1
                                /*  Check for error condition */

Tell Technical Publications how we can improve this information