Conversion Steps

This chapter includes the following topics:

Overview of the conversion tool operation

The operation of the conversion tool consists of a series of steps divided in the following sections:

The following is a summary of the steps:

Pre-conversion planning

  1. Review system exits required in the Control-M environment.

  2. Ensure that all personnel involved in the conversion process have the necessary security privileges and authorizations.

Automated ICE operations

  1. Stage 0 – Set Conversion Defaults

  2. Stage 1 – Data Extraction

  3. Stage 2 – Conversion

Post-conversion operations

  1. Post Step 1 – Customize Control-M and Install User Exits

  2. Post Step 2 – Perform Final Adjustmentss

  3. Post Step 3 – Check Conversion Results

  4. Post Step 4 – Customize the New Day Procedure

BMC recommends that you first review the contents of Planning the conversion and then read through the remainder of this chapter before performing the steps. It is important to follow the outlined sequence of the steps to ensure a successful conversion.

Pre-conversion Planning

Before beginning the actual conversion process, the following list must be reviewed for tasks that might need to be performed in preparation for the conversion:

  1. Review any system or CA ESP exits that perform functions that must be implemented in the Control-M environment.

  2. Ensure that all personnel involved in the conversion process have security access to all required functions and that they have authorization to execute the necessary batch jobs.

Automated ICE operations

Stage 0 – Set Conversion Defaults

In the SET ESP CONVERSION DEFAULTS OPTIONS panel default values are provided for the conversion parameters. In the panel, the parameters are arranged in groups as indicated in Table 1 below. New values can be specified or the default values accepted. When this stage is completed, the ESPDEF defaults member in the INSTWORK ICE library is updated with the new values. Short descriptions of the options are provided in this panel. For more information about the conversion parameters, see Conversion Parameters

Do not add any comment text in conversion default parameter statements. Comments can be specified only in separate records containing an asterisk in column 1.

Table 1 ESPDEF conversion parameters

Parameter group

Parameter

ESP FUNCTIONALITY SETTINGS

CALDFLT

VSYMBOL

CONTROL-M FUNCTIONALITY SETTINGS

DELCOND

FRMCLS

LIBNAME

MAXRRUN

RELEASE

TOCLS

DORERUN

IFRRNCNF

RUNDUMMY

SHOUT PARAMETERS SETTINGS

 SHOUTL

SHOUTN

SHOUTE

SHOUTT

SHOUTS

SHOUTR

CONVERSION FUNCTIONALITY SETTINGS

 COMMENT

JOBSLSH

MAYBEPF

OWNER

OWNLEN

CONVERSION SIZES SETTINGS

 DIRMAX

LINMAX

MAXJOBS

MAXPROC

Stage 1 – Data Extraction

Overview of data extraction

In this stage, the CA ESP scheduling definitions, together with all the production data files and libraries that are required for the conversion, are extracted to a scheduling data package. A job is created that must be copied to and run in an environment where the production files are accessible, from where it extracts the data and generates a scheduling data package.

If you already have your own CA ESP data (such as, CA ESP Reports and JCL libraries) and want to use the CA ESP Conversion ICE Interface to process the conversion, follow the instructions in Using your own data to process the conversion.

This stage consists of the following steps:

  • preparing the conversion environment for the data extraction process

  • extracting the CA ESP environment data and generating a scheduling data package

Using your own data to process the conversion

  1. Choose step 4 and enter your reports file name prefix, (PF3 save and exit).

  2. Choose step 5.

    Your CA ESP reports must have the following suffixes:

    • PROC.SEQFILE - sequential file of the CA ESP Procedures Library

    • SYMVAR.SEQFILE - sequential file of the CA ESP Symbolic Variables Library (if provided)

    1. Enter your CA ESP Events Description File and CA ESP CAL File. Enter Y to continue.

    2. If you have JCL libraries enter the names. Enter Y to continue.

  3. Continue with the conversion steps. When you reach step 9, answer N to the question and then continue with step 10, described in Create CTM scheduling & calendars.

Set File allocation for data extraction

In the SET FILE ALLOCATION DEFAULTS FOR DATA EXTRACTION panel, specify values that will be used in the data extraction stage.

  1. Specify a valid file name prefix that will be used for the CA ESP reports that are created by JOB0 or used by the existing CA ESP reports. In either case, the prefix is required for the conversion process.

  2. Do one of the following:

    • For non-SMS, specify valid values for the UNIT and VOLSER.

    • For SMS, specify valid values for SMS DATA CLASS, SMS STORAGE CLASS, and SMS MANAGMENT CLASS.

  3. For the SPACE ALLOCATION PARAMETERS specify a new value or accept the default value for the ESP PROCEDURES LIBRARY SEQUENTIAL FILE.

If you already entered a value, but wish to reset any of the space allocation parameters to its default value, enter a slash, "/", in the appropriate field.

If there is an SB37 abend due to insufficient disk space, see Table 2, and increase the appropriate space allocation.

Table 2 Fixing SB37 problems in the conversion

JOB

STEP

DD

Fields on the screen with the space information

JOB0

STEP2

SYSUT2

ESP PROCEDURES LIBRARY SEQUENTIAL FILE

STEP4

SYSUT2

ESP PROCEDURES LIBRARY SEQUENTIAL FILE

 

JOB1

 

STEP3

DACAL

CTM CALENDARS LIBRARY

STEP5

SORTIN

TABLE DEFINITION FILE

DABLTPRM

SORTED TABLE DEFINITION FILE

DABLTPRM

DADAILY

DAILY PROCESS LIST

DADAILY

DAONSPT

CMEM EVENT RULE FILE

DAONSPT

STEP6

DASCHD

CTM SCHEDULE TABLE LIBRARY

STEP8

DAEVENTO

CTO RULES FILE

 

JOB2

STEP2

DAXML

XML FILE CONTAINING DISTRIBUTED JOBS DEFS

STEP3

CALXML

XML FILE CONTAINING DISTRIBUTED CALENDARS

STEP4

DAXML

XML FILE CONTAINING MAINFRAME JOBS DEFS

STEP5

CALXML

XML FILE CONTAINING MAINFRAME CALENDARS

STEP6

XMLOUT1

XML FILE CONTAINING DISTRIBUTED JOBS DEFS

XMLOUT2

XML FILE CONTAINING MAINFRAME JOBS DEFS

Extract the data from CA ESP environment

  1. In the EXTRACT CONVERSION INPUT DATA panel, specify file names or values for the following:

    • CA ESP Procedures Library

    • CA ESP Events Description File

    • CA ESP CAL File

    • CA ESP Symbolic Variables Library

    In addition, if you want to upload the compressed package to the BMC FTP support site, specify values for the following:

    • email address

    • issue number

    Enter YES to save and continue.

  2. In the SPECIFY JCL LIBRARIES panel, specify the JCL libraries that need to be converted. If the PNIBTSD conversion option (see Conversion Parameters) is set to Y, then all libraries that contain non-instream ESP utility commands must be included in this list. Initially the library list is empty, but you can enter as many JCL libraries that you need to be converted. For each library, specify a unique name to be used as a suffix. The conversion renames each library, in the restore job, to prefix.suffix, and accesses it using this name. Enter YES to save and continue.

    For CA-LIBRARIAN or CA-PANVALET libraries, the utilities supplied by CA-LIBRARIAN or CA-PANVALET must be used to create and copy the production JCL libraries into PDS libraries, which can then be specified above.

  3. If the data extraction job already exists, you will be prompted if you want to replace the existing copy. The job is then displayed in the ISPF editor. If necessary, edit the job.

  4. Run the job in the environment where CA ESP is installed.

  5. Verify that the job ran successfully.

For more information, see JOB0 - Identify and extract the CA ESP Reports.

Closure for Stage 1

In this stage, the CA ESP scheduling definitions, with all the required production data files and libraries were extracted and compressed into a scheduling data package (prefix.TRS). Copy the scheduling data package, to the test environment. 

Stage 2 – Conversion

Overview of the conversion stage

The scheduling data package, created in the previous stage, is copied to the conversion environment. The CA ESP job scheduling reports and calendars, and the CA ESP JCL libraries and members are all converted to Control-M format. Finally, XML draft files are created that contain the job definitions and calendars in Control-M format. The XML draft files can later be opened by Control-M and loaded into a workspace.

This stage consists of the following steps:

  • preparing the environment for the conversion process files

  • running a job to extract the files from the compressed file taken from the production environment

  • running a job that creates Control-M Calendar and schedule definition libraries (and if necessary, adjusting the results)

  • running a job that creates Control-M XML draft files (and if necessary, adjusting the results)

  • converting the JCL libraries

Set File allocation for Conversion

In the SET FILE ALLOCATION FOR CONVERSION panel, specify values that will be used in the conversion stages that follow.

  1. Specify a valid file name prefix that will be used for the Control-M conversion results. The prefix is required for the conversion process.

  2. Do one of the following:

    • For non-SMS, specify valid values for the UNIT and VOLSER.

    • For SMS, specify valid values for SMS DATA CLASS, SMS STORAGE CLASS, and SMS MANAGMENT CLASS.

  3. At this point you can choose to back up the current values or restore the most recently saved values of parameters, settings, and options for the set of files associated with the specified prefix. In the Backup/Restore field, enter one of the following values:

    • B — back up the current values for the extracted environment

    • R — restore to the most recently saved values

    • blank — continue with file allocations without performing a backup or a restore

    This backup/restore mechanism enables you to run multiple conversion sets in a single IOA environment. After backing up one conversion set and exiting this panel, you can re-enter the panel and work on a different set. At a later time, you can return to this panel, specify the appropriate file name prefix and restore values for the conversion set, and proceed from the last step performed.

    The following information is included in the backup/restore process:

    • Conversion options

    • Allocation attributes

    • Space allocations (from the Extraction and Conversion panels)

    • PARM values (from all panels)

    • List of JCL and PROCEDURE libs

  4. Under the Create CTM Scheduling Definition And Calendars section, specify new values for the space allocation parameters or accept the default values for the following:

    • Control-M calendars library

    • Control-M schedule table library

    • table definition file

    • sorted table definition file

    • daily process list

    • CMEM event rule file

    • Control-O rules file

  5. Under the Create CTM XML section, specify new values for the space allocation parameters or accept the default values for the XML files containing the following:

    • distributed jobs definitions

    • mainframe job definitions

    • distributed calendars

    • mainframe calendars

  6. Press PF3 to save and continue.

Extract the Package File

  1. Select the Extract the Package File step.

    • In the TRS File to be Extracted field, type the new name of the TRS file brought from the production environment.

    • Press Enter.

  2. The jobs for extracting the package file run automatically in the conversion environment.

  3. Confirm to continue, when prompted after the metadata extraction job, before the job that extracts the other files.

  4. Verify that the jobs ran successfully.

Create CTM scheduling & calendars

  1. Select the Create CTM scheduling & calendars step.

  2. If the job for creating the Control-M Calendar and table libraries already exists, you will be prompted if you want to replace the existing copy. The job is then displayed in the ISPF editor. If necessary, edit the job. When editing, it is important to ensure that the table names remain unique, valid PDS member names.

  3. Run the job in the conversion environment.

  4. Verify that the job ran successfully.

For more information, seeJOB1 - Create libraries and the CMEM, Control-O tables, and XML definitions.

Create CTM XML

  1. Select the Create CTM XML step.

  2. In the CREATE CTM XML DEFINITIONS FOR JOBS AND CALENDARS panel, enter the following information:

    • name of Control-M datacenter for distributed jobs

    • name of Control-M datacenter for mainframe jobs

    • the source for table user daily name (SYSTEM/#APPL#/#GRP#/XXX/blank)

    • the prefix to use for distributed to mainframe condition names

    • the prefix to use for mainframe to distributed condition names

    • the prefix to use for global condition names

    • the name of the site standard (if any) to use in enforcing job definition validation rules

  3. Enter YES to save and continue.

  4. If the job for creating the XML definitions for jobs and calendars already exists, you will be prompted if you want to replace the existing copy. The job is then displayed in the ISPF editor. If necessary, edit the job.

  5. Run the job in the conversion environment.

  6. Verify that the job ran successfully.

Convert JCL Libraries

To run the converted jobs on Control-M for z/OS, the CA ESP JCL libraries are made compatible to Control-M.

  1. Select the Convert JCL Libraries step.

  2. If the job for converting the JCL members to Control-M format already exists, you will be prompted if you want to replace the existing copy. The job is then displayed in the ISPF editor. If necessary, edit the job.

  3. Run the job in the conversion environment.

  4. Verify that the job ran successfully.

For more information, see JOB2 - Convert JCL Members.

Closure for Stage 2

In this stage, the scheduling data package (created from the production environment) was copied to the conversion environment, and then uncompressed. Then jobs were run to convert the CA ESP job scheduling reports and calendars, and the CA ESP JCL libraries and members to Control-M format. Finally, XML draft files were created that contain the job definitions and calendars in Control-M format. XML draft files for FTP and SQL Accounts are also created, if necessary.

Load the XML files to Control-M/Enterprise Manager to validate the conversion. For more details, see step 7 in the procedure described in Post Step 3 – Check Conversion Results.

Post-conversion operations

Post Step 1 – Customize Control-M and Install User Exits

  1. Set the SCHPREVD parameter in the CTMPARM member in the IOA.PARM library to Y.

    This parameter operates on jobs scheduled between midnight and the Control-M New Day time. It moves these jobs to the previous day to avoid date discrepancies. This parameter is only operative when the SAC Control-M job scheduling parameter is set. For more information, see Absolute vs. Logical Days and New Day Processing.

  2. Install the shout exit, User Exit 34, to support ESP VS commands. A sample exit is supplied in the IOAX034A member in the IOA SAMPEXIT library. The exit is required if any ESP procedures issue system commands using the ESP VS command.

    This exit causes a CONTROL-M SHOUT message text to be treated as an MVS operator command when the SHOUT destination is specified as TSO-CMD. For more information, see 2. VS.

  3. Set the EMPTYTBL parameter in the CTMPARM member in the IOA.PARM library to Y.

  4. If any ESP procedures specify JCLLIB|DATASET ddname, then support for the value DDNAME=ddname in the Control-M MEMLIB parameter is required and is provided via APAR WM10199.

  5. Apply optional wish WO0987. For details, see 7. DSTRIG.

Post Step 2 – Perform Final Adjustments

The following final adjustments must be performed:

  1. The CTMXRF Control-M utility must be run with the cross reference statement XRF=RES, to determine if any Quantitative resources were placed in the newly created job scheduling definitions. Ifthis is the case, these resources must be added to the Control-M Resources file using the IOA IOACND utility. For more information on the IOACND utility, see the INCONTROL for z/OS Utilities Guide.

  2. If CA-LIBRARIAN or CA-PANVALET libraries were converted to partitioned data sets in Stage1 above, they may be reconverted back to CA-LIBRARIAN or CA-PANVALET format at this point.

  3. Review all CA ESP system exits (if any). Remove or modify such exits as appropriate.

  4. Copy member CNVESPIN from the IOA SAMPLE to the DAGLOBAL library allocated in the Control-M Online/Monitor procedures. This member contains the translation of a limited selection of ESP system variables to Control-M AutoEdit format.

    To make these auto-edit variables accessible in ARGS of Distributed jobs:

    1. Copy member CNVESPIN from the IOA SAMPLE library into a text file in the Control-M Server file system.

    2. Issue the following Control-M command:

      ctmvar -POOL load -POOLNAME ctm_esp_globalvar_pool -FROM <filename>

      where <filename> is the copied file above.

      This command loads all the ESP variables into the named variable pool, and they become accessible to the job via the %%POOLSYM=ctm_esp_globalvar_pool SETVAR auto-edit variable in the job definition.

  5. Add the following list of AutoEdit variables with the values specified below to the Contol-M cache:

    • %%SMF=%%$L

    • %%MNFULLNAME=%%JOBNAME

    • %%MNJOB=%%JOBNAME

    • %%MNJOBNO=%%JOBID

    • %%MNCMPC=%%JOBCC

    • %%MNMXCMPC=%%MAXRC

    • %%MNHICMPC=%%$HIGHRC

    • %%MNHIRC=%%$HIGHRC

    • %%MNAPPL=%%APPL

    • %%MNSYS=%%$SYSNAME

    • %%MNNXN=%%$NODEID

    • %%JOBCARD=jobcard-parameters (used to set JCL JOB card parameters for in-stream JCL jobs containing statements of the form: //jobname JOB %%JOBCARD)

    • %%SUBSYS=ESP-subsystem (same value as entered in the ICE panel)

    Details on creating and using the AutoEdit cache are described in the Control-M for z/OS User Guide, in Chapter 5, "JCL and AutoEdit Facility", under "Local Variables" in the "Loading Members to Cache" section.

  6. Add quantitative resources to the Distributed jobs:

    1. Locate the PREFIX.QUANT.RES file in the mainframe.

    2. Create a copy of this file in the Control-M/Server file system.

    3. If necessary, change the default maximum number of quantitative resources (99) to a new value in the copied file.

    4. (Linux) Insert the following line at the beginning of the file:

      #!/bin/bash

    5. (Windows) Add a BAT suffix to the file name, to rename the file to PREFIX.QUANT.RES.BAT.

    6. Save the copied file.

    7. Run the copied file on the Control-M/Server to add the quantitative resources to the system.

Post Step 3 – Check Conversion Results

  1. Export the job schedule definitions of both Control-M for z/OS jobs and Control-M for Distributed Systems jobs.

    The names of the required Control-Ms for distributed jobs and mainframe jobs that are specified in Step 4 (Create CTM XML) of Stage 2 – Conversion must be the same names that will be used below, in Step 4 of this procedure, where the Control-Ms are defined using the Control-M Configuration Manager.

    The values entered in the CONTROL-M NAME FOR DISTRIBUTED JOBS and the CONTROL-M NAME FOR MAINFRAME JOBS fields are used for the DATACENTER parameter values used as input to the CTMTLB utility.

    If required, Control-M for Distributed Systems jobs can be divided among more than one Control-M. (Tip: use a table name prefix, or a list of table names.) To achieve this, the export to XML step must be repeated, and in each run, a different Control-M and different table names must be specified. This process must be performed on the job created in the conversion job library.

  2. As a result of converting implicit job scheduling predecessors, many RBCs that contain duplicate or empty scheduling criteria may be created. To clean up these RBCs and give them customer-friendly names, perform the following steps:

    1. Install the DS Conversion tool.

    2. Go to directory tools\general\CalendarDuplicatesRemoval\.

    3. Follow the instructions in the ReadMe file.

  3. Export the calendars created in the conversion process.

    Create a calendar XML for each Control-M (either Control-M for z/OS jobs or Control-M for Distributed Systems jobs), so it is possible to load them to all Control-Ms. If there are manual adjustments to calendars, or entire calendars that have to be created, either create them before the export process, or do it from Control-M/EM after loading the exported ones.

  4. Start up Control-M Monitor and IOAGATE on the mainframe for Control-M for z/OS jobs. Start up Control-M Server and its corresponding Gateway for Control-M for Distributed Systems jobs.

    Verify that all are connected and working properly before continuing.

  5. Define all Control-Ms (Control-M for z/OS jobs and Control-M for Distributed Systems) in the Control-M/Enterprise Manager environment.

    Define all required Control-Ms using the Control-M Configuration Manager. It is preferable to use the automatic discovery method. If the manual definition method must be used, verify that all settings and parameters are according to the attributes of the Control-M. The Platform attribute (Distributed or z/OS) is the most important setting that cannot be changed later.

    In any case, you must use the same names of the Control-Ms that were specified for the DATACENTER parameter values in Step 1.

  6. Import the exported Calendars to all Control-Ms on Control-M/EM.

    Use the Control-M/EM defcal utility. If there are manual modifications or whole calendars to be created, verify that all are available.

  7. Define the GCS distribution list.

    In Control-M, in the Tools domain choose Global Condition Prefixes. The Global Conditions Prefixes tab opens. Add the prefixes that were specified in the input file for JOB2 STEP6. Set the "From" and the "To" according to the names that were specified in ICE and placed in the generated JOB2.

    This procedure must be done after the Control-M servers are already defined.

  8. Load each XML file to Control-M.

    For more information, see the subtopics under the Using Workload Automation->Planning->Workspaces->Import/Export topic in the Control-M User Guide.

    Review any error messages, and resolve them. You might be required to re-run several conversion steps in Control-M for z/OS and then continue with step 1 of the testing.

  9. Set the New Day mechanism. For both Control-M for z/OS and Control-M for Distributed Systems, define the User-Daily jobs to be scheduled from the system daily and run at suitable times. Verify that every table is covered by at least one User-Daily. On the Control-M for z/OS, the User Daily can be either based on jobs that reference the various tables, or by job that uses the value of the table User-Daily field. Use the conversion created report as the basis for this process.

  10. Define the Forecast User-Daily settings for the Control-M for z/OS folders in the Forecast domain. For more details, see the Control-M User Guide.

  11. Run Control-M/Forecast for the Control-M or table, and create a full year plan of all jobs. This plan can be exported to text and compared with the reports that are produced from your current scheduling tool.

  12. Load Forecast from the Control-M Planning Domain on a specific date (as many times and various days as required), and compare the predicted flow with the current scheduling tool reports.

In certain cases, you might notice that Job counts of the original ESP procedure libraries are not the same as for the Control-M scheduling library created from them. This discrepancy occurs when any of the following are specified in the ESP input:

INVOKE statements that include ESP job definitions from the same or different procedure libraries.

WOBTRIG FILE_TRIGGER statements in the ESP EVENTS file, which cause CTM AFT distributed job definitions to be created.

[OPER] TRIGGER statements, which cause CTMJOB Started tasks (jobs) to be created.

ESP job types that are not recognized by the conversion tool. For a complete list of supported job types, see 9. [xxx_]JOB name.

Post Step 4 – Customize the New Day Procedure

Specify the new tables in the DAJOB DD statement of the Control-M New Day procedure. Use the list of tables created by JOB2 in the DAILY file.

Order the IOA IOALDNRS utility as part of the New Day procedure (and periodically during the day, if necessary) to produce the IOA Manual Conditions file. This file lists manual conditions for which jobs are waiting and can be used to add (or delete) these conditions to the IOA Conditions file, when necessary.