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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-14
Taking Action Based on the Response
Your application might be interested only in whether the command succeeded or failed,
and perhaps in a limited amount of associated information. In this case, simply check
the value of the return token and ignore any error lists. Some applications, however,
might want full information about multiple errors and warnings and pass-through errors.
The structure of error lists lets these applications retrieve more complete error
information in an organized way, focusing on one error at a time.
For each response record, your application should always:
1. Test the value of the return code token ZSPI-TKN-RETCODE.
2. Scan the response message for error lists.
If the return code is zero, the operation completed successfully, although warnings
might have occurred. If the return code is nonzero, the operation failed, and the value
of the return code identifies the error (or one of the errors, if there were more than one)
that prevented completion of the command. When this happens, additional information
about the error is contained in an error list that contains the same error number (in
ZSPI-TKN-ERROR).
Taking Action Based on the Response
After performing the checks just described, your application can read the other tokens
in the response and take whatever actions are appropriate. Such actions often include
sending other commands.
SPI requesters are expected to be tolerant of extraneous tokens in responses. Future
versions of NonStop Kernel subsystems might return newly defined tokens containing
additional information, and subsystems you write can do the same.
Canceling Commands
Requesters can use the file-system CANCEL or CANCELREQ procedure to cancel
requests that they have issued to a server. The file system does CANCEL operations
automatically in some cases. For instance, any operations outstanding on a file when it
is closed are canceled. In addition, if an AWAITIO operation is issued for a specific file
with a nonzero time limit and the time limit expires without a completion, the oldest
operation outstanding on that file is canceled.
If a message sent to a subsystem is canceled before the subsystem receives it, the
subsystem does not receive the message. If the subsystem has already received the
message, the subsystem might perform the operation (whether it does so depends on
the subsystem), but the file system discards any response.
Closing the Management Process
When your application is finished communicating with the subsystem, it should close
the management process in whatever way is appropriate to the method used to open
the process.