AIOps: Monitoring and Observability - Group home

How to migrate a PARMGEN sharing-with-base RTE to Configuration Manager (by Matthias Tschaffler and Egle Barusauskiene)

  

Introduction

The PARMGEN sharing-with-base configuration option for setting up your runtime environment (RTE) is no longer an available option when you move to Configuration Manager. So, then what happens with your sharing-with-base RTE when migrating from PARMGEN to Configuration Manager? 

This article explains why sharing-with-base is no longer an option and describes how to migrate your existing sharing-with-base RTE to Configuration Manager using the MIGRATE action and the target copy (TRGCOPY) feature.

Note: The target copy feature (action option TRGCOPY) is introduced in APAR OA66050 PTF UJ95019.

Background

PARMGEN supports several types of RTEs: full, sharing-with-SMP/E, sharing-with-base, and sharing-with-another-RTE.

One aim of Configuration Manager is simplification, so Configuration Manager supports only two types of RTEs: full and sharing-with-SMP/E. The concept of “base” libraries is no longer supported.

What exactly are PARMGEN base libraries and the base RTE type?

PARMGEN base libraries are read-only runtime libraries that the configuration process does not alter and that are shareable between systems. These libraries physically exist in a base runtime environment.

As a PARMGEN user, you might currently be using the PARMGEN sharing-with-base RTE type. Historically, the most prominent reasons for using base libraries have been to save DASD space and to (presumably) insulate the SMP/E maintenance dependency.

A sharing-with-base RTE essentially consists of the read-only data sets as per the SMP/E installation, such as the TKANMOD and TKANMODL data sets (and others). When PARMGEN builds the BASE runtime environment (KCIJPLOD job), the T* is replaced with R* in those copies, showing that they are used in runtime environments only. (The high-level qualifier of the base data sets is configured in the RTE_X_HILEV_SHARING parameter.) This base is then referenced in the respective generated started task JCL.  The following example shows a remote TEMS started task, where TDCIT.MS.BASE is the base high-level qualifier:

//TEMSREMT PROC RGN=0M,TIM=1440,MEMLIM=NOLIMIT,                    
//          SYS=PGMS,                                              
//          RHILEV=TDCIT.MS.SHARE,                                 
//          BASEHLEV=TDCIT.MS.BASE.R,                              
//          USERCMDU=TDCIT.MS.SHARE.PGMS.RKANCMDU,                 
//          USERPARU=TDCIT.MS.SHARE.PGMS.RKANPARU,                 
//*   USERSAMU=TDCIT.MS.SHARE.PGMS.RKANSAMU,                       
//* CONFIGDD=TDCIT.MS.SHARE.PGMS.JCL,                              
//          SOUT=X,       LOG OUTPUT CLASS                         
//          DOUT=X,       DEBUGGING OUTPUT CLASS                   
//          RVHILEV=TDCIT.MS.SHARE,                                
//          STARTUP=KDSSYSIN                                       
//******************************************************************
//*                                                                
//TEMSREMT EXEC PGM=KLV,REGION=&RGN,TIME=&TIM,MEMLIMIT=&MEMLIM     
//STEPLIB  DD DISP=SHR,                                            
//         DSN=&RHILEV..&SYS..RKANMODU                             
//         DD DISP=SHR,                                            
//         DSN=&BASEHLEV.KANMODL                                   
//         DD DISP=SHR,                                            
//         DSN=&BASEHLEV.KANMOD                                    
//         DD DISP=SHR,                                            
//         DSN=&BASEHLEV.KANMODP       
...

Limitations of using a base RTE

One downside of using a PARMGEN base RTE is that it does not contain the data sets that are needed for configuration; base libraries contain only the runtime libraries. So, when you need to use PARMGEN again to apply maintenance, there is a dependency on SMP/E data sets, and SMP/E data sets can have different governance or maintenance cycles. Even if you can avoid certain agent maintenance by skipping the first refresh steps in PARMGEN, the moment you need to update PARMGEN components (for example, if there is a bug corrected in one of the PARMGEN programs), that dependency on SMP/E data sets is back.

With this limitation, there is room to improve the PARMGEN base RTE approach. Instead of re-creating the use of base libraries, Configuration Manager provides a better solution by adding enhanced SMP/E copy support to allow for better maintenance rollouts.

Sharing-with-base and sharing-with-SMP/E are essentially the same

In real life, no one would share golden SMP/E data sets with a product directly (the only exception would be a sandbox environment). So, in the real world, a sharing-with-SMP/E RTE is really using a sharing-with-SMP/E-copies setup (see the figure above, where the golden copy is at the top, labeled “SMP/e”).

The problem here is that you might want to have various levels of these SMP/E copies on different systems, as keeping a single copy to manage your maintenance obviously comes with severe restrictions.

How the Configuration Manager MIGRATE action handles sharing-with-base RTEs

When you perform a Configuration Manager MIGRATE action for a PARMGEN sharing-with-base RTE, the MIGRATE JCL output indicates that the configuration is not supported and defaults to sharing-with-SMP/E (that is, parameter RTE_SHARE is changed to value SMP). The following messages are issued: 

KFJ00228W RTE_SHARE “BASE” not supported. RTE_SHARE changed to “SMP”.
KFJ00215W RTE_X_HILEV_SHARING not supported. Parameter ignored

After the MIGRATE job ends, in theory, the previously-used base R* data set contents could be copied back to use the T* naming convention, essentially making them a shadow copy of your SMP/E target libraries, as referenced in the GBL_TARGET_HILEV parameter in RTEDEF(GBL$PARM). Needless to say, this is not an optimal way to manage the “new” base data sets; in addition, as mentioned previously, this copy will not contain the additional data sets that are needed to support the Configuration Manager process.  

The following section describes how you can use the Configuration Manager CREATE and GENERATE actions with the target copy (TRGCOPY) option to have a practical alternative for the PARMGEN sharing-with-base setup.

What needs to be done in Configuration Manager?

There are essentially two approaches to properly handling a PARMGEN sharing-with-base RTE in Configuration Manager:

Option A: Switch to a full (self-contained) RTE
Option B: Use target copy (TRGCOPY) option with actions CREATE and GENERATE

Each of these options is described in the following sections.

Option A: Switch to a full (self-contained) RTE

For a full RTE, parameter RTE_TYPE is set to FULL. Using a full RTE insulates the RTE data sets from any SMP/E target library dependency; however, when it comes to maintenance, you will still need your SMP/E data, as it is referenced in the RTEDEF(GBL$PARM) member (in parameter GBL_TARGET_HILEV). A full RTE is self-contained and can be deployed easily using the PACKAGE and DEPLOY actions. However, this option might not be feasible or acceptable as it will use more DASD space.

A full RTE is best used under the following conditions:

  • Configuration is done on a configuration LPAR that has a central SMP/E repository, and then generated RTEs are distributed to target LPARs. Essentially, if your RTE needs to be self-contained and carry around its own minimal OMEGAMON environment, this option is suitable.
  • DASD space is not an issue. If you have many RTEs on a single SYSPLEX, storage requirements will be larger, and each full RTE cannot share any libraries with other RTEs.

Note: You still need to be aware of your main SMP/E environment referenced in parameter GBL_TARGET_HILEV; configuration of a full RTE depends on it, exactly like PARMGEN sharing environments do (and those that are made into a base).

Option B: Use target copy (TRGCOPY) option with actions CREATE and GENERATE

With this option, an elegant way to manage SMP/E copies is implemented in the CREATE and GENERATE actions using option keyword TRGCOPY:

  • With the CREATE action, the TRGCOPY option adds a new member to the RTEDEF data set; this member contains the main information needed to manage the SMP/E copy and its contents.
  • With the GENERATE action, the TRGCOPY option physically loads the SMP/E copy by referencing the golden SMP/E installation. 

The created copy is separate from your golden SMP/E environment and is also capable of running any Configuration Manager action. It will also include only those libraries needed by your intended configuration (for example, just a subset of the agents configured).

The following example demonstrates how to implement this option.

Example

Step 1 – CREATE action with TRGCOPY option

To use the target copy feature, start by running the CREATE action with the TRGCOPY option, as shown in the following example JCL:

//USER1CRT JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID        
//*                                                      
//CSI    SET  CSI=MONSUITE                               
//*                                                      
//STEP1    EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256      
//STEPLIB  DD   DISP=SHR,DSN=&CSI..TKANMOD               
//KCIFLOW  DD   DISP=SHR,DSN=&CSI..TKANCUS(KFJOMEGA)     
//KCIVARS  DD   *                                        
ACTION          CREATE                              
OPTION          TRGCOPY                             
TRG_COPY_NAME   COPY1
TRG_COPY_HILEV  TDCIT.COPY                 
RTE_PLIB_HILEV  TDCIT.DEMO                          
/*

The following details apply to this step:

  • Running the CREATE action with the TRGCOPY option generates member RTEDEF(trg_copy_name), which contains the target copy definitions.
  • When you use the TRGCOPY option with the CREATE action, you must specify parameter TRG_COPY_NAME instead of parameter RTE_NAME. 
  • RTE_PLIB_HILEV will be used to store your target copy definitions.
  • This example JCL lists the optional parameter TRG_COPY_HILEV, which can be used to separate the target copy high-level qualifier from the RTEDEF high-level qualifier. You can use the same high-level qualifiers by omitting this parameter. 

Tip: You will have the opportunity to update the TRG_COPY_HILEV parameter value in the RTEDEF(trg_copy_name) member.

The contents of member TDCIT.DEMO.RTEDEF(COPY1), as generated in this example, are as follows:

OMEGAMON Copy of SMP/e created by USER1 on 2024-04-05 07:59:23               
                                                                               
* High-level qualifier of SMP/E target libraries                               
GBL_TARGET_HILEV                 MONSUITE                      
* SMP/E target directory containing TKANJAR files (KGW, KJJ)                   
GBL_USS_TKANJAR_PATH             "/tkanjar/path/usr/lpp/kan/bin/IBM"           
                                                                               
TRG_COPY_NAME                    COPY1                                         
* High-level qualifier of the copy of SMP/E target libraries                   
TRG_COPY_HILEV                   TDCIT.COPY                                   
* Directory for a copy of SMP/E TKANJAR files (KGW, KJJ)                       
TRG_COPY_TKANJAR_PATH            "/tkanjar/path/copy1"

* Optional parameters
TRG_COPY_VOLUME                  ""
TRG_COPY_MGMTCLAS                ""
TRG_COPY_STORCLAS                ""
TRG_COPY_UNIT                    ""

CONFIGURE_TEMS_KDS               Y  * TEMS                                     
CONFIGURE_E3270UI_KOB            Y  * Enhanced 3270                            
CONFIGURE_CICS_KC5               Y  * CICS TS                                  
CONFIGURE_CICS_TG_KGW            Y  * CICS TG                                  
CONFIGURE_DB2_AGENT_KD5          Y  * Db2                                      
[... more CONFIGURE_* here ...]
CONFIGURE_ABR_KRV                Y  * Advanced Backup and Rec                  

The following details apply to this member, which will be used in the next step:

  • The GBL_* parameters represent your golden copy, which will feed into the GENERATE TRGCOPY action in the next step.
  • The TRG_COPY* parameters should be reviewed.
  • The block of optional parameters has been added manually to illustrate how you can extend this member to include all possible customizations.
  • You can customize your target copy for a few, select products by switching the CONFIGURE_* flags on or off as necessary. The GENERATE action with the TRGCOPY option will only copy the modules and artifacts for products that are selected. 

Tip: If you change your product selection later, simply rerun the GENERATE TRGCOPY job.

Step 2 – GENERATE action with TRGCOPY option

Now, you can run the GENERATE action with the TRGCOPY option, as shown in the following example JCL: 

//USER1GEN JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID           
//*                                                         
//CSI    SET  CSI=MONSUITE                         
//*                                                         
//STEP1    EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256         
//STEPLIB  DD   DISP=SHR,DSN=&CSI..TKANMOD                  
//KCIFLOW  DD   DISP=SHR,DSN=&CSI..TKANCUS(KFJOMEGA)        
//KCIVARS  DD   *                                           
ACTION               GENERATE                               
OPTION               TRGCOPY                                
TRG_COPY_NAME        COPY1                                  
RTE_PLIB_HILEV       TDCIT.DEMO                             
/*                                   

The following details apply to this step:

  • Running the GENERATE action with the TRGCOPY option builds a copy of the SMP/E libraries.
  • Based on the configuration in this example, the target copy high-level qualifier will be built from the TRG_COPY_HILEV and TRG_COPY_NAME parameter values; and, as a result, allocate the following set of libraries:
       TDCIT.COPY.COPY1.TKANCLI
       TDCIT.COPY.COPY1.TKANCMD
       TDCIT.COPY.COPY1.TKANCUS
       ...

Step 3 – Use the new target copy

Finally, you are ready to run the configuration off this new, isolated target copy.

If you already have an environment ready, you can simply run the GENERATE action. Before running the GENERATE job, you will need to make changes in the following two places: 

  • GBL_TARGET_HILEV
  • JCL reference 

Your RTE definition members can be kept in the same RTEDEF where you define your target copies. 

So, in this case, TDCIT.DEMO.RTEDEF(GBL$PARM) needs to specify the following parameter value:

...
* High-level qualifier of SMP/E target libraries   
GBL_TARGET_HILEV        "TDCIT.COPY.COPY1" 
        
...

And then the JCL will have to be updated, as follows: 

//USER1GEN JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID     
//*                                                   
//CSI    SET  CSI=TDCIT.COPY.COPY1                    
//*                                                   
//STEP1    EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256   
//STEPLIB  DD   DISP=SHR,DSN=&CSI..TKANMOD            
//KCIFLOW  DD   DISP=SHR,DSN=&CSI..TKANCUS(KFJOMEGA)  
//KCIVARS  DD   *                                     
ACTION               GENERATE                         
RTE_NAME             RTE1                             
RTE_PLIB_HILEV       TDCIT.DEMO                       
/*                                                    

Going forward, you can now use a rolling maintenance or “Swap COPY1/COPY2” approach to switch between target copies, as described in the next section.

The TRGCOPY option enables you to do rolling maintenance

A suggested best practice when using the TRGCOPY option is to build two copies (COPY1 and COPY2) of your libraries that can be used to “roll in” or “swap in” different maintenance levels, using the steps shown in the previous section.

The rolling maintenance procedure would then work as follows:

  1. Update the golden SMP/E environment with PTFs or RSU levels.
    Note: You never reference the golden SMP/E directly in any of your RTEDEF configuration members.
  2. Run the GENERATE action with the TRGCOPY option on the SMP/E copy that is not currently in use (for example, COPY2).
  3. Run the GENERATE action referencing the SMP/E copy not currently used (COPY2) in parameter GBL_TARGET_HILEV of your RTEDEF(GBL$PARM) member and in the respective JCL that performs the GENERATE. 
    Note: If you still use PDS V1, stop your STCs before you run the GENERATE job
  4. Recycle the STCs and verify everything is working as expected

Repeat steps 3 and 4 for your remaining RTEs to complete the staged maintenance rollout for all RTEs that were referencing the previously used copy (COPY1).

Review the following details about the above best practice:

  • Normally, the first couple of steps do not affect production systems and can be performed flexibly.
  • Once the rollout is complete, there will be an unreferenced copy that can then be used to apply the next set of maintenance PTFs.
  • When using PACKAGE and DEPLOY, you will have to make sure the respective SMP/E copy – as created by the TRGCOPY option – is available on the target LPARs. 
    Tip: In some cases, using a SMP/E copy for remote deployment might be better suited than using a full RTE.
  • Because all Configuration Manager code will be available in these SMP/E copies, these libraries can be used as small and stable environments where different OMEGAMON product teams can freely and independently experiment on RTE setups.
    For example, you can use the QUICKCONFIG option with the GENERATE action to make ad-hoc configuration changes without reloading parts from the referenced SMP/E libraries.

Related information

#ZAIOPS #OMEGAMON #IBMZ​​​​​​​​​ #IBMChampion