In multiple user mode, the resource adapter provides a cancel function that gets control when the terminal operator issues the SQLHX command. The SQLHX command causes an immediate IUCV or APPC/VM sever to be done. The cancel function causes the database manager to do a ROLLBACK WORK on the current in-progress command or logical unit of work. If an explicit SQL CONNECT was done before the SQLHX command was issued, the IUCV or APPC/VM SEVER done on behalf of the SQLHX command causes the user ID to revert to the virtual machine user ID and the default application server. This is the user ID that is used for the VM implicit CONNECT support. To reestablish the desired user ID, the explicit SQL CONNECT must be reissued. An installation exit can be established that will be given control before the rollback. This installation exit can, at that time, override the SQLHX request, or choose to let the rollback processing continue. If a user enters SQLHX, is using CMS work units,
and has more than one logical unit of work that is uncommitted, only the active logical unit of work is rolled back. The suspended CMS work units maintain their current status and position.
When coding your own interactive program to process SQL statements, you can replace the values supplied by the database manager cancel function with your own.
The resource adapter provides interactive applications the ability to discontinue processing of an SQL request. If a user issues an SQL statement and wants to cancel processing on that statement, he or she can accomplish this by typing SQLHX on the terminal. The SQLHX command causes an immediate IUCV or APPC/VM SEVER to be done. This SEVER causes the running logical unit of work to be rolled back.
If an explicit SQL CONNECT was done before the SQLHX command was issued, the IUCV or APPC/VM SEVER done on behalf of the SQLHX command causes the user ID to revert to the virtual machine user ID and the default application server. This is the user ID that is used for the VM implicit CONNECT support. To reestablish the desired user ID, the explicit SQL CONNECT must be reissued.
For more information on application usage and modification of resource adapter support, see RMXC (Resource Adapter Cancel Exit Control).
This control block controls the resource adapter cancel support. It is used by the immediate command exit supplied with the resource adapter as well as by the resource adapter cancel support. 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. The resource adapter allocates storage for the RMXC, while the ARIRCAN macro provides application addressability to the RMXC.
+---------------------General-Use Programming Interface----------------------+
Macro ARIRCAN is a General-Use programming interface. General-Use programming interface is defined in Programming Interface Information.
Figure 116. Resource Adapter Cancel Exit Control (RMXC)
The resource adapter provides a cancel support for applications by using the VM immediate command extension support. During startup in the multiple user mode environment, the resource adapter establishes an immediate command of SQLHX. When this command is entered, if the resource adapter is waiting for a reply from the virtual machine, the SQL statement that is currently being processed is canceled, and the resource adapter returns to the application with a SQLCODE of -914.
If the SQLHX command is entered and the resource adapter is not waiting for a reply from the database manager, the next SQL statement that is issued is canceled with a return code of -914.
Cancel support is intended for interactive applications such as ISQL, where the terminal operator knows what is being canceled. Applications that perform preplanned SQL queries in a batch type environment can be adversely affected by the arbitrary issuing of the SQLHX command. Also, applications can require that cancel support called by a command other than SQLHX.
To provide flexibility in the resource adapter cancel support, a BAL macro is provided to allow applications to modify the basic cancel support in the following ways:
The format of the ARIRCAN macro is:
{ ARIRCAN CMDNAME=pointer-address }
{ ARIRCAN TYPE=USER }
***********************************************************************
* SAMPLE CANCEL EXIT
***********************************************************************
.
.
.
CANSAMP DS 0H
LA R3,NEWNAME LOAD ADDR OF CANCEL ALIAS
ARIRCAN CMDNAME=(R3) -
ARIRCAN TYPE=USER
GIVE NEW NAME TO SQL
.
.
.
NEWNAME DC CL8'CANCEL' CANCEL ALIAS NAME
The CMDNAME=pointer-address is the address to an 8-byte field containing an alternate command name to be used to call the resource adapter immediate command exit. The command name SQLHX remains in effect while the additional command functions as an alias to call the immediate command exit.
The TYPE=USER specifies that the user handles any cancel exit function. It causes the resource adapter to remove the immediate command exit established at startup.
Output from this macro with the CMDNAME or TYPE operands is an RDIIN, type 166. For the CMDNAME operand, the command name pointer is placed in the RDIVPARM field. A call is also made to ARIPRDI. When the call is made, the resource adapter either establishes an additional immediate command name or removes the SQLHX immediate exit, depending on the parameters specified in the ARIRCAN macro.
On successful return to the application, register 15 points to the RMXC control block. The following are required for the ARIRCAN macro:
+------------------End of General-Use Programming Interface------------------+
The CANCEL function is supported by two parts of the resource adapter:
The resource adapter invokes user exits in AMODE(31).
When the resource adapter calls ARICCOM to send a message across the path to the database manager, a CMS WAITECB macro is issued for two event control blocks (ECBs). One ECB is posted when the communication is complete. The other is posted by the immediate command process if it is called by the SQLHX command (or any other user-defined command). If the cancel ECB is posted, the resource adapter mainline (ARIRVRM) ends processing of the SQL statement by calling ARICCOM to do a CMS IUCV SEVER. This SEVER causes the database manager to rollback the processing that was taking place for the SQL statement. The resource adapter then returns to the application with a -914 SQLCODE.
The resource adapter provides for a user exit to be called from the mainline cancel process. If the RMXCCXIT field contains a nonzero value, it is assumed that a user exit routine exists. The resource adapter branches to this exit before issuing the IUCV SEVER to cause the cancel. At this point the user exit can discontinue the cancel request by setting the RMXCCONT field to N.
Register contents on entry to the user exit are:
It is assumed that registers are restored upon return from the exit.