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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-19
Defining Extensible Structured Tokens
Defining Extensible Structured Tokens
Some restrictions on what can be done with extensible structured tokens are:
•
Any item that is inherently of variable length cannot be included as a field of an
extensible structured token. Although an extensible structured token can grow from
release to release, in any given release it must have a fixed size. You can define
such an item as a fixed-length field large enough for the maximum size plus a
separate field for the length, or you can define it as a simple token by itself.
•
An extensible structured token can be extended only by adding fields to the end of
the structure. Therefore, the grouping of the fields within an extensible structured
token must not be important to the operation of the interface. If the interface
defines any partitioning of the fields within an extensible structured token, no new
fields can be added unless they fall into the category of the group of fields that was
at the end of the original structure.
•
REDEFINES is permitted within the structure definition (DEF) for an extensible
structured token, but redefined fields have the same null value as the fields they
overlay. (See Null Values
on page 5-20.)
Subsystems should use extensible structured tokens to gather related parameters of a
command or response to reduce the number of procedure calls needed to construct a
message or interpret it. Generally, an extensible structured token should be used with
just a single command. Even if all the fields of such a structure are used by several
commands, that might not continue to be true as extensions are added in later versions
of the interface. Consider this when deciding whether to share a structure among
commands.
If an extensible structured token is used with a number of commands, when an
extension is made to the corresponding structure, look at each of the commands that
accept that token and decide how each command should treat the new fields. If a
command does not have a use for a new field, about the only options that maintain
compatibility with earlier requesters are ignoring the new field or insisting that it be null.
Insisting that a new field be null ensures that the command can be extended later to
use the value in the field without changing the behavior of a program that was
implemented since the time the new field was added.
Generally, if a command takes or returns attributes of an object, define all those
attributes as a single extensible structure, although there might be circumstances for
which it is reasonable to organize them differently. For instance, an extensible
structure must be a fixed size in any given release, so it might be better to put an
attribute of variable length in a token of its own rather than reserving a fixed field of
maximum size plus a length field for it. Similar advice applies to a repeating attribute or
a group of attributes that are not made into a subsidiary object type.
Beware of dividing attributes of a single object into a number of structures based on
some characteristic that might change in the future. For instance, it is not a good idea
to make one structure for alterable attributes and another for the remaining attributes
with the idea of using the first as the parameter to ALTER and using both as the