OSI/MHS Management Programming Manual

SPI Programming Considerations for OSI/MHS
OSI/MHS Management Programming Manual—424824-001
3-8
Error Handling
requested names of objects that are of a given object type (and that fit into a single
response buffer) in a single response record.
The recommended buffer size (in bytes) for all commands sent to the OSI/MHS
subsystem is ZMHS-VAL-BUFLEN. The maximum buffer size that OSI/MHS accepts
is ZMHS-VAL-MAX-BUFLEN.
The response buffers for the INFO, LISTOPENS, RESETSTATS, STATISTICS, and
STATUS commands contain extensible structured tokens that return the requested
information.
OSI/MHS supports the use of the token ZSPI-TKN-RESPONSE-TYPE. This token
allows your application to specify which kinds of response records should be returned—
all response records (one for every object, or one for each object type for the
LISTOBJECTS command), or only those for objects on which errors or warnings
occurred. If no value is specified for this token, OSI/MHS returns all response records.
Note that for commands whose purpose is to return information (for instance, the INFO
command), you must ask for all response records if you want to receive the information
the command is intended to provide.
Error Handling
Each response returned by OSI/MHS includes a return token (ZSPI-TKN-RETCODE),
whose value indicates whether an error occurred when OSI/MHS attempted to perform
the command. An error is a serious condition that prevents the command from being
completed. If the command completed with no errors, the value of the return token is
ZCOM-ERR-OK. If the command returns an empty response record—a response record
containing no information—the value of the return token is ZCOM-ERR-EMPT-RSP.
The latter situation occurs, for instance, when an application uses ZSPI-TKN-
RESPONSE-TYPE to request only response records for objects on which errors or
warnings occurred, but the command finishes processing without any errors or warnings.
If ZSPI-TKN-RETCODE has any value other than the two just mentioned, this means
that an error occurred. In this case, OSI/MHS includes an error list in the response,
providing information about the error.
A warning reports a condition less serious than that of an error. If no errors occurred but
a warning did occur, the return token will have the value ZCOM-ERR-OK, but an error
list will appear in the response, providing information about the warning condition.
General programming considerations for handling errors and warnings reported in
responses are discussed in the SPI Common Extensions Manual. Error handling
considerations for specific commands are described along with those commands in
Section 5, Commands and Responses
. Errors defined by the OSI/MHS subsystem,
together with the contents of the error lists returned for them, are described in
Appendix A, Errors and Error Lists. OSI/MHS can also return ZCOM-defined errors,
which are described in the SPI Common Extensions Manual.
Security
OSI/MHS commands are either sensitive or nonsensitive. Sensitive commands can
change the state or configuration of subsystem objects, start or stop tracing, or change
the values of statistics counters; nonsensitive commands cannot. SCP allows sensitive