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

SPI Concepts and Protocol
SPI Programming Manual—427506-006
2-38
Segmented Responses
from this response message tells the requester that all qualifying objects have
been processed and the response for this command is complete.
Segmented Responses
A command might generate a response record that contains so many occurrences of a
particular token or group of tokens that the record does not fit in even the largest
allowable message buffer. This can occur, for example, when a requester sends a
LISTOPENS command to a process that is supporting many openers, or when it sends
a LISTOBJECTS command to a subsystem with many defined objects. A server can
avoid truncating this type of lengthy response by breaking the response record into
segments and returning the segments in multiple messages—a method called
“response segmentation.”
In a segmented response, each response record is divided into one or more segments.
(Figure 2-12
on page 2-39 shows the structure of a segmented response.) Each
segment is an SPI data list that starts with ZSPI-TKN-DATALIST and ends with ZSPI-
TKN-ENDLIST. Each also contains ZSPI-TKN-RETCODE.
Tokens in the response are divided into a base group, which appears once, and a
repeating group, which can appear more than once. A token is included in the base
group if it appears in the response record a predefined number of times. A token is
included in the repeating group if there is no way to know, before the response is
generated, how many times the token will appear.
All base-group tokens appear in the first segment, and are not repeated in later
segments of the record.
Each instance of the repeating group is enclosed in a segment list, which starts with
ZSPI-TKN-SEGLIST and ends with ZSPI-TKN-ENDLIST. Segment lists follow the
base-group tokens. A segmented response always contains at least one segment list
(which is empty if the server has no information to return).
If a segment does not complete a response record, it contains ZSPI-TKN-MORE-DATA
with a value of TRUE, indicating that more segment lists are available. The message
containing this segment also contains ZSPI-TKN-CONTEXT so the requester can
follow the standard protocol for continuing the response. (See Continued Responses
on page 2-34.)
ZSPI-TKN-MORE-DATA does not appear in the last segment (or if it does appear, it
has the value FALSE), indicating that this segment completes the response record.
A response message can contain more than one segment. However, within the context
of a command and its continuations, all segments describing one object must be
returned before any segment describing another object. To ensure this,
ZSPI-TKN-MORE-DATA is only allowed in the last segment in a response message.
Error lists describing the object to which the command is directed can be included in a
segment. Error lists related to information in a particular segment list can be included in
that segment list.