Upgrading a CICSplex to use multiple releases concurrently

About this scenario

Upgrade workflow

Initial configuration of the example CICSplex

As illustrated in Figure 1, the environment consists of a single CICSplex that spans two LPARs, to manage all the CICS regions. All regions are running CICS TS for z/OS 5.5, with a single, shared CICS system definition file (CSD).

LPAR 1

LPAR 1 is running CICS TS for z/OS 5.5 and CICSPlex SM 5.5. It has the following regions:

• One Maintenance Point (MP) CMAS for the CICSplex. The MP CMAS is connected to the CMAS regions that are assigned to manage the CICSplex on LPAR 1 and LPAR 2. Only the CICSPlex SM Web User Interface (WUI) server region is connected to the MP CMAS.
• One non-MP CMAS (shown as CMAS 1A in Figure 1). This CMAS connects to the MP CMAS and the CMAS on LPAR 2. This CMAS is assigned to manage the CICSplex defined in the MP CMAS. All CICS regions on LPAR 1 are connected to this CMAS.
• One CICSPlex SM Web User Interface (WUI) server. It connects directly to the MP CMAS.
• A group of terminal-owning regions (TORs). These regions are linked to AORs on LPAR 1 and LPAR 2 using MRO connections.
• A group of Liberty-owning regions (LORs). These regions are linked to AORs on LPAR 1 and LPAR 2 using MRO connections.
• A group of application-owning regions (AORs). These regions are linked to, from TORs and LORs on LPAR 1 and LPAR 2.

LPAR 2

LPAR 2 is also running CICS TS for z/OS 5.5 and CICSPlex SM 5.5. It has the following regions:

• One non-MP CMAS (shown as CMAS 2A in Figure 1). This CMAS is connected to the MP CMAS and to the CMAS on LPAR 1. This CMAS is assigned to manage the CICSplex defined in the MP CMAS. All CICS regions on LPAR 2 are connected to the CMAS.
• A group of terminal-owning regions (TORs). These regions are linked to AORs on LPAR 1 and LPAR 2 using MRO connections.
• A group of Liberty-owning regions (LORs). These regions are linked to AORs on LPAR 1 and LPAR 2 using MRO connections.
• A group of application-owning regions (AORs). These regions are linked to, from TORs and LORs on LPAR 1 and LPAR 2.

Both sets of TORs are defined with the same z/OS Communications Server generic resource. This means that, when the regions are shut down on one LPAR, the work transfers to the regions on the second LPAR. CICSPlex SM can pass work that comes in to a TOR to any available AOR. This means that, each TOR connects to every AOR.

All LORs receive work using Sysplex Distributor and port-sharing.

The CICSplex has a Workload Management Specification with a default rule, which routes work from the TORs and LORs to the AORs. This means that, when the regions are shut down on one LPAR, the work transfers to the regions on the second LPAR.

Procedure

Assuming the upgrade workflow for the example CICSplex, the steps for the solution are as follows.

As is mentioned earlier, you upgrade the CICSplex on an LPAR-by-LPAR basis. But you start, first, with the LPAR on which the MP CMAS is running. You upgrade this LPAR completely before you start the upgrade on the second LPAR.

Step 1. Back up any data sets that you need to retain

Before you start any upgrade, you should back up any data sets that you need to retain. These data sets include CICS system definition data sets (CSDs), CICSPlex SM data repositories, and exported WUI repositories.

Although it is recommend that you keep a back-up of your CMAS data repositories, if you later need to back out the upgrade, you should use the EYU9XDUT job to reset the repository. See Upgrading CICSPlex SM for details.

Step 2. Upgrade CICS Explorer

Upgrade CICS Explorer to a version that supports the target new release, in this example, CICS TS beta.

Step 3. Upgrade LPAR 1

This section focuses on upgrading the CICSPlex SM topology on LPAR 1.

If you are not running a CICSPlex SM WUI server, ignore the steps that refer to it.

1. Dynamically update the CICS SVC while CICS is running. Use the same SVC number as the CICS TS 5.5 SVC, but replace it with the CICS TS beta SVC. The highest-level CICS SVC is backwards-compatible. You need to do this because all CICS regions that are communicating by using MRO on the same LPAR must use the same SVC, and because CICS does not start with a down-level SVC.
2. Ensure interregion communication (IRC) is closed on every system on the LPAR, including batch jobs and any potential users of EXCI.
3. Dynamically update the LPA modules while IRC is closed.
4. Re-open IRC in the active CICS regions on LPAR 1 and confirm that the CICS connections have been acquired.
5. Upgrade the CSD. Ensure that all GRPLISTs that are used by the CICS regions on either LPAR include the required CSD compatibility groups (see CICS-supplied compatibility groups for details).
6. Shut down the MP CMAS. Upgrade it to beta, and then restart it.
7. Shut down the CICSPlex SM WUI server. Upgrade it to beta, and then restart the server.
8. Check that the CICSplex is working:
   • Check that the unmodified 5.5 CMASs have reconnected to the upgraded MP CMAS.
   • Check that CICS Explorer and the CICSPlex SM WUI server are correctly showing the active CICS regions, which are still at 5.5.
9. Create a new CMAS at CICSPlex SM beta, and start it. In Figure 2, the new CMAS is shown as CMAS 1B.
10. Use CICS Explorer or the CICSPlex SM WUI to create CMAS-to-CMAS definitions (CMTCMDEF) from the existing CMAS regions to the new CMAS, CMAS 1B.
11. Use the CICSPlex SM EYU9XDBT utility to create a batch job to define CMAS-to-CMAS definitions from the new CMAS, CMAS 1B, to the existing CMASs. You can use the CICSPlex SM sample EYUJXBT2 as a template for the commands.
12. Assign the new CMAS, CMAS 1B, to manage the CICSplex:
    • In CICS Explorer, open the SM Administration perspective, and navigate to the CICSplex definitions view. Then right-click the CICSplex and select Assign to CMAS.
    • Use CICS Explorer or the CICSPlex SM WUI to confirm that the new CMAS is listed as an Active CMAS in the CICSplex view.

Result

Figure 2 gives you an update on the configuration of LPAR 1. The MP CMAS and the CICSPlex SM WUI server have been upgraded to beta, and a new CMAS at CICSPlex SM beta (shown as CMAS 1B) has been added to the LPAR.

Step 4. Upgrade LORs on LPAR 1

The steps in this section are required only for the example of providing Java application developers with access to the most up-to-date Liberty features, while leaving the rest of the environment at the existing release of CICS TS.

In these steps, all Liberty-owning regions (LORs) on LPAR 1 are stopped, upgraded, and restarted at the same time. You can also choose to do this one LOR at a time.

1. Quiesce the LORs on the LPAR and perform a shutdown, ensuring that each LOR is stopped cleanly (see message DFHRM0204).
2. Upgrade each LOR to beta:
   1. Remove any compatibility groups from the GRPLIST for the LORs.
   2. Update the JCL to make sure that you use the CICS TS beta data sets, license, and UNIX System Services (USS).
   3. Change the EYUPARMs to reference the CMASSYSID of the new, beta non-MP CMAS on the LPAR.
3. Restart the LORs with START=INITIAL. When you restart the LORs on the LPAR, they run on a newer JVM server and connect to the latest beta CMAS.
4. The workload initiates and runs.
5. Monitor the CICSplex to make sure that the mixed mode is functioning.

Result

Figure 2 shows the resulting configuration of the example CICSplex. The LORs on LPAR 1 are connected to a CMAS at CICSPlex SM beta (shown as CMAS 1B). Table 2 shows the release level of each region in the CICSplex at this stage.

Table 2. The release level of each region in the example CICSplex when you complete step 4

LPAR	Region	Release
LPAR 1	MP CMAS	CICS TS beta CICSPlex SM beta
LPAR 1	WUI	CICS TS beta CICSPlex SM beta
LPAR 1	CMAS 1A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	CMAS 1B (non-MP CMAS)	CICS TS beta CICSPlex SM beta
LPAR 1	TOR 1	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	LOR 1	CICS TS beta CICSPlex SM beta
LPAR 1	AOR 1A	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	CMAS 2A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	TOR 2	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	LOR 2	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	AOR 2A	CICS TS 5.5 CICSPlex SM 5.5

Step 5. Introduce new AORs on LPAR 1

The steps in this section are required only for the example of providing application developers with access to the latest features and functions in CICS TS beta, while leaving the rest of the environment at the existing release of CICS TS.

1. Define new AORs on the LPAR. These should be clones of the existing AOR regions.
   1. Remove any compatibility groups from the GRPLIST for the regions.
   2. Add the CSD resource definitions for the new application resource definitions to the GRPLIST for the new regions.
   3. Update the JCL to make sure that you use the CICS TS beta data sets, license, and UNIX System Services (USS).
   4. Change the EYUPARMs to reference the CMASSYSID of the new, beta non-MP CMAS on the LPAR.
2. Update the CICSplex Workload:
   1. Define a new CICS System definition (CSYSDEF) for each new AOR required on both LPAR 1 and LPAR 2.
   2. Define a new CICS group in the CICSplex and add the new AORs to it.
   3. Add the new CICS group as a sub-group to the existing AOR group.
   4. Create a new routing rule to route the new application transactions to the new AORs.
   5. Install the new routing rule into the CICSplex.
3. Start the new AORs on LPAR 1.
4. Check that the new AORs on LPAR 1 are shown as active target regions under the new routing rule, when they become active.
5. Check that the existing workload is distributed across the previous and new AORs, but that the new application is routed only to the new beta AORs.

Result

Figure 3 shows the resulting configuration of the example CICSplex. A group of new AORs at beta is now active on LPAR 1 and integrated with the CICSplex workload. The new AORs are connected to a CMAS at CICSPlex SM beta (shown as CMAS 1B). Table 3 shows the release level of each region in the CICSplex at this stage.

Table 3. The release level of each region in the example CICSplex when upgrading of LPAR 1 is done

LPAR	Region	Release
LPAR 1	MP CMAS	CICS TS beta CICSPlex SM beta
LPAR 1	WUI	CICS TS beta CICSPlex SM beta
LPAR 1	CMAS 1A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	CMAS 1B (non-MP CMAS)	CICS TS beta CICSPlex SM beta
LPAR 1	TOR 1	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	LOR 1	CICS TS beta CICSPlex SM beta
LPAR 1	AOR 1A	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	AOR 1B	CICS TS beta CICSPlex SM beta
LPAR 2	CMAS 2A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	TOR 2	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	LOR 2	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	AOR 2A	CICS TS 5.5 CICSPlex SM 5.5

Step 6. Upgrade LPAR 2

This section focuses on upgrading the CICSPlex SM topology on LPAR 2.

1. Dynamically update the CICS SVC while CICS is running. Use the same SVC number as the CICS TS 5.5 SVC, but replace it with the CICS TS beta SVC. The highest-level CICS SVC is backwards-compatible. You need to do this because all CICS regions that are communicating by using MRO on the same LPAR must use the same SVC, and because CICS does not start with a down-level SVC.
2. Ensure IRC is closed on every system on the LPAR, including batch jobs and any potential users of EXCI.
3. Dynamically update the LPA modules while IRC is closed.
4. Re-open IRC in the active CICS regions on LPAR 2, and confirm that the CICS connections have been acquired.
5. Create a new CMAS at CICSPlex SM beta (shown as CMAS 2B in Figure 4), and start it.
6. Use CICS Explorer or the CICSPlex SM WUI to create CMAS-to-CMAS definitions (CMTCMDEF) from the existing CMAS regions to the new CMAS, CMAS 2B.
7. Use the CICSPlex SM EYU9XDBT utility to create a batch job to define CMAS-to-CMAS definitions from the new CMAS, CMAS 2B, to the existing CMASs. You can use the CICSPlex SM sample EYUJXBT2 as a template for the commands.
8. Use CICS Explorer or the CICSPlex SM WUI to confirm that the link between the existing MP CMAS and the new CMAS, CMAS 2B, is active.
9. Assign the new CMAS, CMAS 2B, to manage the CICSplex:
   • In CICS Explorer, open the SM Administration perspective, and navigate to the CICSplex definitions view. Then right-click the CICSplex and select Assign to CMAS.
   • Use CICS Explorer or the CICSPlex SM WUI to confirm that the new CMAS is listed as an Active CMAS in the CICSplex view.

Step 7. Upgrade LORs on LPAR 2

The steps in this section are required only for the example of providing Java application developers with access to the most up-to-date Liberty features, while leaving the rest of the environment at the existing release of CICS TS.

1. Quiesce the LORs on the LPAR and perform a shutdown, ensuring that each LOR is stopped cleanly (see message DFHRM0204).
2. Upgrade each LOR to beta:
   1. Remove any compatibility groups from the GRPLIST for the LORs.
   2. Update the JCL to make sure that you use the CICS TS beta data sets, license, and UNIX System Services (USS).
   3. Change the EYUPARMs to reference the CMASSYSID of the new, beta non-MP CMAS on the LPAR.
3. Restart the LORs with START=INITIAL. When you restart the LORs on the LPAR, they run on a newer JVM server and connect to the latest beta CMAS.
4. The workload initiates and runs.
5. Monitor the CICSplex to make sure that the mixed mode is functioning.

Result

Figure 4 shows the resulting configuration of the example CICSplex. LPAR 2 has a new non-MP CMAS at CICSPlex SM beta (shown as CMAS 2B). The LORs in LPAR 2 are running CICS TS beta and connecting to CMAS 2B. Table 4 shows the release level of each region in the CICSplex at this stage.

Table 4. The release level of each region in the example CICSplex when you complete step 7

LPAR	Region	Release
LPAR 1	MP CMAS	CICS TS beta CICSPlex SM beta
LPAR 1	WUI server	CICS TS beta CICSPlex SM beta
LPAR 1	CMAS 1A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	CMAS 1B (non-MP CMAS)	CICS TS beta CICSPlex SM beta
LPAR 1	TOR 1	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	LOR 1	CICS TS beta CICSPlex SM beta
LPAR 1	AOR 1A	CICS TS 5.5 CICSPlex SM 5.5
LPAR 1	AOR 1B	CICS TS beta CICSPlex SM beta
LPAR 2	CMAS 2A (non-MP CMAS)	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	CMAS 2B (non-MP CMAS)	CICS TS beta CICSPlex SM beta
LPAR 2	TOR 2	CICS TS 5.5 CICSPlex SM 5.5
LPAR 2	LOR 2	CICS TS beta CICSPlex SM beta
LPAR 2	AOR 2A	CICS TS 5.5 CICSPlex SM 5.5

Step 8. Introduce new AORs on LPAR 2

The steps in this section are required only for the example of providing application developers with access to the latest features and functions in CICS TS beta, while leaving the rest of the environment at the existing release of CICS TS.

1. Define new AORs on LPAR 2. These should be clones of the existing AOR regions.
   1. Remove any compatibility groups from the GRPLIST for the regions.
   2. Add the CSD resource definitions for the new application resource definitions to the GRPLIST for the new regions.
   3. Update the JCL to make sure that you use the CICS TS beta data sets, license, and UNIX System Services (USS).
   4. Change the EYUPARMs to reference the CMASSYSID of the new, beta non-MP CMAS on the LPAR.
2. Start the new AORs on LPAR 2.
3. Check that the new AORs on LPAR 2 are shown as Active CICS regions.
4. Check that the new AORs on LPAR 2 are shown as active target regions under the new routing rule, when they become active.
5. Check that the existing workload is distributed across the previous and new AORs, but that the new application is routed only to the new beta AORs.

Result

Figure 5 shows the resulting configuration of the example CICSplex. A group of new AORs at beta is now active on LPAR 2. The AORs are connected to a CMAS at CICSPlex SM beta (shown as CMAS 2B).

Result: The final configuration of the CICSplex

Figure 5 shows the final configuration of the CICSplex after its two LPARs are upgraded to use multiple releases concurrently. Some regions are running CICS TS 5.5. Other regions are running CICS TS beta. Table 1 shows the release level of each region in the CICSplex.