Using the RESPONSE and REASON options

The RESPONSE and REASON options are required on each API command. You should specify these options as user-defined variables to receive the numeric response and reason values returned by a command. You can then convert the numeric values into more meaningful character equivalents. In general, RESPONSE describes the result of command processing and REASON further qualifies the response to certain commands.

Note:
The TBUILD and TPARSE commands, which can be used only with the REXX run-time interface, do not use the RESPONSE and REASON options. The result of these REXX-specific processes is returned by their STATUS option. For more information, see REXX error handling.

Types of responses

There are three types of responses that an API command can return:

The character equivalents of the RESPONSE and REASON values that can be returned are given in the description of each command. For a summary of RESPONSE and REASON character values by command, see CICSPlex® System Manager Application Programming Reference. For a list of RESPONSE and REASON character values and their numeric equivalents, also see CICSPlex System Manager Application Programming Reference.

Normal responses

A normal response indicates the API command completed processing successfully. The following values represent a normal response:

OK
The command was successfully processed and control was returned to the program. There are no reasons associated with a response of OK.
SCHEDULED
A command that was issued with the NOWAIT option has been scheduled for processing. The actual result of command processing is returned by the RECEIVE command in an ASYNCREQ resource table record. There are no reasons associated with a response of SCHEDULED.

Warning responses

A warning response indicates the API command was successfully processed, but a condition occurred that should be investigated. A REASON value is also returned that describes the condition. The following values represent a warning response:

NODATA
A command that normally results in data being returned to the program was processed successfully, but there was no data to return. The reasons for a NODATA response are given with the commands that return it.
WARNING
A command that normally results in data being returned to the program was processed successfully, but not all of the available data was returned. A typical reason for this response might be that the output area provided by the program was not large enough to hold all the data. The actual reasons for a WARNING response are given with the commands that return it.

Error responses

An error response indicates the API command was not successful. One or more REASON values are also returned that describe the error.

Note:
Note that, except for the FAILED error response, these response codes usually indicate either an error in the user’s API program (for example, failing to discard resources when they are no longer required), or an error with the CICSPlex SM environment (for example, a CMAS or MAS is not available).

The following values represent an error response:

BUSY
A resource referred to by the command is currently being processed by another command. This situation can occur when a command that was previously issued with the NOWAIT option is processing a resource that is required by the current command. The reasons for a BUSY response are given with the commands that return it.
DUPE
A resource referred to by the command already exists. The reasons for a DUPE response are given with the commands that return it.
ENVIRONERROR
An environmental condition (such as short on storage) prevented the command from being processed. The reasons for an ENVIRONERROR response are given with the commands that return it.
FAILED
An unexpected problem occurred during command processing. The reasons for a FAILED response are given with the commands that return it.

In the case of a FAILED EXCEPTION response, you should check the following sources for information related to the condition:

INCOMPATIBLE
Two or more resources referred to by the command are incompatible. The reasons for an INCOMPATIBLE response are given with the commands that return it.
INUSE
A resource referred to by the command is in use and, therefore, cannot be discarded. The reasons for an INUSE response are given with the commands that return it.
INVALIDATA
The command parameter list contains invalid data. The reason for an INVALIDATA response is always the name of the parameter that contains invalid data. The reasons are given with the commands that return this response.
INVALIDCMD
The command is invalid as indicated by the reason code:
Filter
The filter that is being built is too large or complex.
Length
The total length of all the inputs used in the command exceeds the maximum limit.
N_A
The command is invalid. Check which version of the CICS® translator was used to translate the API command. Also check that the command being used is available on the CICSPlex SM release that the program is using.
INVALIDPARM
The command parameter list is invalid. There are a variety of situations that could result in an INVALIDPARM response. For example:
Syntax error
The syntax of an input parameter is incorrect (for example, a resource table name begins with a numeric character).
Null parameter address
An input parameter could not be found because the generated address for that parameter is 0.
The reason for an INVALIDPARM response is always the name of the parameter that is invalid. The reasons are given with the commands that return this response.
NOTAVAILABLE
A required CMAS or MAS resource is not available. The reasons for a NOTAVAILABLE response are given with the commands that return it.
NOTFOUND
A resource referred to by the command could not be found. The reasons for a NOTFOUND response are given with the commands that return it.
NOTPERMIT
The API request is not permitted by the external security manager (ESM) at your enterprise. The reasons for a NOTPERMIT response are given with the commands that return it.
SERVERGONE
The CMAS to which the processing thread was connected is no longer active. There are no reasons associated with a response of SERVERGONE.
TABLEERROR
An error was detected in a resource table record (either a result set record or a CICSPlex SM definition record). The reasons for a TABLEERROR response are given with the commands that return it.
VERSIONINVL
An invalid version of CICSPlex SM was detected. The reasons for a VERSIONINVL response are given with the commands that return it.

Testing for RESPONSE and REASON

To evaluate the results of an API command, you simply code the RESPONSE and REASON options on the command and follow the command immediately with a test of the returned values. The RESPONSE and REASON options return numeric values. Different built-in functions are provided for converting and testing the numeric response and reason values in the command-level interface and the REXX run-time interface.

Using the command-level interface

When you are using the CICSPlex SM command-level interface, you can use the EYUVALUE built-in function to convert and test the numeric RESPONSE and REASON values returned by an API command.

As an example, consider this API command:

   EXEC CPSM CONNECT
             CONTEXT(WCONTEXT)
             SCOPE(WSCOPE)
             VERSION('0310')
             THREAD(WTHREAD)
             RESPONSE(WRESPONSE)
             REASON(WREASON)
      .
      .

To test for the RESPONSE value in each of the supported languages, you could code:

COBOL or PL/I:
IF WRESPONSE NOT = EYUVALUE(OK) GO TO NOCONNECT.
C:
if (WRESPONSE ¬= EYUVALUE(OK)) { goto NOCONNECT; }
Assembler language:
CLC   WRESPONSE,EYUVALUE(OK)
BNE   NOCONNECT
which the built-in function changes to:
CLC   WRESPONSE,=F'1024'

You can use EYUVALUE in the same way to test for the REASON value, if the RESPONSE is one that returns a reason.

Using the REXX run-time interface

When you are using the REXX run-time interface, you can use the EYURESP and EYUREAS built-in functions to convert and test the numeric RESPONSE and REASON values returned by an API command.

As an example, consider this API command:

   var = EYUAPI('CONNECT'              ,
                'CONTEXT('WCONTEXT')'  ,
                'SCOPE('WSCOPE')'      ,
                'VERSION(0310)'      ,
                'THREAD(WTHREAD)'      ,
                'RESPONSE(WRESPONSE)'  ,
                'REASON(WREASON)')
      .
      .

To test for the RESPONSE value, you could code:

   If WRESPONSE <> EYURESP(OK) Then Signal NOCONNECT

to compare the numeric RESPONSE value returned in WRESPONSE with the numeric equivalent of OK.

Alternatively, you could code:

   If EYURESP(WRESPONSE) <> "OK" Then Signal NOCONNECT

to convert the numeric RESPONSE value to its character equivalent first.

Note:
The RESPONSE and REASON options report only run-time errors. Errors in interpreting an API command are reported in either the REXX RC variable or the variable assigned to a REXX function.
[[ Contents Previous Page | Next Page Index ]]