SPI Common Extensions Manual

Introduction to SPI Extensions
SPI Common Extensions Manual—427508-001
1-3
SPI Message Format
implementation of these general rules. For detailed information about the SPI interface
to a particular subsystem, see the management programming manual for that
subsystem.
SPI Message Format
SPI messages have a common structure. Each message consists of a header followed
by as many tokens as necessary to convey information relevant to the message. (The
number of tokens is limited by the size of the message buffer.) To create a basic SPI
message structure, a program calls the SSINIT procedure.
SPI messages are built in specially allocated buffers. The messages contain tokens
and are sometimes called tokenized messages. The interface itself is described as
token-based. Programs use SPI procedures to allocate message buffers, assign
values to tokens, and put tokens in and retrieve tokens from message buffers. An
application working with an SPI message only needs to refer to a token’s tag. It does
not deal with the address of the token in the message buffer.
Tokens
Tokens are self-identifying data items. A token’s name indicates the function of the
token or identifies the information that the token contains. A typical token in an SPI
message carries an identifying number, the data type of its value, the length of its
value, and the value itself. Some SPI guidelines govern how tokens are named.
With few exceptions, every token has an associated value. Token names and
associated values are two of the types of data items defined in the SPI data definition
files. To place information in an SPI message, a program uses the SSPUT procedure
which assigns a value to a token and puts the token in the message buffer.
SPI Procedures
Five basic SPI procedures are used to compose and decode SPI messages:
Three related procedures, SSPUTTKN, SSGETTKN, and SSMOVETKN, let you
specify tokens in the procedure call by value rather than by reference.
SSINIT Creates a new SPI message and assigns values to selected header tokens
SSNULL Initializes the fields of an extensible structure to null values
SSPUT Either places a token in a message or performs a special operation on a
message, depending on the token specified in the procedure call
SSGET Either extracts a token from a message or retrieves information about a
message, depending on the token specified in the procedure call
SSMOVE Copies a token or group of tokens from one message buffer to another