Upgrading CICS regions
This topic summarizes the actions to take to migrate any CICS® region from one release to a higher, supported release. 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. 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
Table 1 lists the actions you must perform when upgrading to a higher CICS release, regardless of your current release and the target release. The sections that describe these actions in detail are tagged with All versions.
Table 2 lists the actions that depend on your current release and your target release. The sections that describe version-dependent actions in detail also lay out the applicable current-target pairs.
Action | Mandatory or optional? |
---|---|
Upgrade the CSD | Mandatory |
Upgrade user-modified, CICS-supplied resource definitions | Mandatory |
Upgrade your copies of CICS-supplied resource definitions | Mandatory |
Upgrade the CICS data sharing servers | Optional |
Enable z/OS conversion services | Optional |
Reassemble all your macro tables | Mandatory |
Reassemble all Global User Exit programs that are using XPI calls without the RELSENSCALL parameter | Mandatory |
Modify any Global User Exit programs that use XPI INQUIRE_PROGRAM or GET_NEXT_PROGRAM calls with certain equates | Mandatory |
Review DSA size limits | Mandatory |
Review MEMLIMIT | Mandatory |
Review the system dump data set size | Mandatory |
Redefine and initialize the local and global catalogs | Mandatory |
Migrate from CICS HTTP server plug-in to CICS Web Support | Mandatory |
Your current version | Your target version | Action | Mandatory or optional? |
---|---|---|---|
5.5 | 5.6 or later | Migrate group-level feature toggle configuration files | Recommended |
5.6 or earlier | 6.1 or later | Check DSA storage requirements | Mandatory |
6.1 or earlier |
6.2 or later |
Upgrading AORs and FORs that access shared data tables | Mandatory if you are using shared data tables in your CICSplex |
Upgrade the CSD
All versions
Upgrade the CSD as the first thing of upgrading your CICS regions. 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.
- 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.
Changes to the CSD will take effect after a cold or an initial start of the CICS region.
Upgrade user-modified, CICS-supplied resource definitions
All versions
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, along with the CSD upgrade. This action ensures that they are defined correctly with any new values or attributes.
- 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 your target
release. 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 CICSPlex SM WUI server.
Upgrade your copies of CICS-supplied resource definitions
All versions
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. Upgrade these definitions at the beginning of upgrading your CICS regions, along with the CSD upgrade.
- 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.
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.
Enable z/OS conversion services
All versions
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.
Reassemble all your macro tables
All versions
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.
Reassemble all Global User Exit programs that are using XPI calls without the RELSENSCALL parameter
All versions
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 libraries at the same release level as the version of the CICS region that the program will run on, because the assembled code only works on the CICS TS release for which it is assembled.
Modify any Global User Exit programs that use XPI INQUIRE_PROGRAM or GET_NEXT_PROGRAM calls with certain equates
All versions
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.
Review DSA size limits
All versions
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.
Review MEMLIMIT
All versions
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.
Review the system dump data set size
All versions
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.
Redefine and initialize the local and global catalogs
All versions
- 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.
- Ensure that the CICS region is restarted with an initial start.
Migrate from CICS HTTP server plug-in to CICS Web Support
All versions
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.
- 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/"
Migrate group-level feature toggle configuration files
- Your current release: 5.5
- Your target release: 5.6 or later
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.
Check DSA storage requirements
- Your current release: 5.6 or earlier
- Your target release: 6.1 or later
- 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 or later.
- 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.
Upgrading AORs and FORs that access shared data tables
- Your current release: 6.1 or earlier
- Your target release: 6.2 or later
CICS shared data tables support has been enhanced in CICS TS 6.2 to provide threadsafe cross memory services for READ and BROWSE requests. This enhancement also changes how CICS shared data tables support uses z/OS cross memory services, in particular, the use of 16-bit linkage elements (LXs) rather than 12-bit LXs which are restricted in number. This means that without configuration, a region at CICS TS 6.1 or earlier cannot obtain cross memory access to a shared data table at level of CICS TS 6.2 or higher. But when you upgrade your CICSplex to a higher release, you don’t have to upgrade file owning regions (FORs) and application owning regions (AORs) all at the same time; CICS allows a rolling upgrade of regions that access shared data tables, and you can upgrade FORs and AORs in any order.
- If you want to upgrade FORs first to CICS TS 6.2 or
higher and upgrade AORs afterward, this means that pre-6.2 AORs will need to communicate with an FOR
at CICS TS 6.2 or higher that owns the shared data table. To
support this, you must set the feature toggle
com.ibm.cics.sdt.support.precicsts62=true
in the FOR so that it supplies compatible cross memory services for use by pre-6.2 AORs. If the feature toggle is not set to true, any attempt by a pre-6.2 region to obtain cross-memory access to a shared data table at a level of CICS TS 6.2 or higher fails with message DFHFC0435 issued with reason code X'80520102'. This results in a system dump. The request is then function-shipped instead to the FOR. After all AORs have been upgraded to CICS TS 6.2 or higher, you must remove the feature toggle from the FOR so that z/OS cross memory resources are not allocated unnecessarily.For more information about this feature toggle, see Feature toggles. For configuration information, see Specifying feature toggles.
- If you want to upgrade AORs first to CICS TS 6.2 or higher and upgrade FORs afterward, AORs at CICS TS 6.2 or higher can use z/OS cross memory services supplied by the pre-6.2 FOR. This is supported, and no feature toggle is required.
- The use of threadsafe READ and BROWSE access to shared data tables, thereby allowing file control requests to have cross memory access on open TCBs, can only be achieved when both the AOR and the FOR are at CICS TS 6.2 or higher. In the middle of your CICSplex upgrade, when FORs and AORs are at mixed CICS release levels, the requests are forced to run on the QR TCB.