Dynamic Plan Selection Exit Routines

Controlling Dynamic Plan Selection › Dynamic Plan Selection Exit Routines

Dynamic Plan Selection Exit Routines

CICS transactions can dynamically select a plan for execution by using a dynamic plan selection exit routine. By specifying PLNEXIT= with the TYPE=INIT statement, the same exit program can be specified for all Dynamic Plan Selection Table (DCTABPR) entries. Link edit the exit program into the CA Datacom CICS Services library that contains custom modules and is concatenated in the CICS startup JCL.

Note: To use this optional feature you must first assemble and link edit this exit. This program must be made Resident.

Specifying the Routine

To use a dynamic plan selection exit routine, specify the exit program's name in the Dynamic Plan Selection Table (DCTABPR). The three-step process is:

Code an exit program (Sample Exit Program). A sample is delivered to you.
Define the exit program to CICS by either using resource definition online (RDO) or by updating and reassembling the CICS System Definition data set (CSD).
Use the plan exit parameters you have chosen to update and reassemble the Dynamic Plan Selection Table (DCTABPR).

The exit program changes the plan that is to be allocated by changing the AUTHID value associated with the plan.

Coding the Plan Selection Exit Program

By using a plan selection exit program, the AUTHID value associated with the plan can be dynamically modified prior to command execution. The exit program is a user-written, command-level program. If each exit program is defined in the CICS tables, you can have a separate exit program for one or more Dynamic Plan Selection Table (DCTABPR) entries. For an example you can use when coding your own exit program, see Sample Exit Program. Requirements are as follows:

Must be a command-level program adhering to normal CICS conventions.
Must be written in a language supported by CICS, for example Assembler, COBOL, PL/I (and other CICS-supported languages).
Must establish addressability and update the parameter list (if necessary)—standard CICS command-level conventions are used to establish addressability to the parameter list (DFHCOMMAREA).
Can change the authorization identifier (AUTHID) value associated with the plan as passed in the exit parameter list.
Must not contain any SQL statements.
Must be terminated by an EXEC CICS RETURN command.

Exit Parameter List

A parameter list is passed to the exit program in DFHCOMMAREA when CA Datacom CICS Services links to the exit program. The following table shows the contents of the parameter list.

Name	'Hex' Offset	Data Type and Length	Description
CSPLAN	0	character 8 bytes	Plan name of the first SQL statement on entry to the exit program.
CSAUTHID	7	character 18 bytes	Current authorization ID that is invoked at execution time. This field is to be modified by the exit program to establish the use of a new plan (AUTHID plan).
CSUSER	19	character 4 bytes	User area reserved for the exit program's use. This field is preserved between calls to the exit program.

The CSUSER area function and use are intentionally general in nature. For example, CSUSER can be used to address a special user table or a CICS GETMAIN area. Each DCPLAN entry (with PLNEXIT=YES) has a unique CSUSER area.

DCTABPR Changes

Consider the following with regard to DCTABPR's PLNEXIT= parameter when you implement a dynamic plan selection routine:

When you have DCPLAN TYPE=INIT:

PLNEXIT=xxx

Specifies the name of a system-level dynamic plan exit program.
When you have DCPLAN TYPE=ENTRY:

PLNEXIT=xxx

Specifies a plan exit at the transaction level.

PLNEXIT=YES

Specifies to use the system-level plan exit.

Design Consideration for Dynamic Plan Selection

For transactions designed without CICS SYNCPOINTs, dynamic plan selection is only available once (at first SQL call) during the life of the transaction. For transactions designed with CICS SYNCPOINTs, the exit is invoked for each new logical-unit-of-work (LUW).