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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-40
Single and Multiple Response Records per
Response
SERVER-BANNER). Your subsystem should include a similar command. Optionally,
your GETVERSION command can return additional information.
Every command sent to a NonStop Kernel subsystem returns the internal form of the
server version in ZSPI-TKN-SERVER-VERSION. However, GETVERSION is useful
because it is a safe command—one that simply returns information and makes no
changes to the state of the system or network.
Single and Multiple Response Records per Response
All NonStop Kernel subsystems support multiple response records per response
buffer, at least to the extent of recognizing the ZSPI-TKN-MAXRESP token and using it
to decide whether to enclose each response record in a data list. For consistency,
subsystems you write should do the same. However, unless an application specifically
requests multiple response records, the subsystem should return a single response
record per buffer and should not enclose it in a list.
When returning a single response record per response buffer, the server does not
need to check the size of the requester’s buffer; it can assume that the requester has a
buffer of the recommended size. However, when returning multiple response records,
the server must check the size of the requester’s response buffer, in order to determine
how many response records it can return per response message. Your server can
check the requester’s buffer size either by calling the file-system procedure
RECEIVEINFO. Checking the buffer-length field (Z-BUFLEN) in the command is not a
reliable method for determining the requester’s buffer length because the value stored
in that field is the buffer size that the requester specified in its SSINIT call for the
command, which may be smaller than the actual available buffer space.
If the requester has a larger buffer than the server has space in which to build a
response, the server should just use the space it has.
If the requester has asked for up to
n response records, but its buffer is not large
enough to hold that many, the server should simply return fewer than
n response
records—however many will fit in the space available. This action, rather than an error
response, is recommended so that a later revision of your subsystem with an
increased response-record size does not cause errors in existing applications.
If the requester has supplied a buffer smaller than needed for even one response
record, the server should ignore the size of the requester’s buffer and use the
recommended buffer size.
Defining the Context Token
If your subsystem supports response continuation, you must provide a context token in
each response message that is not the end of the response for the command. For
context-free subsystems, this context token must contain all the information the server
needs to continue processing where it left off. A response message should never
contain more than one context token.