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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-21
Defining Extensible Structured Tokens
have a negative value, 255 is a good choice; a numeric field of any length, with this
value in every byte, is always -1.)
In choosing a null value for a field, consider future possible valid values for the field
and avoid making one of those values the null value; otherwise, changes to your
subsystem might make it incompatible with existing applications.
Fields for which it is not necessary to distinguish between being absent and having a
default value can use the default value as the null value. Be cautious about doing this
because if it later becomes necessary to distinguish the cases, changing the null value
of a field introduces incompatibilities.
The data-type definitions provided by SPI for use in declaring the types of fields in
token definitions contain assumed null-value definitions. If desired, your subsystem can
explicitly override these assumptions.
The token map for an extensible structured token defines the null value for each field.
The SPI SSNULL procedure places null values in the fields of a structure, using the
token map for reference. When a program assigns a value to a field, that value
replaces the null value.
Is-Present Fields
Sometimes every possible value of a field is a legitimate one, leaving no value
available to serve as the null value. If this is true, and your subsystem needs to
distinguish whether the field was assigned a value, there are two possible solutions:
•
One solution is to choose a larger size for the field than otherwise necessary. This
makes many new values possible, one of which can serve as the null value. For
example, if a field is a 16-bit integer and all 16-bit values are valid for that field, the
field could be defined as a 32-bit integer.
•
The other solution is to include in the structure an extra field, called an is-present
field, whose only purpose is to indicate whether the field in question should be
considered present. This extra field must be of a Boolean type. For consistency
and clarity, HP recommends that the name of the extra field include the words IS-
PRESENT. For example:
.
.
02 ZSIZE-IS-PRESENT type ZSPI-DDL-BOOLEAN.
02 ZSIZE type ZSPI-DDL-INT.
.
.
With this approach, the program building an SPI buffer must store the value TRUE
in the is-present field whenever it stores a value into the field associated with it.
The significance of an is-present field is not known to DDL, so DDL still insists that
there be a null value defined for the field associated with the is-present field. Any
value will do. When the version information for the structure is described in the
token-map declaration, the token-map field that is associated with the is-present