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

The SPI Procedures
SPI Programming Manual—427506-006
3-12
SSGET and SSGETTKN Procedures
•
The order in which tokens are added to the buffer is not significant except in the
case of: (1) SSPUT and SSPUTTKN calls with token codes for tokens that start
and end lists, and (2) a few subsystem-specific exceptions mentioned in the
subsystem manuals (for example, the ZEMS-TKN-SUBJECT-MARK token in an
event message).
•
Adding a token to the buffer with SSPUT or SSPUTTKN does not affect the
current-token pointer for subsequent calls to SSGET or SSGETTKN.
•
When SSPUT is called with a token map, it uses the null-value and version
information in the token map, if necessary, to update the header token ZSPI-TKN-
MAX-FIELD-VERSION. The token map is not stored in the buffer; instead, SSPUT
creates a token code of type ZSPI-TYP-STRUCT with the token number of the
map.
•
If an error is returned by the procedure, buffer pointer information is not updated.
SSGET and SSGETTKN Procedures
The SSGET and SSGETTKN procedures extract tokens and related information from
an SPI buffer. The two procedures produce the same results, and they are identical
except for the type of the
token-id parameter (SSGET passes token-id by
reference and SSGETTKN passes it by value) and the consequent fact that
SSGETTKN cannot be used with a token map.
A program can retrieve tokens from an SPI buffer in two ways using SSGET. The first
way is to extract a particular token by name. This way is usually most desirable for
management applications. The second way is to use one of the two special operations
ZSPI-TKN-NEXTCODE and ZSPI-TKN-NEXTTOKEN to scan the buffer item by item.
Servers often use this method to determine the contents of a message and to check for
tokens that should not be present in the requester’s message.
Programs should not rely on the relative order of tokens within the buffer, except in the
case of multiple tokens with the same token code and subsystem ID. Such multiple
occurrences are always kept in the order in which they were placed in the buffer, and
can be treated as an array.
General Syntax
buffer input, output
INT .EXT:ref:*
SSGET ( buffer ! i/o
SSGETTKN , token-id ! i
, [ token-value ] ! i/o
, [ index ] ! i
, [ count ] ! i/o
, [ ssid ] ) ! i/o