When coding your own interactive program to process SQL statements, you may want to code a cancel exit. The ISQL CANCEL command is an example of using a cancel exit. Specifically, it allows you to stop an in-progress command or logical unit of work. When a cancel exit is taken, the database manager stops processing the current SQL statement, and does a ROLLBACK WORK RELEASE for the user who issued the cancel request.
The Online Resource Adapter provides the user cancel exit primarily to allow online applications to perform a CANCEL function. When it would be appropriate to cancel SQL requests (for example, while waiting for an XPCC link or an SQL request), the resource adapter gives control to the user cancel exit. This cancel exit can then do a CICS wait on ECBs pointed to by the RMWL for normal processing to complete or for the terminal operator to request a cancel.
Once posted, the exit can then set the appropriate post-code in the RMARPC field and return to the Online Resource Adapter, which interrogates the post-code and takes the corresponding action.
+---------------------General-Use Programming Interface----------------------+
Macro ARIRCAN is a General-Use programming interface. General-Use programming interface is defined in Programming Interface Information.
For the convenience of CICS/VSE user transactions to provide a cancel exit, an assembler language macro is provided to generate the RDIIN set exit call. The format of the macro is:
ARIRCAN RMARPTR = addr where RMARPTR = addr gives the address of a pointer to the RMAR.
Output from this macro with the RMARPTR operand is an RDIIN, type 165 containing the RMARPTR address in field RDIVPARM. (For more information on the RDIIN, see the DB2 Server for VSE & VM Diagnosis Guide and Reference manual.) Also generated is a call to ARIPRDI, which when executed invokes the Online Resource Adapter to perform the Set Exit function.
For the ARIRCAN macro above, the following is required:
To use the cancel exit for cancel support, an interactive application would need to:
If your cancel exit is to take advantage of 31-bit addressing, you must set the high order bit of the cancel exit entry point to '1'.
When the online support invokes the cancel exit pointed to by RMARXP, R1 points to a PLIST, the first word of which points to the RMAR. Some actions that the exit might perform are:
This control block is used for EXEC RDIIN set or reset user wait exit requests. An A within the field description indicates that the field is set by the application. An R indicates that the resource adapter sets the field.
For this type of request, the following is applicable in the RDIIN structure.
RESET has two functions: it allows an application to specify a new exit pointer, and it allows for turning off the exit linkage. For each of these functions, RDICALL=R. If RMARXP is not 0, RMARXP is taken as a new exit pointer. If RMARXP is 0, the resource adapter pointer to the RMAR is nullified.
When an exit has been established, RMLORMAR contains the pointer to RMAR. When the online support invokes an exit, register 1 points to a PLIST, the first work of which points to RMAR.
Figure 114. Online Resource Adapter Asynchronous Request (RMAR)
(1) 0: Resource adapter should continue
4: Reserved
8: Resource adapter should cancel
Others: Reserved
(2) See "RMAR flags" that follows.
RMAR Flags
OFFSET FIELD NAME BITS MEANING
36(24) RMARCNTL
RMARWAIT 1... .... Tells ARIRSEND to use the
wait exit.
0... .... Tells ARISEND to not exit
(because call is an EXEC
RDIIN PTC or EXEC SQL
COMMIT/ROLLBACK WORK (R)
RMARDSPR .1.. .... Tells RMAPI to do a
ROLLBACK via DFHSP. Set by
ARIRSEN when the attempt
to clear did not work
because processing already
finished.
..xx xxxx Reserved. Binary zeros (R)
+------------------End of General-Use Programming Interface------------------+