DEPLOY

Edit online

The DEPLOY action deploys a packaged runtime environment to a remote system.

Before you begin

Review the following information before you use the DEPLOY action:
  • You can run the DEPLOY action only after you have successfully packaged a runtime environment using the PACKAGE action.
  • The DEPLOY action uses z/OS DFSMSdss commands. You might need authority to run ADRDSSU, which is the program that is invoked when using DFSMSdss. If authorization is required, DFSMSdss issues error message ADR707E. For more information, see z/OS DFSMSdss Storage Administration Guide: Protecting DFSMSdss functions with RACF FACILITY class profiles.
  • If you do not have any SMP/E target libraries on the system on which you want to run a DEPLOY action, you can use the utility TKANSAM(KFJMAINT) with the BLDREMDS action to build the necessary minimum data sets (TKANSAM, TKANMOD, and TKANCUS libraries) needed to run the action. Make sure you transfer the created data sets to your remote system where DEPLOY should run and where the necessary APF authorization of the TKANMOD library is made. These SMP/E target libraries are the minimum required to allow Configuration Manager to run for a full runtime environment. However, for a runtime environment that you are sharing with SMP/E, you will need to copy your entire set of SMP/E target libraries to the system where you run the DEPLOY action.
Important: When you use the DEPLOY action, the target runtime environment data sets will be updated. Verify that these data sets are not in use before you use the DEPLOY action.
Important: The PACKAGE action creates a metadata file named package_hlq.rte_name.PACKMD. The DEPLOY action requires the PACKMD metadata file if a data set is renamed, which can occur if the KFJ_LOCAL_* parameters (in the KCIVARS DD and in the PCK$PARM member) are used when creating the package. If the PACKMD file is not available, the DEPLOY action restores packages as is, retaining all high-level qualifiers and SMS properties, and you might experience unpredictable results in your deployment. It is recommended that you use the PACKMD metadata file when using the DEPLOY action.
Related topics

About this task

The following list provides details about the DEPLOY action:
  • The DEPLOY action deploys a runtime environment by restoring package data sets generated by the PACKAGE action on a target system. The DEPLOY action uses DFSMSdss to restore the data sets.
  • The DEPLOY action requires the use of the KCIALPHA program. KCIALPHA is an APF-authorized version of KCIOMEGA.
  • You must specify high-level qualifier values that are used for locating existing data sets. The following parameters are used for specifying high-level qualifiers:
    RTE_PLIB_HILEV
    (Required) Specifies the high-level qualifiers for locating the runtime environment definition (RTEDEF) library. You must specify this parameter and value for the DEPLOY action.
    KFJ_PACK_HILEV
    (Optional) Specifies the high-level qualifier value for the package data sets. If this parameter is not specified, the value for parameter RTE_PLIB_HILEV is used.
    Important: You must use parameter KFJ_PACK_HILEV with the DEPLOY action if you transferred your package data sets with a high-level qualifier that is different from RTE_PLIB_HILEV.
    Note: It is recommended that you specify the KFJ_PACK_HILEV parameter when deploying your runtime environment.
    Note: Parameter KFJ_LOCAL_PLIB_HILEV is not supported on the DEPLOY action.
  • You can optionally control when to run the DEPLOY workflow stage that deploys the parts related to z/OS® UNIX® System Services. By default, the DEPLOY action automatically deploys files and directories related to z/OS UNIX, if they are present in the packaged runtime environment data sets. However, there might be cases where you want to skip this step (for reasons such as authorization issues), and perform this step at a later time. You can use the OPTION parameter to specify the NOUSS or USS value to control this processing, as follows:
    NOUSS

    When OPTION NOUSS is specified, the DEPLOY action does not run the stage that deploys the parts related to z/OS UNIX.

    With this option, only z/OS data sets are deployed; files and directories related to z/OS UNIX are bypassed.

    USS

    When OPTION USS is specified, the DEPLOY action runs only the stage that deploys the parts related to z/OS UNIX; no other processing is performed.

    This option is useful when you want to refresh files and directories related to z/OS UNIX only.

  • The DEPLOY action performs an unconditional restore for the main VSAM and non-VSAM packages (fully replaces the data sets) and a conditional restore for the history packages (does not replace existing data sets). Note the following behaviors:
    • If the history dump data sets (**.PACKHN or **.PACKHV) are not found or failed to restore, a return code of 4 will be generated.
    • If the main dump data sets (**.PACKMN or **.PACKMV) are not found or failed to restore, a return code of 8 will be generated.
    Note: The DEPLOY action replaces some main package VSAM and non-VSAM files, but does not replace any history-related files. Therefore, it is normal for PACKHN and PACKHV deploy flows to end with RC=8. If you want to avoid this, for example if you roll out maintenance, do not transfer these packages to the target system. While normally a return code of 8 would cause Configuration Manager to stop, in this particular situation (history files), a return code of 8 is considered acceptable and will not prevent Configuration Manager from continuing to function.
  • When restoring (and potentially untersing) the packaged runtime environment, the DEPLOY action reuses the following parameters that were used with the PACKAGE action:
    • KFJ_PACK_HILEV
    • KFJ_ADRDSSU_ADMIN
    • KFJ_PACK_TERSE
    • KFJ_PACK_DATACLAS
    • KFJ_PACK_UNIT
    • KFJ_PACK_VOLUME
    See PACKAGE for information about these parameters.
  • If KFJ_PACK_TERSE is set to Y, the DEPLOY action first unterses the package. The untersed DMP file high-level qualifier and SMS parameters are used as specified in the following parameters:
    • RTE_PLIB_HILEV
    • RTE_SMS_MGMTCLAS
    • RTE_SMS_STORCLAS
    • RTE_SMS_UNIT
    • RTE_SMS_VOLUME
  • For large packages being untersed, you should use KFJ_PACK_DATACLAS accordingly to allow multi-volume data set allocation for the extracted package files.
  • If KFJ_PACK_UNIT or KFJ_PACK_VOLUME is specified, it applies to all of the packages being untersed.
  • If RTE_SMS_VOLUME is specified but RTE_SMS_MGMTCLAS is not, RTE_SMS_MGMTCLAS defaults to NULLMGMTCLAS. Similarly, RTE_SMS_STORCLAS defaults to NULLSTORCLAS.

To run the DEPLOY action, complete the following steps.

Procedure

  1. Locate the dump (.DMP) data sets and the metadata file (.PACKMD) that were created by the PACKAGE action.
    The naming convention of the package data sets is package_hlq.rte_name.PACKMD, where package_hlq is the value of parameter KFJ_PACK_HILEV or RTE_PLIB_HILEV.
    Note: It is possible that the high-level qualifier value was modified when transferring the package data sets to the remote system.
  2. Modify the KFJJMCM sample job in TKANSAM (see example below) to select a DEPLOY action.
  3. Change the program name in the JCL EXEC statement from KCIOMEGA to KCIALPHA.
  4. Specify values for the required parameters RTE_NAME and RTE_PLIB_HILEV.
  5. (Optional) Specify any additional parameters as needed.
    Important: You must use parameter KFJ_PACK_HILEV if you transferred your package data sets to the remote system with a high-level qualifier that is different from the RTE_PLIB_HILEV parameter value.
  6. Run the KFJJMCM job to perform the deploy process and restore the related package files.
    Job messages for the DEPLOY action are written to the KCIPRINT SYSOUT data set and to the $REPORT DD. If return code 4 or 8 is received, review the $REPORT DD statement in the JCL job output to ensure that the restore process completed successfully. For more information, see DEPLOY action output.

Example

The following examples restore (deploy) the data sets for a runtime environment that has been packaged by the PACKAGE action.
Using default high-level qualifier with parameter RTE_PLIB_HILEV

In this example, the package data sets were named using the default high-level qualifier of the runtime definition library and were transferred to the remote system using the same file names.

The packaged data sets contain the runtime environment named RTE1 and the runtime environment definition library TSOUID.MONSUITE.RTEDEF.

The packaged data sets are named TSOUID.MONSUITE.RTE1.PACK*.

The following DEPLOY action job, run on the remote system, deploys (restores) the package data sets on the target LPAR to data sets with the high-level qualifier TSOUID.MONSUITE.

Figure 1. Example JCL to perform the DEPLOY action using default high-level qualifier
//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID 
/*JOBPARM SYSAFF=ZOS1 
//S1 EXEC PGM=KCIALPHA,REGION=0M,DYNAMNBR=256 
//STEPLIB DD DISP=SHR,DSN=MONSUITE.TKANMOD 
//KCIFLOW DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA) 
//KCIVARS DD * 
ACTION            DEPLOY 
RTE_NAME          RTE1 
RTE_PLIB_HILEV    TSOUID.MONSUITE 
/*
Using custom high-level qualifier with parameter KFJ_PACK_HILEV

You must use parameter KFJ_PACK_HILEV with the DEPLOY action if you transferred your package data sets to the remote system with a high-level qualifier that is different from the RTE_PLIB_HILEV parameter value.

In this example, the package data sets contain the runtime environment named RTE1 and the runtime environment definition library TSOUID.MONSUITE.RTEDEF. However, the files were transferred to the remote system using the high-level qualifier TESTSYS.

As a result, the package data sets on the remote system are named TESTSYS.MONSUITE.RTE1.PACK*, requiring the use of parameter KFJ_PACK_HILEV.

Figure 2. Example JCL to perform the DEPLOY action using custom high-level qualifier
//UID#ZMCM JOB ,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID 
/*JOBPARM SYSAFF=ZOS1 
//S1 EXEC PGM=KCIALPHA,REGION=0M,DYNAMNBR=256 
//STEPLIB DD DISP=SHR,DSN=MONSUITE.TKANMOD 
//KCIFLOW DD DISP=SHR,DSN=MONSUITE.TKANCUS(KFJOMEGA) 
//KCIVARS DD * 
ACTION            DEPLOY 
RTE_NAME          RTE1 
RTE_PLIB_HILEV    TSOUID.MONSUITE
KFJ_PACK_HILEV    TESTSYS.MONSUITE
/*