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

The SPI Procedures
SPI Programming Manual427506-006
3-3
Using the SPI Procedures
Using the SPI Procedures
The SPI procedures are in the standard operating-system library and can be called
through:
The tal interface directive in C (See Section 6, SPI Programming in C.)
ENTER TAL from COBOL (See Section 7, SPI Programming in COBOL.)
Corresponding built-in functions from TACL (See Section 8, SPI Programming in
TACL.)
Directly from TAL (See Section 9, SPI Programming in TAL.)
To issue a command to an SPI server, a requester first calls the SSINIT procedure,
supplying the buffer, buffer length, subsystem ID, command, and object type if needed.
SSINIT initializes the buffer, placing the supplied information in the appropriate fields of
the message header.
Before adding an extensible structured token to a message, an application must call
the SSNULL procedure to initialize the fields of the structure to null values. A program
must always call SSNULL for each extensible structure to ensure version compatibility,
even if the program explicitly sets all currently defined fields. Then the program sets
the desired fields of each structure.
The application then calls SSPUT to assign values to tokens and add the tokens to the
message.
When the message is complete, the application sends it to the server.
When the server receives the message, it calls the SSPUT procedure to reset control
information in the buffer, uses SSGET to extract relevant token values, and performs
the processing requested by the message. The server uses SSINIT to initialize a
response buffer, uses SSPUT to place a return-code token and other response tokens
in the buffer, and then returns the response message to the requester.
When it receives the response message, the requester calls SSPUT to reset the buffer,
and then uses SSGET to extract token values. The requester can retrieve token values
in any order.
In addition to their main functions, SSPUT and SSGET accept special token codes that
allow an application to retrieve or modify the values of header tokens, scan the data
portion of the buffer token by token, and perform control and positioning operations on
the buffer.
Finally, programs can use the SSMOVE procedure to copy any number of tokens from
one SPI buffer to another. This is useful when copying context information from a
continuation response to a followup command message or when forwarding error lists
from other subsystems.