Pathway/iTS Management Programming Manual

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual—426749-002

3-27

Receiving and Decoding Response Messages

The following subsections summarize the steps your application must take to receive

and decode SPI command responses. These summaries are followed by subsystem-

specific programming considerations for the Pathway subsystem.

For more information on receiving and decoding SPI commands and responses, see

the SPI Programming Manual.

Summary of Steps

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 by 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, including the error list if one exists.

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.

The Pathway subsystem can return an empty response if an application returns a

ZSPI-TKN-CONTEXT token and there are no more responses to be returned. The

return token ZSPI-TKN-RETCODE in the returned response always has the value

ZPWY-ERR-PM-EOF.

6. Take action appropriate to the information in the response.

Considerations

The response buffer always contains the return token, ZSPI-TKN-RETCODE. The

value of the ZSPI-TKN-RETCODE token is either zero (to indicate that the command is

successful), or it is a nonzero error number (to indicate that the command was not

performed). The command can contain error lists in either case.

Although the Pathway subsystem generates responses for all commands, responses

from some commands (such as INFO TCP and STATUS TCP) must be obtained from

fields within an extensible structured token. For example, the extensible structured

token in the INFO TCP or STATUS TCP command contains all of the information about

TCPs that is available from the PATHMON process. To see a field within an extensible