SPI Programming Manual (G06.24+, H06.03+, J06.03+)
General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-37
Checking for Command Cancellation
The method described here is not the only valid approach, but it does illustrate the
functions that should be performed.
Checking for Command Cancellation
As described in Canceling Commands on page 5-14, an application can use the file-
system CANCEL or CANCELREQ procedure to cancel command requests issued to
your subsystem.
Servers do not have to take any special action. A server can continue processing a
command that has been canceled and issue a response for it. The file system
automatically discards the response if the corresponding command has been
canceled. The only negative consequence is that the server might be slower than it
could be in responding to new commands if it is busy working on ones that have been
canceled.
Servers can learn whether commands they have accepted have been canceled by
using the MESSAGESTATUS procedure or SETMODE 80. If your server wishes to
check on a single command, it can call MESSAGESTATUS and pass it the
tag of the
command; MESSAGESTATUS returns a value indicating whether that command has
been canceled. If your server is handling many different commands at once (often true
of a multithreaded server), it can call SETMODE 80 and ask the file system to send it
all interprocess CANCEL messages on commands issued to the server. For more
detailed information about these features, see the
Guardian Procedure Calls
Reference Manual
.
It is strongly recommended that servers implementing commands that can incur
significant processing delays, such as waiting for asynchronous events, doing I/O, and
so on, include checks at appropriate points during the execution of the command (and
during periods of waiting for I/O completions, if practical) to see whether the command
has been canceled. If the server discovers that its command has been canceled, it
should stop processing the command and clean up after it with as little further
processing as possible, consistent with maintaining the integrity of the server and the
objects it controls.
Only check for cancellation when it is reasonable and possible. Do not check for
cancellation when:
•
The command is typically of short duration and can be delayed only by factors that
would also prevent processing of the cancellation (such as lack of CPU or memory
resources).
•
The command, after it is started, must proceed to completion and cannot be safely
interrupted (such as PUP SPARE of an online disk).
•
The only possible delay is due to an operation that must be done in a waited
manner (such as invoking the SORT library or performing I/O from COBOL). If a
command involves several such operations, a check for cancellation between them
would be appropriate unless condition 2 applies.