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

SPI Concepts and Protocol
SPI Programming Manual—427506-006
2-43
Object Identification in Responses
Object Identification in Responses
A response record must contain a subsystem-defined token identifying the object that
the response record describes. This object-name token appears even if the response
contains an error list that includes the object name. The exceptions to this rule are:
•
If the response record corresponds to a command that does not have an object
name, the response record does not include an object name.
•
If the response record corresponds to a command that operates on an unnamed
object and the command includes an object-name token set to some null value
(such as all blanks), the response record contains an object name in the same
form.
•
If the response record reports an error that prevents the command from being
attempted at all, the response record does not necessarily include an object name.
•
If the response record is the empty response record sometimes needed with
continuation, the object-name token does not appear.
Return Code
Every response record contains a return code token (ZSPI-TKN-RETCODE). The
value of this token indicates whether the command completed successfully on the
object described by the response record. ZSPI-TKN-RETCODE can contain these
values:
Except in the case of an empty response, every response record that contains a
nonzero return code also contains an error list in which ZSPI-TKN-ERROR contains
the same nonzero value. This error list might also contain additional information
describing the error condition.
Suppressing Response Records
For commands that operate on more than one object, some subsystems support a
standard SPI token—the response-type token (ZSPI-TKN-RESPONSE-TYPE)—that
lets the requester specify which kinds of response records the server should return.
This kind of control is useful if an application is performing a command on a large
number of objects and is interested only in response information about objects for
which something unusual occurred (an error or a warning).
zero indicates that the command was successfully applied to the object. Such a
response record can contain error lists describing warnings or other conditions of
interest to the requester.
nonzero indicates either an empty response or that the server could not perform the
command as expected. The particular nonzero value is a subsystem-defined
error number identifying the error, or one of the errors, that the server
encountered.