DSM/Tape Catalog Management Programming Manual

SPI Programming Considerations
DSM/Tape Catalog Management Programming Manual—520481-003
3-7
The Command Buffer, Building
Information Tokens
The MEDIASRV process returns information tokens in some of the response buffers.
For example, issuing an INFO MEDIADEFS command results in MEDIASRV returning
the ZMCS-MAP-INFO-MEDIACATALOG token, which contains the requested
information.
Return Token
The response buffer always contains the return token, ZSPI-TKN-RETCODE. The
value of the ZSPI-TKN-RETCODE token is either 0 (to indicate that the command is
successful) or a nonzero error number (to indicate that the command was not
performed. The command can contain error lists in either case.
Error Lists
An error list begins with the ZSPI-TKN-ERRLIST token and ends with the ZSPI-TKN-
ENDLIST token. The information in the list becomes accessible when your program
calls SSGET to select the ZSPI-TKN-ERRLIST token.
The Command Buffer, Building
Building a request message requires you to initialize the buffer through a call to the
SSINIT procedure (specifying a command code and an object-type code). You can
also place additional tokens in the buffer through calls to the SSPUT procedure, and
there are no constraints on the order of SSPUT calls.
Although you cannot include multiple SPI commands in the same message (or
continue one SPI command across multiple messages), the DSM/TC subsystem
supports object-name templates that apply to all objects of a certain type. The DSM/TC
subsystem supports object-name templates for process names, tape volume names,
disk volume names, device names, system names, file names, and so on.
A MEDIASTV process returns the ZSPI-TKN-CONTEXT token to indicate that it has
additional response records available for a specific command. The requester must
send the original command message (and the ZSPI-TKN-CONTEXT token returned by
the MEDIASRV process) back to MEDIASRV to retrieve the additional response
records.
The DSM/TC subsystem also supports extensible structured tokens for many
commands and responses. An extensible structured token can contain fields for
attributes of an object (or objects), or parameters for controlling a command. You must
initialize an extensible structured token by calling the SPI procedure SSNULL before
assigning values to any of the fields in a structured variable. You initialize the
Note. The recommended buffer length for a command is a predefined value named ZMCS-
VAL-BUFLEN. The minimum buffer length is a predefined value named ZMCS-VAL-
MINBUFLEN, and the maximum buffer length is a predefined value named ZMCS-VAL-
MAXBUFLEN. Both byte and word length values are found in Section 4, Common Definitions
.