CICS (Customer Information Control System)

The second of the four "doors to DB2" is CICS (Customer Information Control System). CICS is a teleprocessing monitor that enables programmers to develop online, transaction-based programs. By means of BMS (Basic Mapping Support) and the data communications facilities of CICS, programs can display formatted data on screens and receive formatted data from users for further processing. A typical scenario for the execution of a CICS transaction follows :

1. The operator enters data on a terminal, including a transaction ID, and presses Enter. The data can simply be a transaction ID entered by the operator or a formatted BMS screen with the transaction ID.
   
   
2. CICS reads the data into the terminal I/O area, and a task is created.
   
   
3. CICS checks that the transaction ID is valid.
   
   
4. If the program for this transaction is not in main storage, the program is loaded.
   
   
5. The task is placed into the queue, waiting to be dispatched.
   
   
6. When the task is dispatched, the appropriate application program is run.
   
   
7. The program requests BMS to read data from the terminal.
   
   
8. BMS reads the data, and the program processes it.
   
   
9. The program requests BMS to display the data to a terminal.
   
   
10. BMS displays the data.
    
    
11. The task is terminated .
    
    

When DB2 data is accessed using CICS, multiple threads can be active simultaneously , giving multiple users concurrent access to a DB2 subsystem of a single CICS region. Contrast this functionality with the TSO environment, in which only one thread can be active for any given TSO address space.

A mechanism named the CICS Attach Facility connects CICS with DB2. Using the CICS Attach Facility, you can connect each CICS region to only one DB2 subsystem at a time. You can connect each DB2 subsystem, however, to more than one CICS region at one time, as you can see in Figure 18.22.

Figure 18.22. CICS region to DB2 subsystem relationship.

DB2 provides services to CICS via MVS TCBs. All of these TCBs reside in the CICS address space and perform cross-memory instructions to execute the SQL code in the DB2 database services address space ( DSNDBM1 ). Before you delve too deeply into the specifics of the CICS Attach Facility, you should explore the basics of CICS further.

CICS Terminology and Operation

To fully understand the manner in which CICS controls the execution of an application program, you must first understand the relationships among tasks , transactions, and programs. These three terms define separate entities that function together, under the control of CICS, to create an online processing environment.

A task is simply a unit of work scheduled by the operating system. CICS, a batch job, DB2, and TSO are examples of tasks. CICS, however, can schedule tasks under its control, much like the way an operating system schedules tasks. A CICS task , therefore, is a unit of work, composed of one or more programs, scheduled by CICS.

The purpose of a transaction is to initiate a task. A transaction is initiated by a 1- to 4-byte identifier that is defined to CICS through a control table. Generally , a one-to-one correspondence exists between CICS transactions and CICS tasks, but one transaction can initiate more than one task.

Finally, a program is an organized set of instructions that accomplishes an objective in a given unit of work. A CICS program can perform one or many CICS tasks.

CICS Tables

Older versions of CICS use tables, maintained by a systems programmer, to administer its online environment. These tables control the availability of CICS resources and direct CICS to operate in specific ways. Based on the values registered in these tables, CICS can be customized for each user site. The major tables that affect CICS-DB2 application programs are outlined in the subsections that follow.

PPT (Processing Program Table)

CICS programs and BMS maps must be registered in the PPT (Processing Program Table). If the program or map has not been recorded in the PPT, CICS cannot execute the program or use the map. This is true for all CICS programs, including those with embedded SQL. For programs, the name recorded in the PPT must be the name of the program load module as it appears in the load library.

PCT (Program Control Table)

The PCT (Program Control Table) is used to register CICS transactions. CICS reads this table to identify and initialize transactions. Therefore, all transactions must be registered in the PCT before they can be initiated in CICS.

FCT (File Control Table)

Every file that will be read from or written to using CICS operations must be registered in the FCT (File Control Table). This requirement does not apply to DB2 tables, however. The underlying VSAM data sets for DB2 table spaces and indexes do not need to be registered in the FCT before CICS-DB2 programs read from them. DB2 data access is accomplished through SQL, and the DB2 subsystem performs the I/O necessary to access the data in DB2 data sets. A CICS-DB2 program that reads any file using conventional methods (that is, non-SQL), however, must ensure that the file has been registered in the FCT before accessing its data.

RCT (Resource Control Table)

When a DB2 program will be run under CICS, an additional table called the RCT (Resource Control Table) is used to control the interface. The RCT applies only to CICS transactions that access DB2 data; it defines the manner in which DB2 resources will be used by CICS transactions. In particular, the RCT defines a plan for each transaction that can access DB2. Additionally, it defines parameters detailing the number and type of threads available for application plans and the DB2 command processor.

Other Tables

Other tables used by CICS control resource security, terminal definitions, logging and journaling, and the automatic invocation of program at CICS startup. A discussion of these tables is beyond the scope of this book.

RDO (Resource Definition Online)

As of CICS V4, the manner in which the interface between CICS and a DB2 subsystem is defined began to change. Instead of populating tables and updating the configuration using macros, a new method of changing parameters online is available. This new method is known as Resource Definition Online , or RDO . Whether you use the RCT or the RDO depends on the version of CICS that you are using:

• For CICS/ESA Version 4 (and prior releases) and CICS/TS Version 1 Release 1, the CICS-DB2 interface is defined using the RCT.

• For CICS/TS Version 1 Release 2, the CICS-DB2 interface can be defined using the RCT or using RDO.

• For CICS/TS Version 1 Release 3 and subsequent releases, the CICS-DB2 interface must be defined using RDO.

NOTE

Most shops using CICS will have already converted to using the RDO, or will need to convert soon. The most current release of CICS (circa early 2004) is CICS Transaction Server for z/OS V2.3.

The RDO is simply a new mechanism for defining the interface. It offers several benefits and it is relatively easy to migrate from using the RCT to using RDO. IBM provides a utility named DFHCSDUP that can be used to migrate RCT parameters to RDO names .

The benefits RDO provides over the RCT are:

• You can add, delete, or change RDO definitions without stopping the CCIS-DB2 connection.

• You can use wildcarding to specify groups of transactions and thereby simplify the setup of your CICS-DB2 transactions.

• The CICS-DB2 control blocks are moved above the 16MB line.

Additionally, conversion is not difficult because the RCT parameters and RDO names are similar. You can find more details about the RCT and RDO in the section "CICS-DB2 Connection Guidelines" later in this chapter.

CICS-DB2 Program Preparation

Another consideration when you're using CICS is the program preparation process. When CICS programs are prepared for execution, a step is added to the process to prepare the embedded CICS commands: the execution of the CICS command language translator (see Figure 18.23). You can think of the CICS command language translator as a precompiler for CICS commands. The CICS command language translator comments out the code embedded between EXEC CICS and END-EXEC and replaces it with standard COBOL CALL statements.

Figure 18.23. CICS/DB2 program preparation.

The rest of the program preparation procedure is essentially unchanged. One notable exception is that you must link the CICS language interface ( DSNCLI ), rather than the TSO language interface ( DSNELI ), to the load module.

When embedded CICS commands are encountered , the DB2 precompiler bypasses them, but the CICS command language translator returns warning messages. Thus, you might want to run the DB2 precompiler before running the CICS command language translator. Functionally, which precompiler is run first does not matter. Running the DB2 precompiler first, however, eliminates a host of unwanted messages and speeds up program preparation somewhat because the CICS command language translator needs to perform less work.

CICS Attach Facility

As mentioned, CICS must be attached to DB2 before any transaction can access DB2 data. This is accomplished with the CICS Attach Facility. Figure 18.24 depicts the basic operation of the CICS Attach Facility.

Figure 18.24. The CICS Attach Facility.

The CICS Attach Facility provides support for multiple transactions using multiple threads to access data in a single DB2 subsystem. CICS transactions requiring DB2 resources are routed to DB2 by DSNCLI each time an SQL statement is encountered. The routing is accomplished using the functionality of the CICS Task Related User Exit (TRUE). The TRUE formats the request for DB2 data and passes it to the CICS Attach Facility, which creates a new thread or reuses an existing one.

The following activities occur when a thread is created:

1. A DB2 sign-on is initiated, whereby the authorization ID identifying the user of the thread is established based on a parameter specified in the RCT.
   
   
2. A DB2 accounting record is written.
   
   
3. Authorization is checked for the user.
   
   
4. The executable form of the plan is loaded into memory as follows. The header portion of the SKCT is loaded into the EDM Pool, if it is not already there. This SKCT header is then copied to an executable form called a cursor table , which is also placed in the EDM Pool. (These terms are fully defined in Chapter 22, "The Table-Based Infrastructure of DB2.")
   
   
5. If VALIDATE(RUN) was specified at bind time for the plan, an incremental bind is performed. Avoid incremental binds by specifying VALIDATE(BIND) .
   
   
6. If ACQUIRE(ALLOCATE) was specified at bind time for the plan, the following occurs. Locks are acquired for all table spaces used by the plan, all DBDs are loaded into memory (EDM Pool) referenced by the plan, and all data sets to be used by the plan are opened, if they are not already open .
   
   

After the thread is created, the plan corresponding to the transaction being executed is allocated, and the SQL statement is processed . When the request for DB2 resources is satisfied, the data is passed back to the requesting CICS program through the TRUE. The thread is placed in an MVS-wait state until it is needed again. When the next SQL statement is encountered, the CICS program repeats the entire process except the thread creation because the thread has already been allocated and is waiting to be used.

When the CICS task is terminated or a CICS SYNCPOINT is issued, the thread is terminated and the following actions occur:

1. The CICS Attach Facility performs a two-phase commit, which synchronizes the updates and commits made to all defined CICS resources (for example, IMS databases, VSAM files, and sequential files) and DB2 tables. This process is described in more detail in the "Two-Phase Commit" section, later in this chapter.
   
   
2. A DB2 accounting record is written.
   
   
3. Table space locks are released.
   
   
4. The executable form of the plan is freed from the EDM Pool.
   
   
5. Memory used for working storage is freed.
   
   
6. If CLOSE(YES) was specified for table spaces or indexes used by the thread, the underlying VSAM data sets are closed (provided no other resources are accessing them).
   
   

The CICS Attach Facility is started using the DSNC STRT command, indicating the RCT to use.

The CICS attachment facility is provided on the CICS product tape starting with CICS V4. The CICS attachment that shipped on the DB2 product tape is for versions of CICS prior to V4.

The CICS attachment facility programs are named like DSN 2 xxxx for CICS V4 and subsequent releases; for prior versions of CICS the programs were named like DSN C xxxx .

CAUTION

If you switch CICS attachment facilities due to moving to CICS V4, be sure to check your CSD definitions, Program List Tables (PLTs), and CICS application programs for references to all old attachment facility programs named like DSNCxxxx , and change them to the new DSN2xxxx name.

Types of Threads

You will use the RCT or RDO to define the attachment of CICS to DB2 and to assign threads to each CICS-DB2 transaction. CICS transactions can use three types of threads to access DB2: command threads, entry threads, and pool threads.

Command threads can be used only by the DSNC command processor. If no command threads are available, pool threads are used.

Entry threads, also called dedicated threads, are associated with a single application plan. Multiple transactions can be assigned to an entry thread grouping, but each transaction must use the same application plan. Subsequent CICS transactions that use the same application plan can reuse entry threads. This can result in decreased runtime because you avoid the cost of establishing the thread.

You can define entry threads to be either protected or unprotected. A protected thread remains available for a preset time, waiting for transactions that can reuse the thread to be run. An unprotected thread is terminated upon completion unless another transaction is already waiting to use it.

Finally, if an entry thread is not available for a transaction's use, it may be diverted to the pool, where it will utilize a pool thread. Any transaction specifically defined to the pool can use the pool threads . In addition, you can define any transaction to be divertable. A divertable transaction is one defined to an entry or command thread that, when no appropriate threads are available, will be diverted to use a pool thread. A pool thread is not reusable and is always terminated when the transaction using it is finished.

You define command, entry, and pool threads by specifying the appropriate parameters in the RCT or RDO. The following list summarizes the capabilities of the thread types:

COMD	Used solely for DSNC commands.
ENTRY	Used primarily for high-volume or high-priority transactions. Entry threads can be protected, reused, or diverted to the pool.
POOL	Used primarily for low-priority and low-volume transactions. Pool threads cannot be protected and cannot be diverted. Very limited thread reuse is available with pool threads (only when the first transaction in the queue requests the same plan as the one used by the thread being released ”a rare occurrence indeed).

The next several sections discuss the specific parameters used by the two methods of configuring a DB2-CICS connection: the RCT and RDO.

The RCT Parameters

The RCT is one method to define the relationship environment between CICS transactions and DB2 plans. In essence, it defines the working environment for CICS/DB2 applications. Keep in mind, though, that it will soon be obsolete and replaced by the RDO as you move to later versions of CICS.

Each CICS region can have only one RCT active at any time. Typically, the CICS or DB2 systems programmer handles RCT changes, but application programmers, systems analysts, and DBAs should understand what is contained in the RCT. A sample RCT is shown in Listing 18.2.

Listing 18.2. A Sample Resource Control Table (RCT)

 * *    DEFINE DEFAULTS IN INIT, A COMMAND MACRO, AND A POOL MACRO *      DSNCRCT TYPE=INIT,SUBID=DB2T,SUFFIX=1,SIGNID=XXXXXX,           X             THRDMAX=22,TOKENI=YES      DSNCRCT TYPE=COMD,THRDM=2,THRDA=1,THRDS=1,TWAIT=POOL      DSNCRCT TYPE=POOL,THRDM=4,THRDA=4,PLAN=POOLPLAN * *    DEFINE AN ENTRY MACRO FOR PROTECTED THREADS *      DSNCRCT TYPE=ENTRY,TXID=TXN1,THRDM=4,THRDA=2,                  X             THRDS=2,PLAN=TXN1PLAN,TWAIT=YES,AUTH=(TXID,*,*) * *    DEFINE AN ENTRY MACRO FOR HIGH-PRIORITY UNPROTECTED THREADS *      DSNCRCT TYPE=ENTRY,TXID=(TXN2,TXN3),THRDM=2,THRDA=2,           X             THRDS=0,PLAN=MULTPLAN,TWAIT=POOL,AUTH=(TXID,*,*) * *    DEFINE AN ENTRY MACRO FOR LOW-PRIORITY UNPROTECTED THREADS *      DSNCRCT TYPE=ENTRY,TXID=TXN4,THRDM=1,THRDA=0,                  X             THRDS=0,PLAN=TXN4PLAN,TWAIT=POOL,AUTH=(TXID,*,*) * *    DEFINE AN ENTRY MACRO FOR A MENUING SYSTEM BOUND TO A *           SINGLE, LARGE PLAN *      DSNCRCT TYPE=ENTRY,TXID=(MENU,OPT1,OPT2,OPT3,OPT4),            X             THRDM=4,THRDA=4,THRDS=3,PLAN=APPLPLAN,                  X             TWAIT=POOL,AUTH=(SIGNID,*,*) * *    DEFINE AN ENTRY MACRO THAT WILL ABEND IF NO THREADS *           ARE AVAILABLE (TWAIT=NO) *      DSNCRCT TYPE=ENTRY,TXID=SAMP,THRDM=1,THRDA=1,THRDS=1,          X             PLAN=SAMPPLAN,TWAIT=NO,AUTH=(TXID,*,*) * *    DEFINE AN ENTRY THREAD FOR DYNAMIC PLAN SELECTION *      DSNCRCT TYPE=ENTRY,TXID=TXNS,THRDM=1,THRDA=1,                  X             PLNEXIT=YES,PLNPGME=DSNCUEXT,AUTH=(CONSTANT,*,*)      DSNCRCT TYPE=FINAL      END 

You can code five types of entries, known as macros, in the RCT. Each macro defines a portion of the CICS-DB2 attachment. The valid RCT TYPE entries follow:

INIT	Defines the basic parameters affecting the attachment of DB2 to CICS and the setup of defaults for threads
COMD	Defines the setup parameters for DSNC commands
ENTRY	Defines the dedicated threads
POOL	Defines the parameters for defining pool threads
FINAL	Specifies that no more RCT entries follow

Consult Tables 18.2 through 18.6 for the parameters that you can code for the RCT INIT , COMD , POOL , and ENTRY types of macros. No parameters are specified for the RCT FINAL macro.

Table 18.2. RCT INIT Macro Parameters

RCT INIT Macro Parameters
Parameter	Default	Valid Values	Description
DPMODI	HIGH	HIGH , EQ , LOW	Specifies the default for the DPMODE parameter if it is not coded on subsequent ENTRY and POOL macros.
ERRDEST	(CSMT,*,*)	Valid transient	Specifies destinations data destinations for unsolicited messages.
PCTEROP	AEY9	AEY9 , N906 , N906D	Specifies the type of processing to occur following a create thread error.
PLANI	Entry PLAN or TXID	plan name	Specifies the default name of any plan not using dynamic plan selection. If not specified, the plan name must be specified in each subsequent RCT ENTRY macro; otherwise , it will default to the transaction ID.
PLNPGMI	DSNCUEXT	- - -	Specifies the default value for the PLNPGME parameter if it is not coded on subsequent ENTRY and POOL macros for transactions using the dynamic plan selection.
PLNXTR1	193	1 to 200	Specifies the trace ID for the dynamic plan entry.
PLNXTR2	194	1 to 200	Specifies the trace ID for the dynamic plan exit.
PURGEC	(0,30)	(0,30) thru (59,59)	Specifies the purge cycle for a protected thread. The first value indicates minutes; the second indicates seconds.
ROLBI	YES	YES , NO	Specifies the default value for the ROLBE parameter if it is not coded on subsequent ENTRY and POOL macros.
SHDDEST	CSSL	Valid transient destination data	Specifies a destinations for the statistical report during CICS shutdown.
SIGNID	application name of CICS subsystem	8-character string	Specifies the authorization ID used by the CICS Attach Facility when signing on to DB2.
SNAP	A	Valid SYSOUT classes	Specifies the SYSOUT class to be used by the CICS Attach Facility for snap dumps.
STANDBY	ABEND	ABEND , SQLCODE	Indicates how the CICS Attach Facility will respond to SQL requests when it is not connected to DB2. ABEND causes the attachment to disable the TRUE when in stand by mode (usually results in AEY9 abends); SQLCODE causes a “923 or “924 SQLCODE to be issued instead of an ABEND .
STRTWT	YES	YES , NO , AUTO	Specifies action to be taken by the CICS Attach Facility during startup if DB2 is not operational. YES directs the CICS Attach Facility to wait for DB2 to come up and then attach. NO indicates that the CICS Attach Facility startup will fail. AUTO indicates that the CICS Attach Facility will be automatically restarted when DB2 is stopped and started.
SUBID	DSN	4-character DB2 ID	Specifies the DB2 subsystem to which this RCT will be attached.
SUFFIX		1 byte	Specifies an identifier for the RCT. It is the identifier x , as supplied in the DSNC STRT x command.
THRDMAX	12	Any integer	Specifies the greater than 4 absolute maximum number of threads that can be created by this Attach Facility.
TRACEID	192	Any valid CICS trace ID	Specifies a userid to be used by the CICS Attach Facility to be used for tracing.
TWAITI	YES	YES , NO , POOL	Specifies the default for the TWAIT parameter if it is not coded on subsequent ENTRY and POOL macros.
TOKENI	NO	YES , NO	Specifies the default for the TOKENE parameter if it is not coded on a subsequent ENTRY macro.
TXIDSO	YES	YES , NO	Specifies whether sign-ons are to be suppressed during thread reuse for pool threads and threads with multiple TXID s.

NOTE

The STANDBY option and the AUTO parameter of the STARTWT option are available as of CICS Transaction Server V1.1. You must specify STARTWT=AUTO to specify STANDBY=SQLCODE .

Table 18.3. RCT COMD Macro Parameters

RCT COMD Macro Parameters
Parameter	Default Value	Valid Values	Description
AUTH	(USER, TERM ,TXID)	Character string , GROUP , SIGNID , TERM , TXID , USER , USERID , * AUTH	Defines the authorization scheme to be used for the given transaction. As many as three values can be specified. The attachment facility tries to use them in the order specified from left to right. For the default values, it first tries to use the CICS sign-on ID, and then the CICS transaction ID. For a description of each AUTH value, see Table 18.6.
ROLBE	NO	YES , NO	Defines the action to be taken if this transaction will be the victim in the resolution of a deadlock. If YES is coded, a CICS SYNCPOINT ROLLBACK is issued and a -911 SQLCODE is returned to the program. If NO is coded, a CICS SYNCPOINT ROLLBACK is not issued and the SQLCODE is set to -913 .
THRDA	1	Positive integer or zero	Defines the maximum number of threads that can be connected for the transaction, group of transactions, or pool. When the limit is reached, action is taken according to the values coded in the TWAIT parameter.
THRDM	1	Positive integer or zero	Defines the absolute maximum number of threads that can ever be connected for the transaction, group of transactions, or the pool. This number must be equal to or greater than the value of THRDA . If it is greater than THRDA , you can issue the DSNC MODIFY TRANSACTION command to change the value of THRDA to a greater value but not a value greater than THRDM .
THRDS	1	Positive integer or zero	Specifies the number of protected threads. The value cannot exceed THRDA or 99 , whichever is greater.
TWAIT	YES	YES , NO , POOL *	Specifies the action to be taken when a thread is required but the limit ( THRDA ) has been reached. YES indicates that the transaction should wait until a thread is available. NO causes the transaction to abend. POOL diverts the transaction to the pool, causing a pool thread to be used.
TXID	DSNC	DSNC	Specifies the transaction ID for DB2 command threads. It should always be set to DSNC .

Table 18.4. RCT ENTRY Macro Parameters

RCT ENTRY Macro Parameters
Parameter	Default Value	Valid Values	Description
AUTH	(USER,TERM,TXID)	Character string , SIGNID , TERM , USERID , *	Defines the GROUP authorization scheme to be used for the given transaction. You can specify as many as three values. The attachment facility tries to use them in the order specified from left to right. For the default values, it tries to use first the CICS sign-on ID, and then the CICS terminal ID, and then the CICS transaction ID. For a description of each AUTH value, see Table 18.6.
DPMODE	HIGH	HIGH , EQ , LOW	Defines the dispatching priority limit that can be assigned to the task. This limit overrides the DPMODI parameter if it was coded on the INIT macro.
PLAN	TXID	Plan name	Defines the name of the plan to use for the transaction or transactions being defined. If it is not specified, the plan name defaults to the transaction ID.
PLNEXIT	NO	YES , NO	Indicates whether the dynamic plan selection will be used.
PLNPGME	DSNCUEXT	Program name	Specifies the name of the exit program used to assign a plan name when the dynamic plan selection is used. This name overrides the PLNPGMI parameter if it was coded on the INIT macro.
ROLBE	YES	YES , NO	Defines the action to be taken if this transaction will be the victim in the resolution of a deadlock. If YES is coded, a CICS SYNCPOINT ROLLBACK is issued and a -911 SQLCODE is returned to the program. If NO is coded, a CICS SYNCPOINT ROLLBACK is not issued and the SQLCODE is set to -913 .
TASKREQ	- - -	PA1-PA3 ,	This parameter is PF1-PF24 , used when a OPID , LPA , transaction will be MSRE started by a 3270 function key.
THRDA		Positive integer or zero	Defines the maximum number of threads that can be connected for the transaction, group of transactions, or pool. When the limit is reached, action is taken according to the values coded in the TWAIT parameter.
THRDM		Positive integer or zero	Defines the absolute maximum number of threads that can ever be connected for the transaction, group of transactions, or the pool. This number must be equal to or greater than the value of THRDA . If it is greater than THRDA , you can issue the DSNC MODIFY TRANSACTION command to change the value of THRDA to a greater value but not a value greater than THRDM .
THRDS		Positive integer or zero	Specifies the number of protected threads. The value cannot exceed THRDA or 99 , whichever is greater.
TWAIT	YES	YES , NO , POOL	Specifies the action to be taken when a thread is required but the limit ( THRDA ) has been reached. YES indicates that the transaction should wait until a thread is available. NO causes the transaction to abend. POOL diverts the transaction to the pool, causing a pool thread to be used.
TOKENE	NO	NO , YES	Specifies whether the CICS attachment facility will produce an accounting trace record for every transaction.
TXID	- - -	Transaction ID or list of transaction IDs	Specifies the transaction for this entry.

Table 18.5. RCT POOL Macro Parameters

RCT POOL Macro Parameters
Parameter	Default Value	Valid Values	Description
AUTH	(USER,TERM,TXID)	Character string , GROUP , SIGNID , TERM , TXID , USER , USERID , *AUTH	Defines the authorization scheme to be used for the given transaction. You can specify as many as three values. The attachment facility tries to use them in the order specified from left to right. For the default values, it tries to use first the CICS sign-on ID, the CICS terminal ID, and then the CICS transaction ID. For a description of each value, see Table 18.6.
DPMODE	HIGH	HIGH , EQ , LOW	Defines the dispatching priority limit that can be assigned to the task. This limit overrides the DPMODI parameter if it was coded on the INIT macro.
PLAN	DEFAULT	Plan name	Defines the name of the plan to use for the transaction or transactions being defined. If it is not specified, the plan name defaults to the character string DEFAULT .
PLNEXIT	NO	YES , NO	Indicates whether the dynamic plan selection will be used.
PLNPGME	DSNCUEXT	Program name	Specifies the name of the exit program used to assign a plan name when the dynamic plan selection is used. This name overrides the PLNPGMI parameter if it was coded on the INIT macro.
ROLBE	YES	YES , NO	Defines the action to be taken if this transaction will be the victim in the resolution of a deadlock. If YES is coded, a CICS SYNCPOINT ROLLBACK is issued and a -911 SQLCODE is returned to the program. If NO is coded, a CICS SYNCPOINT ROLLBACK is not issued and the SQLCODE is set to -913 .
TASKREQ	- - -	PA1-PA3 , PF1-PF24 , OPID , LPA , MSRE	This parameter is used when a transaction will be started by a 3270 function key.
THRDA	3	Positive integer or zero	Defines the maximum number of threads that can be connected for the transaction, group of transactions, or pool. When the limit is reached, action is taken according to the values coded in the TWAIT parameter.
THRDM	3	Positive integer or zero	Defines the absolute maximum number of threads that can ever be connected for the transaction, group of transactions, or the pool. This number must be the value of THRDA . If it is greater than THRDA , you can issue the DSNC MODIFY TRANSACTION command to change the value of THRDA to a greater value but not a value greater than THRDM .
THRDS		Positive integer or zero	Specifies the number of protected threads. The value cannot exceed THRDA or 99 , whichever is greater.
TWAIT	YES	YES , NO	Specifies the action to be taken when a thread is required but the limit ( THRDA ) has been reached. YES indicates that the transaction should wait until a thread is available. NO causes the transaction to abend.
TXID	POOL	Transaction ID or list of transaction IDs	Specifies the transaction for this entry.

Table 18.6. RCT AUTH Values

AUTH Value	Description
Character string	The character string specified is used for the authorization ID.
GROUP	The RACF group ID is used for the authorization ID.
SIGNID	The SIGNID specified in the INIT RCT macro is used for the authorization ID.
TERM	The CICS terminal ID is used for the authorization ID.
TXID	The CICS transaction ID is used for the authorization ID.
USER	The CICS sign-on ID is used for the authorization ID.
USERID	This value is similar to the USER option but can be extended using DSN3@SGN to work with RACF to send a secondary authid.
*	Null. You can specify this value only for the second and third values. It Indicates that no additional authorization scheme will be used.

RDO Parameters

When using RDO there are similar parameters for defining transactions as in the RCT. However, as the name implies, RDO (or Resource Definition Online) parameters are set using an online interface.

RDO uses three sets of parameters to define the DB2-CICS connection. These parameters are grouped into the following definitions:

• DB2CONN

• DB2ENTRY

• DB2TRAN

DB2CONN

The first set of parameters to understand is used to define the global attributes of the DB2-CICS connection, as well as the attributes of pool threads and command threads. These parameters are referred to as the DB2CONN definitions.

Only one DB2CONN can be installed in a CICS system at any one time. If you attempt to install a second DB2CONN , the existing DB2CONN will be discarded along with its associated DB2ENTRY and DB2TRAN definitions. The DB2CONN must be installed before any DB2ENTRY or DB2TRAN definitions can be set up.

A definition of each of the DB2CONN parameters follows. The definitions are broken up into three sections because DB2CONN is used to defined connection attributes, pool thread attributes, and command thread attributes.

Connection Attributes

The following DB2CONN parameters are used to define basic DB2-CICS connection attributes:

DB2CONN ” Specifies a name of up to eight characters used to identify this DB2CONN definition.

CONNECTERROR(SQLCODE ABEND) ” Indicates how the CICS Attach Facility responds to SQL requests when it is not connected to DB2. ABEND causes the attachment to return an AEY9 abend; SQLCODE causes a “923 SQLCODE to be issued instead of an abend.

DB2ID ” The name of the DB2 subsystem to which the CICS-DB2 attachment facility is to connect.

DESCRIPTION ” Up to 58 characters describing the resource that is being defined.

MSGQUEUE1 ” Specifies the first transient data destination to which unsolicited messages from the CICS-DB2 attachment facility are sent. The first destination cannot be blank.

MSGQUEUE2 ” Specifies a second transient data destination.

MSGQUEUE3 ” Specifies a third transient data destination.

NONTERMREL(YES NO) ” Specifies whether or not a non-terminal transaction releases threads for reuse at intermediate syncpoints.

PURGECYCLE( x,y )S ” Specifies the duration of the purge cycle for protected threads in minutes and seconds. The default is 0, 30; that is, 0 minutes and 30 seconds.

SIGNID ” Specifies the authorization ID to be used by the CICS-DB2 attachment facility when signing on to DB2 for pool and DB2ENTRY threads specified using AUTHTYPE(SIGN) .

STANDBYMODE(RECONNECT CONNECT NOCONNECT) ” Indicates that action the CICS-DB2 attachment facility will take if DB2 is not active CICS attempts to connect to DB2.

Specifying CONNECT causes the CICS-DB2 attachment facility to wait in standby mode for DB2 to become active. If the connection is made and then DB2 fails, the CICS-DB2 attachment facility terminates.

Specifying NOCONNECT causes the CICS DB2 attachment facility to terminate.

Specifying RECONNECT causes the CICS DB2 attachment facility to wait in standby mode for DB2 to become active. If DB2 subsequently fails after the connection is made, the CICS DB2 attachment facility reverts to standby mode again.

STATSQUEUE(CDB2 name) ” Specifies the transient data destination for CICS-DB2 attachment statistics that are produced when the attachment facility is shut down.

THREADERROR(N906D N906 ABEND) ” Specifies the processing that is to occur following a create thread error.

Specifying ABEND causes CICS to take a transaction dump for AD2S , AD2T , and AD2U errors. For the first error, no abend occurs; but an abend will occur for subsequent errors. The transaction must be terminated and reinitialized before another SQL request can succeed.

Specifying N906D indicates that CICS will take a transaction dump. The transaction receives a -906 SQLCODE if another SQL is issued, unless the transaction issues SYNCPOINT ROLLBACK .

Specifying N906 indicates that CICS will not take a transaction dump. The transaction receives a -906 SQLCODE if another SQL is issued, unless the transaction issues SYNCPOINT ROLLBACK .

TCBLIMIT ” Specifies the maximum number of subtask TCBs that can be attached by the CICS-DB2 attachment facility to process DB2 requests. The default is 12. The minimum number is 4 and the maximum is 2000.

Pool Thread Attributes

The following DB2CONN parameters are used to define pool thread attributes:

ACCOUNTREC(NONE TASK TXID UOW) ” Specifies the minimum amount of DB2 accounting required for transactions using pool threads.

Specifying NONE indicates that no accounting records are required for transactions using pool threads. DB2 will produce at least one accounting record for each thread when the thread is terminated.

Specifying TASK indicates that a minimum of one accounting record for each CICS task will be produced. A transaction with multiple units-of-work (UOWs) may use a different thread for each of its UOWs. This can result in an accounting record being produced for each UOW.

Specifying TXID causes an accounting record to be produced when the transid using the thread changes. Once again, there is a chance that a transaction containing multiple UOWs will use a different thread for each UOW causing an accounting record to be produced per UOW.

Specifying UOW causes an accounting record to be produced for each UOW, assuming that the thread is released at the end of the UOW.

AUTHID ” Specifies the ID that should be used for security checking when using pool threads.

AUTHTYPE(USERID OPID GROUP SIGN TERM TX) ” Specifies the type of ID that can be used for pool threads.

Specifying USERID indicates that the 1 to 8-character USERID associated with the CICS transaction is used as the authorization ID.

Specifying OPID indicates that the operator identification associated with the user of the CICS transaction is used as the authorization ID.

Specifying GROUP indicates that the 1 to 8-character USERID and the connected group name is used as the authorization ID. To use the GROUP option, the CICS system must have SEC=YES specified in the CICS system initialization table (SIT).

Specifying SIGN indicates that the SIGNID parameter of the DB2CONN is used as the resource authorization ID.

Specifying TERM indicates that the terminal identification is used as the authorization ID.

Specifying TX indicates that the transaction identification is used as the authorization ID.

DROLLBACK(YES NO) ” Specifies whether or not the CICS DB2 attachment facility should initiate a SYNCPOINT ROLLBACK if a transaction is selected as the victim of a deadlock resolution.

Specifying YES indicates that the attachment facility will issue a SYNCPOINT ROLLBACK before returning control to the application. This causes a -911 to be returned to the program.

Specifying NO indicates that the attachment facility will not issue a rollback for the transaction. This causes a -911 to be returned to the program.

PLAN ” Specifies the name of the plan to be used for pool threads.

PLANEXITNAME ”Specifies the name of the dynamic plan exit to be used for pool threads. If PLANEXITNAME is specified, PLAN may not be specified (and vice versa). The default plan exit name is DSNCUEXT .

PRIORITY(HIGH EQUAL LOW) ” Specifies the priority of the pool thread subtasks relative to the CICS main task.

Specifying HIGH indicates that subtasks will have a higher priority than the CICS main task.

Specifying EQUAL indicates that subtasks and the CICS main task will have equal priority.

Specifying LOW indicates that subtasks will have a lower priority than the CICS main task.

THREADLIMIT ” Specifies the maximum number of pool threads that can be active before requests are forced to wait or are rejected (depending on the value of the THREADWAIT parameter). The default thread limit is 3, which is also the minimum; the maximum cannot exceed the value of TCBLIMIT .

THREADWAIT(YES NO) ” Specifies whether or not transactions will wait for a pool thread or fail if the number of active pool threads reaches the THREADLIMIT .

Specifying YES causes a transaction to wait until a thread becomes available when all threads are busy.

Specifying NO causes the transaction to terminate with an error code of AD2T or AD3T .

Command Thread Attributes

The following DB2CONN parameters are used to define command thread attributes:

COMAUTHID ” Specifies the ID for the CICS-DB2 attachment facility to use for security checking when using command threads. If COMAUTHID is specified, COMAUTHTYPE may not be specified, and vice versa.

COMAUTHTYPE(USERID OPID GROUP SIGN TERM TX) ” Specifies the type of ID to be used for security checking when using command threads.

Specifying USERID indicates that the 1 to 8-character USERID associated with the CICS transaction is used as the authorization ID.

Specifying OPID indicates that the operator identification associated with the user of the CICS transaction is used as the authorization ID.

Specifying GROUP indicates that the 1 to 8-character USERID and the connected group name is used as the authorization ID. To use the GROUP option, the CICS system must have SEC=YES specified in the CICS system initialization table (SIT).

Specifying SIGN indicates that the SIGNID parameter of the DB2CONN is used as the resource authorization ID.

Specifying TERM indicates that the terminal identification is used as the authorization ID.

Specifying TX indicates that the transaction identification is used as the authorization ID.

COMTHREADLIMIT ” Specifies the maximum number of command threads that can be attached before requests overflow to the pool. The default is 1, but the value can range from 0 to 2000.

DB2ENTRY

After defining a DB2CONN , you can then define DB2ENTRY definitions. A DB2ENTRY specification can apply to one specific transaction or a group of transactions using wildcard characters. And, as we will learn in the next section, additional transactions can be associated with a DB2ENTRY by defining DBTRAN specifications.

You can install a DB2ENTRY only if you have previously installed a DB2CONN .

A definition of each of the DB2ENTRY parameters follows. The definitions are broken up into two sections because DB2ENTRY is used to select threads and control thread operations.

Thread Selection Attributes

The following DB2ENTRY parameters are used to define thread selection attributes:

DB2ENTRY ” Specifies a name of up to eight characters used to identify this DB2ENTRY definition.

TRANSID ” Specifies the transaction ID associated with the entry. Wildcards can be used to make this specification apply to multiple transactions. Additionally, more transactions can be defined for this entry by defining a DB2TRAN that refers to this DB2ENTRY . TRANSID is optional; if it is not specified all transactions are associated with a DB2ENTRY using DB2TRAN definitions instead.

Thread Operation Attributes

The following DB2ENTRY parameters are used to define thread operation attributes:

ACCOUNTREC(NONE TASK TXID UOW) ” Specifies the minimum amount of DB2 accounting required for transactions using this DB2ENTRY .

Specifying NONE indicates that no accounting records are required for transactions using threads from this DB2ENTRY .

Specifying TASK indicates that a minimum of one accounting record for each CICS task is to be produced. A transaction containing multiple UOWs can use a different thread for each UOW, resulting in an accounting record being produced for each UOW.

Specifying TXID indicates that an accounting record is to be produced when the transaction ID using the thread changes. This option applies to DB2ENTRY s that are used by more than one transaction ID. A transaction with multiple UOWs can use a different thread for each UOW, resulting in an accounting record being produced for each UOW.

Specifying UOW indicates that an accounting is to be produced for each UOW (if the thread is released at the end of the UOW).

AUTHID ” Specifies the ID to be used for security checking when using this DB2ENTRY . If AUTHID is specified, AUTHTYPE may not be specified, and vice versa.

AUTHTYPE(USERID OPID GROUP SIGN TERM TX) ” Specifies the type of ID that can be used for threads on this DB2ENTRY . The options mean the same as those specified for AUTHTYPE on a DB2CONN specification as discussed in the previous section.

DROLLBACK(YES NO) ” Specifies whether the CICS DB2 attachment should initiate a SYNCPOINT rollback in the event of a transaction being selected as victim of a deadlock resolution. The options mean the same as those specified for DROLLBACK on a DB2CONN specification as discussed in the previous section.

PLAN ” Specifies the name of the plan to be used for this entry. If PLAN is specified, PLANEXITNAME cannot be specified.

PLANEXITNAME ” Specifies the name of the dynamic plan exit to be used for this DB2ENTRY .

PRIORITY(HIGH MEDIUM LOW) ” Specifies the priority of the thread subtasks in this DB2ENTRY relative to the CICS main task.

Specifying HIGH indicates that subtasks will have a higher priority than the CICS main task.

Specifying EQUAL indicates that subtasks and the CICS main task will have equal priority.

Specifying LOW indicates that subtasks will have a lower priority than the CICS main task.

PROTECTNUM ” Specifies the maximum number of protected threads allowed for this DB2ENTRY .

THREADLIMIT ” Specifies the maximum number of threads for this DB2ENTRY that can be active before requests are forced to overflow to the pool, wait, or be rejected (depending on the value of the THREADWAIT parameter).

THREADWAIT(POOL YES NO) ” Specifies whether or not transactions should wait for a DB2ENTRY thread, terminate, or overflow to the pool when the number of active DB2ENTRY threads reach the THREADLIMIT .

Specifying POOL causes a transaction to use a thread from the pool if the maximum number of threads is reached and they are all busy. If the pool is also busy, and NO has been specified for the THREADWAIT parameter on the DB2CONN , the transaction is terminated with an AD3T error code.

Specifying YES causes a transaction to wait until a thread becomes available when all threads are busy.

Specifying NO causes the transaction to terminate with an error code of AD2P when all threads are busy.

DB2TRAN

The final RDO category for defining DB2-CICS transactions is the DB2TRAN . A DB2TRAN resource definition defines additional transactions to be associated with a particular DB2ENTRY definition. You can use DB2TRAN to enable a DB2ENTRY to have an unrestricted number of transactions associated with it, including names using wildcard characters. Multiple DB2TRAN definitions can be associated with a single DB2ENTRY definition.

You can install a DB2TRAN only if you have previously installed a DB2ENTRY . A definition of each of the DB2TRAN parameters follows:

DB2TRAN ” Specifies a one to eight character name to identify this DB2TRAN .

ENTRY ” Specifies the name of the DB2ENTRY to which this DB2TRAN definition applies.

TRANSID ” Specifies the transaction ID to be associated with the entry. If the TRANSID is not specified, it defaults to the first four characters of the DB2TRAN name. The following wildcard characters can be used:

The asterisk ( * ) character can be used to indicate one or more characters.

The plus sign ( + ) can be used in any position to indicate any single character.

Comparing the RCT and RDO

There are many similarities between the older RCT parameters and the newer RDO parameters. Before embarking on a mission to move from the RCT to RDO, take some time to examine the parameters in each method and note the differences and similarities. A quick comparison chart of the major parameters is provided in Table 18.7.

Table 18.7. RCT versus RDO: The Major Parameters

RCT Parameter	RDO Option	Description
TYPE=INIT	DB2CONN	To define connection limits and default values
TYPE=COMD	DB2CONN	To define DB2 command threads
TYPE=POOL	DB2CONN	To define threads that are not associated with a specific transaction
TYPE=ENTRY	DB2ENTRY	To define threads that are associated with specific transaction(s)
TXID	TRANSID or DB2TRAN	Transaction(s) associated with entry threads
PLAN	PLAN	DB2 plan associated with transaction(s)
AUTH	AUTHID or AUTHTYPE	Primary authid for a thread
DPMODE	PRIORITY	Relative dispatching priority for the thread TCB
THRDA	THREADLIMIT	Maximum number of threads for entry or pool
THRDS	PROTECTNUM	Number of protected threads for entry
TWAIT	THREADWAIT	Action to take when all threads for an entry are busy
TOKENE	ACCOUNTREC	Specifies when a DB2 accounting record is to be cut
ROLBE	DROLLBACK	Controls whether a SYNCPOINT ROLLBACK is issued and whether “911 or “913 is issued.
SIGNID	SIGNID	Authid used by the CICS attached for DB2 signon
STANDBY	CONNECTERROR	Specifies error to return when DB2-CICS connection is down.
THRDMAX	TCBLIMIT	Maximum number of thread TCBs for the CICS region

CICS-DB2 Connection Guidelines

The following guidelines provide helpful advice for generating an efficient CICS-DB2 connection using the RCT or RDO. This section also offers guidance on using CICS commands and features with DB2.

Migrate RCTs to RDO

If you are currently using the RCT to define your DB2-CICS connection, you will eventually have to migrate to using RDO. The RCT is being phased out and is no longer supported as of CICS/TS Version 1 Release 3. Fortunately, existing RCTs can be migrated easily to RDO resource definitions using the DFHCSDUP utility.

Use Caution Before Grouping Transactions

Grouping a set of transaction identifiers together using wildcard characters can reduce the number of DB2ENTRY and DB2TRAN definitions you will need, but this diminishes your ability to collect statistics by transaction. CICS-DB2 resource statistics are collected for each DB2ENTRY . If you want separate CICS-DB2 statistics for a specific transaction, you need to give that transaction its own definition.

Specify DB2 Subsystem ID

Which DB2 subsystem CICS connects to is controlled using the DB2ID parameter when using RDO. But this DB2ID can be overridden by specifying a DB2 subsystem on the DSNC STRT command, by a DB2ID specified on a SET DB2CONN command, or by a subsystem ID specified using INITPARM .

If you do not override the subsystem in any of these manners, the DB2ID value is used. If DB2ID is not specified the default value is blanks. This causes the connection to be attempted to the default DB2 subsystem identifier, which is DSN .

Allow for an Appropriate Number of CICS TCBs

The THRDMAX (RCT) or TCBLIMIT (RDO) parameters are used to control the maximum number of subtask TCBs that can be attached by the CICS-DB2 attachment facility to process DB2 requests. Specify this value with care. A good rule of thumb is to set the parameter to the sum of all the thread limit values, up to a limit of 2,000. For the RCT, add up all the THRDA values and for the RDO add up all the THREADLIMIT values and the COMTHREADLIMIT value.

CAUTION

If the sum of your thread limit values exceed the number of TCBs, it is possible that a task could acquire a thread and then find that there is no available TCB. This will cause the task to be suspended .

Also, when specifying a value for the maximum number of TCBs, be sure to take into account the value specified for the CTHREAD DSNZPARM system parameter. The maximum number of TCBs for the CICS-DB2 attach should not exceed the CTHREAD value.

Avoid AUTHID with RACF Authorization

Do not use AUTHID if you are using RACF (or another external security product) for some or all of your DB2 security. This is because threads using an AUTHID do not pass the required RACF access control environment element to DB2.

Instead, use AUTHTYPE with the USERID or GROUP options.

Implement Security Without Sacrificing Performance

While you're planning your security needs, keep performance in mind. If all security can be implemented with CICS transaction security, for each transaction specify AUTH=(TXID,*,*) in the RCT or use AUTHID for the RDO. In DB2, grant EXECUTE authority on the plan to the transaction name. This way, you can reduce the amount of authorization checking overhead.

Simplify Administration Using RDO Parameter Wildcarding

Consider using the wildcarding capabilities of RDO when setting up your CICS-DB2 transactions. For example, examine the following RDO specification:

 TRANSID(TX*) 

This is equivalent to the following RCT specification:

 TXID=(TX01,TX02,TX03,TX04,TX05,TX06,TX07,TX08,TX09) 

Which one is easier to code? Of course, this approach is workable only if all of the transactions can be defined the same.

Consider Protected Threads for High Volume Transactions

Protected threads can improve the performance of high-volume CICS-DB2 transactions because a new instance of a transaction might not have to wait for a thread to be created. Instead, it can reuse a previously allocated thread.

A protected thread is not terminated immediately when it is released. It is terminated only after two completed purge cycles, if it has not been reused in the meantime. Therefore, if the purge cycle is set to 30 seconds, a protected thread is purged 30 to 60 seconds after it is released. The first purge cycle after the attachment facility starts is always 5 minutes. After that the purge cycle values are applied as specified in the RDO parameters. The parameters for setting the purge cycle are PURGECYCLE (RDO) and PURGEC (RCT).

An unprotected thread is terminated when it is released (at a SYNCPOINT or at the end of the task) if there are no other transactions waiting for a thread on that DB2ENTRY . Only entry threads can be protected; pool and command threads cannot be protected.

You can control the number of protected threads using the PROTECTNUM parameter (RDS) or THRDS (RCT).

Explicitly Code a COMD Entry

When using the RCT, be sure to explicitly code a COMD entry. A command thread is generated regardless of whether it is specified in the RCT. Coding a COMD macro for command threads rather than using defaults, however, is a good idea. This way, you can track and change the parameters for command threads more easily.

Ensure a Sufficient Number of Pool Threads

Be sure to plan for an appropriate number of pool threads on the POOL entry (RCT) or using DB2CONN (RDO). The pool is used not only for threads defined as TYPE=POOL , but also for entry threads defined as TWAIT=POOL . Protected threads can also use the pool if no protected threads are available.

Use your knowledge of your transaction workflow to arrive at a reasonable number for the thread limit for pool threads. Attempt to determine the number of each of the following types of threads that will be running at one time, and use that number (plus a little buffer) for pool threads:

• Explicitly defined pool threads ( TYPE=POOL )

• Overflow threads

Favor Overflowing Entry Threads to the Pool

When you're coding the ENTRY macro (RCT), favor the use of TWAIT=POOL to avoid an excessive wait time or abends. For the RDO the same specification is accomplished by setting THREADWAIT to POOL .

Avoid specifying TWAIT=NO (RCT) or THREADWAIT(NO) (RDO) because it increases the number of abends.

Code THRDM Greater Than THRDA

When setting up the DB2-CICS attach using the RCT, code the THRDM parameter to be at least one greater than the THRDA parameter. This provides a buffer of at least one additional thread for tuning if additional entry threads are required.

Favor Rolling Back Automatically

Use ROLBE=YES (RCT) or DROLLBACK(YES) (RDO) to roll back changes automatically in the event of a deadlock or timeout. Specifying NO to ROLBE or DROLLBACK places the onus on the application program to decide whether to back out changes. Specifying YES can reduce the amount of coding needed in CICS programs.

Favor Dispatching Priorities that are Equal or High

Use DPMODE=HIGH (RCT) or PRIORITY(HIGH) (RDO) for only a few very high-priority transactions. Use DPMODE=EQ (RCT) or PRIORITY(EQUAL) (RDO) for most transactions.

Avoid DPMODE=LOW (RCT) and PRIORITY(LOW) (RDO) unless someone you hate will be using transactions assigned to those threads. You might also choose to specify a low DPMODE or PRIORITY for new transactions if your mainframe is very heavily utilized.

Matching CICS and DB2 Accounting Records

To make it easier to manage the performance of CICS-DB2 applications, it is beneficial to match DB2 accounting records with CICS accounting records. To help match CICS and DB2 accounting records, specify ACCOUNTREC(UOW) or ACCOUNTREC(TASK) in the DB2ENTRY definition when using RDO. By specifying UOW or TASK for ACCOUNTREC , the CICS LU 6.2 token is included in the DB2 trace records (in field QWHCTOKN of the correlation header).

When using the RCT, accounting records are not cut when threads are reused, unless the TOKENE=YES parameter is coded on an ENTRY macro (or TOKENI=YES is coded on the INIT macro). Failure to specify TOKENE=YES might cause your performance monitor to report multiple transactions as a single transaction. DB2 checks the token and, when the token changes, DB2 creates a new trace record.

Specifying TOKENE=YES also causes the CICS attachment facility to pass the CICS LU6.2 token to the DB2 accounting trace record. This capability is important because CICS produces accounting records at the transaction level, whereas DB2 produces accounting records at the thread level. If you include the token in the accounting records, DB2 and CICS accounting records can be easily correlated. This token is contained in the DB2 trace correlation header field ( IFCID 148 ).

Consider Coding Threads to Avoid AEY9 Abends

When using the RCT, code STARTWT=AUTO and STANDBY=SQLCODE to avoid the AEY9 abend when the CICS attachment is not available. You must be using CICS Transaction Server V1.1 or later to specify these options.

Be sure to check for “923 and “924 SQLCODEs in your application programs that use threads defined with STARTWT=AUTO and STANDBY=SQLCODE . A “923 indicates that the CICS Attachment Facility is not up; a “924 indicates that the DB2 error translator is not at a late enough level.

When using RDO, the CONNECTERROR parameter is used to control how the DB2-CICS attachment responds to SQL requests when it is not connected to DB2. Specifying CONNECTERROR(SQLCODE) causes a “923 SQLCODE to be issued instead of an AEY9 abend.

Use the Appropriate Thread Type

Table 18.8 suggests the types of threads to use for different transaction requirements. These are general rule of thumb guidelines only; define your transactions to achieve optimal performance in your environment. In general, transactions requiring high availability or throughput should have dedicated and protected threads. Low-volume or low-priority threads can be diverted to the pool.

Table 18.8. Thread Specification by the Type of Transaction

Transaction	Thread Type to Use	Other Recommendations
Very high volume
High priority	Entry	THRDM > THRDA THRDA > 3 THRDS > 1 TWAIT = POOL (or YES ) DPMODE = HIGH
Moderate to high volume
High priority	Entry	THRDM > THRDA THRDA > 0 THRDS > 0 TWAIT = POOL
Low volume
High priority	Entry	THRDM = 2 THRDA = 1 THRDS = 0 TWAIT = POOL DPMODE = HIGH
Low volume
Moderate priority	Entry	THRDM = THRDA = 1 THRDS = 0 TWAIT = POOL
Low volume
Low priority	Entry	THRDM = THRDA = THRDS = 0 TWAIT = POOL
Very low volume	Pool	THRDM > 3 THRDA > 2 TWAIT = YES

Consider specifying transactions explicitly to the pool if you cannot accurately gauge their volume and priority. You can usually get better performance by explicitly defining entry threads and specifying the appropriate parameters for the performance and importance of the transactions. Even if all of your transactions are defined as entry threads, always define the pool to allow for overflow.

Use DSNC

Use the DSNC DISPLAY STATISTICS command to monitor the CICS environment. You can find details on this command in Chapter 36.

Plan Management and Dynamic Plan Selection

In the CICS environment, multiple programs can be executed in a single task. For CICS, the task defines the unit of work. For DB2, the application plan defines the unit of work. The scope of the unit of work for these two environments must be synchronized for them to operate in harmony. DB2 provides this synchronization in two ways:

• You can bind all programs that can be initiated in a single CICS task to a single plan specified in the RCT for each transaction that can invoke any of the programs. An example was shown in Listing 18.2 for the menuing application.

• You can specify that dynamic plan selection is to be used. Listing 18.2 shows an example of this synchronization also.

Dynamic plan selection uses an exit routine, specified in the RCT by coding PLNEXIT=YES and PLNPGME=exit-routine . If using the RDO, you will code the exit routine name using the PLANEXITNAME parameter. The exit routine determines the plan that should be used for the program being run. IBM supplies a sample exit routine called DSNCUEXT with DB2. This exit routine assigns the plan name to be the same as the program name. This approach is usually adequate, but you can code exit routines to assign plan names as your installation sees fit. Exit routines cannot contain SQL statements.

The first SQL statement executed after a CICS SYNCPOINT signals to DB2 that a new plan name must be selected. When you're using dynamic plan selection, your CICS programs must heed the following rules:

• Use the CICS LINK or XCTL command to call one program from another.

• Issue a CICS SYNCPOINT before the LINK or XCTL . Otherwise, the first SQL statement in the new program receives an SQLCODE of -805 .

• Design your programs so that a complete application unit of work is completed in a single program. Failure to do so results in logical units of work that span physical units of work. Data integrity problems can result.

The second option for the synchronization of DB2 plans to CICS tasks is to create large plans consisting of the DBRMs or packages of all programs that can be called in a single CICS task. Prior to DB2 V2.3, this could not be achieved with packages, so all DBRMs had to be bound into a single plan. This approach had the following negative effects.

When a program changed, a new DBRM was created, which caused the large plan to be bound again. You could not use the REBIND command, and you had no way of simply adding or replacing a single DBRM. As the number of DBRMs added to a plan increased, the time to bind that plan increased. As the plan was being bound, execution of the CICS transactions using that plan was not permitted. Therefore, program changes effectively took the entire application offline. When dynamic plan selection or packages were used, however, only the programs being changed were unavailable.

A second negative effect was that as the plan's size increased, it used more virtual storage. Even though DB2 uses techniques to load only those portions of the plan needed to execute the SQL at hand, performance suffers somewhat as plans increase in size . When you use dynamic plan selection, however, plans are generally much smaller. When packages are used, the plan is broken into smaller pieces that the system can manage more easily.

The recommendation is to create plans using packages, not DBRMs. This technique should be easier to manage and more efficient than either large plans composed of DBRMs or dynamic plan selection. Packages, instead of DBRMs bound directly into plans, should be the standard for all DB2 shops. Yet, many shops still avoid packages because they avoid (or fear) change or simply have not had the time to convert older applications. So, if your installation has stubbornly shunned packages (or, heaven forbid , is running a version of DB2 prior to V2.3), the recommendations change. Use dynamic plan selection for very large applications. Doing so decreases downtime due to program changes. For small applications (four or fewer programs), use a large plan composed of the DBRMs of each program.

Two-Phase Commit

As I already mentioned, changes made in a CICS program are committed by the CICS SYNCPOINT command. Likewise, you can invoke the SYNCPOINT ROLLBACK command to back out unwanted changes. You code these commands as follows:

 EXEC CICS     SYNCPOINT END-EXEC. EXEC CICS     SYNCPOINT     ROLLBACK END-EXEC. 

The SQL COMMIT and ROLLBACK verbs are not valid in CICS programs. An implicit commit is performed when a CICS transaction ends with the EXEC CICS RETURN command.

When a CICS SYNCPOINT is requested in a CICS-DB2 program, a two-phase commit is performed. The commit is done in two phases because CICS must commit changes made to resources under its jurisdiction (such as changes made to VSAM files), and DB2 must control the commit for changes made with SQL UPDATE , INSERT , and DELETE statements.

Figure 18.25 shows the two-phase commit process for CICS. CICS acts as the coordinator of the process, and DB2 acts as a participant. The first phase consists of CICS informing DB2 that a SYNCPOINT was requested. DB2 updates its log but retains all locks because the commit is not complete. When the log update is finished, DB2 informs CICS that it has completed phase 1. CICS then updates its log, retaining all locks.

Figure 18.25. The CICS two-phase commit process.

CICS signals DB2 to begin phase 2, in which DB2 logs the commit and releases its locks. If successful, DB2 sends control back to CICS so that CICS can release its locks and record the success of the SYNCPOINT .

The two-phase commit process virtually ensures the integrity of DB2 data modified by CICS transactions. If changes cannot be committed in either environment for any reason, they are rolled back in both. In a connection failure or a system crash, however, the commit status of some transactions may be in doubt. These transactions are referred to as in-doubt threads. After a system failure, when DB2 and CICS are started and the connection is reestablished, most in-doubt threads are resolved automatically. If any in-doubt threads exist, you can use the RECOVER INDOUBT command to commit or roll back the changes pending for these threads.

CICS Design Guidelines

When designing CICS transactions that access DB2 data, keep the following tips, tricks, and techniques in mind.

Bind CICS Plans for Performance

When you're binding plans for CICS transactions, follow these BIND guidelines:

High volume	ACQUIRE(ALLOCATE) , RELEASE(DEALLOCATE)
All others	ACQUIRE(USE) , RELEASE(COMMIT)

Binding high-volume transactions in this manner reduces overhead by ensuring that all resources are acquired before they are accessed. Why is this so? Consider the ramifications of binding a plan for high-volume CICS transaction with RELEASE(COMMIT) . Say the transaction uses a protected thread and that thread is reused 200 times by the same transaction. Each time the transaction ends (causing a COMMIT ), DB2 would release the table space locks acquired during the course of the program, and then reacquire them again when the transaction runs again and the thread is reused ”200 times. With RELEASE(DEALLOCATE) , resources are not released until the thread is deallocated. So, the table space locks would not need to be released and reacquired 200 times as long as the purge cycle is not met and the thread keeps getting reused. This can save a significant amount of CPU ”perhaps up to 10%.

CAUTION

Be aware that using protected threads and binding with RELEASE(DEALLOCATE) can cause administrative issues. You will probably need to increase the size of your EDM pool, because utilization will increase as more pages become non-stealable due to reuse.

Additionally, rebinding plans may become difficult. You cannot rebind while the plan is in use. But the plan will be in use as long as the thread used to execute the program is allocated. So, binding your CICS-DB2 plans will likely become something that is done only during off hours.

Avoid Conditional Table Access

Additionally, high-volume transactions should eliminate (or minimize) built-in conditional table access and should be as small as possible.

Decrease the Size of Your CICS Programs

The smaller the executable load module for a CICS program, the more efficient it will be. Therefore, CICS programmers should strive to reduce the size of their code. One way to do so is to increase the amount of reuseable code. For example, modularize your program and use common modules rather than recode modules everywhere they are needed.

A second way to increase your reuseable code is to use the COBOL REDEFINES clause to reduce the number of WORKING-STORAGE variables defined by the program. For example, consider a program requiring three text variables all used by different portions of the code. The first variable is 3 bytes long, the second is 8 bytes long, and another is 15 bytes long. Consider defining them as follows:

 01  COMMON-VARS-1.     05  THREE-BYTE-VAR     PIC X(3).     05  FILLER             PIC X(12). 01  COMMON-VARS-2 REDEFINES COMMON-VARS-1.     05  EIGHT-BYTE-VAR     PIC X(8).     05  FILLER             PIC X(7). 01  COMMON-VARS-3 REDEFINES COMMON-VARS-1.     05  FIFTEEN-BYTE-VAR   PIC X(15). 

This way, you can save space. Before deciding to use this approach, however, you should consider the following factors:

• The readability of the code is reduced when you use REDEFINES .

• The program cannot use redefined variables concurrently. Ensure that any variable redefined as another variable can never be used by the program at the same time as another variable assigned for the same redefined group.

Another way to increase reuseable code is to use explicit constants in the program code to reduce the number of WORKING-STORAGE variables required. This approach can enhance performance, but it usually makes maintaining the program more difficult.

Avoid COBOL File Processing

Do not use the COBOL file processing verbs READ , WRITE , OPEN , and CLOSE to access non-DB2 data sets required by your CICS/DB2 programs. If you use these functions in a CICS program, an MVS wait results, causing severe performance degradation. Instead, use the corresponding CICS file processing services (see Table 18.9).

Table 18.9. CICS File Processing Commands

Random Access Commands
READ	Reads a specific record
WRITE	Writes a specific record
REWRITE	Updates a specific record
DELETE	Deletes a specific record
Sequential Access Commands
STARTBR	Establishes sequential positioning in the file
READNEXT	Reads the next record sequentially
Sequential Access Commands
READPREV	Reads the previous record sequentially
RESETBR	Resets positioning in the file
ENDBR	Ends sequential file access

Avoid Resource- Intensive COBOL Verbs

Avoid the following COBOL verbs and features in CICS programs because they use a large amount of system resources:

ACCEPT

DISPLAY

EXAMINE

EXHIBIT

SORT

TRACE

UNSTRING

VARIABLE MOVE

Use WORKING-STORAGE to Initialize Variables

To initialize variables, use the VALUES clause in WORKING-STORAGE rather than the MOVE and INITIALIZE statements.

Avoid Excessive PERFORM s and GOTO s

Design your programs to execute paragraphs sequentially as much as possible. The fewer PERFORM s and GOTO s you use, the better the program performance will be in CICS.

Avoid Conversational Programs

A conversational program receives data from a terminal, acts on the data, sends a response to the terminal, and waits for the terminal operator to respond. This process ties up a thread for the duration of the conversation.

Instead, use pseudo-conversational techniques for your CICS-DB2 programs. Pseudo-conversational programs appear to the operator as a continuous "conversation" consisting of requests and responses, but they are actually a series of separate tasks.

Favor Transfer Control Over Linking

Favor the use of the XCTL command over the LINK command to pass control from one program to another. LINK acquires extra storage, and XCTL does not.

Reduce the Overhead of Sequential Number Assignment

Consider using counters in main storage to assign sequential numbers. This way, you can reduce the overhead associated with other forms of assigning sequential numbers , such as reading a table containing the highest number. Remember that a rollback does not affect main storage. Therefore, rolling back a transaction can cause gaps in the numbering sequence.

AS of DB2 V8, consider using sequence objects to assign sequential numbers. Sequence objects are covered in Chapter 5.

Plan for Locking Problems

Plan for deadlocks and timeouts, and handle them accordingly in your program. If the RCT specifies ROLBE=YES or RDO specifies DROLLBACK(YES) all changes are backed out automatically and a -911 SQLCODE is returned to your program. For ROLBE=NO (RCT) or DROLLBACK(NO) (RDO), -913 is passed to the SQLCODE and automatic backout does not occur. In this case, the application program must decide whether to issue a CICS SYNCPOINT ROLLBACK to back out the changes.

Synchronize Programs and RCT/RDO Entries

You must know the RCT or RDO parameters for your transaction before coding your program. Specifically, coding NO for ROLBE (RCT) or DROLLBACK (RDO) parameters affects the program design significantly by adding a great deal of code to handle rollbacks . Also, coding NO for TWAIT (RCT) or THREADWAIT (RDO) requires additional programming to handle abends.

Place SQL As Deep in the Program As Possible

Minimize thread use by placing all SQL statements as far as possible into the transaction. A thread is initiated when the first SQL call is encountered. The later in the execution that the SQL statement is encountered, the shorter the time during which the thread is used.

Avoid DDL

Avoid issuing DDL from a CICS program. DDL execution is time intensive and acquires locks on the DB2 Catalog and DB2 Directory. Because CICS programs should be quick, they should avoid DDL.

Check the Availability of the Attach Facility

You must start the CICS Attach Facility for the appropriate DB2 subsystem before you execute CICS transactions that will run programs requiring access to DB2 data. If the CICS-to-DB2 connection is unavailable, the task abends with a CICS abend code of AEY9 .

To avoid this type of abend, consider using the CICS HANDLE CONDITION command to check whether DB2 is available, as shown in Listing 18.3. This COBOL routine tests whether the CICS-to-DB2 connection has been started before issuing any SQL.

Listing 18.3. Checking for DB2 Availability

 WORKING-STORAGE.         .         .         .     77  WS-LGTH     PIC 9(8)  COMP.     77  WS-PTR      PIC 9(4)  COMP.         .         .         . PROCEDURE DIVISION. 0000-MAINLINE.         .         .         .     EXEC CICS         HANDLE CONDITION         INVEXITREQ(9900-DB2-UNAVAILABLE)     END-EXEC.     EXEC CICS         EXTRACT EXIT         PROGRAM('DSNCEXT1')         ENTRYNAME('DSNCSQL')         GASET(WS-PTR)         GALENGTH(WS-LGTH)     END-EXEC.         .         .         . 9900-DB2-UNAVAILABLE.  Inform the user that DB2 is unavailable   Perform exception processing  

Use Debugging Tools

Use CICS debugging facilities such as EDF to view CICS commands before and after their execution.