Db2 for z/OS and its ecosystem

 View Only

Continuous Innovations for the Db2 for z/OS migration process

By M. Sueli Almeida posted Mon May 06, 2024 08:34 PM



One of our ultimate goals is to make the Db2 migration process a smooth experience without impacting your workload and environment. The continuous delivery approach puts new features at your hands by simply applying Db2 maintenance and enabling function levels when that is required. However, there will still be times when a migration to a higher version will be required. For those situations, we implemented several enhancements to support Db2 online migration. Db2 13 has dramatically simplified the migration process by validating migration readiness, displaying blockers that would prevent the migration process, and more.

While the Db2 engine provides those enhancements to ease migration, we have also enhanced and modernized the migration process itself, offering our customers options that would help them to:

  • Compensate for general weakening of traditional z/OS skills with a new user experience for Db2 for z/OS lifecycle operations
  • Automate task management for migrating Db2 for z/OS subsystems and data sharing groups
  • Standardize migration procedures for many Db2 subsystems

Our journey is leading us to a “one-click” migration.

With Db2 11, we started supporting z/OSMF workflows for Db2 installation and migration, and since then we have evolved to generating migration artifacts in background mode, and currently we are enhancing the auto-discovery of Db2 parameters. Once we can discover all the required configuration parameters, the process can be automated where you would indicate the Db2 system that is to be migrated, and we can generate all the migration artifacts for z/OSMF workflows or for traditional jobs. With the generated artifacts, different levels of automation can be used. For example, automation to build the z/OSMF workflow, automation to execute that workflow, automation to execute traditional jobs, and more.

z/OSMF Support for a Simpler Db2 Installation & Migration

z/OSMF (IBM z/OS Management Facility) is a standard feature of z/OS that must be enabled for usage in your environment. When enabling z/OSMF,  you must certify that the plugin for workflow support is also enabled.

In general, a z/OSMF workflow has three main artifacts

  • z/OSMF workflow definition XML file
  •   z/OSMF variable input file
  • Tailored JCL templates

Historically, Db2 customers started building their own workflows to standardize and modernize their migration processes for future generations. However, although they were very knowledgeable with the Db2 migration process, they were not familiar with XML, and they were not able to progress with this task.

Db2 development added the support to generate the z/OSMF artifacts by using the Db2 installation CLIST (DSNTINST). By executing DSNTINST, you can generate the required artifacts for the workflow without you having to write a single line of XML code.

To enable that support, some DSNTINST panels were updated, and new ones added. The following updated and new CLIST panels are important for the successful creation and execution of the z/OSMF artifacts.

1. The very first panel, DSNTIPA1/DSNTILA1 was modified to introduce the option to generate z/OSMF artifacts.

Notice that when you specify YES to use z/OSMF workflow, you see an underscore in front of fields 4–7. When a field is selected the field becomes a z/OSMF input variable that is stored in the z/OSMF variable input file. Otherwise, the value of that field is hardcoded in the JCL templates.

2. The panel DSNTIPM5 below is new, and its information is important for the workflow execution.

The user ID that you enter in the CONSOLE NAME field must have RACF master console authority, and it will be used under the covers by the workflow when issuing Db2 STOP/START commands during the workflow execution.

3. The panels below, DSNTIPMS, DSNTIPMT, DSNTIPMN and DSNTIPMD are also new. They show the job steps for migration. The mandatory migration steps are selected and cannot be deselected.  Some optional steps are selected by default and can be deselected.  You can select any optional steps that have not been selected by default.

  • Panel DSNTIPMS is a panel for choosing steps for migrating a non-data sharing Db2 subsystem or the first member of a data sharing group to Db2 13.

  • The steps on panel DSNTIPMS continue on panel DSNTIPMT. 
    The job steps selected in DSNTIPMS and DSNTIPMT are incorporated into the DSNTIWMS migration workflow.
    The DSNTIWMS workflow is for migrating to V13R1M100.

  • Panel DSNTIPMN is a panel for choosing steps for completing the Db2 13 migration process.
    The job steps selected in DSNTIPMN are incorporated into the DSNTIWMN migration workflow.
    The DSNTIWMN workflow is for migrating to a higher function level, such as V13R1M500, V13R1M501, ….

  • Panel DSNTIPMD is a panel for choosing steps for migrating subsequent data sharing group members to Db2 13.
    The job steps selected in DSNTIPMD are incorporated into the DSNTIWMD migration workflow.


4. Another important panel added is DSNTIPM1. In this panel, you indicate where the CLIST-generated z/OSMF artifacts are going to be stored.

  • The workflow definition file and the variable input file are stored in the library specified for WORKFLOW DEFINITION LIBRARY. 
  • The JCL skeleton files are stored in the library specified for JCL TEMPLATE LIBRARY 
  •  All the z/OSMF artifacts are stored in the ZFS path specified for PATH FOR Z/OSMF ARTIFACTS.

Tip: The CLIST-generated z/OSMF artifacts can be saved in a library or in a ZFS directory, but we strongly recommend that you save the artifacts in a ZFS directory, where you will be allowed to edit the artifacts if you want to make further adjustments. The z/OSMF workflow editor currently doesn’t support editing PDS files.

In a nutshell, to generate the z/OSMF workflow for Db2 migration when executing DSNTINST, you must perform the following steps at the minimum:

  2. Select fields in the CLIST panels to be input variables within the workflow.
  3. Specify a user ID (CONSOLE NAME) with master console authority (DSNTIPM5).
  4. Select optional migration jobs to be included in the migration workflow (DSNTIPMS, DSNTIPMT, DSNTIPMN, DSNTIPMD)
  5. Specify the library for the CLIST-generated z/OSMF workflow definition file, variable input file, and JCL templates (DSNTIPM1).
  6. Optionally but highly recommended, specify the name of the ZFS path for the CLIST-generated z/OSMF workflow definition file, variable input file, and JCL templates (DSNTIPM1).

Now that you have the z/OSMF artifacts ready, the next step is to create a workflow instance in z/OSMF.

But before we look at the steps to create and execute the workflow,  I want to show you that you can now generate those artifacts (z/OSMF or traditional JCL jobs) in background mode if you have a current and valid input DSNTIDxx file. Basically, the approximate 30 minutes it normally takes to execute the installation CLIST in the foreground to generate the artifacts can now be accomplished in about 2–3 minutes in background mode. This is another step towards our “one-click” migration goal.

Generating Db2 Migration Artifacts in Background Mode

This support was introduced via the following APAR/PTFs:

·         PH52482/UI91497
This APAR introduces the following program, sample job and sample parameter override files:


  • Program DSNTIFMT 
    DSNTIFMT formats the Db2 installation CLIST DSNTINST into a member called DSNTINSB which is then executed to generate customized migration artifacts in batch. The generated DSNTINSB CLIST is similar to DSNTINST but can be called using JCL to be executed in the background mode.
  • Sample job DSNTIJBC
    DSNTIJBC consists of these two basic steps:
    • Executes the program DSNTIFMT, which creates the CLIST DSNTINSB
    • Starts DSNTINSB using ISPSTART to run DSNTINSB in batch mode

  • Sample parameter override files DSNTIDOM, DSNTIDON, and DSNTIDOA DSNTIDOM, DSNTIDON, and DSNTIDOA are sample parameter override files which consist of a subset of CLIST parameters and their respective values.

    A customized parameter override file must be passed to the DSNTINSB CLIST. The value specified in an override file for a specific CLIST parameter becomes the value of that parameter in the output DSNTIDxx file generated by DSNTINSB.

    The customized override file that you pass to DSNTINSB depends on which activity the DSNTINSB CLIST is set up to do:
    • DSNTIDOM – Migrate 1st member of a data sharing group or a stand-alone Db2 system
    • DSNTIDON – Migrate additional member of a data sharing group
    • DSNTIDOA – Activate function level

    ·         PH52882/UI91519 for Db2 Value Unit Edition(VUE) environments

    This APAR introduces a fourth sample parameter override file:

    • Sample parameter override file DSNTIDVU 
      DSNTIDVU contains parameters that you must initialize when you are using Db2 Value Unit Edition. When you are using Db2 Value Unit Edition, you must also pass this override file to the DSNTINSB CLIST.

    With this feature, you can generate the Db2 migration artifacts in less than 3 minutes, if you have a valid and current input DSNTIDxx file. If your DSNTIDxx file is from a traditional installation or migration of that Db2 system, you can choose to generate artifacts for traditional jobs or for the z/OSMF workflows.

    How Does it Work?

      1. Certify that you have a valid and current DSNTIDxx file.
      2. Customize the DSNTIJBC sample job for your environment, by following the instructions in the DSNTIJBC job prolog. For example:

        If you use Db2 Value Unit Edition, you must also provide the data set name of the DSNTIDVU parameter override file in the IPSTART command in the DSNTIJBC job, as shown in the following example, where <prefix>.SDSNSAMP(DSNTIDVU) is your customized OTC LICENSE file.

                        OVERPARM(IVTD10.E21116.S21117.MIGRATE.TRTOTR(USERIDOM)) +
                        OTCLPARM(<prefix>.SDSNSAMP(DSNTIDVU)) +
                      ) BREDIMAX(1)

      3. Customize the parameter override file specified in your customized DSNTIJBC job, by following the instructions in the parameter override file prolog

        In the above customized DSNTIJBC job, the parameter override file specified is USERIDOM. The value that you specified for a parameter in this file is the value that DSNTIJBC will assign to this parameter in the DSNTIJBC-generated output DSNTIDxx file. 

        In this blog, I will talk about the parameter override file DSNTIDOM.

    This file has 2 parts, and part 1 contains the mandatory parameters. This section is basically requesting the same information as in the CLIST panel DSNTIPA1/DSNTILA1.


      • BATCH_MODE – always YES
      •  Parameters from USE_ZOSMF_WORKFLOW to PARAMETER_OUTPUT_MEMBER correspond to the fields on the Db2 installation CLIST panel DSNTIPA1/LA1.
        •  INSTALL_TYPE – currently only MIGRATE is supported
        •  MIGRATE_INPUT_DATA_SET – the  current and valid input DSNTIDxx file
        • DEFAULT_PARAMETER_INPUT_MEMBER – the default parameter values for the release you are migrating to
        • PARAMETER_OUTPUT_MEMBER – the new DSNTIDxx file from this migration
      • Parameters TARGET_FUNCTION_LEVEL and CONSOLE_NAME are required only if USE_Z/OSMF_WORKFLOW is YES. These override parameters correspond to fields on the Db2 installation CLIST panel DSNTIP00 and DSNTIPM5.
      •  Parameter names are very similar to the corresponding field names in the CLIST panels.

    Part 2 of this override file consists of the optional parameters.


      • Optional parameters correspond to fields on the Db2 installation CLIST panel DSNTIPG1, DSNTIPT, DSNTIP00, DSNTIPX1 and DSNTIPM1, and their names are very similar to the corresponding field names on the CLIST panels.
      • No warning message is issued to indicate that the contents of the specified data sets or ZFS path are going to be overwritten. If you want to preserve the previous contents, verify that you have given new names for the following data sets or ZFS path:

    4.       If you use Db2 Value Unit Edition, you must also customize a parameter override file named DSNTIDVU, which contains notice and acceptance of the license terms.

    5.       Submit the customized DSNTIJBC batch job. In about 2–3 minutes, you will have all the artifacts for your migration.

    If you have generated artifacts for the z/OSMF workflow, your next step is to create a workflow instance in z/OSMF.

    Creating and Executing a z/OSMF Workflow Instance

    With the z/OSMF artifacts ready, you can now create workflow instances, by following the steps described below:

      1. Log into your z/OSMF server, to access its web browser user interface
      2. Select Workflows -> Actions -> Create Workflow…
      3. In the next screen, indicate the location of the CLIST-generated workflow definition file and the variable input file:
        Note: The ZFS path is the same entered in the sample DSNTIPM1 panel earlier.

      4. In the next screen, provide the following information:

        a.       Specific name for this workflow instance.

        b.       User ID under which the workflow is going to be executed.

        c.       System LPAR under which the workflow is going to be executed.


      5. Review the workflow instance created and displayed as shown below:

        Notice that only step 1 is ready to be executed. The state of the subsequent steps will be set to Ready once the previous step was successfully executed.

      6. To submit the workflow, go to Actions -> Perform and then choose if you want to execute the workflow manually (you drive the step execution) or automatically.  If you are new to this process, I strongly recommend that you first practice by executing manually to familiarize yourself with the whole process and then start enabling automation.

      7. To check the output of a step, click on the step. You can also follow the workflow execution progress as indicated in ‘Percent complete’ .

    Additional remarks

    You can always further customize the workflow that was generated in either method. For example, you can use the z/OSMF workflow editor and add a particular step that is not part of our optional list, and basically standardize that workflow to be used for all Db2 systems in your environment.

    With the same workflow definition file you can create several instances for different Db2 systems, by switching the variable input file.

    Before the support to generate the artifacts in background mode was available, you would need to edit the variable input file to customize it for the other Db2 systems. Now it is much faster and accurate for you to just run DSNTIJBC to generate the artifacts and you will have the variable input file for each Db2 system very quickly.

    What’s Next?

    Stay tuned for an upcoming blog post, where we will discuss the enhancements that are in progress to auto-discover the Db2 system configuration parameters, so that you can always have an accurate input DSNTIDxx file.