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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-36
Checking Tokens in the Command
For token maps, the example assumes that the subsys^MAP^xxxx definitions are
used to declare and initialize variables whose names are formed by adding ^V to the
end:
subsys^MAP^xxxx^V. There are, of course, other ways to make the token maps
available in the program.
Because this example focuses on scanning for tokens in the command, it does not
include error handling for errors from the SSPUT calls that build the response. Do not
overlook those errors when writing your subsystem.
The example assumes that the tokens are permitted to appear multiple times. For
those tokens that are allowed to appear only once, there is no need to subscript the
subsys^value variable with the occurrence count.
The example uses an array indexed by token number to keep track of what tokens
have appeared. If you wish, you can use individual variables rather than an array.
Using individual variables might save substantially on the amount of storage used, if
the array would contain many unused entries for tokens that are not permitted in
commands.
Here are a few more points about the example:
•
The program checks the subsystem ID returned by SSGET with NEXTTOKEN to
be sure that all the tokens are qualified by the subsystem ID for this subsystem—a
good practice. Your subsystem should not assume that is true, but should check.
•
Before calling SSGET to retrieve the value of the token, the program checks the
token code to make sure its token type matches the server’s definition (the token
type includes both the token data type and the length). For extensible structured
tokens, it checks just the token type field of the token code. The test is against
ZSPI^TYP^STRUCT, because that is the token type used in the buffer for
extensible structured tokens. For simple tokens, it checks the entire token code
against the server’s literal for the token code; doing so is somewhat easier than
determining what the value of the token-type field by itself should be.
Because the token number is supposed to identify the token uniquely, it might
appear that those extra checks would not be required. However, the server needs
to determine whether the requester’s code accidentally modifies the value of a
token code or used another subsystem’s token code.
•
To preserve version compatibility, your subsystem should always use a token map
when retrieving the value of a structured token (rather than using the simple token
code of type ZSPI-TYP-STRUCT that is stored in the buffer).
•
When an error occurs with an extensible structured token, sometimes the token-
code field in ZSPI-TKN-PARM-ERR is of type ZSPI-TYP-STRUCT, and other times
it is of type ZSPI-TYP-MAP.
•
If there are no validity checks involving more than one token, you do not need the
inter-field checks part of the program—you can do validation of a token value in
that token’s branch of the CASE statement. Checks that involve more than one
token must be done after all the tokens have been retrieved, because your
program cannot count on tokens appearing in a particular order.