OSI/AS Management Programming Manual

Using SPI to Build Commands and Decode Responses
SPI Programming Considerations for OSI/AS
056785 Tandem Computers Incorporated 3–9
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/AS subsystem returns multiple response records in its responses to some
commands, as described in the Distributed Systems Management (DSM) Programming
Manual. In those cases, it returns at most one response record in each reply message,
even if the value of ZSPI-TKN-MAXRESP is greater than 1. A response record
normally contains response information for the operation of the command on a single
object. The one exception to this rule is the LISTOBJECTS command. The response to
LISTOBJECTS contains all the requested names of objects that are of a given object
type (and that fit into a single response buffer) in a single response record.
The recommended buffer size (in bytes) for all commands sent to the OSI/AS
subsystem is ZOSI-VAL-BUFLEN. The maximum buffer size that OSI/AS accepts is
ZOSI-VAL-MAX-BUFLEN.
The response buffers for the INFO, LISTOPENS, RESETSTATS, STATISTICS, and
STATUS commands contain extensible structured tokens that return the requested
information.
OSI/AS 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—all
response records, or only those for objects on which errors or warnings occurred. If no
value is specified for this token, OSI/AS returns all response records. Note that for
commands whose purpose is to return information (for instance, the INFO command),
you must ask for all response records if you want to receive the information the
command is intended to provide.