Upgrading CICSPlex SM

Upgrade actions

Your current version	Action	Mandatory or optional?
	Check compatibility requirements for different levels of	Mandatory
	Back up your configuration	Optional, but strongly recommended
	Replace a CAS with a WUI	Mandatory
	Upgrade a maintenance point CMAS	Mandatory
	Upgrade a WUI and the contents of the WUI server repository (EYUWREP)	Mandatory
	Upgrade a non-maintenance point CMAS	Mandatory
	Upgrade a CICSPlex SM managed CICS system (MAS)	Mandatory
	Upgrade PLTPI	Mandatory
	Upgrade API programs	Mandatory
	Delete previous CICSPlex SM release definitions from CSD files	Mandatory
	Back out of a CICS upgrade (for CICSPlex SM users only)	Mandatory only when backing out of an upgrade
	Upgrade the Region Status Server (for Sysplex Optimized Workload users only)	Mandatory
	Update consumers of Tivoli NetView SNA Generic Alerts (for Tivoli NetView users only)	Mandatory
	Recompile your programs to match the current release of CICSPlexSM (for programs that connect to a previous release of CICSPlexSM only)	Optional, but strongly recommended

Check compatibility requirements for different levels of CICSPlex SM

You can run this release of CICSPlex SM and earlier releases concurrently, but you must take account of a number of conditions for compatibility.

Applying support for a protection exception issue in V3.2

If you have difficulty running CICSPlex SM with CICS® TS for z/OS®, Version 3.2 because of a recursive 0c4 protection exception in module DFHSMSR, apply PTF UK43094 for APAR PK77484 and restart the system.

CMAS

You can run a CMAS at Version 5.3 that connects to a CMAS running at Version 5.2, Version 5.1, Version 4.2, Version 4.1, Version 3.2, or Version 3.1. However:

• A CICS TS for z/OS, Version 5.3 CICSPlex SM CMAS runs only in a CICS system at Version 5.3
• In a CICSplex that consists of CMASs at the latest level and at one or more earlier levels, the maintenance point CMAS must be at the latest level. So, when a CICSplex contains CMASs at more than one level, the first CMAS that you upgrade to Version 5.3 must be the maintenance point.
• You cannot view all resources of a CICS TS for z/OS, Version 5.3 region using a CMAS running at an earlier release

MAS

For a CMAS and a MAS (including those MASs that act as Web User Interface servers) to communicate, they must be running at the same release of CICSPlex SM. For an MP CMAS at the latest release to communicate with a CICS region that runs an earlier release, the MP CMAS must be at the latest release. Connect the MP CMAS to the back-level MAS through a CMAS that runs the same level. For example, a MAS running Version 5.2 is connected to a CMAS that also runs Version 5.2. This CMAS is connected, in turn, to the MP CMAS that runs the latest level. Communication between the MP CMAS at the latest level and the back-level MAS is through the back-level CMAS to which the MP CMAS is connected.

CICS systems (MASs) running at Version 5.3 , Version 5.2, Version 5.1, Version 4.2, Version 4.1, Version 3.2, and Version 3.1 can be connected to CICSPlex SM Version 5.3 . To be connected to CICSPlex SM Version 5.3 , CICS systems must use the CICSPlex SM Version 5.3 MAS agent, so they must have the CICSPlex SM Version 5.3 libraries in their CICS JCL. For a CICS system that runs CICS TS for z/OS, Version 3.1 , you must also apply the compatibility APAR PK17360 to the CICS system.

If you are using the API or Web User Interface to manage MASs connected to a CMAS at an earlier release, make sure that the MASs are managed indirectly from the Version 5.3 CMAS:

• We recommend that WUI servers run at the latest release. If they are not, they cannot see any of the resources of the latest release. If you have a mix of releases, we recommend that only the WUI at the latest release is used to define or alter resources.
• If you require access to the latest fields from the MAS that run the latest release, through a program that uses the CICSPlex SM API, ensure that the API programs connect to a CMAS that runs the latest release. If the API programs connect to a CMAS that runs an earlier release, resource tables that contain new or updated fields for the new release are not returned to the API program.

WUI server

A WUI server at an earlier release that is connected to a CMAS at an earlier release can retrieve data from a MAS connected to a Version 5.3 CMAS, if the CMAS participates in the management of the CICSplex. However, the WUI server cannot retrieve data about resource types that were not available in the earlier release.

If you want to create any of the following CICSPlex SM objects, you must create them using a WUI server that is running at the same CICSPlex SM release level as the maintenance point CMAS:

• CPLEXDEF (CICSPlex definition)
• CMTCMDEF (CMAS to CMAS link definition)
• CSYSGRP (system group definition)
• PERIODEF (time period definition)
• MONSPEC (monitor specification)
• MONGROUP (monitor group)
• MONDEF (monitor definition)
• RTAGROUP (RTA group)
• RTADEF (RTA definition)
• WLMSPEC (WLM specification)
• WLMGROUP (WLM group)
• WLMDEF (WLM definition)
• TRANGRP (transaction group)

If you use the API, EYU9XDBT, or the BATCHREP batched repository-update facility to create these objects, CICSPlex SM and the maintenance point CMAS release level must, again, be at the same release level.

Workload management (from CICS TS V4.2)

If you are using workload management, to use the unit of work (UOW) affinities that are introduced in CICS TS for z/OS, Version 4.2 , the CMAS that owns the workload must be at the Version 4.2 level, or later.

Workload function is controlled by the CMAS that owns a workload. The workload owner is assigned to the CMAS that manages the first started TOR that causes the workload to be initialized. If the workload is not shown as ACTIVE, the first started TOR associated with the workload causes its associated CMAS to be the workload owner. If the workload-owning CMAS is not at the Version 4.2 level or later, any UOW affinity definitions cannot be honored, which means that affinities are not correctly created and obeyed, and are denied to any other CMASs that later join the workload, even if those CMASs are at the Version 4.2 level or later.

To ensure that UOW affinities can be exploited by a workload:

1. Ensure that the existing workload is cloned to a new name, and that any required UOW affinity definitions are applied to the new name.
2. Ensure that the first TOR that is started for the new name is at the Version 4.2 level or later. This causes UOW affinities to be honored by any other region that joins the workload name that is at the Version 4.2 level or later. If any regions that are at earlier release levels join the workload, they are not able to use the UOW affinity function, and must continue to make routing decisions based on the standard workload routing algorithms.

If you believe that your defined UOW affinities are not being implemented, use the System ID of workload owner hyperlink in any of the WUI workload runtime views to determine the CICSPlex SM version of the workload-owning CMAS. If the CPSM version of CMAS attribute is not at least at the 0420 level, the workload is not capable of exploiting any defined UOW affinities.

Considerations for releases earlier than Version 3.1

If you have any CICS systems between Version 3.1 and 5.3 that are connected to an earlier release of CICSPlex SM, you are recommended to migrate them to the current release of CICSPlex SM to take full advantage of the enhanced management services.

If you want to manage CICS systems at an earlier release level than the releases listed here, connect them to a CMAS running at an earlier release level that supported those systems. This CMAS can be connected to your CICSPlex SM Version 5.3 CMAS, so that the older CICS systems are indirectly connected to the Version 5.3 CMAS.

Back to top

Back up your CICSPlex SM configuration

Back to top

Replace a CAS with a WUI

If you still use CAS (coordinating address space), replace it with a WUI server at V3.1. Then, when you upgrade the maintenance point CMAS, upgrade the back-level WUI to the new release.

Back to top

Upgrade a maintenance point CMAS

You must upgrade your CICSPlex SM CMAS to Version 5.3 at the same time as you upgrade the CICS system on which it runs. A CICSPlex SM CMAS runs only in a CICS system of the same release level. During startup, the CMAS checks the CICS release level and stops with message EYUXL0142 if the release does not match.

In a CICSplex that consists of CMASs at the Version 5.3 level and at one or more earlier levels, the maintenance point CMAS must be at the Version 5.3 level. So, when a CICSplex contains CMASs at more than one level, the first CMAS upgraded to Version 5.3 must be the maintenance point. To upgrade the maintenance point CMAS, follow all the steps below.

1. If the MP CMAS is running, stop it. You can continue to execute a workload in the CICSplex while the MP CMAS is down. The running workload should not be affected by the absence of the MP CMAS, but you should not make any changes to definitions while the MP CMAS is down.
2. Upgrade the CICS modules to Version 5.3. For more information about dynamically updating DFHIRP, see Upgrading MRO.
3. In the z/OS image that contains the CMAS, check that the IEASYSxx member of the SYS1.PARMLIB library that you use for z/OS initialization includes the MAXCAD and NSYSLX parameters, with an appropriate value. Specifying each CMAS correctly in IEASYSxx explains what values are suitable. If you are running both a previous release and Version 5.3 of CICSPlex SM, an Environment Services System Services (ESSS) space is started for each release, so you might need to modify the NSYSLX value.
4. Authorize the Version 5.3 libraries by adding them to the list of APF-authorized libraries in the appropriate PROGxx or IEAAPFxx member in SYS1.PARMLIB. See Authorizing the CICS and CICSPlex SM libraries.
5. Update the MVS™ linklist with the Version 5.3 modules that are required for CICS and CICSPlex SM. See Installing CICS-required modules in the MVS linklist.
6. Upgrade the CSD file that the CMAS uses with the Version 5.3 group of resource definitions and CICS startup group list. You do not need to do an additional upgrade that uses a release-dependent set of definitions for CICSPlex SM. CICS supplies a job that is called DFHCOMDS in the XDFHINST library, which is created when you run DFHISTAR. This job assumes that a completely new CSD is created and initialized. It is likely that you prefer to copy the CSD that the CMAS currently uses, and upgrade this copy. Here is an example of a job that does that:

   //DFHCSDUP JOB MSGCLASS=A,NOTIFY=&SYSUID,CLASS=A                              
   //*                                                                           
   //* UPGRADE THE CSD TO 5.3                                                    
   //*                                                                           
   //CSDADD1  EXEC PGM=DFHCSDUP,REGION=2000K,PARM='CSD(READWRITE)'               
   //SYSPRINT DD SYSOUT=A                                                        
   //STEPLIB  DD DISP=SHR,DSN=BLD.CICSDEV.INCCUR.SDFHLOAD                        
   //DFHCSD   DD DSN=CTSSVT.JCA.BANK1.CICS700.DFHCSD,DISP=SHR                    
   //SYSIN    DD *                                                               
     UPGRADE REPLACE                                                             
   /*                                                                            
   //                                                                           

7. If you modified the default resource definitions for your earlier release (these definitions are supplied by CICSPlex SM in the EYU$CDEF sample, which contains definitions for a CMAS), manually upgrade your modified resource definitions by using the equivalents in the EYU$CDEF sample for Version 5.3.

   The safest way is to copy the upgraded default resource definitions and reapply your modifications. It is important to upgrade your modified definitions to ensure that they are defined correctly with non-default values for attributes that are new. If you fail to upgrade modified definitions, CICS assigns default values to any new attributes. The default values might be inappropriate for your requirements.

8. Use the EYU9XDUT utility to upgrade the data repository (EYUDREP data set) for the CMAS to Version 5.3. It is very important that you upgrade the data repository file itself instead of a copy of the data repository. Failure to do this can cause CMAS isolation issues when the CMAS is restarted at the new level. For information about how to upgrade the data repository, see Creating the CICSPlex SM data repository. The conversion utility copies the contents of the existing data repository to a newly allocated data repository. The existing data repository is not modified.
   Note: After you upgrade the data repository for the CMAS, the next time the CMAS is started it must point to the upgraded EYUDREP data set. If it does not, data repository updates can be lost. This loss can lead to incorrect results, which can include other CMASs isolating themselves when they connect to this CMAS. After the upgrade, if you choose to roll back to the version that you upgraded from, use the EYU9XDUT utility with PARM=('TARGETVER=original version number') to downgrade the upgraded data repository for the CMAS. Failure to do this might result in CMASs becoming isolated.
9. Delete, redefine, and initialize the CICS local catalog and global catalog by using the DFHCCUTL and the DFHRMUTL utility programs. If you used DFHISTAR to install CICS, it creates a library that is called XDFHINST. This library contains member DFHDEFDS. DFHDEFDS creates the LCD and GCD files and initializes them. It also creates the other files that CICS requires, such as DFHTEMP, DFHINTRA, and DFHLRQ.
10. Check the CICSPlex SM system parameters that are referenced by the EYUPARM DD statement. If the CASNAME system parameter is present, delete it. For information about these parameters, see CICSPlex SM system parameters.
11. Check that the CICS system initialization parameter GRPLIST references the CICS supplied default startup group list, DFHLIST, and any CSD groups that contain resource definitions that were modified.
12. Use an initial start procedure for the upgraded MP CMAS.

Back to top

Upgrade a WUI and the contents of the WUI server repository (EYUWREP)

A Web User Interface server and the CMAS to which it connects must be at the highest level of CICSPlex SM and CICS in the CICSplex. They must be at the same level as the maintenance point CMAS. Web User Interface servers that have not yet been upgraded to the same level as the maintenance point CMAS can be used, but they might return unreliable results until you upgrade them.

A Web User Interface server can connect only to a CMAS at the same release level. Before you upgrade a Web User Interface server, you must upgrade the CMAS to which it connects, using the instructions in Upgrade a non-maintenance point CMAS. If the CMAS to which the Web User Interface server connects is not the maintenance point CMAS, you must also upgrade the maintenance point CMAS before you start the Web User Interface server and the CMAS to which it connects. Upgrade the Web User Interface server to Version 5.3 before you start any other MASs, so that it is ready to manage the upgraded MASs.

A CICS system that acts as a Web User Interface server is a local MAS. However, when you upgrade a Web User Interface server, you must upgrade both the CICSPlex SM MAS agent and the CICS region to Version 5.3. In other MASs, you can upgrade only the CICSPlex SM MAS agent, and you are not required to upgrade the CICS region.

1. Create a new set of WUI files, or upgrade a copy of your existing WUI files to the latest release.

   If you used DFHISTAR, the XDFHINST library that it creates contains member EYUWUIDS. When EYUWUIDS is run, it creates a new WUI Server repository (EYUWREP) and some new import (EYUCOVI) and export (EYUCOVE) files to use later if you tailored or used your own WUI view or menus. EYUWUIDS also creates the WUIs, the trace, dump, INTRA TD, LCD, GCD, LRQ, and CSD files.

2. If you copy your own files, the WUI Server Repository file (EYUWREP) must be created empty. It will be populated in a later step. If you tailored the WUI, for example with your own menus, views or usergrps, to preserve these changes after the upgrade, export and re-import the artifacts from the current WUI. You can use the COVC transaction to do the export and import. If you use only the IBM-supplied WUI menus and views, you can skip the remainder of this step.
   Using the EYUCOVE (export) dataset that was previously created by EYUWUIDS, apply the COVE file to the WUI start up JCL for the WUI that you are exporting from. For example:

   
   //EYUCOVI  DD DSN=hlq.EYUCOVI,DISP=SHR                        
   //EYUCOVE  DD DSN=hlq.EYUCOVE,DISP=SHR

   With the WUI running at the original version, you are ready to export to the EYUCOVE dataset. Do this with the COVC transaction, by selecting the “Export” option. On the “Output TD Queue name”, specify COVE. The Type can be MENU, VIEWSET, USERGRP, USER, MAP, or specify ALL if you want to extract all of your artifacts together. This example exports to COVE all artifacts that begin with the characters JON*:

   

   After the data is exported, you must import it. This is done later during the step to Upgrade the contents of the Web User Interface server repository (EYUWREP).

3. Authorize the Version 5.3 CICS and CICSPlex SM libraries. See Authorizing the CICS and CICSPlex SM libraries.
4. If you use the link pack area (LPA), decide when you plan to replace the previous release modules in the LPA with the Version 5.3 modules. Every CICSPlex SM module that is installed in the LPA can be used only by the release of CICSPlex SM to which it relates.
   1. If you put the Version 5.3 modules in the LPA immediately, change your previous release MASs to use the previous release modules from the STEPLIB and DFHRPL concatenations, instead of the LPA.
   2. If you put the Version 5.3 modules in the LPA at the end of the upgrade process, make sure your upgraded MASs are using the Version 5.3 modules from the STEPLIB and DFHRPL concatenations instead of the LPA, then change them to use the LPA when you replace the modules.
   For more information, see Controlling the use of modules from the LPA.
5. Upgrade the CSD file that is used by the WUI with the Version 5.3 group of resource definitions and CICS startup group list. You do not need to carry out an additional upgrade that uses a release-dependent set of definitions for CICSPlex SM. CICS supplies a job that is called DFHCOMDS in the XDFHINST library, which is created when you run DFHISTAR. This job assumes that a completely new CSD is created and initialized. It is likely that you prefer to copy the CSD that the WUI currently uses, and upgrade this copy. Here is an example of a job that does that:

   //DFHCSDUP JOB MSGCLASS=A,NOTIFY=&SYSUID,CLASS=A                          
   //*                                                                           
   //* UPGRADE THE CSD TO 5.3                                                    
   //*                                                                           
   //CSDADD1  EXEC PGM=DFHCSDUP,REGION=2000K,PARM='CSD(READWRITE)'               
   //SYSPRINT DD SYSOUT=A                                                        
   //STEPLIB  DD DISP=SHR,DSN=BLD.CICSDEV.INCCUR.SDFHLOAD                        
   //DFHCSD   DD DSN=CTSSVT.JCA.BANK1.CICS700.DFHCSD,DISP=SHR                    
   //SYSIN    DD *                                                               
     UPGRADE REPLACE                                                             
   /*                                                                            
   //                                                                           

6. If you modified the dynamically-created resource definitions for your earlier release that were supplied by CICSPlex SM in the EYU$WDEF sample, manually upgrade your modified resource definitions by using the equivalents in the EYU$WDEF sample for Version 5.3.

   The safest way to upgrade the resource definitions is to copy the Version 5.3 resource definitions and reapply your modifications. It is important to upgrade your modified definitions to ensure that they are defined correctly with non-default values for attributes that are new. If you do not upgrade your modified definitions, CICS assigns default values to any new attributes. These values might be inappropriate for CICS-supplied resource definitions.

7. Edit the JCL used to start the Web User Interface server, changing library names for the previous release of CICSPlex System Manager to the Version 5.3 names. For information about the MAS startup JCL, see Changing startup JCL before starting a MAS.
8. Check that the CICS system initialization parameter EDSALIM is specified for the CICS region, and set it to a value of 800 MB. 800 MB is the default EDSALIM value for a CICS region in Version 5.1 and later. You can tune this value in a similar way to tuning CICS storage in a CMAS. System initialization parameters can be specified before startup in the following locations:
   • In the system initialization table that is specified in the DFHSITxx load module whose suffix (xx) is specified as a SIT= system initialization parameter.
   • In the PARM parameter of the EXEC PGM=DFHSIP statement.
   • In the SYSIN data set defined in the startup job stream.
9. Check that the CICS system initialization parameter CPSMCONN=WUI is specified for the CICS region. This system initialization parameter initializes the CICS region as a Web User Interface server and dynamically creates the required resource definitions for CICSPlex SM.
10. Check that the CICS system initialization parameter GRPLIST references the CICS-supplied default startup group list, DFHLIST, any CSD groups that contain resource definitions that you modified, and the lists of definitions for your own applications.
11. Ensure that you deleted, redefined, and initialized the CICS local catalog and global catalog by using the DFHCCUTL and the DFHRMUTL utility programs.
12. If you use MAS history recording, define new history data sets by using the EYUJHIST sample job. If you prefer to upgrade your existing history data sets, you can also do this by using the EYUJHIST sample job and following the upgrading instructions, which are supplied as comments, in the sample. The EYUJHIST sample is supplied uncustomized in the TDFHINST library, and customized by DFHISTAR in the XDFHINST library. Remember to edit the MAS startup JCL to include the history data sets.

Upgrade the contents of the Web User Interface server repository (EYUWREP)

This step is needed only if you have tailored the WUI, for example, menus, views, and usergrps. If you use only the IBM-supplied menus and views, you can skip this step.

With each release of CICS, internal Web User Interface repository record versions might be incremented to enable the new features in view definitions. For this reason, if your existing Web User Interface repository contains customized view sets or menus, you must upgrade your view set and menu definitions.

The previous steps to upgrade a WUI server included a step to use the export function of the COVC transaction to export your existing view set and menu definitions from the Web User Interface server repository to an export file. When you upgrade the Web User Interface server repository to Version 5 3 , you can import a view set and menu definitions from a previous release into your new Web User Interface server repository. You do not need to make any changes to existing customized views and menus, but you can consider modifying or creating new view sets to take into account the new attributes and resources at the next release level.

1. When you have exported to the COVE file, amend the Version 5 3 WUI start up JCL so that the exported dataset becomes the DD name that is used for the COVI (import) file. For example:

   
   //EYUCOVI  DD DSN=hlq.EYUCOVE,DISP=SHR

2. Start the Version 5.3 WUI.
3. Use the COVC Import from a TDQ option to import the view set and menu definitions from the COVI dataset. On the Input TD Queue name, specify COVI. The Type can be MENU, VIEWSET, USERGRP, USER, MAP or use ALL if you want to import all of your artifacts together. Specify the OVERWRITE option to harden the changes. The following example imports ALL changes from COVI:
   

Back to top

Upgrade a non-maintenance point CMAS

You must upgrade your CICSPlex SM CMAS to Version 5.3 at the same time as you upgrade the CICS system on which it runs. A CICSPlex SM CMAS runs only in a CICS system of the same release level. During startup, the CMAS checks the CICS release level and stops with message EYUXL0142 if the release does not match.

You can upgrade a non-MP CMAS at the same time as the MP CMAS, or, if you are planning a phased migration, you can upgrade the non-MP CMAS later. If you run a a workload during the upgrade, note that non-Sysplex Optimized workloads continue, but information about the region health might be unavailable while the CMAS is down. This can impact routing decisions during this time. For Sysplex Optimized workloads, region information should continue to be obtained from the coupling facility during the time that the CMAS is down.

When you upgrade a CMAS that is not a maintenance point CMAS, all of the CICSplex records are removed from its data repository. The CMAS cannot connect to its MASs, or join MASs connected to other CMASs, until it reconnects to its maintenance point, at which point its data repository is resynchronized for the CICSplex. Both the maintenance point and non-maintenance point issue EYULOG messages EYUCP0203I and EYUCP0204I. The data repository synchronize is not complete until both CMASs issue both messages. Depending on the number of records in the CICSplex, the maintenance point usually takes longer than the non-maintenance point. This means that the time between the two messages on the non-maintenance point is short, but the time between the two messages on the maintenance point is longer.

Back to top

Upgrade a CICSPlex SM managed CICS system (MAS)

When you upgrade a CICSPlex SM MAS to CICSPlex SM Version 5.3, you might choose to upgrade only the CICSPlex SM MAS agent. You are not required to upgrade the CICS region to Version 5.3 at the same time.

Before you upgrade a CICSPlex SM MAS to CICSPlex SM Version 5.3, you must upgrade the CICSPlex SM CMAS to which it connects. You must also upgrade the Web User Interface server for the CICSplex.

1. If you use the link pack area (LPA), decide when you plan to replace the previous release modules in the LPA with the Version 5.3 modules. Every CICSPlex SM module that is installed in the LPA can be used only by the release of CICSPlex SM to which it relates. Every CICSPlex SM module installed in the LPA can be used only by the release of CICSPlex SM to which it relates.
   1. If you put the Version 5.3 modules in the LPA immediately, change your previous release MASs to use the previous release modules from the STEPLIB and DFHRPL concatenations, instead of the LPA.
   2. If you put the Version 5.3 modules in the LPA at the end of the upgrade process, make sure your upgraded MASs are using the Version 5.3 modules from the STEPLIB and DFHRPL concatenations instead of the LPA, then change them to use the LPA when you replace the modules.
   For more information, see Controlling the use of modules from the LPA.
2. In the JCL that is used to start the MAS, replace the previous release SEYUAUTH library name in the STEPLIB concatenation, and the previous release SEYULOAD library name in the DFHRPL concatenation, with the Version 5.3 SEYUAUTH and SEYULOAD library names. The Version 5.3 SEYUAUTH library must be authorized for APF, which you did when you upgraded the CMAS, but the SEYULOAD library must not be authorized. For information about the MAS startup JCL, see Changing startup JCL before starting a MAS.
3. Check that the CICS system initialization parameter EDSALIM is specified for the CICS region, and set it to a value of 800 MB. 800 MB is the default EDSALIM value for a CICS region in Version 5.3. System initialization parameters can be specified before startup in the following locations:
   • In the system initialization table that is specified in the DFHSITxx load module whose suffix (xx) is specified as a SIT= system initialization parameter.
   • In the PARM parameter of the EXEC PGM=DFHSIP statement.
   • In the SYSIN data set defined in the startup job stream.
4. If you use MAS history recording, define new history data sets by using the EYUJHIST sample job. If you prefer to upgrade your existing history data sets, you can also do this using the EYUJHIST sample job and following the upgrading instructions, which are supplied as comments, in the sample. The EYUJHIST sample is supplied uncustomized in the TDFHINST library, and customized by DFHISTAR in the XDFHINST library. Remember to edit the MAS startup JCL to include the history data sets.
5. If you also want to upgrade the CICS region to Version 5.3 at this time. You must upgrade the CSD for CICS as instructed, but you do not need to do any additional upgrade to your CSD to obtain the resource definitions for CICSPlex SM because all CICSPlex SM resources are defined and installed dynamically.
6. Before you can start the MAS at the latest level, you must still consider some more steps. See Upgrading CICS regions for instructions to activate the license file, and to delete, define, and initialize global and local catalogs at the latest level. When you are ready to start the MAS, if you upgraded the CPSM code and the CICS code in the MAS, use an initial start procedure. If you upgraded the CPSM code but not the CICS code, you can use a cold start procedure.

Back to top

Upgrade PLTPI

If you are using the PLTPI approach, you should migrate to using the CPSMCONN system initialization parameter. Support for using PLTPI to run the CPSM PLT program directly will be removed in a future release. It is highly recommended you migrate to using CPSMCONN.

If you continue to use the PLTPI approach, you should be aware that the PLTPI program name changes every supported release. Therefore, when you upgrade from an earlier release, you must update the PLTPI program name based on the target CICS library release (not on the CICSPlex SM release, which can be higher). If you upgrade only the CICSPlex SM release libraries, the CICSPlex SM PLT program name will remain the same and will need to be changed when you upgrade the CICS release libraries in the future. For example, if you are upgrading CICS libraries to CICS TS Version 5.2, the program name should be CJF9NXLM; if you are upgrading to CICS TS Version 5.3, the program name should be CJG9NXLM. See Module prefixes to select the correct module prefix.

If you are using PLTPI and are using DB2 or IBM MQ with CICS, see Activating Db2 and IBM MQ connections during CICS startup for further recommendations.

Back to top

Upgrade CICSPlex SM API programs

CICSPlex SM API programs that were written to run in a MAS at a previous release can be run in a Version 5.3 MAS. You can either continue to access the data that is provided by the previous release or access the new data available from Version 5.3. For information about using API programs with different releases of CICSPlex SM , see Compatibility between releases of CICSPlex SM.

If you modified your application programs to call EYU9XLOP using the EYUAWTRA commarea, recompile and link-edit them using the latest version.

The number of records that are returned by CICSPlex SM API programs querying the WLMAWTOR (Active routing regions) resource increased because WLMAWTOR now includes extra statistical information about units of work as a result of the new key attribute RPTINGCMAS (Reporting CMAS name).

For each TOR in a workload, a WLMAWTOR record is returned from every CMAS that takes part in the workload; that is, every CMAS that manages a TOR in the workload. API programs querying WLMAWTOR, therefore, have more records to process. The number to process depends on the end of unit-of-work count. Existing API applications are unaffected if the first record in the result set is treated as the only record.

Back to top

Delete previous CICSPlex SM release definitions from CSD files

If you are upgrading from CICS TS for z/OS, Version 3.1 or an earlier release, when you successfully upgrade all your systems to CICSPlex SM Version 5.3, delete the definitions for previous versions and releases from the CSD of each CMAS and MAS.

From CICS TS for z/OS, Version 3.2 onwards, the CICS resource definitions for CICSPlex SM are created dynamically, so you no longer need to delete those definitions after the upgrade.

1. Issue the DFHCSDUP UPGRADE command and specify module EYU9Rxxx, where xxx is the release number for the previous release; for example, EYU9R310 for Version 3.1. This module is supplied in CICSTS53.CPSM.SEYULOAD. For example:

    //CSDUP   EXEC PGM=DFHCSDUP
    //STEPLIB  DD  DSN=cics.index.SDFHLOAD,DISP=SHR
    //         DD  DSN=cpsm.index.SEYULOAD,DISP=SHR
    //DFHCSD   DD  DSN=cics.dfhcsd,DISP=SHR
    //SYSPRINT DD  SYSOUT=*
    //SYSIN    DD  *
     UPGRADE USING(EYU9Rxxx
   )
    /*

   When this JCL is run, EYU9Rxxx attempts to delete all the groups and group lists for that CICSPlex SM version from the CSD. However, because not all of the items that the job attempts to delete are defined in the CSD, DFHCSDUP gives a return code of 04.
2. Use the DFHCSDUP SYSPRINT output to check the results of the deletions. The output lists the items that were deleted and the items that were not found.

Back to top

Back out of a CICS upgrade (for CICSPlex SM users only)

Upgrade the Region Status Server (for Sysplex Optimized Workload users only)

The Region Status Server is a standard CICS Coupling Facility Data Table (CFDT) server that is reserved for CICS Region Status recording and reporting. Any upgrade to the CFDT Server function also applies to the RS Server. To upgrade the RS Server, follow the advice in Upgrade the CICS data sharing servers.

Update consumers of Tivoli NetView SNA Generic Alerts (for Tivoli NetView users only)

When you upgrade to a new version of CICS TS, the GDS MSU segment for the CICS TS product identifier changes within SNA Generic Alerts generated by CICSPlex SM.

Product Set ID (X'10') MS common subvector is a Product ID (X'11') common subvector that identifies the product as IBM® Software (X'04'). It contains a Product Number (X'08') Product ID subfield that identifies the product number. See Changes to CICSPlex SM for the product numbers used in different versions of CICS Transaction Server for z/OS.

If you use Tivoli NetView automation processing routines based on SNA Generic Alert headers identifying the product identifier, you will need to update your automation table processing to check for the new version of CICS TS to continue to process the SNA Generic Alerts.

For information about routing alerts using a Message Automation Table, see Writing Automation Table Statements to Automate MSUs in the Tivoli NetView for z/OS documentation.

Recompile your programs to match the current release of CICSPlex SM (for programs that connect to a previous release of CICSPlex SM only)

API programs that specify a CRITERIA string to limit the size of a result set on a GET or PERFORM OBJECT request, or use the SPECIFY FILTER verb, can experience the increase in CMAS CPU and ESSS storage. Batch job run times might also increase.

You are not required to recompile your CICSPlex SM API programs when you upgrade to the new release. However, if you do not recompile affected programs, the CMAS has to convert the records from the current release format to the level specified on the VERSION keyword on the CONNECT verb. This transformation process is highly intensive for CPU and storage when the result set is very large, for example, 300,000 - 500,000 records. Increases are observed in most cases when a criteria string is used to filter the result set; for example, specifying a criteria for the PROGRAM object by using the NAME key for a specific or generic program. In this case, CICSPlex SM has to retrieve all program objects and return them to the CMAS where the API is connected, transform the records to the version of the API, and then apply the filtering.

If you recompile your programs to specify the VERSION keyword to match the current release of CICSPlex SM, this conversion does not take place, and storage and CPU consumption do not increase significantly.