PAM Management Programming Manual

SPI Programming Considerations for the PAM
Subsystem
PAM Management Programming Manual—142481
3-8
Receiving and Decoding the Response Message
COMMENT is the comment token, described in the SPI Programming Manual. ZCOM-
TKN-OBJNAME is the object-name token, described in Section 4, Common
Definitions. ZCOM-TKN-TRACE-OPT is a token used in the TRACE command, and it
is described in Section 5, Commands and Responses
.
If any of the other tokens in a command appear more than once, an error is given either
by the PAM subsystem or by SCP.
Receiving and Decoding the Response Message
Your application must take the following steps to receive and decode a response
message:
1. Declare a buffer of appropriate size.
2. Read the response message using the mechanism appropriate to your programming
language (for example, a WRITEREAD call in TAL).
3. Call SSGET or SSGETTKN to retrieve values of header tokens and other tokens
from the buffer.
4. On encountering the data-list token (ZSPI-TKN-DATALIST) or the error-list token
(ZSPI-TKN-ERRLIST), make another call to SSGET or SSGETTKN to retrieve the
tokens inside the data list or error list.
5. Take action appropriate to the information in the response.
In responses to PAM commands that operate on objects, a response record always
contains response information for the operation of the command on a single object.
The PAM subsystem supports multiple response records in a single reply message. The
number of response records returned in one reply message is controlled by the value of
the header token ZSPI-TKN-MAXRESP in the command.
If multiple response records are to be returned in one reply message, the recommended
buffer size in bytes for the response is a predefined value with the symbolic name
ZPAM-VAL-MAXBUFLEN. If a single response record is to be returned in each reply
message, the recommended buffer size in bytes for the response is the predefined value
ZPAM-VAL-BUFLEN.
The PAM subsystem does support multiple response records over multiple messages
(continuation) by returning a context token when a response is continued.
Error Handling
Each response returned by the PAM subsystem includes a return token (ZSPI-TKN-
RETCODE), whose value indicates whether an error occurred when the PAM subsystem
attempted to perform the command. An error is a serious condition that prevents the
command from being completed. The PAM subsystem does pass through errors from
other subsystems or interfaces.