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

General SPI Programming Guidelines
SPI Programming Manual427506-006
5-43
Context Sensitivity
context. If desired, the server can also provide more detailed information about the
error.
A server is not required to accept a context token from a different version of the server.
Requesters cannot expect to save a context token from some session with a server
and use it with another session sometime later. The server is not required to detect or
reject such long-term saving of context tokens.
When the server receives a command with context, it might find that there are no more
objects to process. (Perhaps the last one was deleted between the time the last
response was composed and the time the continuation arrived.) To cover this case, the
server must be able to build a response record that cannot be mistaken for a response
record about a particular object. The server should return a response record whose
return token contains the error number for an empty response record.
Context Sensitivity
Subsystems you write usually should be context-free servers. However, under some
circumstances you might need to write your subsystem as a context-sensitive server.
A context-sensitive server should use the context token for response continuation just
as a context-free server does, so that programs can use the same continuation
mechanism with all subsystems. In this case, the context token can contain a dummy
valueonly its presence or absence is important.
If a requester just stops sending commands, even though the last response had a
context token, a context-sensitive server might have resources tied up that are no
longer needed. Such a server might provide a null command that the application could
send to let the server know that it no longer is interested in continuing the command in
progress. Alternatively, the server could use the receipt of any command not
containing a context token as the signal that the application is no longer interested in
continuing the command in progress. The latter design would prevent the application
from issuing commands to recover from errors or to implement higher-level constructs,
so you should consider carefully whether such restrictions are necessary.
A context-sensitive server might have to make some other departures from the
guidelines given here. However, you should find ways to keep the differences as few
as possible, to maximize the consistency between subsystems.
Determining How Many Response Records Fit in a Buffer
The guidelines for continuation say that for a command that causes any change to an
object, the server should carry out the command only on objects for which responses
can be returned in the response message immediately following the action on the
objects.
Inquiry commands do not change an object, so they are not affected by this rule. If
your server runs out of buffer space while building an inquiry response, it can flush the
partial response from the buffer, construct a context token as if it never started on the
object whose response overflowed the buffer, and send that response to the requester.