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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-5
Working With Lists
Working With Lists
SPI defines four types of lists, as described in Lists on page 2-19. Every list starts with
a list token corresponding to the type of list (ZSPI-TKN-LIST, ZSPI-TKN-DATALIST,
ZSPI-TKN-SEGLIST, or ZSPI-TKN-ERRLIST) and ends with ZSPI-TKN-ENDLIST. You
can think of the list token and the end-list token as analogous to left and right
parentheses. With the exception of the ZSPI-TKN-NEXTTOKEN special operation,
SSGET only accesses tokens in a list if SSGET is first called to retrieve the list token
that marks the beginning of the list. SSGET retrieves tokens from lists as follows:
•
To extract tokens from a list by name, a program must first select the list by calling
SSGET to get the list token (ZSPI-TKN-DATALIST, ZSPI-TKN-ERRLIST, ZSPI-
TKN-SEGLIST, or ZSPI-TKN-LIST) that begins the list. This call sets the current-
token pointer and the next-token pointer to the start of the selected list and lets
subsequent calls to SSGET get tokens within the list.
•
After a list has been selected, SSGET cannot find tokens that are outside the list
(except with the special operation ZSPI-TKN-NEXTTOKEN, described later in this
section). Your program can exit the list by calling SSGET to get the end-list token,
ZSPI-TKN-ENDLIST. This call exits the list and sets the current position to the list
token that begins the list.
•
Within a list, the default subsystem ID is the subsystem ID that qualifies the list
token.
•
The SSMOVE procedure can copy an entire list in a single call. To copy a list, your
program simply specifies the token code that marks the beginning of the list (the
list token) in the SSMOVE call.
Only lists supported by NonStop Kernel subsystems (data lists, segment lists, and
error lists) are used in responses. However, subsystems you write can return lists in
responses and might define a special-purpose list (using ZSPI-TKN-LIST) used in
requests.
This example shows how a program retrieves tokens from an SPI buffer that contains
nested lists. The sample buffer is a response buffer containing two data lists and an
error list; the error list is within the second data list. All tokens in the example are
simple tokens.
Assume a buffer containing:
<ZSPI-TKN-DATALIST>
<TKN-A>
<TKN-B>
<ZSPI-TKN-RETCODE>
<ZSPI-TKN-ENDLIST>
<ZSPI-TKN-DATALIST>
<ZSPI-TKN-ERRLIST>
<ZSPI-TKN-ERROR>
<TKN-INFO>
<ZSPI-TKN-ENDLIST>
<TKN-A>