Pathway/iTS Management Programming Manual

SPI Programming Considerations
NonStop Pathway/iTS Management Programming Manual—426749-002
3-19
Building and Sending a Command Message
subsystems if you include the ZSPI-TKN-MAXRESP token with a value not equal to
zero.
Building and Sending a Command Message
The following subsections summarize the steps your application must take to create
and send SPI commands. These summaries are followed by subsystem-specific
programming considerations for the Pathway subsystem.
For more information on creating and sending SPI commands and responses, see the
SPI Programming Manual.
Summary of Steps
The following is a summary of the steps your application must take to build and send a
command message to the Pathway subsystem:
1. Declare a buffer of appropriate size. The constant ZPWY-VAL-BUFLEN designates
the buffer length you should use for Pathway requests.
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 COBOL, or a #INPUTV or #OUTPUTV built-in function in TACL).
Note. Always initialize an extensible structured token that is to appear in a command by using
the SPI procedure SSNULL. This procedure ensures that every field of the token is initialized
to its null value. Initializing each field to a null value is important because an operation will be
performed if a field contains a value other than its null value. For example, in the ALTER TCP
command, if a field of the extensible structured token that describes the TCP 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.