PACKAGE

The PACKAGE action packages a runtime environment that can then be deployed to a remote system.

Before you begin

Review the following information before you use the PACKAGE action:
  • You can run the PACKAGE action only after you have successfully generated a runtime environment using the GENERATE action. For more information about the complete remote deployment process, see Remote deployment scenario.
  • The PACKAGE action uses the z/OS DFSMSdss DUMP command. You might need authority to run ADRDSSU, which is the program that is invoked when using DFSMSdss.
    Specifically, the PACKAGE action uses the DUMP command keywords CONCURRENT and TOLERATE(ENQFAILURE). The use of these keywords with the DUMP command is controlled by the following RACF FACILITY class profiles:
    Table 1. RACF FACILITY class profile names for DFSMSdss keywords
    Keyword Profile Name
    CONCURRENT with DUMP STGADMIN.ADR.DUMP.CNCURRNT
    TOLERATE(ENQF) with DUMP STGADMIN.ADR.DUMP.TOLERATE.ENQF

    Make sure that you have the proper RACF authority to use DFSMSdss and these keywords. 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.

  • Before you run the PACKAGE action, perform the following important steps:
    • For an existing runtime environment, stop the started tasks for that runtime environment. Started tasks can lock runtime members, which can cause the PACKAGE action to fail.
    • For the SMS-managed data sets for the runtime environment to be packaged, make sure that any migrated data sets are recalled.
Related topics

About this task

The following list provides details about the PACKAGE action:
  • The PACKAGE action uses the z/OS DFSMSdss DUMP command to create a series of data sets that contain the runtime environment. These dump files can be transferred across SYSPLEX boundaries, using methods like FTPS. The PACKAGE action is used in conjunction with the DEPLOY action.
  • The PACKAGE action requires the use of the KCIALPHA program. KCIALPHA is an APF-authorized version of KCIOMEGA.
  • You must specify high-level qualifier values for locating existing data sets and for allocating the output package data sets. The following parameters are used for specifying high-level qualifiers:
    RTE_PLIB_HILEV
    (Required) Specifies the high-level qualifiers for the runtime environment definition (RTEDEF) library, as follows:
    • If local libraries are not used (that is, parameter KFJ_LOCAL_PLIB_HILEV is not specified), RTE_PLIB_HILEV specifies the high-level qualifier of the RTEDEF library on the configuration system.
    • If local libraries are used (that is, parameter KFJ_LOCAL_PLIB_HILEV is also specified), RTE_PLIB_HILEV specifies the high-level qualifier of the RTEDEF library on the remote (target) system.

    You must specify the RTE_PLIB_HILEV parameter and value for the PACKAGE action.

    KFJ_LOCAL_PLIB_HILEV
    (Optional) Specifies the high-level qualifier for the local libraries. You must specify this parameter and value for the PACKAGE action if the parameter was used with the CREATE and GENERATE actions when building the runtime environment to be packaged. Otherwise, do not specify this parameter for the PACKAGE action. For more information on using local libraries for remote deployment, Remote deployment example using local libraries.
    Note: Parameter KFJ_LOCAL_PLIB_HILEV is used when packaging the runtime environment; it is not used when deploying the package.
    KFJ_PACK_HILEV
    (Optional) Specifies 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. If this parameter is not specified, the value for parameter KFJ_LOCAL_PLIB_HILEV (if specified) or RTE_PLIB_HILEV is used as the high-level qualifier for the output package data sets.
  • The PACKAGE action creates the following package data sets:
    • A set of dump data sets using the following naming convention:
      package_hlq.rte_name.PACKxx.DMP
      where:
      • package_hlq is one of the following values:
        • KFJ_PACK_HILEV parameter value, if specified
        • KFJ_LOCAL_PLIB_HILEV parameter value, if KFJ_PACK_HILEV is not specified
        • RTE_PLIB_HILEV parameter value, if neither KFJ_PACK_HILEV or KFJ_LOCAL_PLIB_HILEV is specified
        To avoid exceeding the z/OS 44-character limit for data set names, the combined length of package_hlq and rte_name should not exceed 28 characters. For example, if rte_name is 8 characters, then package_hlq should not exceed 20 characters.
      • xx is one of the following package codes:
        MN
        Main non-VSAM package. Contains data sets from the RTE_HILEV libraries and some from the RTE_PLIB_HILEV libraries.
        MV
        Main VSAM package. Contains non-history related VSAM data sets from the RTE_VSAM_HILEV libraries.
        HN
        History non-VSAM package. Contains history-related data sets from the RTE_PDS_HILEV libraries.
        HV
        History VSAM package. Contains history-related data sets from the RTE_VSAM_HILEV libraries.
    • A metadata file named package_hlq.rte_name.PACKMD. This flat file is not tersed or dumped and is required for the DEPLOY action if local libraries are used for the deployment.
  • You can specify the following optional parameters in the KCIVARS DD statement when running the PACKAGE action:
    KFJ_ADRDSSU_ADMIN
    Specifies whether to use the ADMINISTRATOR keyword with z/OS DFSMSdss commands. Valid values are Y and N. The default is N. This option might be required depending on the security settings at your site.
    KFJ_PACK_TERSE
    Specifies if the dump data sets should also be tersed. Valid values are Y and N. The default is N. Specify Y if you want to transfer the packages using FTP. In this case, the dump files will be tersed and only the tersed copy will be retained.
    Note: If you are using virtual tapes to transfer your data sets, tersing the dump files is not necessary.
    If specified, the following parameters will be used for both the DMP and DMP.TRS data sets:
    KFJ_PACK_DATACLAS
    Specifies the data class for the package. This setting is needed for large package files or tersed files as it allows you to specify multiple volumes.
    KFJ_PACK_MGMTCLAS
    Specifies he management class for the package.
    KFJ_PACK_STORCLAS
    Specifies the storage class for the package.
    KFJ_PACK_UNIT
    Specifies the unit for the package if non-SMS or virtual tape is used.
    KFJ_PACK_VOLUME
    Specifies the volume for the package if non-SMS or virtual tape is used.
  • You can use the OPTION NOUSS parameter to bypass the z/OS® UNIX System Services workflow stage and not include any related files or directories in the produced output data sets.

To run the PACKAGE action, complete the following steps.

Procedure

  1. Update the KFJJMCM sample job in TKANSAM as follows (see example below):
    1. Select a PACKAGE action.
    2. Change the program name in the JCL EXEC statement from KCIOMEGA to KCIALPHA.
    3. Specify values for the required parameters RTE_NAME and RTE_PLIB_HILEV.
    4. (Optional) Specify any additional parameters as needed.
  2. For an existing runtime environment, stop the started tasks for that runtime environment.
  3. Make sure that any migrated SMS-managed data sets to be packaged have been recalled.
  4. Run the KFJJMCM job to perform the packaging process and generate the related package files.
    Job messages for the PACKAGE action are written to the KCIPRINT SYSOUT data set.

Results

The packaging dump data sets and the metadata file are created.

Example

The following JCL creates DUMP data sets for the runtime environment that is defined by members of the TSOUID.MONSUITE.RTEDEF library.

Figure 1. Example JCL to perform the PACKAGE action
//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            PACKAGE 
RTE_NAME          RTE1 
RTE_PLIB_HILEV    TSOUID.MONSUITE 
/*

What to do next

Transfer the files to the target system using a method like FTPS, and run the DEPLOY action.