Migrating from a CICS release that used RCT definitions for CICS DB2 resources

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:

If you have not used CICS resource definition online (RDO) before

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:

Function

The function of the CICS DB2 attachment facility is enhanced by using online resource definition in the following ways:

System availability

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.

Performance

Online CICS DB2 resource definition provides benefits to performance as follows:

Effect of migration to RDO on CICS DB2 attachment facility operations

Changes to the CICS DB2 attachment facility affect the operation of the facility in the following ways:

Attachment startup and shutdown
You can use the DSNC STRT command to start the CICS DB2 attachment facility.

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:

  1. A subsystem ID in a DSNC STRT command, if specified.
  2. A DB2ID in the installed DB2CONN resource definition, if not blank.
  3. A DB2GROUPID in the installed DB2CONN for group attach, if specified.
  4. A subsystem ID specified on the INITPARM system initialization parameter, when the DB2ID and DB2GROUPID in the installed DB2CONN resource definition are blank (or have subsequently been set to blanks). On any startup, INITPARM is always used if the last installed DB2CONN contained a blank DB2ID and a blank DB2GROUPID, even if the DB2ID or DB2GROUPID were subsequently changed using a SET command.
  5. A default subsystem ID of DSN.

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.

CICS DB2 attachment facility command changes
The pool section of the DB2CONN resource definition does not have a TXID parameter associated with it. To modify the number of threads allowed on the pool, use reserved name CEPL on the DSNC MODIFY TRANS command. For example, issue the following command (where n is the new number of threads).
 
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.

SQL processing
User application programs do not need to be reassembled or rebound.
Dynamic plan exits
Dynamic plan exits can run unchanged and they do not need to be reassembled. The parameters passed to the exits are unchanged. However, you should be aware that dynamic plan switching can occur in new circumstances, and this could affect the operation of your dynamic plan exits.

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.

Messages
The CICS message domain processes all attachment message requests. As a result, all previous DSNC messages now have the form DFHDB2nnn. You can use the DB2CONN MSGQUEUE1, MSGQUEUE2, and MSGQUEUE3 parameters to specify where the messages should be sent. This may have an impact on automation products, for example with NetView®.
Protected threads
If you use protected threads on DB2ENTRYs, note that a thread is no longer flagged as protected for its lifetime. Instead, a thread is protected only when it is not being used. If a new transaction reuses the thread, the thread is in use, and no longer requires protection. Therefore, the current number of protected threads for that DB2ENTRY is decremented. This allows for more effective protection of threads for a DB2ENTRY.

Effect of migration to RDO on application programs

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.

Effect of migration to RDO on the INITPARM system initialization parameter

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.

Effect of migration to RDO on defaults for resource definition parameters

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.

Migrating to RDO for DB2 resource definition

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:

  1. Reassemble your existing RCTs with the DSNCRCT macro from CICSTS31.CICS.SDFHMAC.
  2. Migrate the reassembled RCTs to the CSD using DFHCSDUP (see Migrating RCTs to the CSD using DFHCSDUP)
  3. Add the migrated GROUPs to a suitable list specified on the GRPLIST system initialization parameter
  4. Change any INITPARM definitions in the SIT or SIT overrides to remove any RCT suffix specified. The syntax of the INITPARM is INITPARM=(DFHD2INI=‘yyyy’) (where yyyy is the 1-4 character DB2 subsystem ID). The INITPARM parameter is used to specify a DB2 ID. If the DB2CONN definition contains a non-blank DB2 ID or DB2GROUPID attribute this value is always used, regardless of the INITPARM specification.
  5. Upgrade the CSD Run a DFHCSDUP job to upgrade the CICS DB2 definitions in the IBM®-supplied group, DFHDB2. If you are migrating from CICS/ESA Version 3 or earlier, ensure that no previous user-defined group of CICS DB2 attach definitions is installed -- use the IBM-supplied group DFHDB2.
  6. Change the PLTPI Change and reassemble the PLTPI table to specify program DFHD2CM0.

    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.

  7. Change the PLTSD table to remove either DSN2COM0, DSN2COM1, DSNCCOM0, or DSNCCOM1, the modules used in earlier releases to disconnect CICS from DB2 during warm shutdown.

    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:

  8. Change programs that START or STOP the CICS DB2 connection Change application programs that start or stop the DB2 connection by linking to DSN2COM0, DSNCCOM0, DSN2COM1, or DSNCCOM1 (start) or DSN2COM1, DSNCCOM1, DSN2COM2, or DSNCCOM2 (stop).

    To start the CICS DB2 connection, change application programs to either:

    To stop the CICS DB2 connection, change applications to either:

  9. Check the use of EXTRACT EXIT PROGRAM(...) for DB2 interface Applications issuing the EXEC CICS EXTRACT EXIT PROGRAM(...) ENTRYNAME(DSNCSQL) command, where the program name is DSNCEXT1 or DSN2EXT1, continue to work correctly. CICS dynamically substitutes program name DFHD2EX1, the CICS DB2 task-related user exit. Note that the entryname is still DSNCSQL. New application programs should use a program name of DFHD2EX1.

    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).

Migrating RCTs to the CSD using DFHCSDUP

You can migrate existing RCTs to the CSD with the DFHCSDUP MIGRATE option using the following conventions:

Related concepts
Installation and migration notes for CICS DB2
CICS startup JCL requirements for connection to DB2
Migrating to a different release of DB2
Supported releases of DB2
[[ Contents Previous Page | Next Page Index ]]