OSI/TS Management Programming Manual

Using SPI to Build Commands and Decode Responses
SPI Programming Considerations for OSI/TS
3–8 056786 Tandem Computers Incorporated
Receiving and Decoding a
Response Message
The following is a summary of the steps your application must take 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 the 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. On encountering a context token (ZSPI-TKN-CONTEXT), finish reading the other
tokens in the buffer. Then, optionally use SSMOVE or SSMOVETKN to copy the
context token into the command buffer, and resend the command to get the next
message in the response.
6. Take action appropriate to the information in the response.
The OSI/TS subsystem returns multiple response records in its responses to some
commands. For such commands, it can also return multiple response messages, as
described in the Distributed Systems Management (DSM) Programming Manual.
If your application requests that OSI/TS return multiple response records in a reply
message, the recommended buffer length (in bytes) for a response from OSI/TS is
ZOS4-VAL-MAX-BUFLEN. Otherwise, the recommended buffer size is
ZOS4-VAL-BUFLEN.
The response buffers for the AGGREGATE, INFO, LISTOPENS, RESETSTATS,
STATISTICS, and STATUS commands contain extensible structured tokens that return
the requested information.
In commands operating on multiple objects, OSI/TS supports the use of the token
ZSPI-TKN-RESPONSE-TYPE. This token allows your application to specify which
kinds of response records should be returned—one for every object, or only those for
objects on which errors and warnings occurred. If no value is specified for this token,
OSI/TS returns a response record for every object (except in the case of the
LISTOBJECTS command). Note that for commands whose purpose is to return
information (for instance, the INFO command), requesting the return of only response
records with errors or warnings can result in no information being returned.