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

The SPI Procedures
SPI Programming Manual—427506-006
3-22
Considerations
Considerations
•
Tokens extracted by SSGET and SSGETTKN are not deleted or removed from the
buffer.
•
For checkpointing purposes, note that calls to SSGET and SSGETTKN can modify
the SPI message header. For instance, the header tokens ZSPI-TKN-LASTERR
and ZSPI-TKN-LASTERRCODE change if an SPI error occurs on the call.
Positioning information in the header also changes frequently, and future versions
of SPI might introduce other kinds of change. Programs should never assume that
any SSGET or SSGETTKN operation leaves the buffer unchanged.
•
When the current-token pointer is within a particular list, all SSGET and
SSGETTKN calls pertain only to tokens within that list, but the header tokens listed
in Table 3-2
on page 3-14 are always accessible. Your program can exit the list by
calling SSGET to get the ZSPI-TKN-ENDLIST token.
•
The index and count parameters have no effect when token-id is ZSPI-TKN-
ENDLIST. If supplied,
index must be equal to zero or 1, and count is always
returned as 1.
•
If an error is returned, buffer pointer information is not updated.
•
When you use a token map for the token-id parameter, the map can specify a
structure version that is longer or shorter than the structure contained in the buffer.
If the requested version is longer than the version in the buffer, SSGET calls
SSNULL to set to null values any new fields that are not obtained from the buffer. If
the requested version is shorter than the one in the buffer, SSGET returns only the
requested length.
•
Some of the special operations listed in Table 3-2 on page 3-14 return certain
attributes of tokens in the buffer. These are ZSPI-TKN-COUNT, which gets the
total number of occurrences of a specific token; ZSPI-TKN-LEN, which gets the
length of a token value; ZSPI-TKN-ADDR, which gets the extended address of a
token value; and ZSPI-TKN-OFFSET, which gets the byte offset, from the
beginning of the buffer, of a token value. These special operations are useful to
programs retrieving token values from the buffer. (ZSPI-TKN-ADDR is not
meaningful—and therefore is not available—in TACL.)
When obtaining an attribute of a token with an index of zero, SSGET follows the
same search rules as it does when getting a token value (the search begins with
the token indicated by the next-token pointer) with these exceptions:
•
A special calling mode exists to request an attribute of the current token: if the
token code and index are both null or not supplied, the current token is used.
•
The current and next pointers are not changed if the requested token is the
current token.
•
If the requested token is not the current token, both the current and next
pointers are set to the requested token.