TMF Management Programming Manual (H06.05+)

SPI Programming Considerations for TMF
HP NonStop TMF Management Programming Manual—540140-002
3-5
Using SPI to Build Commands and Decode
Responses
Using SPI to Build Commands and Decode
Responses
The following subsections summarize the steps your application must take to create,
send, retrieve, and decode SPI messages. These summaries are followed by
subsystem-specific programming considerations for TMF.
For more information about creating, sending, retrieving and decoding SPI commands
and responses, see the SPI Programming Manual.
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 to the TMFSERVE process:
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, a READ WITH
PROMPT verb in COBOL85, or a #INPUTV or #OUTPUTV built-in function in
TACL).
The recommended buffer length in bytes for a TMF command is a predefined value
that has the name ZTMF-VAL-BUFLEN. The minimum buffer length is a predefined
value named ZTMF-VAL-MINBUFLEN, and the maximum buffer length is a predefined
value named ZTMF-VAL-MAXBUFLEN.
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 AUDITTRAIL command,
if a field of the extensible structured token that describes the audittrail 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 using a new version of the definition files that add new fields to the token.