Function INGRCRPC

The REXX function INGRCRPC provides a remote procedure call (RPC) from TSO address space to the SA NetView Agent address space on the same z/OS system. The purpose is to execute a standard command (such as a NetView or MVS command) or a self-written REXX program and to route back the output to the calling TSO program.

INGRCRCP uses the specified PPI receiver ID to determine the target command receiver. INGRCRPC uses internally a unique PPI ID to receive the response. This PPI ID is the job ID of the calling job.

Syntax

rc = INGRCRPC(command, input_data, ppi_rcv_id, taskname, resp_name, timeout, security_ctx)

Parameters

command
The command to be executed in the SA NetView Agent.

Maximum length of the command is 31990 characters. The command must not include 'FF'X or 'FE'X. Precede it with 'MVS' if you want to execute an MVS command. No prefix is needed for NetView or SA commands. If it's an MVS command, INGRCRPC waits until the first output line (might be a multi-line) is caught and timeout is not exceeded.

input_data
Optional input data. It's used for a REXX program. Omit it if you execute a standard command.

You can specify the name of a REXX stem, for example, 'input.'. This is an array of data lines which will be provided as NetView default stem for command execution. This name must end with a dot and input.0 must be a positive number specifying the number of input lines and input.n n=1,2,… contains the n-th input line. For example:

input.0=2
input.1=’abc’
input.2=’xyz’
rc = INGRCRPC(‘MYREXPGM’,’input.’)
This REXX program MYREXPGM can read the input data using the NETV default SAFE.
‘PIPE SAFE * | STEM input.’
ppi_rcv_id
Optional target PPI ID.

It is the PPI receiver ID of the command receiver. If not specified, the default INGRCRCV will be used. See also Command Receiver.

A PPI receiver ID must be alphanumerical mixed case and can contain '$%&@#'. It must have a length of 8 characters, right justified with blanks.

taskname
Optional name of the target task. The maximum length of this parameter is 8 characters.

If not specified, the command receiver decides by itself which task is to be used.

For security context AUTOTASK, the command will be executed in the specified taskname. For security context USERTASK, the taskname is ignored and the command will be executed under the user task.

The following rules apply to the taskname:
  1. taskname is the name of an SA Automated Function with status ACTIVE. For a list of possible names, see DISPAOPS in IBM Z System Automation Operator's Commands.
    1. If the SA Automated Function is a single SA Automated Function, for example, EVTOPER, then the associated NetView task is selected.
    2. If the taskname represents an array of SA Automated Functions, then the corresponding NetView task will be selected from this array via “RoundRobin”.

      For example, the taskname is AOFCMDOPER which represents the array (AOFCMD01, AOFCMD02,...). The specific definitions in CGlobals include: AOFCMDOPER.0 is the number of tasks and AOFCMDOPER.n (n=1,2,…) is the n-th SA Operator Function. So for n=1, AOFCMDOPER.1=AOFCMD01. This array of CGlobals must have been defined before you call INGRCRPC.

      Since taskname is restricted to a length of 8 characters, the name of the CGlobal array is also restricted to 8 characters.

  2. taskname is a valid NetView AUTOTASK (for example, AUTBASE) with status ACTIVE.
  3. In any other cases (for example, unknown task name or inactive task), the command will NOT be executed and error message ING332I will be returned.
resp_name
Optional name of a REXX stem that should receive the response.

If not specified, no response is requested (fire-and-forget).

If you specify the name of a REXX stem, it must end with a dot, for example, 'output.'.

On return, output.0 contains the number of output lines and output.n (n=1,2,..) contains the n-th output line.

timeout
Optional number of seconds that INGRCRPC waits for the response.

If not specified, 10 seconds is used.

If timeout occurs, INGRCRPC returns one of the following return codes:
Return code 2
The remote site has not written any response data into the receiver PPI queue so far. Therefore, no response data has been received at all within specified time frame. There is no guarantee that the command has been terminated or is still running. Also, there is no guarantee that the command has even started running. It might still remain in the command queue of the command receiver task and is waiting for execution.
Return code 1
Return code 1 is only possible for the security context USERTASK. The command receiver is interrupted while waiting for asynchronous output due to timeout. Message ING331I is the only response data provided. The command is being executed but the command execution has not been completed within the specified period of time. The command might still run on the remote NetView task until it is complete. But after completion, no data will be returned.
security_ctx
Optional security context specification.
AUTOTASK
The command will be executed within the security context of the SA operator function, which are auto task(s) specified in the start parameters of the command receiver.
USERTASK
The command will be executed within the security context of the NetView operator task, which is equal to the calling TSO user ID.

If not specified, the security context is AUTOTASK. For more details, see Security Considerations.

Return Codes

0
The command has been executed (either successfully or unsuccessfully) and the command response could be transferred back to the TSO caller. For more details, see Response Data.
1
Timeout on NetView site (only provided with USERTASK).
2
Timeout on TSO site.
4
Missing or invalid input parameter.

See message INGPC012I, which tells you the failing function parameter. Check description of the failing function parameter for correct usage.

8
Error while writing into response stem.

The REXX stem name might be incorrect or an internal error occurred with INGPCREX.

9
Error while reading from input data stem.

The reason might be that the stem element input_data.0 does not contain a whole number; the REXX stem name is incorrect; or an internal error occurred with INGPCREX.

16
Error using the NetView PPI API.

For example, writing into a PPI queue failed or DSIPHONE OPEN, CLOSE or READ failed.

For more details, see accompanied message INGPC010I or INGPC011I.

17
Security error.

The TSO user has no access to the SAF profile that protects the usage of this function. For more details, see Security Considerations.

20
Internal error. REXX script error. For example, REXX Syntax error or NOVALUE condition
24
Internal error. Invalid response data stream.
25
Internal error. Cannot decode response data stream.
28
Internal error. Initialization failed.
32
Internal error. Cannot obtain system information.