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.
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:
- EYULOG
- Job log
- AUXTRACE data set
- 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.
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 ]]