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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-3
Scanning a Buffer Sequentially
Successive calls with ZSPI-TKN-NEXTCODE:
token code occurrences
1st call A 3
2nd call B 1
3rd call A 2
4th call C 1
5th call ZSPI-ERR-MISTKN
The NEXTCODE operation sets both the current position and the next position to the
token code it returns. This means that a subsequent call to SSGET with the returned
token code can be used to get the value associated with that token code.
The ZSPI-TKN-NEXTCODE operation does not retrieve token codes that are inside a
list unless the list has been explicitly selected by a call to SSGET. After you are
positioned inside a list, however, you can use ZSPI-TKN-NEXTCODE to exit the list by
requesting the next token code after the ZSPI-TKN-ENDLIST token.
For both ZSPI-TKN-NEXTCODE and ZSPI-TKN-NEXTTOKEN, unlike a regular
SSGET call to get a particular token, the subsystem ID is an output parameter only;
you merely provide a variable in which SSGET will return the subsystem ID that
qualifies the token code. If you do not supply the subsystem ID parameter, and the
subsystem ID associated with the next token code is not the same as the default
subsystem ID, a “missing parameter” error is returned. Therefore, you should always
supply the subsystem ID parameter when calling SSGET with ZSPI-TKN-NEXTCODE
and ZSPI-TKN-NEXTTOKEN unless, for some special reason, you are certain that all
tokens the program could encounter are qualified by the default subsystem ID. The
subsystem ID returned always has a version field of zero (null).
The identifying-code part of each token is always stored in the SPI buffer as a token
code, even for extensible structured tokens. The token code for an extensible
structured token consists of a token type that identifies the token value as a variable-
length structure (ZSPI-TYP-STRUCT) and the token number from the corresponding
token map. When a program scans the buffer using SSGET with ZSPI-TKN-
NEXTCODE or ZSPI-TKN-NEXTTOKEN, it retrieves this token code, not the token
map. After the call with ZSPI-TKN-NEXTCODE or ZSPI-TKN-NEXTTOKEN, your
application can extract the value of the structure in either of two ways:
•
If you are writing a requester using a structure declaration supplied by the
subsystem (which can differ from the version of that structure that you are using),
use the token number from the retrieved token code in a CASE statement or
similar construct. The CASE statement should select a section of code that calls
SSGET specifying the token map that corresponds to the token number.
•
If you are coding an interpreter, debugger, text formatter, or other program that
does not use subsystem-supplied structure declarations and thus does not have
token maps available, obtain the exact token value from the buffer by passing the
retrieved token code to SSGET. The token value returned contains the length word
from the token map, followed by all the structure fields that were actually submitted
with SSPUT.