Remote deployment example using local libraries

This detailed example shows how to use local libraries to implement remote deployment of a runtime environment.

Overview

Using local libraries in a remote deployment scenario is required when the system that you are deploying to requires different high-level qualifiers than the high-level qualifiers used on your configuration system.

Tip: If you can use the same high-level qualifiers on the configuration and target systems, you do not have to use local libraries for remote deployment.

This example demonstrates the steps required to create the necessary data sets and parameter settings using local libraries for a runtime environment that will be deployed to another system.

This example use the following terms:

Configuration system

The system where the runtime environment to be deployed is configured and packaged.

Note: A configuration runtime environment (that is, the runtime environment that is configured for the purpose of deployment) cannot be started.

Target system

The system there the package data sets are restored (deployed) and where the runtime environment will be active. Typically, the target system is a remote system, but it can also be the same system as the configuration system.

Local libraries

The data sets on the configuration system that are used for creating, configuring, and packaging a runtime environment to be deployed to another system. The parameters in the local libraries on the configuration system are configured for the target system.

Local libraries cannot be used for an active runtime environment on the configuration system.

Local libraries are defined and used with parameter KFJ_LOCAL_PLIB_HILEV. The local library RTEDEF data set contains special member PCK$PARM, which is used specifically for packaging and deploying a runtime environment using local libraries.

In this remote deployment scenario, the DASD for the configuration system and the target system is not shared and requires the use of different high-level qualifiers from each other. In this example, the high-level qualifiers for the configuration system are DEV.OMEG and the high-level qualifiers for the target system are PROD.OMEG.

Note: The following examples include only the parameters related to remote deployment. Additional parameters in the KCIVARS DD might be necessary depending on your requirements.

Diagram

The following diagram shows an overview of the steps for implementing remote deployment of a runtime environment using local libraries.

For details about each of the numbered steps in the diagram, refer to the following sections.

1. CREATE or MIGRATE actions

On the configuration system, use the CREATE or MIGRATE action to create the initial local libraries and members that will contain the configuration settings of your target system.

Include the following parameters:

RTE_NAME: Specify the name of the runtime environment that will be active on the target system.
RTE_PLIB_HILEV: Specify the high-level qualifier for the runtime definition (RTEDEF) library to be used on the target system.
KFJ_LOCAL_PLIB_HILEV: Specify the high-level qualifier of the local libraries on the configuration system, which will be used for building the configuration-only runtime environment that will be deployed.

ACTION                CREATE | MIGRATE
RTE_NAME              RTEB 
RTE_PLIB_HILEV        PROD.OMEG
KFJ_LOCAL_PLIB_HILEV  DEV.OMEG

Results

Local library data sets and members are created on the configuration system as a result of this step, as follows:

Local libraries are created on the configuration system using the value specified in KFJ_LOCAL_PLIB_HILEV as the high-level qualifier.
The following members are created in the local library RTEDEF data set:
- Member rte_name is named using the value specified in parameter RTE_NAME. The RTE_PLIB_HILEV parameter and value appear in this member. For more information about the contents of this member, see RTEDEF(rte_name). This member is used for settings for the target system.
- Member PCK$PARM is created and contains information about the configuration system. This member is used to map parameters and values in the configuration-only runtime environment to the target system. For more information about the contents of this member, see RTEDEF(PCK$PARM).
- Product and component-specific members Kpp$PARM (or Kpp$lpar) and GBL$PARM (or GBL$lpar) are created. These members are used for settings for the target system.
  In this example, KDS$PARM, KGW$PARM, and GBL$PARM are created.
For more information about these RTEDEF members, see Initial runtime environment library members.
Note: The RTE_NAME and RTE_PLIB_HILEV parameter values are used to populate some parameter values. Other parameter values are set by default to settings for the configuration system. Customization of parameter values occurs in a subsequent step.
A default security exits library is created: kfj_local_plib_hilev.rte_name.SECEXITS

In this example, local libraries using the high-level qualifiers DEV.OMEG are created on the configuration system, as follows:

DEV.OMEG.RTEB.SECEXITS
DEV.OMEG.RTEDEF  
  Members: RTEB
           KDS$PARM
           KGW$PARM
           GBL$PARM
           PCK$PARM

2. DISCOVER action

On the target system, run the DISCOVER action to discover the subsystems and system symbols.

Include the following parameters, set to the same values that were used in the CREATE (or MIGRATE) action in the previous step:

RTE_NAME: Specify the name of the runtime environment that will be active on the target system.
RTE_PLIB_HILEV: Specify the high-level qualifier for the runtime definition (RTEDEF) library to be used on the target system.

ACTION                DISCOVER
RTE_NAME              RTEB 
RTE_PLIB_HILEV        PROD.OMEG

Notes:

Parameter KFJ_LOCAL_PLIB_HILEV is not used with the DISCOVER action on the target system.
You must change the program name from KCIOMEGA to KCIALPHA for the DISCOVER job.
You do not need to run the CREATE action on the target system before running the DISCOVER action.

Results

This action creates an RTEDEF data set on the target system using the value specified in RTE_PLIB_HILEV as the high-level qualifier. This data set contains the Kpp@lpar members for the subsystems discovered on the target system and the SYS@lpar member containing the system symbols.

In this example, the RTEDEF data set is created on the target system using the high-level qualifiers PROD.OMEG and includes the members for the subsystems and system symbols, as follows:

PROD.OMEG.RTEDEF  
  Members: Kpp@SYSB
           SYS@SYSB

The Kpp@lpar members that are created depend on the subsystems installed on the system.

Note: When discovering MQ subsystems, the DISCOVER action creates only a comment member, as indicated by the hash (#) in the member name. For more information, see RTEDEF(KMQ#lpar).

3. Manual steps to transfer and merge your DISCOVER results

Transfer the members created by the DISCOVER action (members Kpp@lpar and SYS@lpar) from the rte_plib_hilev.RTEDEF data set on the target system to the kfj_local_plib_hilev.RTEDEF data set on the configuration system.

In this example, members Kpp@SYSB and SYS@SYSB are copied from data set PROD.OMEG.RTEDEF on the target system to data set DEV.OMEG.RTEDEF on the configuration system.

4. Manual steps to customize your runtime environment before generating runtime members

On the configuration system, customize your configuration-only runtime environment. Perform customization as follows:

Customize the following RTEDEF members to reflect settings on the target system:
- Members KDS$PARM, KGW$PARM, and GBL$PARM were created using default values from the configuration system. You must review the parameter values in these members to reflect the appropriate settings for the target system.
- In the other Kpp$PARM or Kpp$lpar members, specify the high-level qualifiers needed and features enabled.
Important: There are some limitations regarding the parameters that can be customized. Certain parameters are not allowed in the respective RTEDEF members. For the list of parameters, see Parameters that cannot be customized for remote deployment.
Customize the following RTEDEF member to reflect settings on the configuration system:
- In member PCK$PARM, you must provide z/OS® UNIX System Services paths for allocating the runtime environment data sets or z/OS UNIX directories on the configuration system.
  Important: Because these values are used to generate the runtime members on the configuration system in the next step, you must specify valid local values for parameters KFJ_LOCAL_USS_RTEDIR and KFJ_LOCAL_USS_TKANJAR_PATH.
  
  Tip: The settings in RTEDEF(PCK$PARM) are applicable for all runtime environments configured in the RTEDEF data sets; that is, for all runtime environments of the respective SYSPLEX. If you want to use a different local high-level qualifier for a specific target system system on the configuration system, you can create member RTEDEF(PCK$lpar) by copying RTEDEF(PCK$PARM) and making the respective changes.

5. GENERATE action

On the configuration system, use the GENERATE action to generate runtime members for the runtime environment using the configured parameters. The runtime members are for the runtime environment that will be deployed to the target system and is being configured on the configuration system.

Include the following parameters:

RTE_NAME: Specify the name of the runtime environment that will be active on the target system. Use the same value specified in the CREATE action.
RTE_PLIB_HILEV: Specify the high-level qualifier for the runtime definition (RTEDEF) library to be used on the target system. Use the same value specified in the CREATE action.
KFJ_LOCAL_PLIB_HILEV: Specify the high-level qualifier of the local libraries on the configuration system. Use the same value specified in the CREATE action.
KFJ_SYSNAME: Specify the target system. The value is the SYSNAME or LPAR name, or the SYSSMFID if the LPAR name is longer than four characters. You must specify this parameter for the DISCOVER-generated members Kpp@lpar and SYS@lpar to be used.

ACTION                GENERATE
RTE_NAME              RTEB 
RTE_PLIB_HILEV        PROD.OMEG
KFJ_LOCAL_PLIB_HILEV  DEV.OMEG
KFJ_SYSNAME           SYSB

Results

The GENERATE action creates numerous runtime environment data sets and members in the local libraries on the configuration system using the value specified in KFJ_LOCAL_PLIB_HILEV as the high-level qualifier. The parameters in the runtime members are configured to run on the target system using the RTE_PLIB_HILEV parameter value as the high-level qualifier.

Important: The configuration runtime environment cannot run on the configuration system. The configuration settings are for the target system.

In this example, the runtime environment data sets and members are generated in the local libraries on the configuration system using the high-level qualifiers DEV.OMEG and the settings defined in DEV.OMEG.RTEDEF, including the PCK$PARM member. The following data sets are generated and populated:

DEV.OMEG.*
DEV.OMEG.RTEB.*

The content of the members point to the target system, as shown, for example, in member DEV.OMEG.RTEB.RKANPARU(KPQHINIT):

PDSV1=OFF
PDSV2=ON
DSNHILEV=PROD.OMEG.RTEB
VOLUME=
STORCLAS=
MGMTCLAS=
DATACLAS=
ALLOC_TYPE=CYL

The GENERATE action also maps the high-level qualifiers and z/OS UNIX System Services paths in the local libraries on the configuration system to the runtime libraries on the target system. You can see the mapping results in the GENERATE job output in the KCIPRINT DD.

Note: If you use OPTION DEBUG with the GENERATE action, the mapping results are retained in the KFJSDIFM DD in the job output.

The following figure shows the mapping table that was used in this example:

Figure 2. Local library mapping to target system (in KCIPRINT DD)

KFJ00211I Configuration Manager is allocating data sets using local settings for high level qualifiers and z/OS UNIX system services paths

Configuration LPAR high level qualifiers                             | Target LPAR high level qualifiers   
and z/OS UNIX system services paths                                  | and z/OS UNIX system services paths
------------------------------------------------------------------------------------------------------------------------------------------
KFJ_LOCAL_PLIB_HILEV        DEV.OMEG                                 | RTE_PLIB_HILEV         PROD.OMEG
KFJ_LOCAL_HILEV             DEV.OMEG                                 | RTE_HILIV              PROD.OMEG
KFJ_LOCAL_VSAM_HILEV        DEV.OMEG                                 | RTE_VSAM_HILEV         PROD.OMEG
KFJ_LOCAL_PDS_HILEV         DEV.OMEG.RTEB                            | RTE_PDS_HILEV
KFJ_LOCAL_TARGET_HILEV      DEV.ZSMS21R.SMPE                         | GBL_TARGET_HILEV       PROD.ZSMS21R.SMPE
KFJ_LOCAL_SMS_VOLUME                                                 | RTE_SMS_VOLUME
KFJ_LOCAL_SMS_VSAM_VOLUME                                            | RTE_SMS_VSAM_VOLUME
KFJ_LOCAL_SMS_UNIT                                                   | RTE_SMS_UNIT
KFJ_LOCAL_SMS_STORCLAS                                               | RTE_SMS_STORCLAS 
KFJ_LOCAL_SMS_VSAM_STORCLAS                                          | RTE_SMS_VSAM_STORCLAS
KFJ_LOCAL_SMS_MGMTCLAS                                               | RTE_SMS_MGMTCLAS
KFJ_LOCAL_SMS_VSAM_MGMTCLAS                                          | RTE_SMS_VSAM_MGMTCLAS 
KFJ_LOCAL_USS_RTEDIR        /dev/rtehome                             | RTE_USS_RTEDIR         /prod/rtehome
KFJ_LOCAL_USS_TKANJAR_PATH  /dev/my/smpe                             | GBL_USS_TKANJAR_PATH   /prod/my/smpe
------------------------------------------------------------------------------------------------------------------------------------------

6. PACKAGE action

On the configuration system, run the PACKAGE action to build transferable dump data sets.

Include the following parameters:

RTE_NAME: Specify the name of the runtime environment that will be active on the target system. Use the same value specified in the CREATE action.
RTE_PLIB_HILEV: Specify the high-level qualifier for the runtime definition (RTEDEF) library to be used on the target system. Use the same value specified in the CREATE action.
KFJ_LOCAL_PLIB_HILEV: Specify the high-level qualifier of the local libraries on the configuration system. Use the same value specified in the CREATE action.

ACTION                PACKAGE
RTE_NAME              RTEB 
RTE_PLIB_HILEV        PROD.OMEG
KFJ_LOCAL_PLIB_HILEV  DEV.OMEG

Note: (Optional) You can use parameter KFJ_PACK_HILEV with the PACKAGE action to specify a custom high-level qualifier for the output package data sets, which can be useful to distinguish the package data sets from the many runtime environment data sets in the local libraries.

Results

The PACKAGE action allocates the following package data sets:

kfj_local_plib_hilev.rte_name.PACKxx.DMP
kfj_local_plib_hilev.rte_name.PACKMD

where xx is MN (Main non-VSAM), MV (Main VSAM), HN (History non-VSAM), or HV (History VSAM).

Note: If you included parameter KFJ_PACK_HILEV, the specified value is used as the high-level qualifier of the package data sets.

For more information about the package data sets, see PACKAGE.

In this example, the following package data sets are created:

DEV.OMEG.RTEB.PACKxx.DMP
DEV.OMEG.RTEB.PACKMD

7. Manual steps to transfer your package data sets to the remote system

Transfer the package data sets from the configuration system to the target system using the procedure of your choice (for example, FTPS). Make sure to transfer both the DMP and PACKMD data sets. You can rename the high-level qualifier of the data sets if necessary.

In this example, the high-level qualifier of the package data sets is renamed from DEV.OMEG on the configuration system to TRNSFER.OMEG on the target system.

8. DEPLOY on target system

On the target system, use the DEPLOY action to restore the package data sets that have been transferred from the configuration system.

Include the following parameters:

RTE_NAME: Specify the name of the runtime environment that will be active on the target system. Use the same value specified in the CREATE action.
RTE_PLIB_HILEV: Specify the high-level qualifier for the runtime definition (RTEDEF) library to be used on the target system. Use the same value specified in the CREATE action.
KFJ_PACK_HILEV: Specify the high-level qualifier of the package data sets on the target system. This parameter is required if the high-level qualifier does not match the RTE_PLIB_HILEV parameter value.

ACTION                DEPLOY
RTE_NAME              RTEB 
RTE_PLIB_HILEV        PROD.OMEG
KFJ_PACK_HILEV        TRNSFER.OMEG

Results: The DEPLOY action restores the package data sets with the KFJ_PACK_HILEV parameter value as the high-level qualifier to data sets the with RTE_PLIB_HILEV parameter value as the high-level qualifier. The restored data sets constitute the deployed runtime environment.
In this example, package data sets TRNSFER.OMEG.RTEB.PACKxx.DMP are restored to runtime data sets with high-level qualifier PROD.OMEG. The PROD.OMEG data sets are the runtime libraries for the deployed runtime environment.
Note: Although the PACKMD metadata file itself is not restored, the DEPLOY action requires the PACKMD file when local libraries are used for remote deployment.

9. Manual steps to adjust or copy your started task procedures

On the target system, adjust or copy your started task procedures.