Migration (2)

Db2 for z/OS APAR PH02437 introduces the new DSNB233I message in Db2 12 and Db2 11. The new message reminds you to convert pagesets to the extended 10-byte RBA or LRSN format, to avoid outages that might occur if Db2 reaches the 6-byte logging limit. Read the full story.

Always get the latest news about Db2 for z/OS from the IBM lab! How to subscribe

Follow us on Twitter: @DB2zLabNews

Read more…

Executive summary

DB2 for z/OS is expected to run 24-7 with almost zero down time, and DB2 version upgrade has little tolerance for failure. Yet, DB2 migration is considered a cumbersome project. An automated and reliable approach is needed to simplify DB2 migration tasks and free the SMEs involved in DB2 migration. System administrators, database administrators and system programmers can use DB2 z/OS Management Facility (z/OSMF) workflows to define an automated DB2 migration process one time and execute it many times. z/OSMF is a free product of z/OS that improves the repeatability of tasks and improve efficiencies while saving time and workforce expenditures.


This article consists of 2 parts. In the first part of this article, we will introduce what the new approach is and how to prepare the artifacts needed by the new approach. In the second part of this article, we will introduce how to perform DB2 migration with z/OSMF.


A new approach to DB2 migration challenges

DB2 for z/OS has been the underpinning of enterprise applications for the past few decades. As a synonym of reliability and availability, DB2 is expected to run 24-7 with almost zero down time. With this expectation, DB2 version upgrade has little tolerance for failure.


Yet, DB2 migration is considered a cumbersome project, especially for large enterprises that might have hundreds of DB2 subsystems. Traditionally, migration of every individual DB2 system involves many migration steps, and requires resources and effort, such that the processing of migrating all of the DB2 subsystems in one larger enterprise might last for weeks.


For instance, a DB2 for z/OS customer has more than 100 DB2 systems. However, the small administration team is unable to manage the migration of more than 20 DB2 systems at a time with the traditional approach. Therefore, they must spend several weeks on the migration project, which wastes resources, and prevents fast deployment of new business. It costs even more considering the preparation for the migration of so many systems, including pre-migration checking, collaboration with other groups, and so forth.


Therefore, strong demand exists for an automated and reliable approach to simplify DB2 migration tasks and free system programmers, database administrators, and other SMEs that are involved in DB2 migration.


z/OS Management Facility is a free product of z/OS, and an approach for automating DB2 migration with z/OSMF workflows. z/OSMF helps to improve the repeatability of tasks and improve efficiencies while saving time and workforce expenditures. z/OSMF is also designed to use role-based assignments, creating clear workforce tasks while minimizing questions about who should perform each task.


This article introduces a new approach for migrating a DB2 system or a DB2 data sharing group with z/OSMF. The new approach helps reduce the effort of managing multiple sets of migration jobs and automates the execution of these jobs. In the new procedure, users complete the following actions:


  1. Generate the z/OSMF workflow artifacts with the enhanced DB2 installation CLIST.
  2. Customize the workflow artifacts for the users' environment.
  3. Create z/OSMF workflow instances for each DB2 system to migrate.


With the new approach, the migration steps can be expressed in customized z/OSMF workflows, which can be automated and managed on a web portal or through REST APIs.


This approach provides the following benefits:

  • Improves speed of business
  • Reduces costs
  • Lowers skill barriers, with a modern user interface
  • Provides a solution easily integrated into Cloud infrastructure


About z/OSMF workflows


z/OSMF is a free product for z/OS that simplifies, optimizes, and modernizes the z/OS system programmer experience. It delivers solutions in a task-oriented, Web-browser-based user interface with integrated user assistance, to improve system programmer productivity, and make z/OS functions easier to understand and use. It provides an engine which can execute workflows.


In z/OSMF, a workflow is a guided set of steps that help you perform an activity on z/OS, such as configuring a software product or component, managing a z/OS resource or structure, or simplifying some relatively complex operation. The steps of a workflow can be a descriptive instruction that guide users to take actions, or executable programs defined by template files. Templates are widely used in scenarios where the main motivation is automation and simplification.


A file template can be a JCL job, a REXX statement, or a shell script that contains embedded workflow variables, a key element for improving the productivity of repeated tasks with z/OSMF. Variables are embedded in the JCL, REXX, or shell script as symbols. At execution time, input values are required to substitute these symbols and produce an executable JCL, REXX, or shell script.


For example, assume that a DBA must grant access of a set of tables to a user when he or she receives a request. The DBA can create a workflow that has a step with a JCL template that executes GRANT statements. The grantee can be defined as a workflow variable. The following illustration depicts the structure of a workflow:




The file template GRANTU.JCL contains symbol ${USERID} which represents a workflow variable USERID.




The workflow variable must be substituted by a value so the GRANTU.JCL. For example, if the DBA needs to grant the access of these 5 tables to the user USR001, the DBA must provide the value "USR001" to z/OSMF. Then z/OSMF can substitute ${USERID} with "USR001", produce the JCL as below, and submit it at workflow instance execution time.




A workflow is defined by an XML file that is called workflow definition file. The content of a workflow definition file includes the information about the workflow, step definitions, variable definitions, and file templates. As of today, the workflow definition file must be created from scratch in a text or XML editor.


For complete instructions for creating workflow definition files, see IBM z/OS Management Facility Programming Guide.


A workflow instance is created from a workflow definition and the file templates that are defined in the workflow. Optionally, a workflow input variable file can be provided so users don’t need to manually input the values in the Web interface. The default values of the variables can be loaded from the workflow input variable file. Collectively, the workflow definition file, the workflow input variable file, and the file templates are called workflow artifacts.


If the DBA needs to grant access of these tables to another user USR002, the DBA can create another workflow instance with the same set workflow artifacts but with "USR002" as input for the USERID variable.


Planning for migrating DB2 with z/OSMF


Before you begin

DB2 installation CLIST DSNTINST can generate z/OSMF workflow artifacts used for DB2 11 installation or migration, enabled by DB2 11 for z/OS APAR PI38553 and z/OSMF V2R1 APAR PI42725.


The advantage of using z/OSMF workflows for the migration process is the efficiency of the defining once, and executing multiple times.


Today many DB2 customers create many sets of migration JCL jobs for their systems. A common approach is to use DB2 installation CLIST DSNTINST to tailor the migration jobs for one system. Then they duplicate these jobs and customize them for other systems. The result of this approach is many jobs, which are hard to maintain and error-prone in the customization.


With z/OSMF, you can generate only one set (or a few) of z/OSMF workflow artifacts, create multiple workflow instances by filling system-specific input to these workflow instances. Then these workflow instances can be reused to for many DB2 subsystems. Moreover, the migration workflow execution can be fully automated and reduce the burden of constantly submitting jobs and checking return codes.


In order to leverage z/OSMF in DB2 migration, you must decide how many z/OSMF artifacts that you need in the first place. It is determined by the migration steps and the variable selections.


Migration steps


For migration to DB2 11 for z/OS, the migration process uses 3 migration modes, each with different steps:

  1. Migrating a non-data-sharing DB2 subsystem or the first member of a data sharing group to conversion mode (CM).
  2. Migrating subsequent members of data sharing groups to CM.
  3. Migrating a DB2 subsystem or data-sharing group to new-function mode (NFM).


For an overview of the process for migrating to DB2 11 for z/OS, see Introduction to Migration.


The migration steps might have slight differences for different types of subsystems in some shops. For the subsystems whose migration steps are different, new set of workflow artifacts should be created for them.


Selecting variables


More than 1000 input fields are variable candidates in DB2 migration. However, choosing all of them as variables introduces a huge amount management effort and might result in unexpected problems. A good practice is to choose the right variable set because, most settings are the same across a single enterprise.


An example of workflow artifacts generation migrating a data sharing group with z/OSMF


For example, assume that a data sharing group consists of 16 members. 12 members process the online transaction processing (OLTP) workload, and the other 4 members process the online analytical processing (OLAP) workload. The OLTP members and OLAP members might have different subsystem parameters setting for buffer pool sizes, sort pool sizes, and even accelerator settings. You can create 3 sets of workflow artifacts to migrate the data sharing group:


1. Workflow to migrate the first OLTP member - DSNTIWMS;

2. Workflow to migrate the subsequent OLTP and OLAP member - DSNTIWMD;

3. Workflow to migrate to new function mode - DSNTIWMN.


Because the OLTP members and OLAP members might have different patterns of parameter configurations it is best to use two base workflow input variables files: one for OLTP members, and one for the OLAP members. You can customize other members based on their particular characteristics.



Generating z/OSMF workflow artifacts


The z/OSMF workflow artifacts generation follows the usual process of tailoring DB2 installation and migration jobs. The main entry is also DSNTINST which is in the data set prefix.SDSNCLST. For example, if the DB2 SMP/E libraries' prefix on your system is DSNB10 then you can execute 'DSNB10.SDSNCLST(DSNTINST)' to start the guided process through DB2 installation panels.


For detailed instructions for tailoring DB2 installation and migration job, see Tailoring DB2 jobs to your environment using the installation CLIST.


With APAR PI38553 applied, DB2 installation panel DSNTIPA1 contains a new option for generating z/OSMF workflow artifacts and using the z/OSMF workflow feature to migrate or install a DB2 subsystem.


The default setting of the USE Z/OSMF WORKFLOW field is "NO." Under this setting, only the usual tailored jobs are generated. Specify “YES” to generate to also generate the z/OSMF workflow artifacts.




When "YES" is specified, you can select input fields as z/OSMF workflow variables. As variables, the values that you provide on the installation panels are not used in the generated JCL templates directly. Instead, the generated JCL templates contains the variable symbolic, and the generated workflow input variable file contains the values in "key=value" pairs.


For example, it is very likely that the high level qualifiers of DB2 SMP/E library name prefix are different across subsystems. Then you can select the "LIBRARY NAME PREFIX" field as a variable by typing "S" to the left of the field.


With "LIBRARY NAME PREFIX" selected as a variable, all the jobs referring to DB2 SMP/E libraries are tailored to use a symbolic representing the prefix of the DB2 libraries.


For example, in DSNTIJIC, the JOBLIB refers to ${DSNTLIBP}.SDSNEXIT and ${DSNTLIBP}.SDSNLOAD. DSNTILIBP is the variable name which is prefixed by $ and enclosed by brace to identify it as a variable.




Any values that you provide on the panel are saved in the workflow input variable file as the default value of the prefix of DB2 libraries.




When the workflow is instantiated in z/OSMF, it substitutes the symbolic with the value saved in the workflow input variable file and produces an executable JCL.




Besides the four input fields on the entry panel, most of the input fields can be selected as variables.


Some of them might have different level of granularity so one can override another. For example, on the panel DSNTILT, if the checkbox for the input field "EXIT LIBRARY" is selected, the full library path instead of its prefix is considered as a variable. All other libraries will still use the prefix as variables in their path. This is useful when most of the libraries have the same prefix but a few do not.




As a comparison, when the "EXIT LIBRARY" is selected as a variable, DSNTIJRW refers to the full path of the library as a variable.




Some input fields are grouped as they are related. For example, the work file database settings on DSNTIL9.


Some fields are calculation results. They still can be selected as variables, for example, the fields on the panel DSNTILC.


Besides the existing input fields, the subsystem parameters not on the installation panels before PI38553 can also be selected as variables.




It's recommended to select those input fields that have different configurations on different systems, such as subsystem ID, buffer pool size, and so forth. Because each DB2 subsystem to migrate has its own input variable input file, selecting too many variables makes the variable input file longer, meaning that maintenance work might be error prone.


Installation or migration steps can also be customized to support specific customer’s processes that add to or skip steps in the documented migration process.




The z/OSMF workflow artifacts are generated in the PDS that you specify. The workflow definition file and the workflow input variable file are generated in the "WORKFLOW DEFINITION LIBRARY". The JCL templates will be generated in the "JCL TEMPLATE LIBRARY".




Customizing z/OSMF workflow JCL templates


The JCL templates that the installation CLIST generates work for most users. However, you need to customize JCLs for your shop. You can edit the JCL templates to further customize them by adding or removing steps.


We will introduce how to perform DB2 migration with these artifacts in the second part of this article.



Kewei Wei (魏可伟) is a senior software engineer in DB2 for z/OS development.

Paul A. McWilliams is a content developer in DB2 for z/OS development


If you have any questions about the solution, please feel free to contact Kewei (weikewei@cn.ibm.com).

Read more…