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

SPI Concepts and Protocol

SPI Programming Manual—427506-006

2-7

Types of Tokens

Tokens are divided into four categories:

Simple Tokens

Tokens whose values are elementary data items or fixed structures are called simple

tokens. After they are defined, the size, data type, and structure of a simple token

cannot be changed.

These are examples of simple tokens defined by SPI or NonStop Kernel subsystems:

Extensible Structured Tokens

Extensible structured tokens are tokens whose values are structures that can be

extended by adding fields to the ends of the structures. Like a simple structured token,

an extensible structured token lets a program place multiple data items in an SPI buffer

(or to retrieve them) using a single procedure call. Unlike simple structured tokens,

extensible structured tokens allow the addition of new data fields. The version of each

field in the structure is recorded in an associated token map so that a specific version

of a program sees only those fields of the structure that are defined for that version.

Also, each field has a defined null value, which lets a process determine whether the

message originator stored a value in the field.

Version and null value information is kept in a separate structure called a token map.

The SSNULL procedure initializes extensible structures based on the information in the

corresponding map, and the SPI procedures process extensible structured tokens

through reference to the map. Token maps have names of the form

subsys-MAP-

desc.

To add an extensible structured token to a message, a program specifies the map in

the SSPUT procedure call. The procedure then places the associated structure, not the

Simple tokens Have a simple data item or fixed structure as a value

Extensible structured tokens Have an extensible structure as a value

Zero-length tokens Have no value and consist of a token code only

Header tokens Have values that reside in the SPI message header

ZSPI-TKN-RETCODE The standard SPI return token, whose value is a number

indicating command success or an error

ZCOM-TKN-SUB The subordinate objects command modifier token used by

extended SPI subsystems

ZFUP-TKN-SOURCE-FILE The file name of the source-file parameter for a FUP

command

ZSPI-TKN-ERROR A fixed structure containing a subsystem ID—itself a fixed

structure—and an error number