MIGRATE

The MIGRATE action imports configuration settings from a runtime environment that is configured with PARMGEN to one that is configured with Configuration Manager.

Before you begin

Review the following information before you use the MIGRATE action:

If you migrate a runtime environment that is configured with PARMGEN to one that is configured with Configuration Manager, you can no longer use PARMGEN to configure the runtime environment. For more information, see Comparison with PARMGEN.
In this task, source refers to the runtime environment that is configured with PARMGEN, and target refers to the runtime environment that is configured with Configuration Manager.
Migration works only for OMEGAMON products that are supported by Configuration Manager. If the migration source contains other products configured by PARMGEN that are not supported by Configuration Manager, error message KFJ00001E is issued for the MIGRATE action in the KCIPRINT output, and the job ends. For the list of supported products, see Products supported by Configuration Manager.
Consider the naming convention that you will use for your target runtime environment. Source and target runtime environments can share the same high-level qualifier, which is referred to as an in-place migrate.
Note: Whereas PARMGEN stores parameters in rte_plib_hilev.rte_name.WCONFIG for each runtime environment, Configuration Manager stores parameters and variables in rte_plib_hilev.RTEDEF, which can contain definitions for multiple runtime environments. For more information about the differences between PARMGEN and Configuration Manager, see Comparison with PARMGEN.
The MIGRATE action supports migrating one or multiple PARMGEN runtime environments into a single Configuration Manager RTEDEF configuration. It is recommended that you decide prior to the migration of your first runtime environment whether you plan to migrate one or multiple runtime environments into a single RTEDEF.
Note: If you are going to set up a High Availability TEMS (HA TEMS), make sure only one runtime environment is defined in the RTEDEF (that is, the one used for the HA TEMS).
For parameters that describe data set qualifiers, the MIGRATE action does not migrate parameters that have been customized with hardcoded values that partially match the PARMGEN RTE_HILEV parameter value. For example, if in your PARMGEN configuration, you have set parameter KD2_OMPE_DSHLQ to use value TEST.RTE1.HLQ1, and RTE_HILEV is set to "TEST.RTE1", then KD2_OMPE_DSHLQ will not be migrated.
Before migrating from PARMGEN to Configuration Manager, review your customized parameters that describe data set qualifiers. If you have customized data set names that partially match your PARMGEN configuration RTE_HILEV value, but use a hardcoded value instead of parameter reference %RTE_HILEV%, you must update the value to use %RTE_HILEV% in order for the parameter to migrate successfully.
Before performing a MIGRATE action, make sure you have a backup of your source PARMGEN runtime environment. The next step in Configuration Manager after a migration is to generate runtime members using the GENERATE action. If you perform an in-place migration, the subsequent GENERATE action will overwrite the runtime environment data sets that were used by PARMGEN.

About this task

With the MIGRATE action, you can import existing PARMGEN runtime environment configuration settings from a specific WCONFIG member into the Configuration Manager rte_plib_hilev.RTEDEF. The MIGRATE action reads the WCONFIG and other data sets from a PARMGEN installation, from which it creates the sparse descriptors containing the parameters, hiding every parameter setting that is considered a default or has not been changed. It also copies other files for system variables support, embed overrides, and security exits that are required to support the migration.

The following list provides details about the MIGRATE action:

The MIGRATE action supports migrating one PARMGEN runtime environment at a time.
You can migrate one or more PARMGEN runtime environments into a single Configuration Manager RTEDEF configuration. The default behavior of the MIGRATE action is to migrate only one runtime environment into the RTEDEF data set. Using the OPTION MULTIPLE parameter, you can migrate multiple runtime environments into a single RTEDEF data set. Each runtime environment migration requires a separate MIGRATE action job. If you plan to migrate multiple runtime environments into a single RTEDEF data set, make sure to include the OPTION MULTIPLE parameter on every MIGRATE action job, including the first one.
Note: You can abbreviate OPTION MULTIPLE to OPTION MULTI.
The MIGRATE action creates the necessary members in the RTEDEF data set, as follows:
- When using the default behavior of the MIGRATE action to migrate one runtime environment into a single RTEDEF data set (omitting the OPTION MULTIPLE parameter), the MIGRATE action will create members of type Kpp$PARM in the respective created RTEDEF data set, along with the rte_name member for the runtime environment-specific parameters.
- When migrating multiple runtime environments into a single RTEDEF configuration, use parameter OPTION MULTIPLE and KFJ_SYSNAME lpar in KCIVARS DD. The MIGRATE action will create members of type Kpp$lpar in the RTEDEF data set, along with the rte_name member for the runtime environment-specific parameters.
  On subsequent runs of the MIGRATE action, reuse the same RTE_PLIB_HILEV parameter value, but update the values for parameters RTE_NAME, KFJ_MIGRATE_WCONFIG, and KFJ_SYSNAME to create a new set of runtime environment parameter members. There is no limit on how many runtime environments can be migrated into a single RTEDEF data set.
If the MIGRATE action detects that a specified target RTEDEF already contains Kpp$lpar and rte_name members, MIGRATE issues an error message and stops. Note that MIGRATE will detect Kpp$PARM and VAR$GLOB members in RTEDEF as well. Because these members are considered to have a sysplex scope, they can only exist in RTEDEF during the migration process if no additional Kpp$lpar members are intended to be migrated into the same RTEDEF. Depending on the case, any of the following messages might appear: KFJ00218E, KFJ00219E, KFJ00220E
The MIGRATE action accepts PARMGEN runtime environments with system variables. However, system variables are not copied unless you have chosen to override them in your PARMGEN configuration. Variables are copied to the RTEDEF member VAR$GLOB for a default (single) MIGRATE action or member VAR$lpar in a multiple MIGRATE action.
The MIGRATE action allocates the security exits library with the default name rte_plib_hilev.rte_name.SECEXITS (or, optionally, the name specified in the KFJ_SECURITY_EXITS_LIB parameter). The MIGRATE action also copies the security exits used by the PARMGEN environment to the specified security exits library, and defines the source security exits library to the runtime environment using the RTE_X_SECURITY_EXIT_LIB parameter. For more information, see Setting up security exits in your runtime environment.
Important: The RTE_X_SECURITY_EXIT_LIB parameter will contain the name of the security exits library used by the source PARMGEN environment; you must review this setting and update it if necessary before running the GENERATE action.
If the use of override embed members is enabled by specifying parameter KFJ_USE_EMBEDS set to Y, the MIGRATE action allocates the embeds data set with the default name rte_plib_hilev.rte_name.EMBEDS (or, optionally, the name specified in the KFJ_EMBEDS_LIB parameter). The MIGRATE action sets up the embeds data set, populates it with supported override embed parameters (if applicable), and defines it to the runtime environment using the RTE_X_OVERRIDE_EMBEDS_LIB parameter. For more information, see Using override embed members in Configuration Manager.
The MIGRATE action works with the KFJ_LOCAL_PLIB_HILEV parameter to allow for local generation of runtime environments for remote systems using different high-level qualifiers.
When the KFJ_LOCAL_PLIB_HILEV parameter is specified, the generated kfj_local_plib_hilev.RTEDEF data set will contain an additional member: PCK$PARM for a default (single) MIGRATE action, or member PCK$lpar in a multiple MIGRATE action. This member allows locally generated runtime environments using a different data set high-level qualifier than the one intended to be used on the deployment target (for example, the production system).

For more information about remote deployments, see Special considerations for SYSPLEX rollout, RTEDEF(PCK$PARM), and Remote deployment scenario.

After you run the MIGRATE action, you must carefully review the generated RTEDEF data set members to verify that the parameters have the expected values. You can use the report provided in the MIGRATE job output identified by the MIGRPT DD statement to review details about the parameters. This report presents parameters in the following groups:

Parameters that are migrated to the RTEDEF data set because their values are different from the default values
Parameters that are always migrated, regardless of values being default or not
Parameters that are not migrated because of having default values
Parameters that are not migrated because they match the PARMGEN RTE_HILEV parameter value

This report provides each parameter with its resolved value. Note that some parameters use system variables or are dependent on other parameters, and some parameters inherit values from other parameters and might be regarded as having default values. Additionally, some parameters have different default values than PARMGEN, as outlined in Parameters with different default values than PARMGEN.

Important: Verify that the data set high-level qualifiers, data set names, and z/OS® UNIX System Services paths are correct, as a subsequent GENERATE action might overwrite existing files.

To migrate a PARMGEN runtime environment to a Configuration Manager runtime environment, use the following procedure.

Note: The CONFIRM workflow variable is not supported for the MIGRATE action.

Procedure

Modify the KFJJMCM sample job in TKANSAM (see example below) to select a MIGRATE action.
Specify the required parameter values, as follows:
1. Specify values for the target environment that is to be configured with Configuration Manager in parameters RTE_NAME and RTE_PLIB_HILEV.
2. Specify the name of the source WCONFIG data set in the KFJ_MIGRATE_WCONFIG parameter. This is the WCONFIG data set of the PARMGEN-configured runtime environment from which configuration settings are to be imported.
(Optional) Specify additional parameters as needed, for example:
- To migrate this runtime environment into a RTEDEF data set containing multiple runtime environment configurations, add the OPTION MULTIPLE and KFJ_SYSNAME lpar parameters. If this is a subsequent run of the MIGRATE action, reuse the same RTE_PLIB_HILEV parameter value, but update the values for parameters RTE_NAME, KFJ_MIGRATE_WCONFIG, and KFJ_SYSNAME.
- To specify a different name for the security exits library, add the KFJ_SECURITY_EXITS_LIB parameter and value.
- To enable the use of override embed members, add the KFJ_USE_EMBEDS parameter set to Y and the KFJ_EMBEDS_LIB parameter and value.
Run the KFJJMCM job to perform the migration and generate the new RTEDEF data set.
Job messages for the MIGRATE action are written to the KCIPRINT SYSOUT data set.
Review the generated RTEDEF data set members to verify that the parameters have the expected values. Verify that the data set high-level qualifiers, data set names, and z/OS UNIX paths are correct. You can also use the report provided in the MIGRATE job output identified by the MIGRPT DD to review details about the parameters.

Example

The following JCL jobs migrate an existing PARMGEN configuration pointed to by highlevel.WCONFIG into an RTEDEF library TSOUID.MONSUITE.RTEDEF. The first example is for a single runtime environment RTEDEF, and the second example is for a multiple runtime environment RTEDEF. These examples also specify that override embed members are enabled and provide custom data set names for the security exits and embeds libraries.

Figure 1. Example JCL to perform the MIGRATE action for a single runtime environment RTEDEF

//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=ZOS1
//S1       EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256
//STEPLIB  DD DISP=SHR,DSN=MONSUITE.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
*                                                                               
ACTION                  MIGRATE                                                    
RTE_NAME                RTE1
RTE_PLIB_HILEV          TSOUID.MONSUITE
                                                                                
KFJ_MIGRATE_WCONFIG     highlevel.WCONFIG                                       
                                                                                
KFJ_SECURITY_EXITS_LIB  TEST1.TST.DEMO.MYEXITS
KFJ_USE_EMBEDS          Y
KFJ_EMBEDS_LIB          TEST1.TST.DEMO.MYEMBEDS
/*

Figure 2. Example JCL to perform the MIGRATE action for a multiple runtime environment RTEDEF

//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM SYSAFF=ZOS1
//S1       EXEC PGM=KCIOMEGA,REGION=0M,DYNAMNBR=256
//STEPLIB  DD DISP=SHR,DSN=MONSUITE.TKANMOD
//KCIFLOW  DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA)
//KCIVARS  DD *                                        
*                                                                               
ACTION                  MIGRATE                                                    
OPTION                  MULTIPLE
RTE_NAME                RTE1
RTE_PLIB_HILEV          TSOUID.MONSUITE
                                                                                
KFJ_MIGRATE_WCONFIG     highlevel.WCONFIG                                       
                                                                                
KFJ_SECURITY_EXITS_LIB  TEST1.TST.DEMO.MYEXITS
KFJ_USE_EMBEDS          Y
KFJ_EMBEDS_LIB          TEST1.TST.DEMO.MYEMBEDS

KFJ_SYSNAME             &SYSNAME
/*

What to do next

After you have finished migrating your PARMGEN runtime environments into the Configuration Manager RTEDEF library, use the GENERATE action to generate runtime members using the configured parameters. See GENERATE.