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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-22
Defining Extensible Structured Tokens
field must be described as NOVERSION to let SPI’s automatic determination of
maximum field version work properly.
The first approach has the advantage that no extra field is involved. The second has
the advantage that the data type of the field is what it naturally should be.
Reset Values
Your subsystem might also want to define a set of special values that, when specified
in structured-token fields representing the attributes for an ALTER command, direct the
subsystem to reset those attributes to their default values as defined for the object. The
Pathway subsystem uses this feature.
If you implement this feature, choose reset values that are different from the null values
but are, likewise, not meaningful values for the corresponding fields. However, if your
reset values are not legitimate values for the corresponding STRUCT fields in TACL,
applications coded in TACL must use the #SETBYTES built-in to move values into
those fields, as described in Section 8, SPI Programming in TACL
.
As discussed in Section 2, SPI Concepts and Protocol
, token maps let the SPI
procedures maintain compatibility between different versions of an extensible
structured token. To define an extensible structured token and its token map, you
specify the structure in a DEF statement, and then write a TOKEN-MAP statement that
references the DEF.
When writing the DDL DEF statements that specify the structures for your extensible
structured tokens, you specify the null value for each field in an SPI-NULL clause. For
fields with no corresponding SPI-NULL clause, DDL assigns the value 255 (a field with
all bits set).
The SSNULL procedure uses token maps to set a structure to its null values. SSPUT
uses token maps to set the maximum field version (ZSPI-TKN-MAX-FIELD-VERSION)
in the SPI message header for use in version compatibility checking. Finally, SSGET
uses token maps to truncate or pad the value in the buffer to match the value expected
by the caller.
The maximum field version in a token map is the most recent release 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 in the message header, as necessary, so it reflects the most
recent version of any non-null field of any extensible structured token in the entire
buffer. (When the special SSPUT operation ZSPI-TKN-DATA-FLUSH or ZSPI-TKN-
DELETE has been performed on the buffer, the maximum field version can actually be
greater—that is, more recent—than the most recent field version still represented in the
buffer.)
The format of a token map is given in Appendix C, SPI Internal Structures
. You should
only need this information for debugging.