How to Perform an Active Multi-User Facility Upgrade

This scenario describes how a database administrator (DBA) performs a successful Version 14.0 to Version 15.x upgrade of a single active Multi-User Facility (MUF) instance. The term active means that the MUF is enabled and application requests are being processed against the following resources:
datacom
This scenario describes how a database administrator (DBA) performs a successful Version 14.0 to Version 15.x upgrade of a single active Multi-User Facility (MUF) instance. The term active means that the MUF is enabled and application requests are being processed against the following resources:
  • User application databases
  •  
    CA Datacom® Datadictionary™
     (DD) and Data Definition Directory (DDD) database
On this page:
 
 
Overview
The upgrade from 
CA Datacom®/DB
 Version 14.0 to Version 15.x is different from all prior version upgrades. This difference is because the CXX release stays at 14.0 and supports access from either a Version 14.0 or Version 15.x MUF. The CXX is becoming release independent and it will probably remain so going forward, just as the LXX, FXX, and database data areas have been up to this point.
Since the CXX no longer goes through a conversion process as a part of the upgrade, the term "upgrade" in Version 15.x only refers to the system database resources associated with a Version 14.0 
CA Datacom®/DB
 MUF. The database resources are:
  •  
    CA Datacom® Datadictionary™
     databases
  •  
    CA Dataquery™ for CA Datacom®
     database
  • Dynamic System Tables database.
In all cases, the MUF must already be running at the 
CA Datacom®
 Version 15.x code level before performing any part of the Version 14.0 to 15.x Active MUF upgrade process.
Definition of the Active MUF Upgrade
 
CA Datacom®
 development has introduced a new concept of "Library Swapping" for the MUF instance. We recommend that you use the Shadow-MUF technology to implement this library concept. If your choice is not to use Shadow Technology, you need to cycle your MUF instance with the new 15.x libraries. This process allows you to execute the 15.x libraries until you are comfortable with the new version of the code. Once you are comfortable, you have to schedule the three remaining components (jobs) that make up the Active Upgrade.
The definition of the new Library concept for 15.x is the creation of the Customization Libraries and creation of the SMP/E environment with current maintenance using CA Recommended Service (CA RS), or Chorus Software Manager (CSM).
The following databases can be open and active in MUF at the time the 
CA Datacom® Datadictionary™
 upgrade process is performed:
  •  
    CA Datacom® Datadictionary™
     (DD) database (default DBID 002)
  • Data Definition Directory (DDD) database (default DBID 015)
  • Dynamic System Tables (DST) database
There should be no CICS 
CA Datacom® Datadictionary™
 On-line (DDOL) or 
CA Ideal™ for CA Datacom®
 (IDEA) user sessions attached at the time the 
CA Datacom® Datadictionary™
 upgrade process is performed. The 
CA Dataquery™ for CA Datacom®
 (DQ) database (default DBID 003) needs to be closed in MUF during its upgrade, so no CICS Dataquery (DQRY) sessions can be attached and no batch DQ jobs running at the time it is upgraded.
There is not a requirement to perform all three upgrades at the same time. However, the 
CA Datacom® Datadictionary™
 upgrade must be successfully completed before the other two.
Performing an Active MUF Upgrade
As a DBA in your mainframe environment, you can install, maintain, deploy, configure, and customize features for the database product. The information that follows describes how to successfully upgrade one Version 14.0 candidate MUF environment to Version 15.x.
 
Benefits
 
  • The primary benefit is that the candidate MUF remains fully operational and available while its DD, DDD, DQ, and DST system resources are upgraded to Version 15.x.
  • User applications, both online and batch, can continue to run at the Version 14.0 code level while the MUF is running at the Version 15.x code level.
  • The DD, DDD, DQ, and DST system resource upgrades need not all be done at the same time.
  • The time to complete the DD, DDD, DQ, and DST system resource upgrades typically only takes a few minutes.
The following graphic shows the workflow that is associated with creating and utilizing the 
CA Datacom®/DB
 Parallel Upgrade process.
  Performing an Active S A MUF Upgr  
Review the Prerequisites
Before you perform an Active MUF Version 15.x upgrade, complete the following prerequisites:
  • Verify that you have a version of z/OS as supported by IBM.
  • Have experience with the 
    CA Datacom®/DB
     installation and upgrade process.
  • Have successfully run the Version 14.0 
    CA Datacom® Datadictionary™
     compare utility program (CAI.THLQ.CABDSAMP JCL member ADSDC14) before starting the candidate upgrade MUF using Version 15.x libraries.
  • Verify that the following 
    CA Datacom®/DB
     system database ID (DBID) defaults are being used:
    •  
      CA Datacom® Datadictionary™
       (DD) is 002.
    • CA Data Definition Directory (DDD) is 015.
    •  
      CA Dataquery™ for CA Datacom®
       (DQ) is 003.
    • Dynamic System Tables (DST) is 1000.
Review the recommended method for modifying JCL members
To update the variables in all installation JCL members, use the CAI.THLQ.CABDSAMP member $DCBDEDT. This method is preferable to editing each individual member manually.
The $DCBDEDT member contains the macro ISREDIT. Updating and saving the $DCBDEDT member in your SYSPROC or TSO CLIST data set allows all the variables in each Parallel Upgrade JCL member to be modified to site standards before submission.
After you modify the $DCBDEDT member, save it to your SYSPROC or TSO CLIST data set using any name that you want. In the following steps, UPG15 is used as the name of the modified and saved $DCBDEDT macro. When you enter the UPG15 command, the edit macro is activated to allow custom tailoring of each JCL member before submission.
 
Example
 
The following three ISREDIT macro entry examples contain a "from" character string followed by a "to" character string. Change the “to” character string to a value that matches your sites standards.
/* WKSHT #2 */ ISREDIT C ALL "CAI.SHLQ" "CAI.SHLQ" /* WKSHT #3 */ ISREDIT C ALL "CAI.THLQ" "CAI.THLQ" /* WKSHT #4 */ ISREDIT C ALL "CAI.CHLQ" "CAI.CHLQ"
Create the CAI.HLQ.INSTJCL Installation JCL Library
This task is the beginning point for any of the Version 14.0 to Version 15.x upgrade methods. It needs to be performed for each MUF being upgraded because the group of data sets and their contents are unique to a specific MUF. When edited and executed, the CAI.THLQ.CABDSAMP data set member BDCUS00 creates and populates the following:
  • CAI.HLQ.INSTJCL data set
  • CAI.CHLQ.CUSLIB data set
  • CAI.CHLQ.CUSMAC data set
  • CAI.CHLQ.CUSPROC data set
 
Follow these steps:
 
  1. Locate CAI.THLQ.CABDSAMP data set member BDCUS00. This member allocates the CAI.HLQ.INSTJCL data set. It also copies the 
    CA Datacom®
     Version 15.x upgrade JCL members from the CAI.THLQ.CABDSAMP library into the CAI.HLQ.INSTJCL data set.
  2. Type UPG15 in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
  3. Submit the member for execution and then cancel out of it. Do not save the changes because the members in the CAI.THLQ.CABDSAMP data set are under SMP/E control.
In the CAI.HLQ.INSTJCL data set are BDCUS JCL members. These members can be used to perform a new Version 15.x installation or any one of the three available Version 14.0 to 15.x upgrade processes. The JCL members are:
  • BDCUSNEW - Version 15.x new MUF installation process
  • BDCUSACT - Version 14.0 to 15.x Active MUF Upgrade process
  • BDCUSPAR - Version 14.0 to 15.x Parallel Upgrade process
  • BDCUSIMP - Version 14.0 to 15.x Parallel Upgrade implementation process
  • BDCUSUPG - Version 14.0 to 15.x traditional or legacy MUF upgrade process
Create the CAI.HLQ.ACT.INSTJCL Installation JCL Library
This task is the starting point for the Version 14.0 to 15.x Active MUF Upgrade process. The following steps create a CAI.HLQ.ACT.INSTJCL data set. This data set contains the required JCL members to successfully upgrade one active MUF from Version 14.0 to Version 15.x.
 
Follow these steps:
 
  1. Locate CAI.HLQ.INSTJCL data set member BDCUSACT. This member allocates the CAI.HLQ.ACT.INSTJCL data set. Additionally, it copies the 
    CA Datacom®
     Version 15.x upgrade JCL members from the CAI.THLQ.CABDSAMP library into the CAI.HLQ.ACT.INSTJCL data set.
  2. Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
  3. Submit the member for execution and then cancel out of it. Do not save the changes because the members in the CAI.THLQ.CABDSAMP data set are under SMP/E control.
Modify and Execute the CAI.HLQ.ACT.INSTJCL Upgrade JCL Members
The following CAI.HLQ.ACT.INSTJCL members are used to upgrade system resources for one Active MUF to Version 15.x. The required system resources to upgrade are the 
CA Datacom® Datadictionary™
 component, 
CA Dataquery™ for CA Datacom®
 component, and the Dynamic System Tables database. The required JCL members to accomplish these upgrades are presented in the CA recommended order.
  • $DCBDEDT - ISREDIT macro
  • @BDWKSHT - Upgrade JCL variable definitions
  • ADSDC14 - 14.0 
    CA Datacom® Datadictionary™
     comparator utility
  • ADSDC15 - 15.x 
    CA Datacom® Datadictionary™
     comparator utility
  • BDCICS - Create version 15.x DDOL CICS CSD members
  • BDRIM01 - Install Version 15.x PC Call modules
  • BDACTALC - Allocate Upgrade related data sets
  • BDCUSUPG - Assemble and link-edit custom macros
  • *******************************************************************************************************************
We always suggest that you follow the best practices for successful execution of the Active MUF Upgrade. In this situation, we strongly recommend that you keep the environment running without executing the remainder of the upgrade jobs until you are certain that reverting to the prior version of the code is not an option.
  • *******************************************************************************************************************
  • BDACTDD1 - DBUTLTY Version 14.0 DD and DDD backup
  • BDACTDD2 - Version 14.0 to 15.x 
    CA Datacom® Datadictionary™
     upgrade
  • BDACTDDR - Version 14.0 DD and DDD restore
  • BDACTDQ - Version 14.0 to 15.x DQ upgrade
  • BDACTDQR - Version 14.0 DQ restore
  • BDACTDYN - Version 14.0 to 15.x DST database upgrade
  • BDACTDYR - Version 14.0 DST database restore
  • DBUTLTYU - 15.x Sample DBUTLTY CXX report JCL
  • DBHST01U - Closes the history database
  • DBHST02U - Adds any missing history tables to the CXX and null loads 1007 
Every JCL member is re-runnable. If an error is encountered, correct the error, and simply resubmit it until a successful execution is accomplished. It is recommended that the DD, DDD, DQ, and DST system resource upgrades all be done at the same time unless there are special circumstances that prevent this from occurring.
 
Follow these steps:
 
  1. Locate CAI.HLQ.ACT.INSTJCL member BDCUSUPG. This JCL member assemblies and link edits all the 
    CA Datacom®
     Version 15.x custom macros. Review the custom macro parameter settings of all CAI.HLQ.CUSMAC members and adjust the parameter values in each member as needed. If the Version 14.0 CUSMAC members are available, they can be used as input to this JCL member in place of the Version 15.x CUSMAC.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  2. Start the 
    CA Datacom®
     Version 15.x candidate MUF. Or, use the 
    CA Datacom®/DB
     Shadow MUF option to migrate to the candidate Version 15.x MUF.
    Note:
     
    Broadcom
     always suggests that you follow the best practices for successful execution of the Active Upgrade. In this situation, we strongly recommend that you keep the environment running without executing the remainder of the upgrade jobs until you are certain that reverting to the prior version of the code is not an option.
  3. Locate CAI.HLQ.ACT.INSTJCL member BDACTALC. This JCL member executes IEFBR14 to allocate all needed backup data sets. Additionally, it adds the INCLUDE members used by the remaining BDACT
    sfx
     upgrade JCL members to the CAI.CHLQ.CUSPROC data set.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  4. Locate CAI.HLQ.ACT.INSTJCL member BDACTDD1. This JCL member executes DBUTLTY to create backups of the Version 14.0 CXX, DD, DDD, and ADRPNL data sets. If a restore back to the Version 14.0 DD and DDD becomes necessary, these backup data sets are the input to that process.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  5. Locate CAI.HLQ.ACT.INSTJCL member BDACTDD2. This JCL member executes DDUPDATE to convert the Version 14.0 DD and DDD databases to Version 15.x. Additionally, it updates the Version 14.0 DDOL signon/signoff panels to Version 15.x. It can be successfully run while the databases are open in MUF.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  6. Locate CAI.HLQ.ACT.INSTJCL member BDACTDQ. This JCL member executes the 
    CA Dataquery™ for CA Datacom®
     DQLANGMT utility to upgrade the Dataquery database DQM data area tables from Version 14.0 to Version 15.x. This member can be run at any time, but it is recommended that it be run after step 5 completes successfully.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  7. Locate CAI.HLQ.ACT.INSTJCL member BDACTDYN. This JCL member removes the Version 14.0 Dynamic System Tables database from the active MUF and replaces it with the Version 15.x equivalent. Do not run this member until after step 5 has completed successfully.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  8. Locate CAI.HLQ.ACT.INSTJCL member BDHST01U. This JCL member closes the DBID 1007 history database.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
  9. Locate CAI.HLQ.ACT.INSTJCL member BDHST02U. This JCL member rebuilds the datadictionary/DDD definition for history database (DBID 1007) and post definition to the CXX to make the CXX definition current. At this time, we are adding area EVT and table EVT to the history database. This JOB does condition code setting based on error cases to populate each of the existing areas for the history database. It is normal to have some of the bypassed steps to be condition codes.
    Type 
    UPG15
     in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards.
    Submit the member for execution and then cancel out of it so the changes are not saved.
This task completes the Active MUF Upgrade process for one candidate Version 14.0 MUF instance. To upgrade another candidate 14.0 MUF to Version 15.x, return to "Create the CAI.HLQ.INSTJCL Installation JCL Library" and repeat all the steps.
Modify and Execute the CAI.HLQ.ACT.INSTJCL Restore JCL Members
The following CAI.HLQ.ACT.INSTJCL members are available for restoring a Version 15.x system resource back to Version 14.0. Since all Version 14.0 and 15.x system resources are compatible across versions, needing to perform any of these restores would be extremely rare. If one or more Version 15.x system resources cannot remain at that level, select the appropriate restore JCL member from the following, edit it and run it.
Version 14.0  
CA Datacom® Datadictionary™
 restore
Locate CAI.HLQ.ACT.INSTJCL member BDACTDDR. This JCL member executes DBUTLTY to load the Version 14.0 CXX, DD, DDD, and ADRPNL data set backups that JCL member BDACTDD1 created. Type 
UPG15
 in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards. Submit the member for execution and then cancel out of it so the changes are not saved.
Version 14.0 
CA Dataquery™ for CA Datacom®
 restore
Locate CAI.HLQ.ACT.INSTJCL member BDACTDQR. This JCL member executes the Version 14.0 
CA Dataquery™ for CA Datacom®
 DQLANGMT utility to revert the Dataquery database DQM data area tables back to version 14.0. Type 
UPG15
 in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards. Submit the member for execution and then cancel out of it so the changes are not saved.
Version 14.0 Dynamic System Tables database restore
Locate CAI.HLQ.ACT.INSTJCL member BDACTDYR. This JCL member executes DDUPDATE to remove the Version 15.x Dynamic System Tables database and replace it with the Version 14.0 equivalent. Type 
UPG15
 in the command line and press Enter. The ISREDIT macro is invoked, and all the member variables are changed to your site standards. Submit the member for execution and then cancel out of it so the changes are not saved.