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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-38
Using SSPUT to Place Lists in the Buffer
Servers that do not otherwise need to support command cancellation need not be
aware of command cancellation at all.
If a subsystem needs to provide a way for a requester to cancel a command and learn
something about how much the command did before it was canceled, that subsystem
must implement an additional form of cancellation.
Using SSPUT to Place Lists in the Buffer
To place a list in the buffer:
1. A program calls SSPUT to put the beginning token—ZSPI-TKN-DATALIST, ZSPI-
TKN-ERRLIST, ZSPI-TKN-SEGLIST, or ZSPI-TKN-LIST—in the buffer.
2. SSPUT adds that list token to the buffer and selects the list, so that subsequent
SSPUT calls place the specified tokens inside the list.
3. To end the list, the program calls SSPUT with ZSPI-TKN-ENDLIST.
4. SSPUT adds the ZSPI-TKN-ENDLIST token to the buffer, pops out of the list so
that the list is no longer selected, and sets the current-token pointer to the list
token that begins the list.
Your program can initialize the current position to the beginning of the currently
selected list by using ZSPI-TKN-INITIAL-POSITION with a token value of ZSPI-VAL-
INITIAL-LIST (-1). If no list is currently selected, SSPUT sets the position to the
beginning of the buffer.
This pseudocode example shows how a sequence of SSPUT operations can be used
to build a response buffer containing lists. It contains two data lists and one error list,
the latter enclosed within the second data list.
The same response tokens (TKN-A and TKN-B) appear in both response records, but
that they have different values (A[1] and B[1], A[2] and B[2]), representing results for
different objects.
SSINIT (BUF, LEN, SSID, ZSPI^VAL^CMD^HDR, CMD); !INITIALIZE
! BUFFER
SSPUT (BUF, ZSPI-TKN-DATALIST) !FIRST RESPONSE RECORD
SSPUT (BUF, TKN-A, A[1])
SSPUT (BUF, TKN-B, B[1])
SSPUT (BUF, ZSPI-TKN-RETCODE, STATUS)
SSPUT (BUF, ZSPI-TKN-ENDLIST) !END OF FIRST
! RESPONSE RECORD
SSPUT (BUF, ZSPI-TKN-DATALIST) !SECOND RESPONSE
! RECORD
SSPUT (BUF, ZSPI-TKN-ERRLIST) !WARNING
SSPUT (BUF, ZSPI-TKN-ERROR, ERROR) !ERROR TOKEN
SSPUT (BUF, TKN-INFO, INFO) !ERROR INFORMATION
SSPUT (BUF, ZSPI-TKN-ENDLIST) !END OF WARNING
SSPUT (BUF, TKN-A, A[2])
SSPUT (BUF, TKN-B, B[2])