OSI/MHS Management Programming Manual

SPI Programming Considerations for OSI/MHS
OSI/MHS Management Programming Manual—424824-001
3-6
Building and Sending a Command Message
For more information on creating, sending, retrieving and decoding SPI commands and
responses, see the SPI Programming Manual. The SPI Common Extensions Manual
provides additional information for subsystems that, like OSI/MHS, are based on the
common SPI extensions.
Building and Sending a Command Message
The following is a summary of the steps your application must take to build and send a
command message:
1. Declare a buffer of appropriate size.
2. Call the SSINIT procedure to initialize the command buffer. SSINIT sets the values
of certain header tokens, including the command, the object type, and the target
subsystem ID.
3. Call SSNULL to initialize each extensible structured token to be used in the
command.
4. Call SSPUT or SSPUTTKN to place the appropriate tokens in the buffer.
5. If you are resending a command to retrieve the next response message in a series,
call SSMOVE or SSMOVETKN to move the context token from the previous
response buffer into the command buffer.
6. Send the command message using the mechanism appropriate to your programming
language (for example, a WRITEREAD call in TAL).
The recommended buffer length in bytes for an OSI/MHS command is a predefined
value with the name ZMHS-VAL-BUFLEN.
The OSI/MHS subsystem does not support multiple commands in a single request
message. However, many of the OSI/MHS commands accept multiple object names in
one command (as many as will fit in the buffer), so a single command can operate on a
number of objects. All objects named in a command must be of the same object type.
Object-name templates (wild-card names), an implicit way of specifying more than one
object in a command, can also be used with the LISTOBJECTS command.
The command buffers for the ADD and ALTER commands contain extensible
structured tokens.
Caution. An extensible structured token that is to appear in a command should always be
initialized using the SPI procedure SSNULL. Doing this ensures that every field of the token is
initialized to its null value. This is important because an operation will be performed if a field
contains a value other than its null value. For example, in the ALTER PROFILE command, if a
field of the extensible structured token that describes the profile attributes contains a value
other than its null value, that value is assigned to the attribute corresponding to that field.
Using SSNULL is important even when your application assigns a value to every field of an
extensible structured token. Otherwise, the application will not work correctly later if it is
compiled with a new version of the definition files that add new fields to the token.