Upgrading CICS regions

This section summarizes the actions to take to migrate any CICS® region from one release to another. Other sections go through the actions to take for other elements of a CICS environment.

All versions

Upgrade the CICS data sharing servers

You should periodically upgrade the three CICS data sharing servers: temporary storage data sharing, coupling facility data tables, and named counters. Upgrade the data sharing servers before you upgrade the clients. As a result, a new server should always support old clients in a fully compatible way, including mixtures of client levels. Although upgrades are not a requirement if no functional changes have been made in the new release of the product, it is still recommended that you upgrade the shared data server to the new release. When you have upgraded the shared data servers, CICS can then be upgraded as a client of the servers.

V3.1-V4.2

APF-authorize the CICS activation modules

CICS TS V5 introduced activation modules for each edition: base, Developer Trial, and Value Unit Edition. At the start of upgrading your regions, you must:
  • AFP-authorize the SDFHLIC or SDFHVUE library.
  • Add the SDFHLIC or SDFHVUE library in the STEPLIB of the CICS TS JCL.
  • If you use coupling facility data table servers, temporary storage servers, region status servers, or named counter-servers, also add the SDFHLIC or SDFHVUE library to the STEPLIB of the JCL for each of the servers.
All versions

Redefine and initialize the local and global catalogs

For each CICS region, you must delete, redefine, and initialize the DFHLCD and DFHGCD data sets:
  • Delete your existing data sets.
  • Define and initialize new local and global catalogs, following the instructions in Defining the global catalog and Defining the local catalog. Make sure that you use the DFHRMUTL and DFHCCUTL utility programs or the CICS-supplied JCL DFHDEFDS from your target version of CICS TS.
  • Start the CICS regions with an initial start, by using the START=INITIAL parameter.
All versions

Enable z/OS conversion services

Optionally, at the start of upgrading your regions to obtain the benefits of z/OS conversion services for data conversion, you must enable the z/OS conversion services and install a conversion image that specifies the conversions that you want CICS to perform. For example, your system might require support for the conversion of UTF-8 or UTF-16 data to EBCDIC.

For the instructions to set up and configure conversions that are supported through the operating system services, see z/OS Unicode Services User's Guide and Reference.

If z/OS conversion services are not enabled, CICS issues a message. If such a message is issued when you start a CICS region that is expected to use the z/OS conversion services, an IPL is necessary to enable these services. If you do not need the z/OS conversion services, you can suppress that message.

All versions

Upgrade the CSD

If you have resource definitions in your CSD that support other IBM® products, such as z/OS, you might also need to upgrade these definitions when you start the upgrade of your regions. If you need to share your upgraded CSD with different CICS releases, the CSD must be at the highest release, and compatibility groups must be specified in the correct order. For more information, especially if you are using DFHLIST, see CSD compatibility between different CICS releases for details.

To upgrade the CSD, you have two alternatives:
  1. Upgrade the CICS-supplied definitions in your CSD to the latest level. To do this upgrade, run the DFHCSDUP utility program with the UPGRADE command.
  2. Define a new CSD by using DFHCSDUP INITIALIZE command.

In CICS TS 4.2 or below, if you have the LE resource definitions in your CSD that support other IBM products, upgrade these definitions as required. For example, if you upgrade z/OS release, you must upgrade your LE resource definitions to the new z/OS level by deleting and replacing the CSD group that contains them. The LE resource definitions are in the SCEESAMP library in member CEECCSD. Figure 1 is an example of how to delete and replace the CSD group that contains the LE definitions. For CICS TS 5.1 and above, this is not required as the LE definitions are system-autoinstalled by CICS, provided that the required maintenance which adds autoinstall capability for LE definitions is applied. For CICS/TS V5.4 the system autoinstall capability is part of the base product.

Figure 1. Sample job for additional CSD modification
//JOBNAME  JOB 1,userid,
//         NOTIFY=userid,CLASS=n,MSGLEVEL=(n,n),MSGCLASS=n 
/*JOBPARM SYSAFF=sysid                                   
/*  Remove Old Language Environment group               
//CSDUP1   EXEC PGM=DFHCSDUP,REGION=2M,PARM='CSD(READWRITE)'
//STEPLIB  DD DSN=CICSTS54.CICS.SDFHLOAD,DISP=SHR 
//DFHCSD   DD DSN=CICSTS54.CICSHURS.DFHCSD,DISP=SHR
//SYSPRINT DD SYSOUT=*     
//SYSABOUT DD SYSOUT=*     
//SYSABEND DD SYSOUT=*     
//SYSUDUMP DD SYSOUT=*     
//SYSIN    DD *  
 DELETE GROUP(CEE)         
/*                         
//*                        
//CSDUP2   EXEC PGM=DFHCSDUP,REGION=2M,PARM='CSD(READWRITE)' 
//STEPLIB  DD DSN=CICSTS54.CICS.SDFHLOAD,DISP=SHR 
//DFHCSD   DD DSN=CICSTS54.CICSHURS.DFHCSD,DISP=SHR
//SYSPRINT DD SYSOUT=*        
//SYSABOUT DD SYSOUT=*        
//SYSABEND DD SYSOUT=*        
//SYSUDUMP DD SYSOUT=*         
//SYSIN    DD DSN=SYS1.ZOS113.SCEESAMP(CEECCSD),DISP=SHR                                                     
//                               
All versions

Upgrade user-modified, CICS-supplied resource definitions

If you modified any of the CICS-supplied resource definitions in your current release of CICS TS, you must upgrade them at the start of upgrading your regions. This action ensures that they are defined correctly with any new values or attributes.

To upgrade the CSD, you have two alternatives:
  1. Confirm whether your CSD contains any user-modified, CICS-supplied resource definitions. Use the DFHCSDUP SCAN command to compare the CICS-supplied resource definitions with any user-modified versions. The DFHCSDUP SCAN command searches for the CICS-supplied version of a specified resource name of a specific resource type and compares it with any other resource definition of the same name and type. DFHCSDUP reports any differences that it finds between the CICS-supplied definition and a user-modified version. If you copied and changed the name of a CICS-supplied definition, the SCAN command permits you to specify the changed name as an alias.
  2. Copy the upgraded CICS-supplied definitions and reapply your modifications. This action is the safest way to upgrade your definitions and is necessary because the DFHCSDUP UPGRADE command does not operate on your own groups, or on CICS groups that you copied.
  3. If the CICS region uses CICSPlex® SM, manually upgrade any of the dynamically created CICSPlex SM resource definitions that you modified in your previous release, by using the equivalents in Version 5.4. The dynamically created resource definitions and their attributes are in the following members of the SEYUSAMP sample library:
    • EYU$CDEF contains the default resource definitions for a CMAS.
    • EYU$MDEF contains the default resource definitions for a MAS.
    • EYU$WDEF contains the default resource definitions for a WUI server.
All versions

Upgrade your copies of CICS-supplied resource definitions

If you made copies of CICS-supplied resource definitions, you might need to change your copies to match the changes that are made to the supplied definitions for this release, when you start upgrading your regions. DFHCSDUP UPGRADE does not operate on CICS groups that you copied. To help you, member DFH$CSDU in library SDFHSAMP contains ALTER commands that you can apply by using the CSD utility program DFHCSDUP.
  1. Review your resource definitions to determine whether you copied any CICS-supplied definitions.
  2. Review DFH$CSDU to determine whether the changes that it contains apply to your resource definitions.
  3. Make any necessary changes to DFH$CSDU. It is advisable to make a copy of DFH$CSDU and apply any changes to the copy.
  4. Run DFHCSDUP with your modified version of DFH$CSDU as input. As supplied, the ALTER commands in DFH$CSDU specify GROUP(*), which means that DFHCSDUP attempts to change resources in the CICS-supplied groups. This action is not permitted and results in message DFH5151. You can ignore this message.
As an example, program DFHD2EDF is now defined as CONCURRENCY(THREADSAFE). Therefore, DFH$CSDU contains the following command:
ALTER PROGRAM(DFHD2EDF) GROUP(*) CONCURRENCY(THREADSAFE) 

When you run DFHCSDUP, the attribute is added to the definitions of program DFHD2EDF in all groups. Other attributes that are not mentioned in DFH$CSDU are unchanged.

All versions

Reassemble all your macro tables

When you start to upgrade your regions, all your macro tables must be reassembled by using the macros supplied with the new release. During CICS initialization, CICS detects if a macro table is not reassembled, so issues a message DFHLD0110, or DFHFC0110 for File Control table (FCT), and CICS terminates.

All versions

Review DSA size limits

It is not advisable to set the size of individual dynamic storage areas (DSAs), and usually it is not necessary, if you want to do this you must apply it to each CICS region, as necessary. However, it is possible to set the size of some DSAs by using the CDSASZE, UDSASZE, RDSASZE, ECDSASZE, EUDSASZE, ESDSASZE, and ERDSASZE system initialization parameters. All of these parameters defaults to 0. The limit of storage that is available for DSAs in 24-bit storage is specified by the DSALIM SIT parameter. Allow at least 256 KB for each DSA in 24-bit storage for which you have not set a size. The limit of storage available for DSAs in 31-bit storage is specified by the EDSALIM SIT parameter. Allow at least 1 MB for each DSA in 31-bit storage for which you have not set a size. You cannot set individual DSA in 64-bit storage.

For example, CDSASZE sets the size of the CICS dynamic storage area (CDSA), and ECDSASZE specifies the size of the extended CICS dynamic storage area (ECDSA). The default value for these parameters is 0, indicating that the size of the DSA can change dynamically. If you specify a nonzero value, the DSA size is fixed. If you specify DSA size values that in combination do not allow sufficient space for the remaining DSAs, CICS fails to initialize.

All versions

Review MEMLIMIT

Review your calculation of the value of the z/OS MEMLIMIT parameter to make sure that it provides sufficient 64-bit (above-the-bar) storage for the upgraded CICS region. For more information, see Estimating, checking, and setting MEMLIMIT.

All versions

Review program and transaction definitions

Defaults of the following resource attributes are changed in CICS Transaction Server for z/OS, Version 5 Release 4. This change will have different impact on resources depending on the way the resources are defined. You should review your resource definitions to ensure that the specification of these new defaults is appropriate.

Resources New attribute defaults
Program definition DATALOCATION(ANY)
Transaction definition

SPURGE(YES)
TASKDATALOC(ANY)
TPURGE(YES)

Resources already defined via CEDA, CPSM BAS, DFHCSDUP or a bundle are unaffected, but new definitions will default to the new value.

Resources installed through the EXEC CICS CREATE command will use the new default.

For program autoinstall, the default model program DFHPGAPG now specifies DATALOCATION(ANY). If you do not specify DATALOCATION in a program autoinstall exit, nor do you specify your own program to be used as a model in the exit, you should review whether the specification of DATALOCATION(ANY) is appropriate. If not, choose one of the following ways to prevent DATALOCATION from defaulting to ANY:
  • Specify the name of your own program to be used as the model in an autoinstall exit.
  • Copy the definition of DFHPGAPG to your own group and alter the DATALOCATION setting. Ensure that the definition is installed after group DFHPGAIP.

Only AMODE(24) programs need to use DATALOCATION(BELOW). CICS issues a DFHPG0104 warning message when it loads an AMODE(24) program defined with DATALOCATION(ANY).Specify DATALOCATION(BELOW) explicitly for definitions of AMODE(24) programs instead of using the default value.

Only transactions that execute AMODE(24) programs need to use TASKDATALOC(BELOW). CICS abends transactions with an AEZC abend code if an AMODE(24) program is run under a transaction that runs withTASKDATALOC(ANY).Specify TASKDATALOC(BELOW) explicitly when you define transactions that execute AMODE(24) programs instead of using the default value.

All versions

Review the use of MQCONN

The introduction of the MQMONITOR resource in CICS TS 5.4 enhances the control and security associated with MQ connections. CICS now differentiates between the userID under which the transaction that is monitoring the MQ queue runs (the MONUSERID) and the userID under which the initiated transactions run. This userID (the USERID) is used by default, unless it is otherwise provided. This has implications for any MQMONITOR resources that are dynamically created when an MQCONN is installed.

In CICS TS 5.3 and earlier releases, when an MQCONN specifying the INITQNAME attribute is installed, a MQINI resource is dynamically created. This MQINI resource uses, for transactions started by the initiation queue, the userID under which the MQCONN was installed. In CICS TS 5.4, when an MQCONN specifying the INITQNAME attribute is installed, it now creates a MQMONITOR resource called DFHMQINI. This MQMONITOR resource uses either the PLTPI user or, if not available, the region userid as the MQMONITOR MONUSERID. However, for transactions started by the initiation queue, the userID is the MQMONITOR USERID, which defaults to the default CICS user.

To avoid a change in user associated with the transactions that are started by the initiation queue, you must:
  • Remove the INITQNAME from the MQCONN resource definition
  • Create an MQMONITOR with the following attributes:
    • MONUSERID and USERID attributes set to the appropriate userIDs
    • QNAME to match the INITQNAME that was previously specified in the MQCONN resource definition.
All versions

Review the system dump data set size

CICS now supports dumping of multiple address spaces and data spaces on the SET SYSDUMPCODE command. Certain system dump codes, such as LG0772, SO0113 and SO1000, have been added to the CICS system dump code table during CICS initialization, and more dump codes might be added to the table in the future.

As a result of this change, more data might be dumped during a system dump. Therefore, you should increase the system dump data set size to ensure sufficient storage is allocated to contain dumped data.

V5.1, V5.2, and V5.3

Upgrade programs that process policy events

The order of the capture data items in policy events is changed in CICS Transaction Server for z/OS, Version 5 Release 4, therefore you must upgrade any programs that process policy events as follows:

  • Any program that processes CFE format policy events emitted by the TS, TD or IBM MQ EP adapters must be recompiled.
  • Any program that is started by the transaction start EP adapter or any custom EP adapters must be modified, to change the container names that are referenced in the source to pick up each capture data item. The following table lists the changes to the container names for each capture data item in CICS TS 5.4:
    Capture data item name Container name in previous releases Container name in CICS TS 5.4
    policy_name DFHEP.DATA.00001 DFHEP.DATA.00006
    rule_name DFHEP.DATA.00002 DFHEP.DATA.00007
    rule_type DFHEP.DATA.00003 DFHEP.DATA.00009
    rule_category DFHEP.DATA.00004 DFHEP.DATA.00022
    rule_operator DFHEP.DATA.00005 DFHEP.DATA.00023
    rule_threshold DFHEP.DATA.00006 DFHEP.DATA.00024
    current_count DFHEP.DATA.00007 DFHEP.DATA.00025
    platform_name DFHEP.DATA.00008 DFHEP.DATA.00016
    application_name DFHEP.DATA.00009 DFHEP.DATA.00017
    application_version_major DFHEP.DATA.00010 DFHEP.DATA.00018
    application_version_minor DFHEP.DATA.00011 DFHEP.DATA.00019
    application_version_micro DFHEP.DATA.00012 DFHEP.DATA.00020
    operation DFHEP.DATA.00013 DFHEP.DATA.00021
    bundle_name DFHEP.DATA.00014 DFHEP.DATA.00010
    bundle_version_major DFHEP.DATA.00015 DFHEP.DATA.00011
    bundle_version_minor DFHEP.DATA.00016 DFHEP.DATA.00012
    bundle_version_micro DFHEP.DATA.00017 DFHEP.DATA.00013
    bundle_id DFHEP.DATA.00018 DFHEP.DATA.00014
    task_id DFHEP.DATA.00019 DFHEP.DATA.00002
    transaction_id DFHEP.DATA.00020 DFHEP.DATA.00003
    user_id DFHEP.DATA.00021 DFHEP.DATA.00004
    program_name DFHEP.DATA.00022 DFHEP.DATA.00005
    policy_user_tag DFHEP.DATA.00023 DFHEP.DATA.00015
    For more information about the capture data items, see Data captured for a policy event.
V3.1-V5.1

Migrate the DFHLRQ data set

If outstanding BTS activities for BTS processes exist in CICS, you migrate the contents of your local request queue data set, DFHLRQ. You can use a utility such as IDCAMS COPY to update the new data set with the contents of the DFHLRQ data set from your current release. You must apply this to each CICS region, as necessary.



upgrade_regions.html | Timestamp icon Last updated: Sunday, 4 June 2017