This section describes how to switch application plans within the same Natural session in different TP-monitor environments or in batch mode.
The following topics are covered below:
When using application plan switching, you can switch to a different application plan within the same Natural session.
If a second application plan is to be used, this can be specified by executing the Natural program NATPLAN. NATPLAN is contained in the Natural system library SYSDB2 and can be invoked either from within a Natural program or dynamically by entering the command NATPLAN at the NEXT prompt. The only input value required for NATPLAN is an eight-character plan name. If no plan name is specified, you are prompted by the system to do so.
Before executing NATPLAN, ensure that any open DB2 recovery units are closed.
Since the NATPLAN program is also provided in source form, user-written plan switching programs can be created using similar logic.
The actual switch from one plan to another differs in the various environments supported. The feature is available under Com-plete, CICS, and IMS TM MPP. When using the Call Attachment Facility (CAF) or Resource Recovery Services Attachment Facility (RRSAF), it is also available in TSO and batch environments.
In some of these environments, a transaction ID or code must be specified instead of a plan name.
Under CICS, you have the option of using either plan switching by transaction ID (default) or dynamic plan selection exit routines. Thus, by setting the field #SWITCH-BY- TRANSACTION-ID in the NATPLAN program to either TRUE or FALSE, either the subroutine CMTRNSET or the desired plan name is written to temporary storage queue.
See more information on activating plan switching under CICS in the section Steps Specific to CICS (Installing Natural for DB2).
If #SWITCH-BY-TRANSACTION-ID is set to TRUE, the subroutine CMTRNSET is invoked, which changes the current pseudo-conversational transaction ID to the one you want to switch to.
CMTRNSET is documented in the Natural system library SYSEXTP, which is invoked with the SYSEXTP system command. After calling CMTRNSET, you have to perform a terminal I/O to ensure that a new CICS transaction is used.
Using plan switching by transaction ID enables you to use existing CICS entry threads for your Natural transactions, where each transaction ID can have its own entry thread assigned.
If #SWITCH-BY-TRANSACTION-ID is set to FALSE, the desired plan name is written to a temporary storage queue for a CICS/DB2 exit routine, the NATPLAN program must be invoked before the first DB2 access. For additional information on CICS/DB2 exit routines, refer to the relevant IBM literature.
The name of the temporary storage queue is PLANxxxx, where xxxx is the CICS terminal identifier.
When running in a CICSplex environment, the CICS temporary storage queue PLANxxxx containing the plan name must be defined with TYPE=SHARED or TYPE=REMOTE in a CICS TST.
For each new DB2 unit of recovery, the appropriate plan selection exit routine is automatically invoked. This exit routine reads the temporary storage record and uses the contained plan name for plan selection.
When no temporary storage record exists for the Natural session, a default plan name, contained in the plan exit, can be used. If no plan name is specified by the exit, the name of the plan used is the same as the name of the static program (DBRM) issuing the SQL call. If no such plan name exists, an SQL error results.
In Com-plete environments, plan switching is accomplished by using the Call Attachment Facility (CAF), which releases the thread in use and attaches another one that has a different plan name.
Once the DB2 connection has been established, the same plan name continues to be used until the plan is explicitly changed with IBM's call attachment language interface (DSNALI). For additional information on the CAF interface, refer to the relevant IBM literature.
Under Com-plete, the NATPLAN program first issues an END TRANSACTION statement and then invokes an Assembler routine by using DB2SERV.
The assembler routine performs the actual switching. It issues a CLOSE request to DSNALI to terminate the DB2 connection (if one exists). It then issues an OPEN request to re-establish the DB2 connection and to allocate the resources needed to execute the specified plan.
If NATPLAN has not been executed before the first SQL call, the default plan used is the one defined in the Com-plete startup parameters. Once a plan has been changed using NDBPLAN, it remains scheduled until another plan is scheduled by NDBPLAN or until the end of the Natural session.
In an IMS MPP environment, the switch is accomplished by using direct or deferred message switching. As a different application plan is associated with each IMS application program, message switching from one transaction code to another automatically switches the application plan being used.
Since Natural applications can perform direct or deferred message switches by calling the appropriate supplied routines, use of the NATPLAN program for plan switching is optional.
NATPLAN calls the Assembler routine CMDEFSW, which sets the new transaction code to be used with the next following terminal I/O.
In the TSO and batch environments, plan switching is accomplished by using the Call Attachment Facility (CAF) or the Resource Recovery Services Attachment Facility (RRSAF). Either facility releases the thread in use and attaches another one that has a different plan name.
Below is information on:
When using the Call Attachment Facility (CAF), plan selection is either implicit or explicit. If no DB2 connection has been made before the first SQL call, a plan name is selected by DB2. If so, the plan name used is the same as the name of the program (DBRM) issuing the SQL call.
Once the DB2 connection has been established, the plan name is retained until explicitly changed by IBM's call attachment language interface (DSNALI). For additional information on the CAF interface, refer to the relevant IBM literature.
Under TSO and in batch mode, the NATPLAN program first issues an END TRANSACTION statement and then invokes an Assembler routine by using DB2SERV.
Note:
Modify the NATPLAN program by setting the #SSM field to the current
DB2 subsystem name; the default name is DB2.
The assembler routine performs the actual switching. It issues a CLOSE request to DSNALI to terminate a possible DB2 connection. It then issues an OPEN request to re-establish the DB2 connection and to allocate the resources needed to execute the specified plan.
If NATPLAN has not been executed before the first SQL call, plan selection is done by DSNALI. If so, the plan name used is the same as the name of the program issuing the SQL call. The subsystem ID used is the one specified during the DB2 installation. If no such plan name or subsystem ID exists, a Natural error message is returned.
If a static DBRM is issuing the SQL call, a plan name must exist with the same name as the one of the static DBRM.
If dynamic SQL is being used, a plan name of NDBIOMO must exist which must contain a DBRM called NDBIOMO, too. NDBIOMO is the default plan name.
Note:
To avoid any confusion concerning the chosen plan name and/or
subsystem ID, always call NATPLAN before the first SQL call.
When using the Resource Recovery Services Attachment Facility (RRSAF), plan selection is explicit.
RRSAF is used if IBM's DSNRLI interface module is linked to Natural. Once the DB2 connection has been established, the plan name is retained until explicitly changed with RRSAF. For additional information on RRSAF, refer to the relevant IBM literature.
The NATPLAN program performs the actual switching. It issues a TERMINATE IDENTIFY request to DSNRLI to terminate a possible DB2 connection. NATPLAN then issues an IDENTIFY request to re-establish the DB2 connection. This request is followed by SIGNON and CREATE THREAD requests.
In an RRSAF environment, up to four of the following parameters can be specified in NATPLAN where #PLAN is mandatory:
| Parameter | Default Value | Format | Explanation |
|---|---|---|---|
| #PLAN | None | A8 | Name of the plan used for SQL processing in the thread created (CREATE THREAD). |
| #SSM | DB2 | A4 | Subsystem ID of the DB2 server connected (IDENTIFY). |
| #COLLID | COLLID | A18 |
Only used if the first character of #PLAN is a question mark (?). Collection ID used for SQL processing in the thread created (CREATE THREAD). |
| #XID | 1 | I4 |
Indicates that a global transaction ID is used. If set to 0 (SIGNON), no global transaction ID is used. |
Example of Plan Selection with RRSAF under TSO
The example below demonstrates plan selection under TSO by using RRSAF.
NATPLAN
<ENTER>
Please enter new plan name NDBPLAN4
,SUB SYSTEM ID DB27
,COLLECTION ID
,global XID (0/1) __________1
<ENTER>
The example below demonstrates plan selection in batch mode by using RRSAF:
NATPLAN NDBPLAN4,DB27, ,1