SPI Programming Manual (G06.24+, H06.03+, J06.03+)

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-6
Checking for Null Values
<TKN-B>
<ZSPI-TKN-RETCODE>
<ZSPI-TKN-ENDLIST>
<ZSPI-TKN-CONTEXT>
When SSGET is first called to scan this buffer (with any token code other than ZSPI-
TKN-NEXTTOKEN), it sees only three tokens:
<ZSPI-TKN-DATALIST> <ZSPI-TKN-DATALIST> <ZSPI-TKN-CONTEXT>
The tokens inside the lists are not available until the list is selected. Calling SSGET
with a list token selects that list. After the first ZSPI-TKN-DATALIST is selected, the
buffer appears to contain:
<TKN-A> <TKN-B> <ZSPI-TKN-RETCODE>
Because the current context is a list, SSGET stops searching when it reaches the end-
list token. Selecting the end-list token with SSGET has the effect of returning to the
previous context (in this case, the topmost level) with the current-token pointer set to
the list ended by the end-list token.
If the program selects the next ZSPI-TKN-DATALIST, the buffer then appears to
contain:
<ZSPI-TKN-ERRLIST> <TKN-A> <TKN-B> <ZSPI-TKN-RETCODE>
The error list describes a warning that occurred on this response, so it is nested within
the data list for this response. If a program calls SSGET to select the error list, the
buffer then appears to contain:
<ZSPI-TKN-ERROR> <TKN-INFO>
At this point, the program can retrieve either ZSPI-TKN-ERROR or TKN-INFO, can
return to the data-list context by selecting ZSPI-TKN-ENDLIST, or can return to the
topmost context by calling ZSPI-TKN-INITIAL-POSITION with the token value ZSPI-
VAL-INITIAL-BUFFER.
Lists can be nested to any depth, but they are limited by the size of the buffer. A
segmented list is the only case in which a list is continued across more than one
message, but even in this case no list really spans messages, but is instead broken
into smaller lists.
Checking for Null Values
Your program might need to test a field of an extensible structured token (for instance,
in a response from a subsystem) to determine whether it has a null value. To perform
this test, declare a copy of the structure, initialize the copy with SSNULL, and then
compare the field in question with the corresponding field in the copy.
Deleting Tokens From a Buffer
A program can delete a specific token or a list from the buffer by using SSPUT with the
special operation ZSPI-TKN-DELETE. It can delete all tokens in the buffer located at