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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-7
Resetting the Buffer
and after the current position, including any tokens within lists, by using SSPUT with
the operation ZSPI-TKN-DATA-FLUSH.
These two operations are useful mostly to server programs in preparing response
messages. For instance, a subsystem preparing a response buffer with multiple
response records can ensure that there is space for the context token by putting a
dummy context token in the buffer, then deleting the dummy token when the buffer is
filled and substituting the actual context token if the response requires continuation.
Such a subsystem typically places response records in the buffer one token at a time
until it runs out of buffer space. When this occurs, the subsystem can call SSPUT with
ZSPI-TKN-DATA-FLUSH to flush all data from the buffer beginning at the current-token
position.
Resetting the Buffer
Before calling SSGET to retrieve any tokens from the data portion of an SPI buffer
received from another process, it is recommended that your program call SSPUT to
reset the buffer using the special operation ZSPI-TKN-RESET-BUFFER. This
operation performs three actions:
•
It resets the maximum buffer length to the value specified in the call.
•
It clears the last-error information to null values (equivalent to the action of ZSPI-
TKN-CLEARERR).
•
It resets the current-token pointer to the beginning of the buffer (equivalent to the
action of ZSPI-TKN-INITIAL-POSITION with ZSPI-VAL-INITIAL-BUFFER).
If the maximum buffer length specified in the call is less than the actual number of
bytes used in the buffer as given in the header token ZSPI-TKN-USEDLEN, the
procedure returns ZSPI-ERR-NOSPACE. SPI still resets the maximum buffer length in
the SPI message header, causing subsequent SPI calls for that buffer to fail with error
ZSPI-ERR-INVBUF. This action enables a program to check for situations where data
is lost because its buffer is not large enough to hold the entire message.
Working With SSIDs
These two system procedures are available for use with the SPI procedures:
•
TEXTTOSSID converts a character string that represents a subsystem ID to the
internal format used by SPI.
•
SSIDTOTEXT converts the internal SPI format of a subsystem ID to a character
string representing the subsystem ID.
Examples of character strings that represent subsystem IDs are
“TANDEM.PATHWAY.C20” and “TANDEM.52.0.” The TEXTTOSSID and
SSIDTOTEXT procedures are described in the
Guardian Procedure Calls Reference
Manual .