Specifying an API command

When you write a program in REXX, you pass a character image of the command to be issued to the REXX function package supplied by CICSPlex SM.

The command string can include imbedded REXX variables, as appropriate. You can specify the command in one of two ways:

Invoke the EYUAPI function with the name of the command as its parameter.
Use the REXX ADDRESS command to pass subsequent statements to the function package.

Note: You can also use the REXX PARSE VALUE command to pass API commands to the function package. However, the processing overhead of PARSE VALUE is quite high. Furthermore, the EYUAPI function returns only a single character (0 or 1), so there is no need to parse its results. For these reasons, using PARSE VALUE is not recommended.

The following example shows a partial GET command as it would be issued using the EYUAPI function:

  var = EYUAPI('GET OBJECT(LOCTRAN)...')

var is the variable assigned to receive the return code from the EYUAPI function.

The next example shows the same GET command being issued by the REXX ADDRESS command:

   ADDRESS CPSM 'GET OBJECT(LOCTRAN)...'

When the data in a REXX variable is to be passed to the function package the text portion of the API command must be terminated, the REXX variable provided, and the rest of the API command completed. The following is an example of a complete GET command that demonstrates the imbedded use of REXX variables:

  var = EYUAPI('GET OBJECT(LOCTRAN)' ,
              'RESULT(setvar) THREAD(THRD1)' ,
              'RESPONSE(rspvar) REASON(reavar)')

In this example, the result set to receive the LOCTRAN objects, and the RESPONSE and REASON options are all specified as REXX variables.

Because of the way REXX handles variable substitution, you must keep in mind whether a variable is being used to send data to the API, receive data from the API, or both. The next example shows a CONNECT command where the USER and VERSION options send data to the API. The THREAD, RESPONSE, and REASON options all name variables to receive data from the API. Note that names of variables that receive data are specified as part of the command.

  var = EYUAPI('CONNECT USER('userid') VERSION(0310)' ,
              'THREAD(thdtkn) RESPONSE(rspvar) REASON(reavar)')

In those cases where you want to access a resource table, special processing is required. An example of this is a FETCH command, which requires an INTO option to define where the resource table data should be placed for processing by your program. In REXX, you must specify the INTO option as the prefix of a stem variable to receive one or more resource table records. The zero entry of the stem variable indicates the number of records returned.