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

SPI Concepts and Protocol
SPI Programming Manual—427506-006
2-8
Extensible Structured Tokens
map itself, into the buffer. The message recipient retrieves the structure from the
message by specifying its own version of the map in an SSGET call.
These are examples of extensible structured tokens:
Token Maps
Every extensible structured token has an associated token map that contains the null
value and version for each field in the structure.
A token map is an extended form of tag used by the SPI procedures to ensure
compatibility between different versions of extensible structured tokens. It includes a
token number and a token type indicating it is a variable-length extensible structure.
The SSNULL procedure uses token maps to set a structure to its null values, SSPUT
uses token maps to set the maximum field version in the SPI message header for use
in version compatibility checking, and SSGET uses token maps to truncate or pad the
corresponding structure in the buffer to match the value expected by the caller.
The maximum field version in a token map is the most recent version associated with
any of the fields defined in the map. When an application adds an extensible structured
token to a buffer, the SPI procedure SSPUT updates the maximum field version (ZSPI-
TKN-MAX-FIELD-VERSION) in the message header to reflect the most recent version
of any non-null field in any extensible structured token in the buffer. (SSPUT does not
update the maximum field version when it deletes an extensible token from a message,
so following such an operation the maximum field version can actually be greater than
the most recent field version actually in the buffer.)
Only the structure described by a token map is put into a message, never the map
itself. The SSPUT procedure stores the extensible structured token in the buffer as a
typical token with a token type of ZSPI-TYP-STRUCT (token data type ZSPI-TDT-
STRUCT and token length 255) and a token number that matches the number of the
corresponding map.
Null Values
Every field in an extensible structured token is assigned a null value as part of its DDL
structure definition. As a result, any field not assigned a value by a program contains a
known value, and the message recipient can determine whether the sender assigned a
value to a field. The null values for a structure are recorded in the corresponding token
ZPWY-MAP-DEF-PATHWAY An extensible structure containing parameters for
Pathway system configuration
ZFUP-MAP-LOAD-KEYSEQ-OPTS An extensible structure containing options for key-
sequenced destination files for the FUP LOAD
command
ZX25-MAP-INFO-SU An extensible structure containing subdevice
information returned by X25AM