Upgrading CICS regions

This topic summarizes the actions to take to migrate any CICS® region from one release to another. This information applies to all currently supported CICS TS releases, regardless of your current release and the target release.

If you are upgrading from an end-of-service release, you might need to take additional actions that are relevant to your current, end-of-service release, along with the actions summarized in the upgrade instruction of each CICS configuration aspect. You can find additional upgrade actions for migrating from end-of-service releases in Upgrading from end-of-service releases.

Before you begin

It is recommended that you upgrade your CICS Explorer® to the latest release before you upgrade CICSPlex® SM environments or single CICS regions. This ensures that your CICS Explorer can support the target CICS release. For detailed instructions, see Upgrading CICS Explorer.

Upgrade actions

Your current version	Action	Mandatory or optional?
All versions	Upgrade the CICS data sharing servers	Recommended
All versions	Redefine and initialize the local and global catalogs	Mandatory
All versions	Enable z/OS® conversion services	Optional
All versions	Upgrade the CSD	Mandatory
All versions	Upgrade user-modified, CICS-supplied resource definitions	Mandatory
All versions	Upgrade your copies of CICS-supplied resource definitions	Mandatory
All versions	Reassemble all your macro tables	Mandatory
All versions	Reassemble all Global User Exit programs that use XPI calls without the RELSENSCALL parameter	Mandatory
All versions	All versions Modify any Global User Exit programs that use XPI INQUIRE_PROGRAM or GET_NEXT_PROGRAM calls with certain equates	Mandatory
All versions	Review DSA size limits	Mandatory
All versions	Review MEMLIMIT	Mandatory
All versions	Review program and transaction definitions	Mandatory
All versions	Review the system dump data set size	Mandatory
All versions	Review the use of MQCONN as a result of its change of impact	Mandatory
All versions	Review whether the prerequisite PTF is installed on your z/OS operating system for IBM® Health Checker for z/OS	Mandatory
All versions	Migrate from CICS HTTP server plug-in to CICS Web Support	Mandatory
All versions	Migrate system events to CICS policy system rules	Recommended
All versions	Check DSA storage requirements	Mandatory
5.5	Migrate group-level feature toggle configuration files	Recommended

All versions Upgrade the CICS data sharing servers

You should periodically upgrade the three CICS data sharing servers: temporary storage, coupling facility data table, and named counter. 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 were made in the new release of the product, it is still advisable to upgrade the shared data servers to the new release. After you upgrade the shared data servers, CICS can then be upgraded as a client 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, when you start to upgrade your regions, to obtain the benefits of z/OS conversion services for data conversion, 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 use DFHLIST, see CSD compatibility between different CICS releases.

To upgrade the CSD, you have two alternatives:

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.
Define a new CSD by using DFHCSDUP INITIALIZE command.

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:

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 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 enables you to specify the changed name as an alias.
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.
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 6.1. 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

When you start to upgrade your regions, if you copied any 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. 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.

Review your resource definitions to determine whether you copied any CICS-supplied definitions.
Review DFH$CSDU to determine whether the changes that it contains apply to your resource definitions.
Make any necessary changes to DFH$CSDU. It is advisable to make a copy of DFH$CSDU and apply any changes to the copy.
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 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 that are 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 Reassemble all Global User Exit programs that are using XPI calls without the RELSENSCALL parameter

Using the RELSENSCALL parameter with XPI calls means that the XPI call executes successfully on all supported CICS releases. You can use this release-sensitive XPI call alternative with all XPI commands.

If your Global User Exit program uses XPI calls without the RELSENSCALL parameter, the XPI calls must be reassembled against the CICS Version 6.1 libraries, because the assembled code only works on the CICS TS release for which it is assembled.

All versions Modify any Global User Exit programs that use XPI INQUIRE_PROGRAM or GET_NEXT_PROGRAM calls with certain equates

To support Instruction Execution Protection, the DFHPGISY LOCATION equates changed. If your GLUE makes XPI INQUIRE_PROGRAM or GET_NEXT_PROGRAM call and uses equates PGIS_CDSA, PGIS_SDSA, PGIS_ECDSA and PGIS_ESDSA, you must modify it to use the equates PGIS_PCDSA, PGIS_PUDSA, PGIS_EPCDSA, and PGIS_EPUDSA instead.

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. 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. 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 all 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 want to set DSA size limits, you must do so for each CICS region, as necessary. 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 DSAs in 64-bit storage.

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 and checking MEMLIMIT.

All versions Review program and transaction definitions

Defaults of the following resource attributes changed in CICS TS 5.4. This change will have a different impact on resources, depending on the way the resources are defined. 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 that are already defined through CEDA, CICSPlex SM BAS, DFHCSDUP, or a bundle are unaffected, but new definitions will default to the new value.

Resources that are 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, 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 that is defined with DATALOCATION(ANY). Specify DATALOCATION(BELOW) explicitly for definitions of AMODE(24) programs instead of using the default value.

Only transactions that run 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 with TASKDATALOC(ANY). Specify TASKDATALOC(BELOW) explicitly when you define transactions that run 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 enhanced the control and security that is associated with IBM MQ connections. CICS now differentiates between the user ID under which the transaction that is monitoring the IBM MQ queue runs (the MONUSERID) and the user ID under which the initiated transactions run. All these have significant implications on MQ resources.

MQINI(DFHMQINI) replaced with MQMONITOR(DFHQMINI)

The MQINI(DFHMQINI) resource dynamically created by CICS when an MQCONN resource definition with the INITQNAME parameter set to the name of an MQ queue is installed has been replaced with a dynamically created MQMONITOR resource DFHQMINI.

DFHQMINI uses either the PLTPI user or, if not available, the region user ID as the MONUSERID value, and uses the default CICS user as the USERID value.

User ID changes to CKTI

As is mentioned earlier, CICS now differentiates between the user ID under which the transaction monitoring the MQ queue runs and the user ID under which the initiated transactions run. This has implications for any dynamically created resources.

CICS TS 5.3 or earlier	CICS TS 5.4 or later
Resource name: MQINI(DFHMQINI)	Resource name: MQMONITOR(DFHQMINI)
Transaction: CKTI	Transaction: CKTI
Default user ID for CKTI: Either of CICS region user ID PLTPIUSR	Default user ID for CKTI: Either of CICS region user ID PLTPIUSR
The CKTI transaction runs under the authority of the transaction that initiated the CKTI instance. The CKTI transaction uses the authority of the transaction that initiated the CKTI instance also for starting the transaction associated with the IBM MQ application queue (IBM MQ Process name).	The CKTI transaction runs under the authority of the DFHQMINI MONUSERID, which is either the CICS region user ID, or the PLTPI user ID if specified. CKTI uses the DFHQMINI USERID, which is set to the CICS default user ID, for starting the required application transaction.

The user ID changes are required to remove a security exposure where potentially unauthorized user IDs could be used.

To avoid a change in the user that is associated with the transactions that are started by the initiation queue, you must:

Remove the INITQNAME from the MQCONN resource definition
Create an MQMONITOR resource 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.

If you have concerns about the default settings of MQMONITOR DFHMQINI (for example, migrating to DFHMQINI proves more complicated than anticipated), it's possible to install a user-defined MQMONITOR resource with the name of DFHMQINI. This gives you the flexibility in setting the AUTOSTART, STATUS, MONUSERID and USERID attributes to user-defined values so as to be backward compatible, thus making migration easier. The TRANSACTION attribute must be CKTI.

All versions Review the system dump data set size

CICS supports dumping of multiple address spaces and data spaces on the SET SYSDUMPCODE command. Certain system dump codes, such as LG0772 and SO0113, are added to the CICS system dump code table during CICS initialization by the user replaceable module DFHSYDMP if the PLTPI SIT parameter has a value other then NO. More dump codes might be added to the table in the future.

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

All versions Review whether the prerequisite PTF is installed on your z/OS for IBM Health Checker for z/OS

You can check your CICS configuration with IBM Health Checker for z/OS. CICS TS supports health checker rules that define best practices for CICS system configuration. This capability requires that the following PTF is installed on your z/OS operating system:

For z/OS V2.1: UA91584
For z/OS V2.2: UA91583

All versions Migrate from CICS HTTP server plug-in to CICS Web Support

The IBM HTTP server on z/OS has changed and is now based on Apache technology. As a result of this change, the CICS HTTP server plug-in capability no longer works and has been withdrawn. If you are using the CICS HTTP server plug-in, you must migrate that workload to using the CICS Web Support.

To migrate the Service definitions from the http.conf file, perform the following steps:

Define a TCPIPSERVICE with PROTOCOL(HTTP) and a PORTNUMBER that has been allocated for CICS to use. If CICS can receive large HTTP requests (greater than 32K), you will have to set a suitable value for MAXDATALEN. You can use the default values for all other attributes. Install the TCPIPSERVICE in the CICS region (or the set of cloned regions) that will process the HTTP requests that come through the HTTP server.

Create a set of URIMAP definitions to match all of the CICS related Service directives in the httpd.conf file. For example, the Service directives that are listed in Figure 1 are represented by the set of URIMAPs in Figure 2.

Figure 1. Service directives

Service /app1/* dfhwbapi.so:DFHService/applid/CICS/APP1/APP1PROG
Service /app2/* dfhwbapi.so:DFHService/applid/CICS/APP2/APP2PROG
Service /app3/* dfhwbapi.so:DFHService/applid/APP3CONV/APP3/APP3PROG

Figure 2. URIMAPs representing Service directives listed in the preceding figure

URIMAP(APP1) USAGE(SERVER) SCHEME(HTTP) HOST(*) PATH(/app1/*) TRANSACTION(APP1) PROGRAM(APP1PROG)
URIMAP(APP2) USAGE(SERVER) SCHEME(HTTP) HOST(*) PATH(/app2/*) TRANSACTION(APP2) PROGRAM(APP2PROG)
URIMAP(APP3) USAGE(SERVER) SCHEME(HTTP) HOST(*) PATH(/app3/*) TRANSACTION(APP3) PROGRAM(APP3PROG) CONVERTER(APP3CONV)

Update the httpd.conf file and change the Service directives to be ProxyPass directives. For example, the Service directives that are listed in Figure 1 are represented by the following set of ProxyPass directives:
```
ProxyPass "/app1/" "http://cicshostname:cicsport/app1/"
ProxyPass "/app2/" "http://cicshostname:cicsport/app2/"
ProxyPass "/app3/" "http://cicshostname:cicsport/app3/"
```

Note: The applid is no longer used to route requests to the required CICS region. If requests need to be handled by specific regions, each region will need its own TCPIPSERVICE and PORTNUMBER, and the ProxyPass rule must use the cicsport that matches the required backend CICS region.

All versions Migrate system events to CICS policy system rules

Support for system events is deprecated and may be removed in a future release of CICS TS. While system events can still be defined and installed in CICS TS, you are recommended to migrate to policy system rules. Support for application events is unaffected and remains strategic.

Policy system rules provide functional equivalence and map one to one to the system events supported in CICS TS 5.3, but with much simpler configuration, and they support four possible actions:

Issue a CICS message
Emit a CICS event
Reject EXEC CICS request
Set z/OS WLM health open status (which requires CICS TS 5.6 or later)

A CICS message may be sufficient for your needs and system rules with this action are simple to adopt, avoiding the complexity that comes with supporting an event consumer. The CICS message could also be used with your existing automation products to trigger further automated actions. However, if you wish to perform further analysis on the ‘event’ using tools such as IBM Decision Manager or IBM Operational Decision Manager, or if you wish to start a CICS task to perform some automated action, then the event action will be required. For the event action, you can define items of static data to be emitted with any policy event and specify user-defined names for the policy events.

For more information about policy system rules, see Policy system rules.

You can use CICS Explorer to define policy rules. For more information, see CICS Explorer product documentation.

All versions Check DSA storage requirements

To allow some programs to run in storage that is not protected from instruction execution, there are new DSAs and some subpools have moved (see Changes to storage and Instruction execution protection. The new DSAs are used even if instruction execution protection is not available or is not requested and the distribution of storage is changed, even if instruction execution protection is not active. Be aware of the following and review your environment accordingly:

Depending on the attributes of the program, CICS loads the program into one of the four new DSAs or into the RDSA or ERDSA. Where storage might have been allocated from the CSDA or ESDA, it can now be allocated from the PCDSA or EPCDSA. Where storage might have been allocated from the SDSA or ESDSA, it can now be allocated from the PUDSA or EPUDSA. See CICS dynamic storage areas (DSAs) for information about the settings that determine in which DSA a program runs.
The ETDSA is removed and any storage that was allocated from this DSA is now allocated from the ECDSA.
Although IEP does not increase the amount of storage used within a CICS region, the changed distribution of storage within the CICS DSAs makes it likely that more DSA storage is required. If the CICS region is close to its DSA limits and these limits cannot be increased, it is advisable to run load tests on the region before switching any production regions to CICS TS 6.1.
When programs that are loaded into the CDSA and SDSA are deleted, this frees up space in these DSAs. This is not the case when programs are deleted from the PCDSA and PUDSA. A new DSA extent must be freed before any storage from the PCDSA and PUDSA can be reallocated to another DSA.

5.5 Migrate group-level feature toggle configuration files

From CICS TS 5.6, the group-level feature toggle configuration files have been deprecated. Their use will be removed in a future release of CICS TS. No messages will refer to the group-level feature toggles unless they are specified.

You should migrate to using the common configuration files or the region-specific configuration files. For instructions, see Specifying feature toggles.