SPI Programming Manual (G06.24+, H06.03+, J06.03+)

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-39
Defining Commands
SSPUT (BUF, ZSPI-TKN-RETCODE, STATUS)
SSPUT (BUF, ZSPI-TKN-ENDLIST) !END OF SECOND
! RESPONSE RECORD
SSPUT (BUF, ZSPI-TKN-CONTEXT, CONTEXT) ! CONTEXT INFORMATION
Defining Commands
After you have determined what objects your subsystem will manage, you must decide
what management services the subsystem needs to have, and then design
programmatic commands to implement those services. Most SPI interfaces need to
provide the same basic operations on their objects: creating them; altering them;
deleting them; starting, stopping, and otherwise controlling their execution; and
reporting their configuration and state. If applications will use your subsystem in
conjunction with NonStop Kernel subsystems provided by HP, HP recommends that
your programmatic commands be as consistent as possible with the corresponding
programmatic commands defined by those subsystems. Preserving consistency makes
application programming easier.
A single command can operate on a single object or, if appropriate, on multiple objects.
You must define your commands and parameters so that a single command always fits
into a buffer of the recommended size you define. (SPI does not support multiple
commands in one SPI buffer or commands continued across multiple buffers.)
Likewise, you must define your commands and recommended buffer size so that a
single response record and its associated context information always fits into a buffer
of the recommended size. SPI does not support continuation of a single response over
multiple buffers.
Ensuring that a single response record fits into a single buffer can require redefining
the command. For example, consider the conversational FUP INFO command. It can
return several different types of information: partition information, alternate-key
information, alternate-file information, extent information, statistics information, and so
on. For programmatic use, this function needs to be redefined as separate commands,
each of which returns a single type of information: INFO EXTENTS, INFO ALTKEYS,
INFO ALTFILES, INFO STATISTICS, and so on. For each of these separate
commands, a single response record (information about a single file) easily fits into a
single buffer of reasonable size.
In the example above, it would not be sufficient to simply define EXTENTS, ALTKEYS,
ALTFILES, and so on as command parameters. If an application were to specify all the
parameters, the resulting response record might overflow a single buffer, violating the
rule that a single response record must always fit into a buffer of the recommended
size.
GETVERSION Command
All NonStop Kernel subsystems include a GETVERSION command, which returns the
version number of the server in both internal form (in the header token ZSPI-TKN-
SERVER-VERSION) and displayable form (in the nonheader token ZSPI-TKN-