OSI/MHS Management Programming Manual

SPI Programming Considerations for OSI/MHS
OSI/MHS Management Programming Manual—424824-001
3-7
Discontinuing a Command in Progress
For the OSI/MHS subsystem, only the LISTOBJECTS PROCESS and LISTOBJECTS
SUBSYS commands support the subordinate names option (ZCOM-TKN-SUB) to select
subordinate objects.
In addition to ZCOM-TKN-OBJNAME, a few other tokens can appear more than once
in an OSI/MHS command. These tokens are identified in the command descriptions in
Section 5, Commands and Responses
.
Discontinuing a Command in Progress
In commands operating on multiple objects, OSI/MHS supports the use of the token
ZSPI-TKN-ALLOW-TYPE. This token allows an application to specify whether or not
OSI/MHS should continue immediately to the next object if it failed on the previous
one. If no value is specified for this token, OSI/MHS continues to the next object only
if no errors or warnings occurred on the current one.
When the OSI/MHS subsystem discontinues a command because of an error or warning,
it immediately sends a reply message to the application. The reply message contains a
context token. The application can choose either to resend the command including the
context token, causing OSI/MHS to proceed to the next object, or to abandon the
command.
Receiving and Decoding a Response Message
The following is a summary of the steps your application must take to receive and
decode a response message:
1. Declare a buffer of appropriate size.
2. Read the response message using the mechanism appropriate to your programming
language (for example, a WRITEREAD call in TAL).
3. Call SSGET or SSGETTKN to retrieve the values of header tokens and other tokens
from the buffer.
4. On encountering the data-list token (ZSPI-TKN-DATALIST) or the error-list token
(ZSPI-TKN-ERRLIST), make another call to SSGET or SSGETTKN to retrieve the
tokens inside the data list, including the error list if one exists.
5. On encountering a context token (ZSPI-TKN-CONTEXT), finish reading the other
tokens in the buffer. Then, optionally, use SSMOVE or SSMOVETKN to copy the
context token into the command buffer, and resend the command to get the next
message in the response.
6. Take action appropriate to the information in the response.
The OSI/MHS subsystem returns multiple response records in its responses to some
commands, as described in the SPI Programming Manual. In those cases, it returns at
most one response record in each reply message, even if the value of ZSPI-TKN-
MAXRESP is greater than 1. A response record normally contains response information
for the operation of the command on a single object. The one exception to this rule is
the LISTOBJECTS command. The response to LISTOBJECTS contains all the