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

Introduction to SPI
SPI Programming Manual—427506-006
1-7
Tokens
SPI messages are built in buffers initialized by the SSINIT procedure. The messages
contain tokens (and are sometimes called tokenized messages). The interface itself is
described as token-based. Programs use SPI procedures to format message buffers,
assign values to tokens, and put tokens into and retrieve tokens from message buffers.
An application working with an SPI message refers to a token by its symbolic name,
and does not need to be concerned 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 with it an identifying number, the data type of its value, the length of
its value, and the value itself. Some of the SPI guidelines govern how to name tokens.
Most tokens have an associated value. Programs use the SSPUT procedure to assign
a values to tokens and put the tokens into a message buffer.
The four basic token types (described in Section 2, SPI Concepts and Protocol) are:
SPI Procedures
The five basic SPI procedures used to compose and decode SPI messages are:
Three related procedures, SSPUTTKN, SSGETTKN, and SSMOVETKN, let tokens be
specified in the procedure call by value rather than by reference.
Similarly named built-ins allow access to the SPI procedures from TACL.
The SPI procedures to format and decode messages are available:
Simple Value can be a simple data item or a data structure. In either case, the type
and structure of the value are fixed for the life of the token.
Extensible
structured
Can be extended by adding fields in new releases of the server.
Zero-length Has no associated value.
Header Appears in every SPI message; has values but no corresponding token code
in the buffer.
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 buffer or performs a special operation on a
buffer, 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.