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

SRVCALL()

This function executes 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 is 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. Do not use it in an IMOD running in an ISERVE address space.

Syntax

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

Parameters

result

If the operation was successful, this is the value the last-executed REXX RETURN or EXIT instruction in the called routine specified. 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 executed.

Default: The 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 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 stack for the caller. Upon return, any records that are 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 passed to the called routine. 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

A string that is passed to the called routine as an argument string.

Default: NONE

Usage Notes

• Only a single argument can be passed, although this argument can have many fields.
• The called IMOD Only references the passed stack. If the called IMOD creates more 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, 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.
• Only pass required stack records to an IMOD. Although unread records are passed back to the stack for the caller, this results in considerable (and avoidable) overhead.
• Do not execute SRVCALL() 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 that SRVCALL and its associated components generate sets 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 */