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

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-46
Checking the Context Token
•
Make the server context-sensitive and hold a snapshot of the object’s current state
in the server’s memory.
•
Take a snapshot of the object, store it in a file (called a “snapshot file”), and use
the context token to keep track of where the snapshot is stored. This solution can
be implemented in a context-free server, but the server needs to open and close
the file on each command, because there is no guarantee each command would
be sent to the same server process if there are several server processes.
A variation on this solution is to have the requester create a snapshot file into
which the server writes the information in an externally defined format. Then the
requester can read the information from the file.
In many cases, the consequences of inconsistency are not serious enough to warrant
making the extra effort involved in any of the approaches just described. But for those
cases in which consistency is important, one of these approaches probably will work.
Checking the Context Token
Your server should check the context token for consistency with the command. The
nature and extent of the tests should depend on how your server is organized and
what problems it could encounter if the context is invalid in some way. For instance, it
might be helpful to put the command number and object-type number in the context
and determine whether they match those of the new command. If the context contains
table indexes, be sure to check them against the table sizes before using them.
Take into account that a requester might send a context returned by a different release
of the server. It is not imperative that your server detect this case and return an error,
provided it does not compromise the server to accept the context from a different
version of the server. However, it is recommended that your server detect and reject
this case.
To protect against a forged context token being used to bypass security, the server
must treat the contents of the context token with as much caution as it treats command
parameters. The server must not use the context token to carry any kind of user
identification or access rights that it determined while processing the previous part of
the command, unless it can verify that the requester has not tampered with that
information. A simple approach is to have the server do any security tests from scratch
on each command. If the tests are time-consuming, you might prefer to find a way to
use the context to reduce the work on subsequent commands.
Reporting Errors
SPI servers should report errors as described in Section 2, SPI Concepts and Protocol.
Remember to define the tokens you return in responses and in error lists. If desired,
your subsystem can also define special lists using the generic-list token type, ZSPI-
TYP-LIST, with a subsystem-supplied token number.
In addition, if your subsystem encounters errors in calls to software for the NonStop
system facilities that do not have a programmatic command interface based on SPI but