Using the run-time interface

Command format

An API command can be passed from REXX to CICSPlex® SM in one of two ways. The first method is to use the REXX ADDRESS command, like this:

   ADDRESS CPSM 'command option(arg)...'

This method of calling the API invokes a CICSPlex SM host subcommand environment.

Alternatively, you can use the EYUAPI() function supplied by CICSPlex SM:

   var = EYUAPI('command option(arg)...')

This method invokes the CICSPlex SM REXX function package.

Note that with both methods you can enter text in either upper or lower case.

Here is an example of an API command as it would be issued from a REXX program:

   var = EYUAPI('CONNECT'              ,
                'CONTEXT('WCONTEXT')' ,
                'SCOPE('WSCOPE')'     ,
                'VERSION(0310)'      ,
                'THREAD(THRDTKN)'     ,
                'RESPONSE(RESPVAR)' ,
                'REASON(REASVAR)')
      .
      .

Argument values

The CICSPlex SM run-time interface makes full use of the standard REXX variable interface. REXX processes variables differently depending on the parameter’s data type and whether it is used for input, output, or both. In addition, REXX provides substitution of variables into a command stream that may in some cases make them transparent to the run-time interface.

For the REXX run-time interface, the parenthesized argument values that follow options in an API command are specified as follows:

data-value
A sending argument used to pass character or binary data from your program to CICSPlex SM.

A data-value argument is considered to be character input. Binary data (including EYUDA and CVDA values) is translated into the appropriate internal format. User tokens are not translated.

data-ref
A receiving (or sending and receiving) argument used primarily to pass data from CICSPlex SM to your program.

A data-ref argument must be a named variable that can be used to receive the resulting output. The output data is translated as appropriate:

In some cases, you can use a data-ref argument to provide input to CICSPlex SM before CICSPlex SM returns its output to you (the COUNT option on the FETCH command is an example of this). If a data-ref argument can be supplied as input, you must specify a variable for that argument. If you do not want to specify an input value, you should initialize the variable.

data-area
A sending or receiving argument used to identify a buffer that contains data. A data-area argument must be a named variable.

For output buffers that could receive multiple resource table records, CICSPlex SM creates (or fills) stem variables to hold the data. The zero entry of the stem array indicates the number of entries in the array.

For example, in the stem variable called W_INTO_EVALDEF, the W_INTO_EVALDEF.0 entry contains the number of EVALDEF resource table records returned. The entries W_INTO_EVALDEF.1 through W_INTO_EVALDEF.n contain the actual resource table records.

A stem variable is created regardless of whether the actual output is a single record or multiple records.

ptr-ref
A receiving argument used to pass pointer values from CICSPlex SM to your program.

A ptr-ref argument must be a named variable that can be used to receive the resulting output. The data being passed is a character representation of a hexadecimal address.

cpsm-token
A sending or receiving argument used to pass identifying tokens that are generated by CICSPlex SM.

A cpsm-token argument must be a named variable. Tokens are not translated; the token value is placed into the variable as is.

Note:
Each variable (or stem variable) returned by CICSPlex SM contains an entire resource table record. You can use the TPARSE command to break a record into individual fields. For a description of this command, see REXX functions and commands.
[[ Contents Previous Page | Next Page Index ]]