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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-4
Positioning the Buffer Pointers
Positioning the Buffer Pointers
Whenever SSGET retrieves a token from the data portion of the buffer, it starts at a
given position and scans the buffer until it finds the appropriate token. The SSGET
procedure maintains pointers in the SPI message header to keep track of positioning in
the buffer. As your program scans the buffer with SSGET, these pointers are
automatically updated. Special token codes can be passed to SSGET and SSPUT to
get or change the values of the pointers. SSGET uses four pointers: the current-token
pointer, the next-token pointer, the last-put-token pointer, and the current list pointer.
The current-token pointer contains the location of the last token selected with SSGET.
SSINIT sets the current -token pointer to the beginning of the buffer (immediately
following the header). Thereafter, the current-token pointer is affected implicitly by calls
to SSGET and SSMOVE and explicitly by calls to SSPUT with the special token codes
ZSPI-TKN-POSITION, ZSPI-TKN-INITIAL-POSITION, and ZSPI-TKN-RESET-
BUFFER. Other calls to SSPUT do not affect the current-token pointer.
The next-token pointer normally contains the position of the token immediately
following the current position. It points to the token that will be extracted next when
SSGET scans the buffer using the special operations ZSPI-TKN-NEXTCODE or ZSPI-
TKN-NEXTTOKEN.
The current-list pointer always points to the currently selected list, if any; if no list is
currently selected, this pointer is set to null. SPI uses the current and next pointers to
determine the starting point of a scan when SSGET is called with an index value of
zero. Positioning with lists is described later in this section.
Selecting a header token or an attribute of the current token does not change the
current-token pointer or the next-token pointer.
The special SSGET operation ZSPI-TKN-POSITION is available to retrieve the value
of the current position. A corresponding SSPUT special operation, also called ZSPI-
TKN-POSITION, restores a position previously saved using SSGET.
A position (ZSPI-TKN-POSITION) returned by SSGET remains valid until the buffer
involved is modified with the SSPUT operation ZSPI-TKN-DELETE or ZSPI-TKN-
DATA-FLUSH (described later in this section) or until a call to SSMOVE replaces a
token in the buffer. If the contents of the buffer are moved to another buffer with
SSMOVE, the position, address, or offset is still valid when used with the original
buffer, but is not valid for use with the target buffer of the SSMOVE.
When an SPI buffer is reset with SSPUT, there is no current list, and both the current
and next pointers indicate a point just prior to the first token that is not a header token:
current + next
|
v
* <token> <token> <list> <list> <token>
A similar position exists at the beginning of every list.