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

SPI Internal Structures
SPI Programming Manual—427506-006
C-2
Standard Part of Header
not implemented as true tokens—they are identified in the buffer by their positions
rather than by their token codes. However, application programs and subsystems you
write retrieve and change the values of header tokens using SSGET and SSPUT as if
they were true tokens.
Standard Part of Header
The first data structure in the buffer contains the standard part of the header. This
structure contains information that is common to all SPI buffers. For example:
STRUCT ZSPI^DDL^STDHDR^DEF(*);
BEGIN
INT Z^MSGCODE; ! -28
INT Z^BUFLEN; ! Buffer length in bytes
INT Z^OCCURS; ! # bytes in rest of buffer
STRUCT Z^SSID; ! Subsys ID used w/SSINIT
BEGIN
INT Z^SSOWNER[0:3]; ! Subsystem owner
INT Z^SSNUM; ! Subsystem number
INT Z^SSVERSION; ! Subsystem version
END;
INT Z^XSUM; ! Buffer checksum word
INT Z^MAX^FIELD^VERSION; ! Maximum field version
INT Z^FLAGS; ! Flag word
STRUCT Z^FLAG = ZFLAGS;
BEGIN
UNSIGNED(1) Z^XSUM; ! .<0> = Checksum flag
BIT_FILLER 11; ! .<1:11> = Reserved
UNSIGNED(4) Z^VERSION; ! .<12:15> = SPI version
END;
END;
The first field, called Z-MSGCODE, is a signed integer whose value is always -28; this
number identifies the message as an SPI buffer. Z-BUFLEN is an unsigned integer
field whose value is the maximum buffer length—that is, the length in bytes of the
entire buffer as declared. Z-OCCURS is an unsigned integer included to facilitate the
declaration of COBOL I/O buffers.
As programs using the SPI procedures see it, the remaining portion of the buffer
contains tokens. However, the declared length of the buffer might not always be filled
with token information. The used length of the buffer is the length in bytes of the
currently used portion. Programs can call the SSGET procedure with the token code
ZSPI-TKN-USEDLEN to get the used length.
Programs should call the SPI procedures to perform all operations on the buffer; they
should not attempt to modify the buffer directly. The SPI procedures return an error if a
program attempts to modify some parts of the buffer directly. Although programs can
modify the Z-BUFLEN field, it is recommended that they not do so, but instead call
SSPUT with the token code ZSPI-TKN-RESET-BUFFER to reset the maximum buffer
length when they receive an SPI buffer from another process.