In releases of CICS® earlier than CICS Transaction Server for OS/390®, Version 1 Release 2, the connection between CICS and DB2® was defined in the resource control table (RCT). The RCT described the relationship between CICS transactions and DB2 resources (application plans and command processors) and was generated using the DSNCRCT macro provided by the CICS DB2 attachment facility. Versions and releases of CICS from CICS Transaction Server for OS/390, Version 1 Release 3 onwards do not support running the CICS DB2 attachment facility using the macro DSNCRCT.
If you are migrating from a CICS release that defined the CICS DB2 connection using a resource control table, you now need to define DB2 resource definitions using CICS resource definition online (RDO). Macro RCTs can still be assembled for the purpose of migrating them to the DFHCSD file only. The DSNCRCT macro is shipped with CICS to allow migration of RCT tables to the CSD. It is now wholly owned by, and incorporated in, CICS . For more information about DSNCRCT, see CICS Resource Definition Guide.
When describing parameters of the CICS DB2 connection, the names of the parameters of the RDO objects are now used, not the DSNCRCT macro parameter names. The CICS Resource Definition Guide describes which DSNCRCT macro parameter applies to which RDO parameter, and which RDO parameter applies to which DSNCRCT macro parameter.
All changes made to DB2 resource definitions installed directly from the CSD, or made by using EXEC CICS CREATE commands, are cataloged and recovered in a CICS restart. Also, the DB2 objects installed from the CSD remain installed after the CICS DB2 attachment facility is stopped.
This topic provides information to assist you with the migration process, as follows:
Using online CICS DB2 resource definition means that you do not have to shut down the interface between CICS and DB2 when adding, deleting, or changing CICS DB2 resource definitions. The benefits of using online definition for DB2 resources are discussed in the following sections:
The function of the CICS DB2 attachment facility is enhanced by using online resource definition in the following ways:
Enhancements made to the CICS DB2 attachment facility before CICS Transaction Server for OS/390, Version 1 Release 3 included:
Online CICS DB2 resource definition allows you to add, delete or change definitions without the need to shut down the interface between CICS and DB2. You are therefore provided with continuous availability.
Online CICS DB2 resource definition provides benefits to performance as follows:
Changes to the CICS DB2 attachment facility affect the operation of the facility in the following ways:
The syntax of the DSNC STRT command is DSNC STRT yyyy. Any value specified after the STRT is treated as a DB2ID. This overrides any DB2ID or DB2GROUPID specified in the DB2CONN definition. If no value is specified, the value from the installed DB2CONN is used. If you want to use group attach, do not specify a value on the DSNC STRT command.
CICS obtains the ID of the DB2 subsystem to which it connects from one of the following sources, in the order of priority shown:
You can use the DSNC STOP <QUIESCE|FORCE> command to stop the CICS DB2 attachment facility. The QUIESCE option now waits for all active transactions to complete, that is, new UOWs can start and acquire threads. In releases of CICS earlier than CICS Transaction Server for OS/390, Version 1 Release 2, a quiesce would only wait for active transactions to release their thread, which, typically, was at the end of a unit of work (UOW).
During shutdown of the CICS DB2 attachment facility initiated by DSNC STOP, the terminal remains locked until the stop is complete, when message DFHDB2025 is issued.
As an alternative to the DSNC command, you can start and stop the CICS DB2 attachment facility using the EXEC CICS SET DB2CONN CONNECTED|NOTCONNECTED commands. You can also stop the CICS DB2 attachment facility by starting the CICS-supplied transactions CDBQ and CDBF from an application program, using an EXEC CICS START command. CDBQ causes a quiesce close and CDBF causes a force close.
DSNC MODIFY TRANS CEPL n
The DSNC DISP TRAN tttt command now displays all threads running for a particular transid, instead of all the transactions associated with an RCT entry. In earlier releases, CICS uses the tttt operand to locate an RCT entry and then displays all the threads for that entry.
When you use the DSNC DISP STAT command, CICS displays statistics for DSNC commands on a line beginning '*COMMAND'. Pool thread statistics are displayed on a line beginning '*POOL'.
When modifying an RCT entry using the DSNC MODIFY TRANS tttt command, specify tttt exactly as it was defined in the RCT. If you defined a generic TXID, you must refer to the generic name when modifying it with a DSNC command. For example, if you have transactions called TAB and TAC, but they are defined generically as TA*, you can modify these on a DSNC command only by their generic name:
DSNC MODIFY TRANS TA*
and not by their specific names TAB and TAC.
A dynamic plan exit is invoked to determine which plan to use at the start of the first unit-of-work (UOW) of the transaction. This is referred to as dynamic plan selection.
A dynamic plan exit can also be invoked at the start of a subsequent UOW within the same transaction (provided the thread was released at syncpoint) to determine what plan to use for the next UOW. The plan exit can then decide to use a different plan. For this reason, this is referred to as dynamic plan switching.
In releases of CICS earlier than CICS Transaction Server for OS/390, Version 1 Release 2, dynamic plan switching can occur only for the pool, or for RCT entries defined with THRDA (THREADLIMIT) specified as zero; that is, overflowed to the pool. A consequence of using DSNC MODIFY to modify THRDA to zero is that it makes dynamic plan switching effective. An RCT with THRDA greater than 0 is not capable of dynamic plan switching in earlier releases, and the plan selected for the first UOW is used for all subsequent UOWs of the transaction.
In CICS Transaction Server for OS/390, Version 1 Release 2 and later versions and releases, dynamic plan switching can occur for DB2ENTRYs as well as for the pool, irrespective of the THREADLIMIT parameter. If you have coded your own dynamic plan exit, check that the logic can handle subsequent invocations for the same task. Your user application program, or the dynamic plan exit, must be written to tolerate consequences of additional calls to the exit. If the dynamic plan exit would change the plan when you do not want it to, the application program can avoid this by ensuring the thread is not released at syncpoint. However, the recommended method is to release the thread and ensure that the dynamic plan exit provides the correct plan for the new circumstances in which it is called.
The removal of support for macro RCTs after creating the new type of DB2 resource definition means that application programs cannot access the RCT load module to obtain information about the connection, as in earlier releases of CICS .
Application programs running in earlier releases can find the address of the RCT by means of an EXEC CICS EXTRACT EXIT command that specifies the DB2 task-related user exit on the PROGRAM option, and specifies the GASET(ptr_ref) option to get the address of the global work area (GWA). The address of the RCT is stored by releases of the attachment facility earlier than CICS Transaction Server for OS/390, Version 1 Release 2 at offset 8 in the GWA. Because the RCT is no longer available, the CICS DB2 attachment facility now sets offset 8 in the GWA to the address of fetch-protected storage, causing programs that use this address to fail with an ASRE abend. CICS issues message DFHSR0619 to the console and transient data queue CDB2 when an ASRE abend occurs.
You can use the DISMACP system initialization parameter to disable transactions that abend with an ASRE abend.
CICS no longer supports running the CICS DB2 attachment facility by specifying the DSNCRCT macro in the PARM statement, and a suffix should no longer be specified on the INITPARM parameter. The INITPARM parameter is now solely used to supply a DB2 subsystem override. The syntax of the INITPARM parameter is INITPARM=(DFHD2INI=‘yyyy") where yyyy is the (optional) 1-4 character DB2 subsystem identifier.
The DB2 subsystem identifier specified on the INITPARM system initialization parameter does not override a DB2 ID or DB2GROUPID specified in the DB2CONN definition. For a description of the sequence in which the DB2 subsystem identifier is determined, see DSNC STRT.
The defaults for many of the new DB2 resource definition parameters are different from the defaults of their macro equivalents.
Most of the defaults of the DSNCRCT macro supplied in CICSTS31.CICS.SDFHMAC are unchanged from the DSNCRCT macro supplied in previous releases. If the DSNCRCT macro generates a default value that is changed from a previous release, it flags it with an MNOTE 5 during table assembly. The default parameters generated in an assembled RCT are migrated unchanged to the CSD.
Migrate your existing RCT load modules into the CSD using the DFHCSDUP MIGRATE command. After migration, maintain the CSD definitions using RDO instead of maintaining the DSNCRCT macro definitions. To use the new CSD definitions, install the DB2 RDO definitions before the CICS DB2 attachment facility is actually started. You can dynamically modify most parameters of the DB2 resource definitions, and you can add new DB2ENTRY and DB2TRAN definitions while the CICS DB2 attachment facility is active.
To use the CICS DB2 attachment facility, the minimum migration requirements are:
This module replaces the DSN2COM0, DSN2COM1, DSNCCOM0, or DSNCCOM1 modules used in earlier releases to connect CICS to DB2 during startup.
Alternatively, avoid specifying DFHD2CM0 in a PLTPI table altogether by specifying system initialization parameter DB2CONN=YES. This causes CICS to invoke the CICS DB2 attachment facility startup module automatically without requiring an entry in the PLTPI for the CICS DB2 adaptor module.
The CICS DB2 attachment facility now uses the RMI shutdown function, meaning that it is called automatically to shut down the interface when CICS is shut down, as follows:
To start the CICS DB2 connection, change application programs to either:
To stop the CICS DB2 connection, change applications to either:
Similarly, application programs that issue the EXEC CICS INQUIRE EXITPROGRAM(DSN2EXT1) ENTRYNAME(DSNCSQL) command continue to work correctly. CICS automatically substitutes name DFHD2EX1. New application programs should use the exit program name DFHD2EX1.
In earlier releases of the CICS DB2 attachment facility, more than one task-related user exit is enabled. In addition to the exit with entryname DSNCSQL, earlier releases also support exits with entrynames DSNCIFC and DSNCCMD. Now, all requests through the CICS DB2 attachment facility are handled by a single task-related user exit program, DFHD2EX1, with entryname DSNCSQL. EXTRACT or INQUIRE EXITPROGRAM commands using entry names of DSNCIFC or DSNCCMD fail with INVEXITREQ (on the EXTRACT command) and PGMIDERR (on the INQUIRE command).
You can migrate existing RCTs to the CSD with the DFHCSDUP MIGRATE option using the following conventions:
You can override the default DB2CONN name (RCTxx) by specifying your own name on the RDONAME parameter on the DSNCRCT TYPE=INIT macro definition. If RDONAME is specified on the TYPE=INIT macro, the DB2CONN is named by the RDONAME value.
You can override the default DB2ENTRY name by specifying your own name on the RDONAME parameter on the TYPE=ENTRY macro definition. If RDONAME is specified on the TYPE=ENTRY, the DB2ENTRY is created with the RDONAME value.
You can override the default DB2TRAN name by specifying your own name on the RDONAME parameter on the TYPE=ENTRY macro definition. If the RDONAME is present on the TYPE=ENTRY and there is only one transaction ID specified for that entry, the DB2TRAN is created with the RDONAME value.
DSNCRCT TYPE=ENTRY,TXID=J+++,RDONAME=J
DSNCRCT TYPE=ENTRY,TXID=D*,RDONAME=D
DSNCRCT TYPE=ENTRY,TXID=(ANDY,BILL,CARL),RDONAME=A
the following equivalent RDO definitions are generated:
DB2ENTRY(J)
DB2TRAN(J) TRANSID(J+++) DB2ENTRY(J)
DB2ENTRY(D)
DB2TRAN(D) TRANSID(D*) DB2ENTRY(D)
DB2ENTRY(A)
DB2TRAN(ANDY) TRANSID(ANDY) DB2ENTRY(A)
DB2TRAN(BILL) TRANSID(BILL) DB2ENTRY(A)
DB2TRAN(CARL) TRANSID(CARL) DB2ENTRY(A)
You cannot define multiple generic transids referring to the same entry in the DSNCRCT macro, and these must be defined explicitly in the CSD using the DEFINE command.
Note that defining transaction IDs using wildcard characters removes the ability to collect CICS DB2 statistics on a per transaction basis, as statistics are now collected for each DB2ENTRY, which represents a group of transactions.