TS/MP 2.5 Management Programming Manual

Previously in the ZSPIDDL file, ZSPI-DDL-CHAR8 is defined as eight ASCII characters.
ZSPI-DDL-FNAME is defined as a Guardian internal format file name, including disk name, process
name, and device name.
Throughout this manual, the type of a field is indicated wherever the field is described. Definitions
for Pathway subsystem private token and field types are in “ZPWY-DDL- Definitions” (page 53),
“ZPWY-TKN- Definitions” (page 71), and “ZPWY-MAP- Definitions” (page 75). The type names
defined by SPI (using the prefix ZSPI- ) are fully described in the SPI Programming Manual.
Data Lists and Error Lists
Responses from the Pathway subsystem can contain data lists and error lists as described in the
SPI Programming Manual.
The Pathway subsystem does not support arrays or multiple instances of tokens. The PATHMON
process never returns more than one response in a message. However, the single response can
be enclosed in a data list for consistency with other subsystems if you include the ZSPI-TKN-MAXRESP
token with a value not equal to zero.
Building and Sending a Command Message
The following subsection summarizes the steps 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
This 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 used 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, then 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 must appear in a command by using
the SPI procedure SSNULL. This procedure ensures that every field of the token is initialized to the
null value. Initializing each field to a null value is important because an operation is performed if
a field contains a value other than a 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
a 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 does not work correctly later if it is compiled with a
new version of the definition files that add new fields to the token.
Considerations for SSINIT
When setting up a call to SSINIT, you need to consider this information.
38 SPI Programming Considerations