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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-20
Defining Extensible Structured Tokens
parameters to ADD. If a change is made that makes a formerly unalterable attribute
alterable, problems arise. You can not move the field from the second structure to the
first, because removing a field is an incompatible change. If you leave the field where it
is, your partitioning of fields is no longer consistent.
Do not place other command parameters or results in the structures that contain object
attributes. If a group of parameters are related to each other, they can be placed
together in an extensible structured token. Unrelated parameters should be kept
separate. No firm rule explains what constitutes enough of a relationship to justify
placing parameters in the same structure. The fact that the parameters go with a given
command/object-type pair is reasonable grounds for grouping them, especially if there
is no desire to attempt grouping according to other criteria. If possible, take into
account future extensions of the interface and choose an approach to grouping that is
less likely to cause difficulties.
You can define single parameters either as simple tokens or as extensible structured
tokens that have only one field. The latter choice is recommended if there is some
chance that command extensions will add parameters that logically should be grouped
with the initial solitary parameter. Otherwise, we recommend using simple tokens.
Null Values
A requester might not always have a definite value to supply for each field of a
command parameter (or set of parameters) that is an extensible structured token. To
indicate the absence of a value for a field, the server must define a null value for the
field. SPI requires a null value to be defined for every field of an extensible structured
token.
An SPI null value in DDL is a single-byte value, defined either as a character or as an
integer from 0 to 255. The SPI procedures form the null value of each field by
concatenating the given byte value with itself as many times as necessary to fill the
data field. Because of the repetition to fill the field, the null value of the field is, in
general, not the value specified to DDL. For example, an SPI null value of 1 for a 16-bit
field gives a null value of 257 (1 << 8 + 1). Because the null values are generated by
repetition of a given byte value, only some possible values of the field can be null
values. For example, a 16-bit integer field cannot have 1 as its null value, because the
value 1 is not formed by repeating the same bit pattern in both bytes of the field.
If a field is one whose presence or absence must be detectable, the null value for the
field must be a value that is not in the legitimate range of values for the field. Fields
conveying attribute values for an ALTER command are a common example of this.
To choose appropriate null values for the fields of your structures:
1. Examine what valid, meaningful values each field can have or might have in the
future.
2. Choose as your null value some value that consists of the same byte value
repeated in every byte of the field and (if the presence or absence of the field must
be detectable) is not a valid value for the field. (If this field is never expected to