Upgrading from end-of-service releases

CICS® TS 5.2, 5.3, 5.4, and 5.5 are withdrawn from support. This section is provided as-is for extended service. When you upgrade from an end-of-service release, you should follow the same migration process as you do for upgrade from any in-service release, but there are additional migration considerations and actions that are specific to your current end-of-service release. This section summarizes the actions that you must take to upgrade from any of these versions if you are under extended contract.

See the lists of changes in CICS TS Versions 5.3, 5.4, and 5.5 here: Summary of changes from end-of-service releases.

Table 1. Upgrade considerations for Versions 5.3, 5.4, and 5.5
Upgrade requirement	Actions
Upgrading CICSPlex SM	Follow the instructions in Upgrading CICSPlex SM and Upgrading CICSPlex SM: additional considerations for upgrading from an end-of-service release.
Upgrading CICS Explorer	Follow the instructions in Upgrading CICS Explorer.
Upgrading CICS regions	Follow the instructions in Upgrading CICS regions and Upgrading regions: additional considerations for upgrading from an end-of-service release.
Upgrading security	Follow the instructions in Upgrading security and Upgrading security: additional considerations for upgrading from an end-of-service release.
Upgrading the Java environment	Follow the instructions in Upgrading the Java environment and Upgrading Java: additional considerations for upgrading from an end-of-service release.
Upgrading applications	Follow the instructions in Upgrading applications.
Upgrading applications, platforms, and bundles	Follow the instructions in Upgrading applications, platforms, and bundles from CICS TS 5.3.
Upgrading connections	Follow the instructions in Upgrading IPIC, Upgrading MRO, and Upgrading connections with IBM MQ.
Upgrading JSON web services	Follow the instructions in Upgrading JSON web services and Upgrading JSON web services: additional considerations for upgrading from an end-of-service release.
Upgrading MRO	Follow the instructions in Upgrading MRO and Upgrading MRO: additional considerations for upgrading from an end-of-service release.
Upgrading SOAP web services	Follow the instructions in Upgrading SOAP web services.

The following sections give details about the additional actions that you must perform to upgrade from an end-of-service release. In these sections, the version tags such as , 5.3, 5.4, or 5.5 that precede each action indicate that you must perform the action if your current version matches.

Upgrading CICSPlex SM: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading CICSPlex SM, you must do the following:

5.3 5.4 5.5 Migrate PLTPI to using CPSMCONN. (Mandatory): Support for using PLTPI to run the CICSPlex SM PLT program directly has been removed as of CICS TS 5.6. You must migrate to using the CPSMCONN system initialization parameter.
5.4 5.5 Upgrade the CMCI JVM server configuration. (Mandatory, unless you disable the feature): If your WUI region is already using the CMCI JVM server, during your upgrade to a higher release of CICS TS, ensure that you give users access to authenticate with the CMCI JVM server, including the authority to use the CMCI. If you are using RACF, you must define the RACF EJBROLE profile &PROFILE_PREFIX.CMCI.CMCIUSER and give all CMCI users read access to this profile. For details, see Configuring CMCI in a WUI region.

Upgrading regions: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading CICS regions, you must do the following:

5.3 Review program and transaction definitions (Mandatory)

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.

5.3 Upgrade programs that process policy events. (Mandatory)

The order of the capture data items in policy events changed in CICS TS 5.4. Therefore, you must upgrade any programs that process policy events as follows:

Recompile any program that processes CFE format policy events that are emitted by the IBM MQ Queue, TD Queue, or TS Queue EP adapters.

Modify any program that is started by the Transaction Start EP adapter, or any custom EP adapter, 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 and later releases:

Capture data item name	Container name in previous releases	Container name in CICS TS 5.4 onwards
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
version	DFHEP.DATA.00024	DFHEP.DATA.00001
rule_group	DFHEP.DATA.00025	DFHEP.DATA.00008

For more information about the capture data items, see Data captured for a policy event.

5.3 Review the use of MQCONN (Mandatory)

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.

5.3 5.4 Make the source code of any required PLTs available to CICS at run time. (Mandatory)

CICS support for PLTs (Program List Tables) is changed in CICS TS 5.5. CICS is no longer able to process assembled PLTs. After PLTs are coded, it is not required to assemble the tables before use. Attempts to assemble a PLT will cause the DFHPLT macro to issue return code 8.

As a result of this change, you must ensure that the source code of any required PLTs are available to CICS at run time, and this includes any copy members referenced by the source. To achieve this, you can either place the source in a PARMLIB member that is part of the IPL PARMLIB concatenation, or add a DD card that specifies the PLT source location into the CICS JCL.

The source dataset should have the same attributes as that of a PARMLIB namely:

It must be a PDS or PDSE.
It must have a fixed block format.
It must have a record length of 80.
It must have a BLKSIZE which is a multiple of 80.

The DD statement should be of the form: //DFHTABLE DD DSN=pds name,DISP=SHR.

Alternatively DFHTABLE can reference a concatenation of partitioned data sets.

Ensure CICS has READ access to data sets in PARMLIB or DFHTABLE concatenations.

Note that PLTs should still be coded using DFHPLT macro calls.

5.3 Re-run the DFHIHFS0 job. (Optional)

As of CICS TS 5.4, in support for the feature toggle capability, the DFHIHFS0 job has been changed to create an empty featuretoggle.properties file in the dfhconfig directory. If a region at 5.4 or later is initialized without any featuretoggle.properties file, messages DFHPA1951I and DFHPA1959I are issued during startup. If you are upgrading from a release earlier than 5.4, you should rerun the DFHIHFS0 job to avoid these informational messages.

5.3 5.4 Review MAXPROCSYS and MAXPROCUSER. (Mandatory)

As of CICS TS 5.5, CICS now manages the release of USS processes from X8, X9, L8, and L9 TCBs when the TCB is released from the CICS task and returned to the relevant CICS dispatcher pool of open TCBs. The termination of removed processes is asynchronous, so such processes will continue to be counted against MAXPROCSYS momentarily. Review MAXPROCSYS and MAXPROCUSER to ensure that the LPAR has sufficient capacity. See The SYS1.PARMLIB(BPXPRMxx) parameters.

5.4 5.5 Migrate group-level feature toggle configuration files. (Recommended)

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.

Upgrading security: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading security, you must do the following:

5.3 5.4 without APAR PI85443: Specify the KERBEROSUSER SIT parameter for regions that use the Kerberos service. (Mandatory if you use Kerberos)

If you have installed and implemented the change in APAR PI85443, no action is required.

From CICS TS 5.5, the Kerberos service must be enabled by setting the KERBEROSUSER SIT parameter. If KERBEROSUSER is not specified, the region does not support the Kerberos service. On 5.3 and 5.4, this capability is provided with APAR PI85443.

In CICS TS 5.3 and 5.4, if KERBEROSUSER is not specified, the default is to use the CICS region user ID to be associated with the Kerberos service principal. Therefore, when you upgrade a CICS region that uses the Kerberos service to CICS TS 5.5 or higher, you must specify the KERBEROSUSER SIT parameter for the region to identify a user ID that is associated with the Kerberos service principal.

5.3 5.4 If you are upgrading to 5.5, 5.6 or 6.1, adopt CICS surrogate user checking to secure JCL job submissions. (Optional)

If you are upgrading to 6.2 or later, see Migrate to using CICS surrogate user checking in JCL job submissions.

Protection for JCL jobs that are submitted to the internal reader by using spool commands is provided by surrogate user checking.

Protection for JCL jobs that are submitted through the TDQ is provided by resource security on the TDQ. Additional protection is provided by surrogate user checking if the USER parameter is specified on the JOB card.

In releases earlier than CICS TS 5.5, all JCL jobs submitted from CICS run under the CICS region user ID.

Recommended:

Do not use the CICS region user ID in customer applications to submit jobs because the job would have access to all the resources of the CICS region.
Do not use passwords on the JOB card. Instead, secure JCL job submissions by using surrogate access.

Migrate to using CICS surrogate user checking to secure JCL job submissions. There are two options:

Option 1: Jobs still run under the CICS region user ID, but only with authorization.
Option 2: Jobs submitted by some or all applications run under the task user ID.

In either case, it is necessary to have a profile for the CICS region user ID in the JESSPOOL class to give the CICS region user ID authority to submit jobs for the job user IDs, regardless of whether CICS surrogate user checking is active or not.

Option 1: Migrate to a configuration where jobs still run under the region user ID, but only with authorization

Identify application code that uses SPOOLWRITE and submits jobs without a USER option on the JCL.
Identify the group of users who are allowed to run these applications.
Define surrogate checks to allow only this group of users to submit JCL under the CICS region user ID.
Ensure that XUSER=YES (or its default) is set for the region.

Configure the following feature toggle:

com.ibm.cics.spool.surrogate.check=true

Test the new configuration.

Option 2: Migrate to a configuration where jobs submitted by some or all applications run under the user ID of the signed-on user

Identify application code that uses SPOOLWRITE and submits jobs without a USER option on the JCL.
If some applications must submit JCL under the CICS region user ID, add USER=&SYSUID to the JOB statement.
Identify the group of users who are allowed to run these applications.
Define surrogate checks to allow only this group of users to submit JCL under the CICS region user ID.
Identify the group of users who are allowed to run the other applications that submit jobs without a USER option on the JCL. It is assumed that these will need to run under the task user ID, and have the authority to do so.
Define surrogate checks to allow the CICS region user ID to submit jobs on behalf of these users.
Ensure that XUSER=YES (or its default) is set for the region.

Configure the following feature toggles:

com.ibm.cics.spool.surrogate.check=true
com.ibm.cics.spool.defaultjobuser=TASK

Test the new configuration.

What application changes are needed

Applications that use WRITEQ TD to submit jobs without a USER option do not need any application change. They need RACF definitions only if you specify JOBUSERID on the TDQ definition.

You need to define additional surrogate checks, or change an application if it specifies a USER option on the JOB card, with a user ID different from the task user ID.

Learn more details in Security for submitting a JCL job to the internal reader.

5.4 5.5 Review external security settings for CMCI

The GraphQL API, CICS bundle deployment API, and user of MFA in the CICS Explorer require the CMCI JVM server. In 5.6 regions, this is enabled by default in regions that use the CMCI. In 5.5 regions, this is off by default. In 5.4 regions, this is enabled by APAR PI87691. If you installed and implemented the change in APAR PI87691, no action is required for 5.4.

If you disable the CMCI JVM server by using the feature toggle, no further action is required, but the GraphQL API, CICS bundle deployment API, and user of MFA in the CICS Explorer will not be available.

If you use the CMCI JVM server, you must define additional security profiles to maintain operation of the CMCI API. You can use the sample CLIST EYU$CMCI in SEYUSAMP, which includes sample RACF® profiles. For more information, see Step 11 in Configuring a WUI region to use the CMCI JVM server.

Additionally, if you want to set up the CICS bundle deployment API, which allows Java developers to deploy CICS bundles by using the Gradle or Maven plug-in, you need to define additional security settings. You can use the sample CLIST EYU$BUND to define the required RACF profiles. For more information, see Step 3 in Configuring the CMCI JVM server for the CICS bundle deployment API.

5.3 5.4 5.5 Define new Category 1 transactions to RACF

Category 1 transactions are for CICS internal use only and must not be started from a user terminal. They run under the CICS region user ID. You must define these transactions to RACF, and authorize the region user ID to access them. Sample CLIST DFH$CAT1 is provided to assist with this. See Authorizing the region user ID to access category 1 transactions.

For a list of CICS transactions, see All supplied transactions and associated security categories

Upgrading Java: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading the Java environment, you must do the following:

If you use the _EDC option to set the UMASK that applies when JVMSERVER files are created, migrate to using the _DFH_UMASK option in the JVM profile. (Mandatory): If at CICS TS 5.3 you use the _EDC option to set the UNIX System Services process UMASK that applies when JVMSERVER files are created, you must remove it and code a _DFH_UMASK option in the JVM profile when you migrate to CICS TS 5.4 or higher.
Use new output file structure. (Mandatory): From CICS TS 5.3, the default location of output files is relative to the directory structure WORK_DIR/<applid>/<jvmserver> rather than WORK_DIR. The default output file names, previously prefixed with <applid>.<jvmserver>, are no longer prefixed.

Upgrading applications, platforms, and bundles from CICS TS 5.3

You must do the following:

If your application has URIMAP resource and URIMAP entry point in different CICS bundles, review the change in availability. (Optional)

If you have applications where the URIMAP resource and URIMAP entry point are in different CICS bundles in the application, you might want to take action to control the availability of the URIMAP resource.

In CICS TS 5.3, the availability of the application does not restrict the work that comes in through the enabled URIMAP resource. So, you can apply or remove the application context by making the application available and unavailable, without affecting the work that runs through the URIMAP. In CICS TS 5.3, the URIMAP resource adheres to the application availability. So, work stops coming through the URIMAP resource when the application is made unavailable.

This behavior is appropriate for most situations. However, if you want to preserve the CICS TS 5.3 behavior of the URIMAP resource that is defined as an entry point (that is, it does not change its availability in line with the availability of the application), then define the URIMAP resource outside the CICS application.

Upgrading MRO: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading MRO, you must do the following:

5.3 5.4 5.5 Evaluate your use of Comm Areas used for DPL requests over MRO connections

As of CICS TS 5.6, COMMAREAs greater than 24 KB are supported for DPL requests over MRO connections. However, the use of COMMAREAs that is larger than 24 KB for DPL requests over MRO connections requires that both regions are at Version 5.6 or later. At Version 5.6 and higher, a COMMAREA that is greater than 24KB is shipped using the DFHTRANSACTION channel. Complication might arise if you have a mixed environment that has regions at Version 5.6 or later as well as regions at Version 5.5 or earlier. Issues might occur when passing a COMMAREA larger than 24 KB; if the target region is at Version 5.5 or earlier, an abend (for example, AXGE) will occur. In this case, you can disable the capability by specifying the following feature toggle:

com.ibm.cics.dpl.32kcommarea=false

The feature toggle means that the COMMAREAs used for DPL requests over MRO connections must not exceed 24 KB, as in CICS TS 5.5 or earlier.

Important: When all regions in your environment are at Version 5.6 or later, you should remove this feature toggle or re-enable the capability by specifying com.ibm.cics.dpl.32kcommarea=true.

Upgrading JSON web services: additional considerations for upgrading from an end-of-service release

In addition to the actions described in Upgrading JSON web services, you must do the following:

5.3 Use the EXEC CICS TRANSFORM command to parse and generate JSON. (Optional): Consider using the EXEC CICS TRANSFORM command to parse and generate JSON, rather than linking to DFHJSON. The EXEC CICS TRANSFORM command is extended to transform both XML and JSON data, removing the requirement to link to a separate program to provide this capability, or to configure a JVM server for JSON transformation. For more information about the command, see Transforming JSON to application data by using the TRANSFORM JSONTODATA API command.