Conversion Details
This chapter includes the following topics:
Overview of conversion details
This details the conversion of relevant CA ESP components into corresponding Control-M job scheduling definition parameters and Control-O rule definition parameters, and describes the unique Control-M conversion parameters that can be specified.
Component conversion summary
The conversion tables on the following pages list CA ESP components that are converted to corresponding Control-M and Control-O parameters.
The item number ("Item No.") in the following tables refers to the topic number in this section.
This summary of components is followed by conversion details for each component.
Table 8 Components of CA ESP Procedure Scripts and Events Reports
CA ESP Statement |
Control-M Job Scheduling Def Parameter |
Item No. |
---|---|---|
SE[ND] |
SHOUT, CONTROL-O DO TSO SEND |
1 |
VS |
SHOUT, CONTROL-O DO TSO COMMAND |
2 |
DELAYSUB |
TIME FROM |
3 |
EARLYSUB |
TIME FROM |
3 |
AT |
TIME FROM |
3 |
RESUME |
TIME FROM |
3 |
SUSPEND[(nn)] |
TIME UNTIL, ACTIVE UNTIL |
11 |
LATESUB |
SHOUT WHEN LATESUB |
4 |
CAL[ENDAR] |
DCAL, WCAL, CONFCAL |
5 |
APPL |
APPL |
6 |
SUBAPPL |
GROUP |
61 |
DSTRIG |
CMEM ON DSNEVENT |
7 |
REEXEC |
TASKTYPE=CYC, INTERVAL |
8 |
Job Name |
MEMNAME, DESC, JOBNAME |
9 |
DUEOUT |
EXEC SHOUT WHEN LATESUB, DUE OUT |
10 |
ABANDON |
SUBMISSION TIME UNTIL |
11 |
PRIORITY |
PRIORITY |
12 |
[NO]RUN/[NO]SCHEDULE |
Basic Scheduling Criteria |
13 |
EXCEPT |
Negative Scheduling Criteria |
16 |
[DE]SELECT |
|
17 |
TAG |
SETVAR |
18 |
RESOURCE |
RESOURCE |
19 |
AFTER[ADD] |
IN, OUT, DO COND |
20 |
RELEASE |
IN, OUT, DO COND |
20 |
POSTREQ |
IN, OUT, DO COND |
20 |
PREREQ |
IN, OUT, DO COND |
20 |
NOTWITH |
CONTROL resource |
56 |
CCFAIL |
ON PGMST....CODES |
21 |
CCCHK |
ON PGMST....CODES |
22 |
EXITCODE |
ON PGMST....CODES |
22 |
variable definitions |
SETVAR |
24 |
CRITICAL |
PRIORTIY * |
25 |
EVENT ID |
Event name, OWNER, DESC |
26 |
JCLLIB |
MEMLIB |
27 |
DATASET |
MEMLIB |
27 |
COPYJCL |
History AJF |
54 |
TEMPLIB |
OVERLIB |
28 |
DOCMEM |
DOCMEM |
29 |
ROUTE |
NJE-NODE |
30 |
NOTIFY |
SHOUT, DO SHOUT |
31 |
MEMBER |
%%INCLIB, %%INCMEM |
32 |
PROCESS, CONDITION[AL] |
----- |
33 |
COM |
Control-O comments (/*) |
34 |
HOLD[(nn)] |
CONFIRM=Y, ACTIVE UNTIL |
11,35 |
LINK, TASK, SELFCOMPLETING |
MEMLIB=DUMMY |
36 |
INVOKE |
DO FORCEJOB |
37 |
SUBMIT |
Control-O DO TSO SUBMIT |
38 |
REQUEST |
CONFIRM=Y |
39 |
EVERY |
INTERVAL, cyclic job/Control-O rule |
42 |
MANUAL |
ON JOBEND … DO FORCEJOB |
44 |
EXTERNAL |
DUMMY, IN, OUT, ON JOBARRIVAL … DO FORCEJOB |
45 |
(APPL) WAIT, JOB_ANCESTOR_WAIT |
IN, OUT, CONTROL |
43 |
CMDNAME |
MEMLIB, MEMNAME |
46 |
FILENAME |
|
9, 46 |
AGENT |
NODEID |
47 |
SCRIPTNAME |
MEMLIB, MEMNAME |
46 |
CLPNAME |
MEMLIB, MEMNAME |
46 |
USER[ID], APPL OWNER, EVENT NAME prefix |
OWNER |
55 |
COREQ |
ON JOBARRIVAL … DO FORCEJOB |
51 |
SHELL |
CMDLINE |
48 |
ENVAR |
AutoEdit variables |
49 |
ARGS |
AutoEdit %%PARMn variables |
50 |
STARTING/ENDING date |
CTO IF %%DATE |
52 |
/* |
--- |
53 |
SQL |
AutoEdit variables |
57 |
TEXT_MON |
Embedded script |
58 |
SETVAR |
SETVAR |
59 |
VGET/VPUT/VSET |
SETVAR |
63 |
ENCPARM |
Control-M/Restart parameters |
67 |
%ESPSHH/%ESPSMN, %ESPSTIME |
CYC-RUNTIME |
62 |
APPLEND |
MEMLIB=DUMMY, IN cond |
69 |
APPLSTART |
MEMLIB=DUMMY |
75 |
DURATION |
SETVAR %%CONV-ELAPSED |
70 |
ABSORB |
PRIORITY=* |
71 |
ESP TR[igger] |
Started task CTMJOBPR |
72 |
ESP RESDEF |
Utilities ecaqrtab, IOACND |
73 |
JOBATTR |
|
74 |
HELD_MANUAL |
CMEM On Spool job |
76 |
INHERIT|NOINHERIT |
ADJUST-CONDS=D|Y |
77 |
AJ or APPLJOB action |
CTMAPI AJF command |
78 |
RELDELAY |
IOATEST WAIT=n |
79 |
ENQUEUE |
CONTROL |
80 |
SUSPEND/RESUME |
TIME UNTIL/FROM |
81 |
SYMBOL |
auto-edit symbol |
83 |
EXIT |
END-TABLES = Y |
84 |
CONCAT |
MEMLIB=GENERAL |
27 |
CRITPATH ON |
SETVAR %%CRITPATH=ON |
|
Table 9 Components of CA ESP JCL Members
CA ESP Statement |
Control-M Job Scheduling Def Parameter |
Item No. |
---|---|---|
%variables (JCL) |
%%auto-edit-variable |
23 |
%INCLUDE/%EXCLUDE %ENDINCL/%ENDEXCL |
Control-M AutoEdit statements |
66 |
PGM=ESP |
CTMAPI |
82 |
//*ESPSYMBOL |
auto-edit symbol |
83 |
SUBSYS |
deleted for PGM=ESP |
|
Component conversion detail
1. SE[ND]
A CA ESP Event or procedure (at the application or job level) can send a message to a user, a group of users, or an operator console. The SEND statement specifies a message text and userid(s) or console identifier to which the message is being sent.
When converting CA ESP procedures, the conversion tool converts the SEND statement to a Control-M SHOUT WHEN OK statement with the supplied message text and destination. The OPER and CN(xxx) parameters are converted to the Control-M destination code of OPER. The OPER(n) NONDEL parameters are converted to the Control-M destination code of OPER2-n. The U[SER](*) parameter is converted to the Control-M destination code of T-jobname-prefix (using the prefix length specified in the OWNLEN option). CA ESP SEND messages which span multiple lines are supported.
When converting CA ESP events, the conversion tool converts the SEND statement to a Control-O ON EVENT DO TSO SEND command with the supplied message text and destination.
-
Embedded quotes within the SEND message text are converted to '`' (hex 79).
-
ESP SEND statements that specify a blank send-text value are converted to a Control-M MSG text of ‘?’
2. VS
A CA ESP Event, procedure (application), or job can issue an MVS operator command. The CA ESP VS statement specifies the command to be issued.
When converting CA ESP jobs, the conversion tool converts the VS statement to a Control-M SHOUT WHEN OK statement with the command specified as the SHOUT message text.
When converting application level VS commands, the conversion tool converts the VS statement to a Control-M SHOUT WHEN EXECTIME,TIME>000 statement with the command specified as the SHOUT message text.
The Control-M destination code is specified as TSO-CMD, which together with IOA sample exit IOAX034A causes the message text to be issued as an operator command. For more information, see Post Step 1 – Customize Control-M and Install User Exits.
When converting CA ESP events, the conversion tool converts the VS statement to a Control-O ON EVENT DO COMMAND command with the supplied command text.
3. DELAYSUB, EARLYSUB, AT, RESUME
The CA ESP EARLYSUB (early submit time) or DELAYSUB (delayed submit time) statements mark a job for delayed submission relative to the scheduled time of the Event.
If an EARLYSUB is defined for an event, the conversion tool uses that time in the Control-M TIME FROM scheduling definition parameter to specify the lower time limit for job submission.
If no EARLYSUB time is specified, the Control-M TIME FROM parameter is left blank. If the NOW, REALNOW, TOMORROW, MIDNIGHT and NOON keywords are used instead of, or in addition to, a fixed time, see 13. RUN/SCHEDULE, NORUN/NOSCHED for how they are converted.
If the PLUS nnn DAYS keyword is specified then the TIME FROM DAYS offset field is set to nnn. PLUS nnn WORKDAYS is not supported.
In CA ESP template definitions, the following common usage is encountered: EARLYSUB hh.mm PLUS nnn MINUTES (HOURS) where nnn is variable parameter. The CA ESP AT and RESUME parameters are treated the same as EARLYSUB.
The conversion tool calculates the proper time offset in setting the TIME FROM parameter, as described below.
In the following situations, the FROM time DAYS offset field is set:
-
The TOMORROW sub-parameter is treated as PLUS 1 DAY and is converted as DAYS-offset +1. However, the TOMORROW parameter is ignored if it is associated with a time that precedes the Newday time that would normally cause a SAC=P to be created in the job definition. In such cases, both the SAC and the DAYS-offset are omitted.
-
When a job’s DELAYSUB time is less than the time of the Event that Invoked it, then the FROM time must be set with a DAYS-offset of 1.
-
When a job’s DELAYSUB time is equal to the Newday time and the time of the Event that Invoked it is less than Newday time, then the FROM time must be set with a DAYS-offset of 1.
Processing when the NOW subparameter is or is not specified:
-
DELAYSUB hh:mm NOW is converted to FROM-TIME hhmm.
-
DELAYSUB hh:mm without specification of NOW is converted depending on the DELNOW conversion option.
-
When DELNOW is set to 0, DELAYSUB hh:mm is converted to FROM-TIME hhmm and a SETVAR statement %%SUBMIT=NOTNOW is added to the job definition. This SETVAR may then be used by Control-M exit 1 to determine if and when to make the job eligible for execution (depending on when the job is ordered or triggerred).
-
When DELNOW is set to a non-zero 1-digit number (1-9), the conversion creates the following parameter: UNTIL-TIME=hh(mm+n). This allows an n minute grace period after the FROMTIME for the job to become eligible for execution for that day; otherwise the job waits until the next day.
-
MAXWAIT must be set to a value greater than 0.
-
When the daynam|WORKDAY|WEEKDAY subparameters are specified, the job definition is duplicated using the specified scheduling criteria and overriding the original time criteria (if one was specified): [dayname=MON,TUE,WED,THU,FRI,SAT,SUN]
The conversion takes the same action if it encounters any scheduling criteria beginning with a numeric character (for example, DELAYSUB 07:00 3RD WORKDAY OF MONTH).
The above action is also performed for other ESP commands that specify both time and scheduling criteria (LATESUB, DUEOUT EXEC|INPUT, ABANDON SUBMISSION).
-
An ESP DELAYSUB|EARLYSUB statement at the application level globally delays all jobs that are placed after it. Using this method sets a delayed submission time for all jobs within the application, except for those specifying the DELAYSUB statement within the scope of the JOB statement. The conversion provides limited support for such statements when they specify only the time parameter in the format hh:mm.
-
For all non-cyclic jobs that have a non-blank FROM-TIME and no DAYS-OFFSET specified, the TIME-UNTIL is set to '>'.
-
Any time parameter specified in the SCHEDULED(xxxx) statement of an EXTERNAL job is ignored.
-
A table that corresponds to an ESP Event that has no SCHEDULEd time is created with a table-entity specifying FROM-TIME=0000.
-
If [REAL]NOW PLUS nnn MIN|HOUR is specified, without a time specified, then the conversion adds the following reserved SETVAR variable:
%%CTM_PRE_SUB_WAIT=nnn
4. LATESUB
The CA ESP LATESUB specifies a late submission for a job. This identifies a time by which CA ESP should submit a job.
The conversion tool uses the LATESUB to set a Control-M SHOUT WHEN LATESUB message to indicate that the job is late when this time has passed. For more information, see SHOUTT in Conversion Parameters.
5. CALENDAR
CA ESP events may be associated with a CA ESP default calendar (or the CA ESP installation defined SYSTEM calendar) or a CALENDAR command may be used to specify additional calendars to schedule events in terms that might be unique to your calendar.
The conversion tool assigns the CA ESP calendar name to the Control-M DCAL, WCAL, and/or CONFCAL scheduling parameters whenever required.
ESP Calendars specified in ESP Events are propagated by the conversion to the applications invoked by the event. Calendars defined at the Application level are propagated to the jobs in the application.
The conversion supports only 1 calendar name on ESP CALENDAR statements.
6. APPL
The CA ESP APPL statement identifies the application of which the event is a part.
The conversion tool creates the Control-M APPL parameter, used to supply a common descriptive name to a set of related groups of jobs, from the CA ESP APPL statement.
When a global APPL is specified in an ESP procedure, the conversion tool adds the symbolic variable ESPAPPL=xxx, where xxx is the APPL name value. This value will then be used by the conversion process to resolve the ESP %ESPAPPL symbolic variable used throughout the procedure.
7. DSTRIG
The CA ESP data set triggering facility may be employed at the Event level or at the job level.
On the job level, the DSTRIG (DT) statement sets up a data set trigger object in a CA ESP Application to create data set dependencies at the job level. A data set trigger workload object can be completed by the successful creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user.
The conversion tool creates a dummy job using the data set trigger object name as the MEMNAME and within the job definition adds an IN condition of the form:
-
DS+dsnprfx, where dsnprfx is the last 36 characters of the data set name in the CA ESP DSNAME parameter.
The conversion tool also creates a CMEM rule that defines a DSNEVENT event. The rule specifies that upon closing a specific data set name or generation data group, the following condition is added to the IOA Conditions file:
-
DS+dsnprfx ODAT, where dsnprfx is the last 36 characters of the data set name.
The rule may be triggered by
-
any job, or by a specific job if the CA ESP JOB (job-trigger) parameter is coded
-
any user, or by a specific user if the CA ESP USER(user-trigger) parameter is coded
If the ESP ANYCLOSE parameter is specified, the above CMEM rule triggers the DSNEVENT event whenever the specified DSN is CATLGed. However, if the DSN is a non-GDG file, then the triggering occurs when file disposition is RETAIN (see the Control-O User Guide for details). If this is not desired, either delete the CMEM rule from the DAONSPT file, or define an exception action to prevent the prior DSNEVENT event, for specific jobs, and for similar events.
Since the COND parameter of the CMEM rule contains only the last 36 characters of the data set name, different data set names whose last 36 characters are the same may trigger an incorrect job. It is the user's responsibility to modify the COND parameters and the corresponding IN conditions of jobs that may be incorrectly triggered.
If the data set name indicates a generic or generation data group, meaning, if it is of the form A.B.G-, the conversion tool substitutes G* for the last qualifier in both the IN condition and the CMEM rule. This allows generic data set selection.
At the event level, an Event can be triggered automatically similarly to job level data set triggering. The conversion tool creates a Control-O ON DSNEVENT event using the data set name in the DSTRIG parameter and the job name in the JOB (jobtrigger) parameter, if coded. Generic job triggers are supported. In addition, the USER(userid) is supported and is used as the OWNER of the ON DSNEVENT event.
Warning: In a CA ESP Event that contains both SCHEDULE commands and DSTRIG commands, executions caused by the time schedule do not affect the DSTRIG conditions. The Event executes at both the scheduled times and when the DSTRIG conditions are satisfied. In Control-O, data set trigger rules are ordered daily (if no ESP SCHEDULE statement was coded) but are not acted upon until all run-time criteria (if any exist) are satisfied.
The DSTRIG MULTIPLE sub-parameter is supported as follows: For all DSTRIG MULTIPLE statements contained within an ESP EVENT definition, multiple Control-O ON DSNEVENT events are created for each of the multiple data set name triggers in the DSTRIG parameters. Each rule creates a unique OUT condition (event-name_nnnn). When all of the related dataset rules have been triggered, a final rule, which has all of these conditions as prerequisite IN conditions, is activated to perform the Event's DO FORCEJOB (INVOKE) action. The IN conditions are then deleted.
-
If conversion option ORDEREX is set to the REXX exec name, all DO FORCEJOB actions are converted to DO TSO actions with the REXX exec name of ORDEREX, to perform the CTMAPI ORDER process.
-
BMC recommends that you apply optional wish WO0987 if you experience premature or double rule triggering. See the explanation and implementation/reconfiguration details in the description of WO0987.
8. REEXEC
The CA ESP REEXEC statement allows re-execution of a CA ESP procedure at a specified time or after a certain time interval.
The REEXEC IN(nn) statement causes the Control-M job definition to be created as a cyclic job (TASKTYPE=CYC) and sets the wait time between cyclic runs with a Control-M INTERVAL of nn.
9. [xxx_]JOB name
The CA ESP JOB name is the same as the MVS JCL member name for JOB type events and is used by CA ESP to track the event during its life cycle (see 32. MEMBER for an exception to this rule). The conversion tool creates the Control-M MEMNAME parameter from the CA ESP JOB name.
CA ESP permits job names with a qualifier consisting of up to 8 alphanumeric characters, and separated from the job name by a period. Qualification of job names can be used to define duplicate jobs, give a meaningful name to other job types, such as links and tasks, give a more descriptive name to a job, and so on. The Control-M conversion tool supports such use of qualified job names and places the fully qualified job name in the DESC job scheduling parameter so that the original event of each Control-M job is identifiable.
The conversion tool also adds the following symbolic variables to all jobs that have a qualified name. In each of these symbolic variables, xxx is the qualifier (as a Control-M SETVAR auto-edit variable).
-
ESPAPQUAL=xxx
-
ESPCUQUAL=xxx
These values can then be used at run time to resolve the ESP symbolic variables %ESPAPQUAL and %ESPCUQUAL (respectively) in JCL members or by the conversion process to resolve the ESP %ESPAPQUAL and ESP %ESPCUQUAL symbolic variables (respectively) used throughout the ESP procedure.
The JOB name parameter can also be used to create the Control-M OWNER parameter. For more information, see "OWNER" in Conversion Parameters.
CA ESP jobs on distributed platforms are identified by the following keywords:
-
NT_JOB (NT) (Windows)
-
AIX_JOB, UNIX_JOB (UJ)
-
HPUX_JOB
-
LINUX_JOB
-
NCR_JOB
-
SAP_JOB
-
SAPE_JOB
-
FTP_JOB
-
SCP_JOB
-
PS_JOB
-
AS400_JOB
-
SUN_JOB
-
SQL_JOB
-
TEXT_MON (TM)
-
FILE_TRIGGER (FM)
-
DSTRIG (DT)
-
DB_TRIG
-
INFORMATICA_JOB (IJ)
Only passive support is provided for the following distributed platforms:
-
EXTMON
-
CPU_MON
-
DISK_MON
-
HTTP_JOB (HJ)
-
IP_MON
-
SERVICE_MON
-
AGENT_MONITOR
-
PROXY_JOB
-
BWPC_JOB
-
SEQUENT_JOB
-
PROCESS_MON
-
JMSS_JOB
-
JMSP_JOB
-
MSSQL_JOB
For such jobs, the Control-M MEMNAME parameter is omitted if the distributed job is a command (see item 49. ENVAR). Not all job parameters for all job types are supported.
In addition, for distributed job definitions a Control-M JOBNAME XML parameter is created, either from the CA ESP JOBNAME parameter in the CA ESP script or the LONGNAME subparameter or from the job name specified in the xxx_JOB statement (if neither the JOBNAME nor LONGNAME subparameters are present). The platform name (3 character prefix) is also added the DESC job scheduling parameter.
Long job names for both mainframe and distributed jobs are supported. However, because Control-M supports only 8-character job names, the ESP long job names are converted to a name of the form +xxx where xxx is a unique alphanumeric string. These short job names are used in IN/OUT conditions in job flows involving these jobs. For distributed jobs, these short job names are converted back to the original long name in both the JOBNAME and IN/OUT condition names. For mainframe jobs with long names, a Control-M SETVAR variable %%J is added to the job definition to specify the long jobname.
Other distributed job definition parameters are created as Control-M SETVAR parameters or (XML) ACCOUNTS – see the lists below for the specific parameters which are supported.
The following is a list of ESP AS400 specific keywords supported by the conversion:
Table 10 ESP AS400 specific keywords
Keyword |
Description |
---|---|
name |
Specified in the Control-M SETVAR %%OS400-JOB_NAME |
USER |
The user ID that the agent job runs under. Specified in the Control-M SETVAR %%OS400-JOB_OWNER field. |
COMMAND |
The command that you want to run on an i5/OS system. Specified in the Control-M SETVAR %%OS400-CMDLINE1 |
CLPNAME |
The program that you want to run on an i5/OS system. Specified in the Control-M SETVAR %%OS400-CMDLINE1 |
OTHERS |
Allows specification of any valid SBMJOB command keyword and value combination. |
PRTDEV |
Sub-parameter of OTHERS; printer information. Specified in the Control-M SETVAR %%OS400-PRTDEV. |
JOBPTY |
Sub-parameter of OTHERS; specifies the scheduling priority for the job. Specified in the Control-M SETVAR %%OS400-JOBPTY |
JOBD |
The job description for the program submitted. Specified in the Control-M SETVAR %%OS400-JOBD |
JOBQ |
The i5/OS job queue for the submitted program. Specified in the Control-M SETVAR %%OS400-JOBQ |
LIBL |
The names of the libraries that the job uses that are added to the library list. Specified in the Control-M SETVAR %%OS400-INLLIBL1 |
LOGCLPGM |
Sub-parameter of OTHERS; information included in a job log regarding the commands in a CL (control language) program. Specified in the Control-M SETVAR %%OS400-LOGCLPGM |
LOG |
Specified in the Control-M SETVAR %%OS400-LOG |
MSGQ |
Sub-parameter of OTHERS; Name of the message queue to which a completion message is sent when the submitted job has completed execution. Specified in the Control-M SETVAR %%MSGQ |
CURLIB |
The name of the current library to use when running the job. Specified in the Control-M SETVAR %%OS400-CURLIB |
AS400LIB |
The name of the library that contains the Control Language (CL) program, the source file for the program, or the command that you want to run. Specified in the Control-M SETVAR %%OS400-INLLIBL |
OUTQ |
Qualified name of the output queue used for spooled files. Specified in the Control-M SETVAR %%OUTQ |
INQMSGRPY |
Manner in which pre-defined messages issued as a result of running this job are answered. Specified in the Control-M SETVAR %%INQMSGRPY |
CCEXIT |
The CCEXIT statement specifies the type of exit code returned by an i5/OS job. This parameter is ignored by the conversion. |
*SEVERITY |
Subparameter of CCEXIT: Sends the job’s ending severity code. This parameter is ignored by the conversion. This is the default action of Control-M. |
The following Control-M/EM fields are also created for each AS400 job:
-
APPL_FORM="OS/400 Full"
-
APPL_TYPE=OS400
-
APPL_VER=ALL
-
CM_VER=700
The following is a list of ESP SAP specific keywords supported by the conversion:
Table 11 ESP SAP specific keywords
Keyword |
Description |
---|---|
USER |
The user ID that the agent job runs under Specified in the Control-M SAP ACCOUNT SAPR3-USER parameter |
AGENT |
Identifies the distributed platform where the job runs under the control of the agent Specified in the Control-M SAP ACCOUNT SAPR3-ASHOST parameter |
ABAPNAME |
Starts a step definition within a SAP job definition and identifies the ABAP step to be run. Specified in the Control-M SETVAR %%SAPR3-STEP-Snn-PROGRAM |
VARIANT |
The name of the variant Specified in the Control-M SETVAR %%SAPR3-STEP-Snn-VAR-NAME |
STEPUSER |
The user under whose authorization the ABAP program runs Specified in the Control-M SETVAR %%SAPR3-STEP-Snn-OWNER |
SAPCLIENT |
The SAP client within the SAP system Specified in the Control-M SAP ACCOUNT SAPR3-CLIENT parameter |
SAPJOBNAME |
The SAP job name that identifies the workload to the SAP system Specified in the Control-M SETVAR %%SAPR3-JOBNAME |
RFCDEST |
The SAP destination as specified in the connection properties file The conversion ignores this parameter. |
BANNER |
Whether to include an SAP cover page Specified in the Control-M SETVAR %%SAPR3-STEP-Snn-PRINT_BANNER |
PRINTIMMED |
Whether the job prints immediately when the job completes Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_IMMED |
PRINTCOPIES |
The number of copies for any report associated with the ABAP that the job starts Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_COPIES |
PRINTDEST |
The print destination for an ABAP Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_DEST |
COLUMNS |
The line width of the list Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_NUMCOLUMNS |
LINES |
The number of lines per list page Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_NUMLINES |
SAPTARGETSYSTEM |
The name of the SAP system application server where the SAP job is to run Specified in the Control-M SETVAR %%SAPR3-TARGET_SERVER |
SAPFAILUREMSG |
Specifies a string that indicates the failure of a job Converted to the Control-M ON SYSOUT text-string … DO NOTOK |
PRINTDEPT |
The department name to be printed on the cover page Specified in the Control-M SETVAR %%SAPR3-STEP-S01-DEPT |
PRINTREC |
The recipient of a print document Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_RECIPIENT |
PRINTTEXT |
Specified in the Control-M SETVAR %%SAPR3-STEP-S01-LIST_TEXT |
PRINTLIST |
Specified in the Control-M SETVAR %%SAPR3-STEP-S01-LIST_NAME |
SAPUSER |
Specifies the RFC logon for the SAP system user that the ABAP runs under and overrides the SAP user specified in the connection properties file. Specified in the Control-M OWNER parameter. |
JOBCOPY JOBCOUNT(count) |
Copies an existing SAP job with all of its attributes and specifies the ID of the job to be copied. Specified in the Control-M SAP SETVARs: %%SAPR3-JOB_COUNT=Specific_Job %%SAPR3-JOBCOUNT=nnnnnnnn |
ARCMODE PRINT |
The archive mode that the SAP external archive system uses. PRINT specifies that spool output is to be printed. Specified in the Control-M SETVAR %%SAPR3-STEP-S01-PRINT_ARCHMODE=PRINT |
STARTMODE |
The action to take when the job is readied on the SAP system. Specified in the Control-M SETVAR %%SAPR3-SUBMIT_ASAP=X|N for ASAP|IMMEDIATE |
LANGUAGE |
The language used for the ABAP started by the SAP_JOB. The only language supported by the conversion tool is E(nglish). |
In addition, the following fixed SETVARS are added to every SAP job:
-
%%SAPR3-GROUP_ORDID=%%GROUP_ORDID
-
%%SAPR3-DETECT_CHILD_TABLE=%%SCHEDTAB
-
%%SAPR3-JOB_MODE=CREATE
-
%%SAPR3-SERVER_OR_GROUP_TYPE=S
-
%%SAPR3-JOBCLASS=C
-
%%SAPR3-KEEP_JOBLOG_OPTION=S
-
%%SAPR3-OVERRIDE_JOBLOG_DEFAULT=X
-
%%SAPR3-JOBLOG=*SYSOUT
-
%%SAPR3-SUBMIT_ASAP=X
-
%%SAPR3-DETECT_CHILD_RELEASE=N
-
%%SAPR3-DETECT_OPTION=1
-
%%SAPR3-INC_APP_STAT=no
-
%%SAPR3-RERUN_STEP_NUM=1
-
%%SAPR3-RECIP_TYPE=B
-
%%SAPR3-RECIP_COPY=N
-
%%SAPR3-RECIP_BLIND_COPY=N
-
%%SAPR3-RECIP_EXPRESS=N
-
%%SAPR3-RECIP_NO_FORWARDING=N
-
%%SAPR3-RERUN_FROM_POF=N
The following Control-M/EM fields are also created for each SAP job:
-
APPL_FORM="SAP R3"
-
APPL_TYPE=SAP
-
APPL_VER=7.0.0.200
-
CM_VER=7.0.0.200
External SAP jobs are treated as regular dummy jobs.
The following is a list of ESP SAPE (SAPEvent) specific keywords supported by the conversion:
Table 11a ESP SAPE (SAPEvent) specific keywords
Keyword |
Description |
---|---|
EVENT |
The name of the SAP Event |
REGISTER |
The SAP Event is monitored |
TRIGGER |
The SAP Event is triggered |
In addition, the following fixed SETVARS are added to every SAPE job:
-
%%SAPR3-GROUP_ORDID=%%GROUP_ORDID
-
%%SAPR3-DETECT_CHILD_TABLE=%%SCHEDTAB
-
%%SAPR3-EVENT_ID
-
%%SAPR3-EVENT_PARAM
-
%%SAPR3-ACCOUNT
-
%%SAPR3-JOB_MODE=EVENT_WATCHER / EVENT_TRIGGER
The following Control-M/EM fields are also created for each SAPE job:
-
APPL_TYPE="SAP"
-
APPL_VER="9.0.01"
-
APPL_FORM="SAP R3"
-
CM_VER="9.0.01"
The following is a list of ESP FTP/SCP specific keywords supported by the conversion:
Table 12 ESP FTP/SCP specific keywords
Keyword |
Description |
---|---|
USER |
The user ID the agent job runs under Specified in the Control-M FTP XML ACCOUNT parameter USERNAME |
SERVERADDR |
The name of the FTP server in an FTP job Converted to the Control-M FTP XML ACCOUNT parameter REMOTE HOSTNAME |
SERVERPORT |
The FTP server port number in an FTP job Converted to the Control-M FTP XML ACCOUNT parameter REMOTE PORT |
[TRANSFER]DIRECTION |
The direction of files to be transferred in an FTP job Converted to Control-M SETVAR %%FTP-UPLOAD1 |
REMOTE[FILE]NAME |
Name of one or more files on a remote server involved in an FTP transfer Converted to Control-M SETVAR %%FTP-RPATH1 |
LOCAL[FILE]NAME |
Name of one or more files on the agent computer involved in an FTP transfer Converted to Control-M SETVAR %%FTP-LPATH1 |
FTPFORMAT|TRANSFERCODETYPE |
An ASCII, binary, auto-detect, or EBCDIC transfer, FTP communication type (SSL or regular), and compression level in an FTP job Converted to Control-M SETVAR %%FTP-TYPE1 |
NOCHANGE(nnn) |
The number of minutes that the file must remain unchanged to satisfy the monitor condition. Converted to Control-M SETVAR=%%FileWatch-INT_FILESIZE_COMPARISON=nnn |
In addition the following fixed SETVARS are added to every FTP job:
-
%%FTP-ACCOUNT=FTPACCT
-
%%FTP-LOSTYPE=Windows
-
%%FTP-ROSTYPE=MVS
-
%%FTP-RUSER=REMOTUSR
-
%%FTP-USE_DEF_NUMRETRIES=1
-
%%FTP-RPF=1
-
%%FTP-CLEAR_ALL=1
-
%%FTP-CONNTYPE1=LOCAL
-
%%FTP-CONNTYPE2=FTP
-
%%FTP-LHOST=Local
-
%%FTP-LPASSIVE=0
-
%%FTP-RPASSIVE=0
-
%%FTP-UPLOAD2=1
-
%%FTP-UPLOAD3=1
-
%%FTP-UPLOAD4=1
-
%%FTP-UPLOAD5=1
-
%%FTP-TRANSFER_NUM=1
-
%%FTP-TYPE2=I
-
%%FTP-TYPE3=I
-
%%FTP-TYPE4=I
-
%%FTP-TYPE5=I
-
%%FTP-MINSIZE1=0
-
%%FTP-MINSIZE2=0
-
%%FTP-MINSIZE3=0
-
%%FTP-MINSIZE4=0
-
%%FTP-MINSIZE5=0
-
%%FTP-TIMELIMIT1=0
-
%%FTP-TIMELIMIT2=0
-
%%FTP-TIMELIMIT3=0
-
%%FTP-TIMELIMIT4=0
-
%%FTP-TIMELIMIT5=0
-
%%FTP-IF_EXIST1=0
-
%%FTP-IF_EXIST2=0
-
%%FTP-IF_EXIST3=0
-
%%FTP-IF_EXIST4=0
-
%%FTP-IF_EXIST5=0
-
%%FTP-SRCOPT1=0
-
%%FTP-SRCOPT2=0
-
%%FTP-SRCOPT3=0
-
%%FTP-SRCOPT4=0
-
%%FTP-SRCOPT5=0
-
%%FTP-DSTOPT1=0
-
%%FTP-DSTOPT2=0
-
%%FTP-DSTOPT3=0
-
%%FTP-DSTOPT4=0
-
%%FTP-DSTOPT5=0
-
%%FTP-ABSTIME1=0
-
%%FTP-ABSTIME2=0
-
%%FTP-ABSTIME3=0
-
%%FTP-ABSTIME4=0
-
%%FTP-ABSTIME5=0
-
%%FTP-TRIM1=1
-
%%FTP-TRIM2=1
-
%%FTP-TRIM3=1
-
%%FTP-TRIM4=1
-
%%FTP-TRIM5=1
-
%%FTP-TRANSFER_ALL1=1
-
%%FTP-TRANSFER_ALL2=1
-
%%FTP-TRANSFER_ALL3=1
-
%%FTP-TRANSFER_ALL4=1
-
%%FTP-TRANSFER_ALL5=1
-
%%FILEWATCH-FILESIZE_WILDCARD=Y
The following Control-M/EM fields are also created for each FTP job:
-
APPL_FORM=AFT
-
APPL_TYPE=FILE_TRANS
-
APPL_VER=ANY
-
CM_VER=7.0.00
The following is a list of ESP PEOPLESOFT specific keywords supported by the conversion:
Table 13 ESP PEOPLESOFT specific keywords
Keyword |
Description |
---|---|
PROCESSNAME |
The name of the PeopleSoft report that you want the job to run Converted to Control-M SETVAR %%PS8-PRCSNAME |
PROCESSTYPE |
The type of PeopleSoft report that you want the job to run Converted to Control-M SETVAR %%PS8-PRCSTYPE |
RUNCONTROLID |
A set of PeopleSoft run parameters for a given PeopleSoft process Converted to Control-M SETVAR %%PS8-RUNCONTROLID |
OUTDESTTYPE |
The output destination type for a report Converted to Control-M SETVAR %%PS8-OUTDESTTYPE |
OUTDESTFORMAT |
The type of format for the report output Converted to Control-M SETVAR %%PS8-OUTDESTFORMAT |
OUTDESTPATH |
The path to an output directory or the path to a printer for a PeopleSoft job Converted to the Control-M SETVAR %%PS8-USERDEF1 |
PSOPRID |
The operator ID under whose authority the report runs Converted to Control-M SETVAR %%PS8-USERID |
SERVERNAME |
The name of the target server that executes the job Converted to Control-M SETVAR %%PS8-SERVERNAME |
The following Control-M/EM fields are also created for each PEOPLESOFT job:
-
APPL_FORM=PEOPLESOFT
-
APPL_TYPE=PS8
-
APPL_VER=8
-
CM_VER=6.1.01
The following is a list of ESP SQL specific keywords supported by the conversion:
Table 14 ESP SQL specific keywords
Keyword |
Description |
---|---|
USER |
The user ID the agent job runs under Specified in the Control-M SQL XML ACCOUNT parameter USERNAME |
DB_URL xxx:databasetype:host:port/databasename |
The DB_URL is decomposed into the following Control-M SQL XML ACCOUNT parameters:
|
See 57. SQL for further information on the SQL command.
The following is a list of ESP FILE_TRIGGER specific keywords supported by the conversion:
Table 15 ESP FILE_TRIGGER (FM) specific keywords
Keyword |
Description |
---|---|
FILENAME |
The name of the file to monitor for activity within a File Trigger job (See %%FileWatch-FILE-PATH below). The CREATE and UPDATE sub-parameters are ignored. |
WOBTRIG |
The WOBTRIG command specifies an event-level sensor, which triggers an event upon notification from an agent monitor. When the WOBTRIG FILE_TRIGGER command occurs in an EVENT the resultant FileWatcher job is placed into a Control-M scheduling table named @AFT@ together with any scheduling criteria in the Event. Any INVOKE statements in the EVENT are converted to a Remote DO FORCEJOB (REMFORCE) with a fixed Control-M Datacenter MF (which can be manually change by the user post-conversion). The Control-O rule for the EVENT will be created without the FILE_TRIGGER. The actual file name that triggers the Control-M File Watcher is passed via the DO REMFORCE statement in the local variable %%TRDSN. This is done by capturing the file name from the output Sysout of File Watcher process. |
USER|OWNER |
The user ID that the agent job runs under. See 55. USER/USERID/APPL OWNER/EVENT NAME prefixfor details. |
AGENT |
Identifies the distributed platform where the job runs under the control of the agent. Specified in the Control-M NODE-ID parameter. |
CONTINUOUS(eventid) |
Specifies the identifier of an event to be triggered when the specified file trigger conditions occur. Alerts are not supported. The conversion converts this to ONPGM ANYSTEP CODES OK DO FORCEJOB TABLE(eventid) |
The following Control-M/EM fields are added to the job definition for each FILE_TRIGGER job to create a FileWatcher job:
-
SETVAR=%%M=FW_Job
-
APPL_FORM="File Watcher"
-
APPL_TYPE=FileWatch
-
APPL_VER=8.0.00
-
CM_VER=610
-
SETVAR=%%L="Not in use for File Watcher jobs"
-
SETVAR=%%FileWatch-MIN_DET_SIZE=0
-
SETVAR=%%FileWatch-INT_FILE_SEARCHES=60
-
SETVAR=%%FileWatch-INT_FILESIZE_COMPARISON=10
-
SETVAR=%%FileWatch-NUM_OF_ITERATIONS=3
-
SETVAR=%%FileWatch-TIME_LIMIT=0
-
SETVAR=%%FileWatch-START_TIME=NOW
-
SETVAR=%%FileWatch-STOP_TIME=0
-
SETVAR=%%FileWatch-MIN_AGE=NO_MIN_AGE
-
SETVAR=%%FileWatch-MAX_AGE=NO_MAX_AGE
-
SETVAR=%%FileWatch-PATH="Not in use for File Watch
-
SETVAR=%%FileWatch-MODE=CREATE
-
SETVAR=%%FileWatch-FILESIZE_WILDCARD=N
-
SETVAR=%%FileWatch-FILE-PATH=%%FILENAME
-
SETVAR=%%FILENAME=filename
The following is a list of ESP PROXY specific keywords supported by the conversion:
Table 15a ESP PROXY specific keywords
Keyword |
Description |
---|---|
REMOTE_COMMAND |
Specifies a command or script to run on a remote system. Converted to the same as the CMDNAME parameter (see 46. CMDNAME, SCRIPTNAME, CLPNAME, FILENAME. |
REMOTE_TARGET |
Specifies the host name of the remote system where the job is to run. Converted to the same as the AGENT parameter (see 47. AGENT). If an AGENT statement is included in the ESP PROXY job definition, it is ignored. |
The following is a list of ESP BWPC (Oracle Business Warehouse Process Chain) specific keywords supported by the conversion:
Table 15b ESP BWPC specific keywords
Keyword |
Description |
---|---|
CHAIN |
Identifies the name of a Business Warehouse Process Chain (BWPC) on the SAP system. Specified in the Control-M SETVAR: %%SAPR3-ProcessChain_ID |
In addition, the following fixed SETVARS are added to every BWPC job:
-
%%SAPR3-DETECT_CHILD_TABLE=%%SCHEDTAB
-
%%SAPR3-JOB_WAIT_CHILD=N
-
%%SAPR3-JOB_STATUS_CHILD=N
-
%%SAPR3-JOB_MODE=PC_RUN_ORG
-
%%SAPR3-PROCESS_TYPE=ProcessChain
-
%%SAPR3-ProcessChain_Desc=pc-desc
-
%%SAPR3-PROCESSCHAIN_RERUN_INSTANCE=PC_RUN_CURRINSTANCE
-
%%SAPR3-JOBNAME=SAP Business Warehouse_Job_3
-
%%SAPR3-JOBNAME="SAP Business Warehouse_Job_3"
-
%%SAPR3-PC_periodic=X
-
%%SAPR3-PC_DONT_POLL=N
-
%%SAPR3-JOB_COUNT=FIRST_SCHEDULED
-
%%SAPR3-JOBCOUNT=FIRST_SCHEDULED
-
%%SAPR3-OVERRIDE_JOBLOG_DEFAULT=X
-
%%SAPR3-JOBLOG=*SYSOUT
-
%%SAPR3-DETECT_CHILD_RELEASE=N
-
%%SAPR3-DETECT_OPTION=1
-
%%SAPR3-RUNCOUNT=%%RUNCOUNT
The following Control-M/EM fields are also created for each BWPC job:
-
APPL_FORM="SAP BUSINESS WAREHOUSE"'
-
APPL_TYPE=SAP'
-
APPL_VER=9.0.00.000'
-
CM_VER=9.0.00.000'
The following is a list of ESP INFORMATICA specific keywords supported by the conversion:
Table 15c ESP INFORMATICA specific keywords
Keyword |
Description |
---|---|
REPOSITORY |
Determines the name of the repository where the repository folders and workflows are located. This parameter is specified in the Control-M connection profile (ACCOUNT). Converted to Control-M SETVAR %%INF-ACCOUNT |
WORKFLOW |
Defines the workflow that you want to run in Control-M for Informatica. Converted to Control-M SETVAR %%INF-WORKFLOW |
FOLDER |
Defines the Repository folder that contains the workflow that you want to run. Converted to Control-M SETVAR %%INF-REP-FOLDER |
The following Control-M/EM fields are also created for each INFORMATICA job:
-
APPL_FORM=Informatica
-
APPL_TYPE=ETL_INFA'
-
APPL_VER=8.0.00'
-
CM_VER=8.0.00'
10. DUEOUT
The conversion tool determines a value for Control-M DUE OUT parameter according to the value of the DUEOUT EXEC statement. The conversion tool also adds a SHOUT WHEN LATESUB message. The Control-M monitor uses the calculated DUE IN time of the job to determine if the job is submitted on time, that is, if it will finish by the DUE OUT time of the job. For distributed (non-mainframe) jobs, the actual DUE OUT time specified is used in the SHOUT WHEN LATESUB message.
In the following situations, the DUE OUT DAYS offset field is set:
-
When the PLUS nnn DAYS keyword is specified, the offset field is set to nnn.
-
When a job’s DUE-OUT time is equal or greater than the Newday time and less than the time of the Event that Invoked it, then the offset is set to 1.
-
When a job’s DUE-OUT time is equal or greater than the Newday time and the Event that Invoked it is less than the Newday time, then the offset is set to 1.
For the ESP DUEOUT INPUT statement, the conversion tool only adds a SHOUT WHEN LATESUB message.
If the TOMORROW subparameter is coded on the DUE OUT, see 3. DELAYSUB, EARLYSUB, AT, RESUME.
11. ABANDON SUBMISSION, SUSPEND[(nn)], HOLD(nn)
The CA ESP ABANDON SUBMISSION statement specifies a time to bypass submission of the job. The conversion tool creates the Control-M TIME UNTIL parameter from the ABANDON SUBMISSION time to indicate that the job cannot be submitted after this time. Parameter MAXWAIT is also set to 0.
The CA ESP SUSPEND parameter is treated the same as ABANDON SUBMISSION.
If the PLUS nnn DAYS keyword is specified, the TIME UNTIL DAYS offset field is set to nnn.
If the common practice at the site is to prevent the submission of the job after its calculated DUE IN time has passed, then set the DUEINCHK parameter in the CTMPARM member in the IOA PARM library to Y.
The SUSPEND(nn) and HOLD(nn) parameters which appear on an ESP EVENT ID statement indicate that the Event is placed initially in the suspended/held state. The conversion tool creates the Control-M DEFINITION ACTIVE UNTIL parameter with the current date to indicate that the job is not active.
12. PRIORITY
The CA ESP PRIORITY statement specifies the relative priority of the job within a CA ESP group. The maximum value is 99; the lowest priority value, and the default, is 0. This allows prioritization of jobs within a group without the possibility of delaying jobs in another group. CA ESP uses the priority when one or more jobs, within the same CA ESP group, are competing for the same resource. The queuing sequence of jobs in other groups is not affected.
The conversion tool creates the Control-M PRIORITY parameter by copying the CA ESP PRIORITY value.
The Control-M PRIORITY parameter applies globally and is not restricted within groups as in CA ESP.
If an ESP job definition specifies both a PRIORITY and an ABSORB statement, only the first is processed and the second is ignored.
13. RUN/SCHEDULE, NORUN/NOSCHED
The CA ESP RUN/SCHEDULE, NORUN/NOSCHED statements identify a job or event schedule frequency.
The following conditional IF statements are equivalent to the [NO]RUN statement:
-
IF TODAY(‘scheduling-criteria’) THEN [NO]RUN TODAY
-
IF TODAY(‘scheduling-criteria’) THEN DO
-
[NO]RUN TODAY
-
ENDDO
The following table shows the Control-M job scheduling parameter equivalents for the various CA ESP RUN/SCHEDULE parameters.
The SUSPEND and RESUME statements are not supported when specified in the same event which also specifies a SCHEDULE statement.
Table 16 CA ESP RUN/SCHEDULE Parameters
[NO]RUN/SCHEDULE Keywords |
Control-M Schedule Criteria |
Item No. |
---|---|---|
DAILY, TODAY(DAY) |
DAYS=ALL |
14 |
WORKDAYS |
SCHEDULE RBC=workcal |
|
HOLIDAY |
SCHEDULE RBC=holidaycal |
|
SUNDAY-SATURDAY |
WDAYS=0-6 |
16 |
JANUARY-DECEMBER, %ESP[A|S]MM[M] |
MONTHS=1-12 |
16 |
LAST nth [WEEK]DAY [OF YEAR] |
[W]DAYS=Ln |
16 |
nth [WORKDAY] |
[W]DAYS=[D]n |
14,16 |
various date formats |
DATES=mmdd, ACTIVE FROM/UNTIL |
41 |
[TOMORROW]HOLIDAYS |
DCAL, RBC |
14,16 |
WEEKEND[S] |
WDAYS=0,6 |
14,16 |
WEEKDAYS |
WDAYS=1,2,3,4,5 |
14,16 |
CALENDAR |
DCAL |
14,16 |
nth day-name OF MONTH[-name] |
WDAYS=DmWn m=0-6 [MONTH=nn] |
15 |
nth [DAY OF MONTH] PLUS 0 |
DAYS=>n, DCAL |
14,15 |
nth DAY OF month-name |
DAYS=n, MONTHS=m |
16 |
n-m[LAST] [WORK]DAY of MONTH |
DAYS=[D|L]n, …, DAYS=[D|L]m |
14,16 |
n[LAST] [WORK]DAY of PERIOD |
DAYS=[D|L]n Pi |
16 |
Calendar Special days names |
[-][D|L]xPy |
14,68 |
nth-mth MONTH |
MONTHS=n, …, MONTHS=m |
|
nth WEEK OF MONTH |
WDAYS=(D0Wn,… D6Wn) n=0-6 |
15 |
EXCEPT day-name |
WDAYS=-n |
14,15,16 |
REQUEST |
DCAL=ALLDAYS, CONFIRM=Y |
14,39 |
HOURLY |
INTERVAL=060 |
|
EVERY nnnnn [MINUTES|HOURS|DAYS|WEEKS] |
INTERVAL=nnnnn |
42 |
ROUND |
EVENT name |
26 |
LESS/PLUS nn [WORK]DAYS |
SHIFT, CONFCAL, DAYS offset |
3,10,11,14,40 |
AT [REAL]NOW PLUS nnn MIN/HOUR |
SETVAR %%CTM_PRE_SUB_WAIT=xxxxM |
|
SCHEDULED(YESTERDAY) |
IN condition odate=-001 |
60 |
TOMORROW |
DAYS offset=1 |
|
MIDNIGHT |
TIMEFROM=2400 |
|
NOON |
TIMEFROM=1200 |
|
AND (&) |
RELATION=A |
|
OR (|) |
|
14 |
TIMEZONE (ADT,AST, EDT, EST, CDT, CST, MDT, MST, PDT, PST, BST, GMT, UK) |
TIME-ZONE |
64 |
ANY[DAY]|NOW|TODAY |
SCHEDULE-RBC=* |
60 |
REF |
SCHEDULE RBC |
|
nth DAY OF YEAR |
DAYS=nn, MONTH=mm |
|
nth WORKDAY OF YEAR |
DATES=0101, CONFCAL=cal-name, SHIFT=>+(n-1) |
|
[NORUN] special-dayname |
[EXCLUDE RBC] |
68 |
IF TOMORROW(‘scheduling-criteria’) |
SHIFT=-1 |
|
STARTING|ENDING |
ACTIVE-FROM|ACTIVE-UNTIL |
|
QUARTERLY |
MONTHS=3,6,9,12 |
|
LESS/PLUS nn MINUTES|HOURS |
FROM TIME adjustment of SCHEDULE time |
|
NORUN TODAY |
all prior scheduling criteria are nullified |
|
RUN YESTERDAY |
ignored |
|
NORUN nth day-name OF MONTH |
Exclude RBC |
The above table entries assume that SWEEK=MON. For more information, see 15. WDAYSS.
14. DCAL, WCAL, CONFCAL
Various CA ESP [NO]RUN/SCHEDULE parameters and the use of Special days in the ESP Calendar definitions cause the conversion to utilize regular or periodic calendars.
The conversion tool places this calendar name in the Control-M DCAL, WCAL or CONFCAL parameters, as required. The choice of which parameter may depend on whether the RUN criteria are connected via explicit or implicit AND or OR Boolean operators. For more information, see Calendars.
In ESP events the CALENDAR statement is ignored unless the SCHEDULE statement includes a WORKDAY parameter (or equivalent).
The following ESP scheduling criteria constructs:
IF TOMORROW('HOLIDAY') THEN NORUN
or
NORUN HOLIDAY LESS 1 DAY
are converted as an Exclude RBC named TOMORROW.HOLIDAY
where the RBC specifies
DCAL=@calname
CONFCAL=ALLDAY,SHIFT=-1
and calname is the calendar name specified in the CALDFLT conversion option.
15. WDAYS
The setting of the Control-M WDAYS parameter depends on the setting of the IOA SWEEK Installation Parameter. The illustrations in Table 15 in 13. RUN/SCHEDULE, NORUN/NOSCHED, all assume that the SWEEK parameter is set to MON. If the SWEEK parameter is set to SUN, add 1 (modulo 7) to all WDAYS or Dn specifications.
16. EXCEPT
The EXCEPT keyword is supported with the following CA ESP RUN parameters:
-
SUNDAY-SATURDAY
-
JANUARY-DECEMBER
The EXCEPT keyword causes the job to be excluded from being scheduled according to the specified scheduling parameter. For example, EXCEPT TUESDAY is converted to the Control-M WDAYS=-2 basic scheduling parameter.
17. SELECT/DESELECT
Specifying the name of the job in a SELECT statement selects a job for submission. DESELECT prevents a job from being submitted.
The SELECT/DESELECT statements are usually part of the CA ESP conditional clause: IF TODAY(‘scheduling criteria’) THEN [DE]SELECT
For details on how these CA ESP clauses are converted in Control-M, see Scheduling.
In a job definition, statement SELECT this-jobname, where this-jobname is the same as the jobname that contains the SELECT, is converted as SCHEDULE-RBC=*.
18. TAG
The CA ESP TAG statement is used to "tag" jobs in an Application. In particular, a tag may be used to pass information to JCL. The %ESPAPTAG symbolic variable contains the data in the TAG statement.
The conversion tool supports CA ESP TAGs by converting them to Control-M SETVAR parameters as follows:
%%ESPAPTAG=character-string-tag-value
Embedded blanks in the TAG value are converted to underscores.
19. RESOURCE
CA ESP resources are classified as ENTERPRISE, NODAL or LOCAL resources and are divided into the following three types:
-
renewable
-
depletable
-
threshold
The implementation of some of the advanced uses of CA ESP resources (ENTERPRISE, threshold) is currently beyond the scope of Control-M. The ESP Resource definition file (or RESDEF statement) specifies the class/type of each resource.
The conversion tool converts CA ESP resources, specified as:
RESOURCE (nn,res-name-1,mm,res-name-2,…) to Control-M quantitative resources simply by specifying the CA ESP Resource Name in the Control-M RESOURCE parameter together with the quantity (nn,mm) specified. The user should determine whether this simple conversion is appropriate based on the context of its use in the CA ESP job definition. If no quantity nn is specified then 1 is set as the default.
Resources with a quantity of 0 are ignored.
Resource names longer than 20 characters are truncated to 20. In such a case, it is the user responsibility to ensure that the resource name uniqueness is maintained.
In ESP the HOLD attribute of the RESOURCE statement means that the specified resource is held until the jobs affected by the RESOURCE statement run successfully. In Control-M this is converted to the RESOURCE onFail attribute K, which means keep the resource. The resource remains allocated to the job until one of the following occurs:
-
The job is rerun and ends OK
-
The job is deleted
-
The job is FORCEd OK
In ESP the DEPLETABLE attribute of the RESOURCE statement means that the specified resource is a consumed resource. When ESP submits a task, it permanently removes the depletable resource from the resource pool. In Control-M this is converted to the RESOURCE onOk attribute D, which means the resource is not reusable and to keep it tied to the job if the job ends OK. Depletable resources are converted to the RESOURCE OnOk attribute D, which means it permanently removes the quantity specified in the RESOURCE statement from the resource pool.
20. AFTER, RELEASE, POSTREQ, PREREQ
The CA ESP AFTER [ADD], RELEASE (REL), POSTREQ, and PREREQ parameters specify a job's predecessor and successor relationships. The conversion tool creates corresponding Control-M IN, OUT or ON PGMST parameter definitions for these dependency parameters.
All condition names shown in this item assume that conversion option CONDNM is set to ‘S’. See Conversion Parameters for further details.
The CA ESP job dependency is coded as: [pfx]jobname[.qualifier][(x)] [CONDITIONAL]
For every job, the conversion tool always creates an OUT condition of the form:
[pfx]jobname[.qualifier] ODAT+
When x is omitted, or x=N, the conversion tool creates an IN condition of the form:
[pfx]jobname[.qualifier] ODAT
When x=A, the relationship indicates a dependency on the abnormal end of a job. The conversion tool creates an IN condition of the form:
[pfx]jobname[.qualifier]_! ODAT
In addition, the conversion tool creates an ON PGMST parameter in the job scheduling definition of jobname. This parameter is of the format:
ON PGMST ANYSTEP CODES NOTOK
DO COND [pfx]jobname[.qualifier]_! ODAT +
When x=U, the relationship indicates a dependency when a job ends either normally or abnormally (any termination). The conversion tool creates an IN condition of the form:
[pfx]jobname[.qualifier]_= ODAT
In addition, the conversion tool creates an ON PGMST parameter in the job scheduling definition of jobname. This parameter is of the format:
ON PGMST ANYSTEP CODES **** *****
DO COND [pfx]jobname[.qualifier]_= ODAT +
The ‘maybe’ prefix pfx is added to the IN/OUT conditions depending on the setting of the Conversion option DOMAYBE. The value of pfx is set by Conversion option MAYBEPF. For more information about these Conversion options, see Conversion Parameters.
When the list of job names is followed by COND([NOT] [RC(rc)] [AND|OR] [NOT] [RC("Shhh"|"Unnnn")] [AND|OR] [NOT] [STEPRC('[proc].step',"Shhh"|"Unnnn"|nnnn)]) then rather than building a standard OUT condition, to support the COND criteria, the conversion creates a structure similar to the following for each job in the job-list:
ON PGMST step1 PROCST proc CODES Crc A/O A
ON PGMST step2 PROCST CODES NShhh A/O
DO COND cond-name ODAT +
If the COND(RC|STEPRC(xxx)) subparameter is specified, then instead of creating a Control-M OUT parameter, an ON PGMST stepname PROCST procst CODES xxx, DO COND cond-name is created where xxx is the return code/system code/user code specified. When no ESP STEPRC is coded, then the Control-M stepname +JOBRC is used. Return code ranges are supported.
IN/OUT conditions are created only for job dependencies where the predecessor/successor jobs reside in the same table. The only exception to this is for External jobs, which allow cross-table dependencies.
21. CCFAIL
The CCFAIL statement identifies which condition code should cause CA ESP to consider a job as failed.
The CA ESP CCFAIL statement has the following format:
CCFAIL ([procstepname.]stepname|*,oper,nn)
and is converted to a Control-M ONPGM post-processing job scheduling statement as follows:
ONPGM,STEP=stepname,PROCST=procstepname
CODES=code
DO=action
where:
-
procstepname is the step name of the JCL procedure being invoked
-
stepname is the step name directly specified in the JCL when the procstepname is not specified, or the step name with the specified procedure
-
rather than specifying a stepname and/or procstepname, an '*' may be specified to indicate that any step (STEP=ANYSTEP) can satisfy the condition code
-
oper can specify any of the following GE, GT, LE, LT, EQ, NE
-
nn is any numeric value up to 4095
Since Control-M, by default, treats all conditions codes greater than 4 (or 0 depending on the MAXCCOK parameter specified in the CTMPARM member of the IOA PARM library) as NOTOK, the conversion translates the CA ESP operator and codes as follows:
CA ESP |
Control-M Code |
Action |
---|---|---|
GT 0 |
>C0000 |
DO NOTOK |
GT nn (nn not 0) |
<C(nn+1) |
DO OK |
GE nn |
<Cnn |
DO OK |
LE nn |
<C(nn+1) |
DO NOTOK |
EQ nn |
Cnn |
DO NOTOK |
NE nn |
Cnn |
DO OK |
Any CCFAIL statement which results in a Control-M ON PGMST ANYSTEP statement is always placed before any other ON PGMST statement which does not specify ANYSTEP
22. CCCHK/EXITCODE
The CCCHK statement identifies specific completion codes and indicates how CA ESP should handle the job when those completion codes are matched.
The CA ESP CCCHK statement has the following format:
CCCHK [STEP([procstepname.]stepname)|PROGRAM(pgm-name)]
RC(nn[:mm]|Snnn|Unnnn) FAIL|OK CONTINUE|STOP
The conversion tool converts the CA ESP CCCHK statement either to a Control-M ON PGMST post-processing job scheduling statement (similar to the CA ESP CCFAIL statement) or a CMEM ON STEP event as follows:
-
When the PROGRAM option is specified, the conversion tool creates an entry in the PGMST member of the CTM PARM library with the specified program-name.Application-level CCCHK statements are also specified in the PGMST member in sections with the following label:
++ SCHLIB=schedule-lib-name,TABLE=application-name.
For details about the PGMST member (JSCSF feature), see The Job/Step Completion Status Facility (JSCSF) in the INCONTROL for z/OS Administrator Guide.
-
CA ESP stepname and procstepname are converted as in the CA ESP CCFAIL statement (see 21. CCFAIL)
-
CA ESP RC range codes are converted as described in the following table:
CA ESP RC |
Control-M Codes |
---|---|
Sxxx |
Sxxx |
Unnn |
Unnnn |
nn |
Cnnnn |
nn:mm |
>C(nn-1), <C(mm+1) (nn=0 is ignored) |
nn:mm specified as 0:4095 is converted to C****
nn:mm specified as nn:4095 (where nn is not =0) is converted to >C(nn-1)
-
CA ESP code FAIL is converted to the Control-M DO NOTOK statement, and CA ESP code OK is converted to the DO OK statement
-
When a STOP action is specified, the CCCHK statement is converted to a CMEM ON STEP rule (rather than a Control-M ON PGMST statement) that contains a DO STOPJOB statement
The EXITCODE statement for distributed jobs is similar to the CCCHK statement and is converted similarly. It has the following format:
EXITCODE nnn-mmm [SUCCESS/FAILURE]
An EXITCODE statement which specifies '0 SUCCESS' is ignored, since this is the Control-M default action. Similarly, an EXITCODE statement which specifies '1-nnn FAILURE' is ignored, since this is the Control-M default action.
For distributed job definitions, the format of the ON is as follows:
ON CODE="COMPSTAT x mmm" STMT="*"
DO=action
Where x is the operator (>, <, =, etc.) and mmm is the job’s highest return code and action is OK or NOTOK.
The range form of the EXITCODE statement is supported only in the following instances:
-
The status is SUCCESS and nnn is 0 or 1, which is converted to <C(mm+1) DO OK
-
The status is SUCCESS and mmm is 9999, which is converted to >C(nnn-1) DO OK
-
The status is FAILURE, which is converted to <Cnnn DO OK
Any CCCHK statement which results in a Control-M ON PGMST ANYSTEP statement is always placed before any other ON PGMST statement which does not specify ANYSTEP.
Any CCCHK statement that specifies PGM(ESP) is ignored.
23. % VARIABLES (in JCL)
CA ESP provides substitution capabilities through symbolic variables. A symbolic variable is an object whose value can be changed during ESP processing. CA ESP % variables provide flexibility to define date parameters, specify job names, define job dependencies, and to use in command input.
The conversion tool converts all CA ESP % variables to Control-M %%AutoEdit variables wherever they appear in the JCL stream. The statement
%%GLOBAL CNVESPIN
is inserted into any JCL stream that utilizes variables (at the first occurrence of a symbolic variable). The %%GLOBAL statement aids in resolving user-defined variables to their assigned values. The member CNVESPIN (which was copied from the IOA SAMPLE library) contains the translation of ESP system variables to Control-M AutoEdit format.
CA ESP variables might also appear in job definition scripts (for example, in the JCLLIB and TEMPLIB statements). These are likewise converted to Control-M AutoEdit variables.
CA ESP variables defined in the symbolic-variable members (specified in the DASYM dd statement) are also used to resolve symbolic names specified as the values of certain ESP job definition parameters (for example, in the RUN, IF TODAY(sym-var), AGENT, USER, and so on).
Currently, the ESP symbolic variable members are not used for JCL variable resolution.
When an ESP symbolic variable is concatenated with a constant value, e.g %var.ABC, the conversion tool converts this to %%var%%.ABC using the Control-M AutoEdit ‘%%.’ concatenation symbol. In addition, for ESP symbolic variables which are followed by a period and then a character which is a Control-M AutoEdit delimiter character, the period is dropped. For example, %dsn-var.(%membr) is converted to %%dsn-var(%%membr).
Symbolic variable substrings of the form %var(n:m) are supported and are converted using the Contol-M auto-edit %%SUBSTR function.
Nested ESP JCL variables of the form %(var1%(var2%var3)) are supported and are converted as: %%var1%%var2%%var3 (no periods between the variables). Similarly, %(%(%var) is converted to %%%%%%var.
-
For installations using an alternate symbolic character sign (instead of %), set this value in the VSYMBOL conversion option. For a description of this conversion option, see Conversion Parameters).
-
The character ‘#’ contained in any variable name is changed to the underscore character ‘_’.
24. Variable definitions (in ESP procedures)
CA ESP variables can be set in CA ESP procedures (see 23. % VARIABLES (in JCL)) to set variable values. To assign a value to a symbol the following is coded:
variable = 'variable-value'
The variable-value can itself be a symbolic variable or contain a symbolic variable.
These variables are converted by the conversion tool to Control-M SET VAR job scheduling parameters as follows:
SET VAR %%variable=variable-value
-
ESP variable names are treated by the conversion as being non-case-sensitive, both as objects of the symbolic variable definition and when used within the value of the variable.
-
CA ESP variables of the form %var.XYZ are converted to the Control-M AutoEdit variable %%var%%.XYZ, using the Control-M concatenation symbol. CA ESP variables of the form %var%XYZ are converted to the Control-M concatenated AutoEdit variables %%var.%%XYZ.
-
Recursive symbolic variable definitions are not supported.
ESP variables defined on multiple lines are supported. However, Global variables (at the Application level) are supported only if the total length of the variable name and value do not exceed 65 characters.
Variable values of the form ‘xxx’+‘%yyy’ are converted as concatenated AutoEdit values ‘xxx%%yyy’.
Certain ESP symbolic variables cause the conversion to create SHOUT statements in Control-M job definitions. Here are several examples:
-
The MAXRUNTIME=nnn variable is converted to the following SHOUT statement:
CopySHOUT-WHEN=EXECTIME,TIME=>nnn
This SHOUT statement has the message text 'JOB %%JOBNAME IS LATE!' and a destination of OPER.
MAXRUNTIME values that exceed 999 minutes are reduced to 999.
-
The MAXRUNTIME = AVGRUNTIME [+|-] nnn variable is converted to the following SHOUT statement:
CopySHOUT WHEN=EXECTIME,TIME=[+|-]nnn
This SHOUT statement has the message text 'JOB %%JOBNAME IS LATE!' and a destination of OPER.
-
The MINRUNTIME=nn variable is converted to the following SHOUT statement:
CopySHOUT WHEN=EXECTIME,TIME=<nnn
This SHOUT statement has the message text 'JOB %%JOBNAME has ended prematurely!' and a destination of OPER.
-
For installations using an alternate symbolic character sign (instead of %), set this value in the VSYMBOL conversion option. For a description of this conversion option, see Conversion Parameters.
-
Single-level nested variables of the form %(var-name) are supported. Multi-level nested variables (such as %(var1%(var2%var3)) are not supported.
-
The character ‘#’ contained in any variable name is changed to the underscore character ‘_’.
25. CRITICAL
The CA ESP CRITICAL keyword on the JOB statement identifies a critical job.
The conversion tool sets the Control-M PRIORITY parameter to * to indicate that this is a critical path job.
26. EVENT ID (prefix.descriptor)
The CA ESP EVENT ID consists of 2 parts - a prefix and the event description. The Eventprefix establishes its ownership, which is used for security purposes to control the authority and access users have to the event. The descriptor is a description that can contain up to 16 characters.
The conversion tool creates the Control-O EVENT OWNER parameter from the prefix name.
If there is a USER or OWNER parameter on the EVENT statement, then whichever occurs first overrides the owner from the prefix name. When the Control-O rule is merged into the corresponding SMART scheduling table (for details of this process, see Events), the OWNER parameter is placed into the table entity and propagated to all the jobs in the table, except for distributed job definitions, where the USER parameter in the ESP job definition, if specified, takes precedence. Control-M folders not associated with an ESP Event are assigned an OWNER by the conversion (the userid running the conversion job).
The conversion tool also creates a SYSEVENT=event-id statement in all ESP procedures which are invoked by the event.
The conversion tool creates the Control-O ON EVENT name parameter from the first 8 characters of the CA ESP event descriptor and places the full 16 character descriptor in the DESC job scheduling parameter so that the original event name of each Control-O rule is identifiable.
If a CA ESP Event's schedule criteria specifies HOURLY this indicates that the event is a cyclic event.
In Control-O, to run a cyclic event rule at designated times (for example, at exactly 2:00, 3:00, and so on.), besides setting the INTERVAL parameter, the EVENT name prefix FIXT must be specified. Even if the rule is ordered after the specified TIME FROM, the rule is not executed until the next interval as calculated from the starting time.
-
The ESP Event name can be displayed in the Control-O OR rule list screen by issuing the STAT top line command.
-
The SYSTEM parameter on ESP Events is ignored.
27. JCLLIB, DATASET
The CA ESP JCLLIB statement specifies the JCL library to be used for all (z/OS) jobs following this statement. The CA ESP DATASET statement overrides the JCL library for a particular job. The conversion tool creates the Control-M MEMLIB parameter from the CA ESP JCLLIB statement or the CA ESP DATASET statement, when present. For distributed job definitions, see the SCRIPTNAME statement described in 46. CMDNAME, SCRIPTNAME, CLPNAME, FILENAME.
If the value of the JCLLIB|DATASET statement is 8 or less characters, with no embedded special characters (such as periods), then the value is treated as a ddname and is converted to the Control-M MEMLIB parameter as DDNAME=ddname. This functionality requires that the following exits be installed: CTMX002G, CTMX014G, CTMX015C (see the IOA SAMPEXIT library).
The DATASET parameter is ignored if specified on an EXTERNAL or LINK type (DUMMY) jobs.
When the JCLLIB statement is preceded by a corresponding ESP CONCAT statement, the conversion sets the Control-M MEMLIB parameter to GENERAL. It is the user's responsibility to supply a concatenated list of JCL libraries referenced by the ESP CONCAT statement in the DALIB DATASET concatenation in the local version of the IOADSN member of the IOA PARM library. For details, see Allocation Members in the INCONTROL for z/OS Administrator Guide.
When an ESP JCLLIB/DATASET specifies a ddname rather than a dataset name, the conversion creates the Control-M MEMLIB parameter as DDNAME=ddname. This functionality requires that the following IOA sample exits be installed: CTMX002G, CTMX014G, CTMX015C
28. TEMPLIB
The CA ESP TEMPLIB statement specifies the temporary, or override JCL library, to be used as the default for all (z/OS) jobs following this statement. CA ESP uses JCL from this library for job submission, if it exists. Otherwise, it uses JCL from the most recent CA ESP JCLLIB statement.
The conversion tool creates the Control-M OVERLIB parameter for non-DUMMY and mainframe jobs from the CA ESP TEMPLIB statement.
29. DOCLIB/DOCMEM
The DOCLIB statement is used to identify the name of the job documentation library to be used throughout an ESP application. Similarly, the conversion tool creates the Control-M DOCLIB parameter from the CA ESP DOCLIB statement.
CA ESP retrieves job documentation by job name. To reference a job documentation member with a name other than the job name, the DOCMEM keyword is specified when you identify the job in a CA ESP Procedure. The conversion tool creates the Control-M DOCMEM parameter from the CA ESP DOCMEM statement.
30. ROUTE
CA ESP can automatically insert a /*ROUTE statement into the JCL it submits. This statement routes a job to a different node for execution. The name of the JES node to which you want to route the job is specified in the XEQ sub-parameter. The conversion tool creates the Control-M NJE-NODE parameter from the node-name in XEQ.
31. NOTIFY
A CA ESP NOTIFY statement is used to send a message or trigger an Event when a job becomes overdue, is submitted, starts, ends abnormally (ABENDs or ABANDONSUBMISSION), fails (for example, condition code failures), ends (successfully or unsuccessfully), or resubmits a job.
The conversion tool supports the NOTIFY message sending function only by creating SHOUT and ONPGM parameters as follows:
CA ESP NOTIFY |
Control-M |
---|---|
FAIL[URE] |
SHOUT-WHEN NOTOK |
ABEND |
SHOUT-WHEN NOTOK |
ABANDONSUBMISSION |
SHOUT-WHEN NOTOK |
OVERDUE/DUEOUT EXEC |
SHOUT-WHEN LATE |
OVERDUE/LATESUB |
SHOUT-WHEN LATESUB |
RESUB |
SHOUT-WHEN RERUN (inside job definitions only) |
[JOB]END |
ONPGM ANYSTEP CODES **** ***** DO SHOUT |
[JOB] START |
SHOUT EXECTIME > 000 (001 for distributed jobs) |
SUBMIT |
SHOUT EXECTIME > 000 (001 for distributed jobs) |
LATEPRED |
SHOUT EXECTIME +5 |
PNODE(SUBERROR) |
SHOUT-WHEN NOTOK |
PNODE(COMPLETE) … EVENT(eventid) |
ONPGM ANYSTEP CODES [NOT]OK DO FORCEJOB TABLE(eventid) LIBRARY(lib) |
SUBJECT |
not supported |
The Control-M SHOUT destination is determined by the U[SERS], ROUT[E], or MAILBOX parameter on the CA ESP NOTIFY statement. The Control-M SHOUT message text is taken from the ESPDEF defaults source conversion member, and the SHOUTL, SHOUTN, SHOUTR, SHOUTE, SHOUTT, and SHOUTS parameters. When the NOTIFY statement specifies a descriptor code (DESC) of 2, the Control-M SHOUT Urgency is set to V (Very urgent) and a descriptor code of 3 is set to Urgency U.
MAILBOX names of up to 12 characters are supported in the SHOUT DEST=U-M:mbox-name. The mbox-name must be coded in the MAILDEST member of the IOA PARM library as a GROUP name with all of its associated e-mail addresses.
For full e-mail names of the form MAILBOX(name@suffix), only the prefix of the name, up to the '@' character (for those that contain an '@'), will be used in the SHOUT ... DEST=U-M:prefix statement.
The suffix should be specified in the DFLTSFFX parameter in the MAIL section of the IOAPARM member in the IOA PARM library. Alternatively, a nickname (and GROUP) can be specified in the MAILDEST member of the IOA PARM library.
In cases where the ‘name’ portion of the mailbox e-mail exceeds 12 characters, an error message will be produced, informing you that the MAILBX name was truncated to form the prefix and the user should take remedial action as described above.
A CA ESP NOTIFY statement may contain multiple notification reasons. The conversion tool creates an appropriate SHOUT or rule for each one.
CA ESP ALERT processing is not supported.
When a NOTIFY statement specifies an EVENT ID instead of a destination, then rather than a CONTROL-M SHOUT-WHEN being generated, a CMEM rule or an ONPGM ANYSTEP CODES code with a DO FORCEJOB TABLE(folder name that corresponds to the EVENT ID) action is created, as follows:
ONPGM STEP ANYSTEP CODES [NOT]OK
DO FORCEJOB TABLE <folder name>
When the NOTIFY statement appears in the APPL level, it propagates the above action to each job in the TABLE.
Parameters of the NOTIFY statement are converted as follows:
-
FAIL, ABEND => code NOTOK
-
JOBEND => codes ‘*****,****’
-
JOBSTART => CMEM ON JOBARRIVAL
32. MEMBER
The conversion tool normally specifies the CA ESP job name in the Control-M MEMNAME parameter. For more information, see 9. [xxx_]JOB name. If the CA ESP JOB name differs from the CA ESP JCL member name, the conversion creates the following In-stream JCL in the job definition as follows:
%%INCLIB jcl-lib %%INCMEM member-name
The above AutoEdit command copies the JCL from the member-name specified in the CA ESP MEMBER parameter. The data set name of the JCL library is determined by a previously defined CA ESP JCLLIB statement.
33. PROCESS, CONDITION[AL]
The CA ESP PROCESS and CONDITION[AL] parameters on the JOB statement are ignored by the conversion tool.
34. COM
A CA ESP COM command is used to add any number of comments, anywhere in an Event. CA ESP ignores them when it executes the Event.
The conversion tool converts the COM statement to a Control-O comment. Comments are free text descriptions of rule definition parameters that are stored in a rule definition member. Comments are not processed during rule execution. Comment lines are opened beginning with the symbol /*. An unlimited number of comment lines can be included within a rule definition.
35. HOLD
The CA ESP HOLD keyword on the JOB statement indicates that CA ESP must hold an event from being processed by CA ESP at a particular time.
The conversion tool sets the Control-M CONFIRM parameter to Y.
36. LINK, TASK, SELFCOMPLETING
The CA ESP LINK, TASK, and SELFCOMPLETING keywords on the JOB statement indicate that CA ESP does not try and submit JCL for the job.
The conversion tool sets the Control-M MEMLIB parameter to DUMMY.
A TASK without the SELFCOMPLETING attribute is created with the Control-M CONFIRM=Y parameter.
37. INVOKE
The CA ESP INVOKE command invokes a CA ESP Procedure or a CA ESP Symbolic variable member by specifying where the CA ESP Procedure/Symbolic variable member is stored.
The conversion determines which type of member is being invoked depending on the contents of the XLATDSN file and then processes the INVOKE statement according. See JOB1 Input for full details and examples of how to code the XLATDSN file.
If conversion option ORDEREX is set to the REXX exec name, all DO FORCEJOB actions are converted to DO TSO actions with the REXX exec name of ORDEREX, to perform the CTMAPI ORDER process.
38. SUBMIT
A CA ESP Event can submit JCL from a data set to the internal reader using the SUBMIT command. A single event can submit more than one job.
The conversion tool converts the SUBMIT statement to a Control-O ON EVENT DO TSO SUBMIT command with the supplied library and member name.
If the ESP Event does not contain a SCHEDULE statement, the conversion causes it to be scheduled daily.
39. REQUEST
In CA ESP, On-request jobs take their place in the schedule when they are selected and are subsequently explicitly requested. If you have not explicitly requested the job, CA ESP bypasses it and treats it as a normal completion, releasing its successor jobs.
By selecting a REQUEST job, you are not requesting the job, you are only making it eligible for explicit request by means of CA ESP commands.
CA ESP REQUEST jobs are converted with the Control-M CONFIRM parameter set to Y.
CA ESP NOREQUEST jobs are converted with the Control-M CONFIRM parameter set to N.
40. LESS, PLUS
The CA ESP LESS/PLUS n units keywords specify a value to be subtracted or added to the base scheduling time to produce a time/date execution time. The conversion tool converts this to the following Control-M parameters:
When n is not 0:
-
SHIFT @-nn or @+nn
-
CONFCAL ALLDAYS (when units=DAYS)
-
CONFCAL SYSTEM (default calendar) or the calendar specified in the ESP CALENDAR statement (when units=WORKDAYS)
When n=0, the SHIFT parameter is created only with '<' (LESS) or '>' (PLUS) and the +/-n extended shift is omitted.
The Control-M conversion tool only supports this parameter when the units are either DAYS or WORKDAYS.
41. Dates
CA ESP dates of the form mm/dd/yy, dd/mm/yy, yy/mm/dd (depending on the CA ESP DATEFORM Initialization parameter), ddmmm[yy]yy (mmm=month name), yy.ddd, and yyyy.ddd schedule jobs on the date specified.
Control-M converts the date to:
-
DEFINITION ACTIVE FROM=yy0101
-
DEFINITION ACTIVE UNTIL=yy1231
-
DATES=mmdd
If an event definition contains multiple dates, the conversion may result in the creation of multiple Control-M job scheduling definitions. For example, if the event is scheduled for two dates in different years, two job scheduling definitions are created, with differing DEFINITION ACTIVE FROM and DEFINITION ACTIVE UNTIL parameters.
42. EVERY
The CA ESP EVERY nn [MINUTES|HOURS|DAYS|WEEKS] parameter schedules an event every nn units of the specified time parameter. If the EVERY parameter appears in an ESP EVENT scheduling definition then it is converted to a Control-O cyclic event by specifying INTERVAL=nnn (in minutes) in the ON EVENT rule and specifying the rule name with the prefix ‘FIXT’. See Events for further details.
Note that in CTO the INTERVAL parameter cannot exceed the equivalent of 999 minutes.
If the EVERY parameter appears in an ESP procedure job definition, then the job is converted to a cyclic job with an INTERVAL=nnnnn which cannot exceed the equivalent of 64,800 minutes (45 days).
If the EVERY parameter is not followed by a numeric value, for example, EVERY MON, then the word EVERY is ignored and the scheduling criteria is converted as non-cyclic criteria.
If EVERY nnn is specified in an ESP job or event definition, and no other scheduling criteria is specified in the job or event, then the corresponding Control-M definition is created with the WDAYS ALL scheduling criteria.
43. APPL WAIT, JOB_ANCESTOR_WAIT, POST_OLDEST, NOPOST_UNTIL_READY
In CA ESP, specifying WAIT on an application indicates that concurrent processing of different generations of the application is not permitted.
WAIT specifications are converted to the Control-M by specifying the following IN parameter on the SMART Table Entity of the SMART Table:
IN application-group-name PREV
which causes the group to wait until the previous occurrence of the group has successfully processed.
An Exclusive CONTROL resource parameter of the format WAIT-tablename is also added to the SMART Table Entity of the SMART Table. This serializes the table if it is ordered multiple times during the same day.
The JOB_ANCESTOR_WAIT(ANY|LAST) on the APPL statement prevents each job in the application from being submitted until a previous run of the same job has completed. When conversion option ANCESTR is set to C, this is converted by adding an Exclusive Control-M CONTROL resource to each job in the application of the form:
CONTROL jobname E K
where the K (Keep) sub-parameter indicates that the resource is kept allocated to the job until one of the following events occurs:
-
the job is rerun and ends OK
-
the job is deleted
-
the job is FORCEd OK
The Keep attribute is not supported for distributed job definitions.
When conversion option ANCESTR is set to I, this is converted by adding a Control-M IN condition to each job in the application of the form:
IN JAW-jobname PREV
In CA ESP, specifying POST_OLDEST on an application indicates that EXTERNAL and MANUAL jobs are posted complete in the oldest active generation of an application.
POST_OLDEST specifications are converted to the Control-M by specifying an Exclusive CONTROL resource parameter of the format POST-tablename in the SMART Table Entity of the SMART Table. This serializes the table when several generations are ordered concurrently.
The NOPOST_UNTIL_READY prevents each job in an application from being marked complete until the job has been readied. The conversion ignores this attribute, as this is the default Control-M action.
44. MANUAL
The CA ESP MANUAL job attribute indicates that the job is submitted outside an Application. This includes jobs submitted directly by an Event.
The Manual job is created as a Dummy Control-M job definition with IN condition HM-tablename-jobname and OUT statement to delete the condition. The conversion tool creates a Control-O ON JOBEND rule, which monitors the system for the completion of the specified job, and then the rule issues a DO COND HM-tablename-jobname to release the manual job.
If conversion option ORDEREX is set to the REXX exec name, all DO FORCEJOB actions are converted to DO TSO actions with the REXX exec name of ORDEREX, to perform the CTMAPI ORDER process.
45. EXTERNAL, APPLID
The CA ESP EXTERNAL job attribute indicates the job is submitted by another CA ESP application and is used to build inter-application dependencies.
The conversion tool marks the external job as a DUMMY job and creates the inter-application dependency by adding a standard format OUT condition to the ‘home’ job and specifying the same condition in the External occurrence of the job as an IN condition. The location of the ‘home’ job of an external job is determined by the APPLID parameter on the JOB statement. When APPLID is coded, the ‘home’ job is searched for only in the ESP Application specified in APPLID. When no APPLID is coded on the JOB statement, then only the first home job of the possible home jobs, regardless of the Applications they appear in, is treated as ‘home’ job and the requisite IN/OUT conditions are built using it.
For an external mainframe job, if its ‘home’ job cannot be found in the ESP Procedure libraries, the conversion will create a CMEM ON JOBARRIVAL rule specifying DO FORCEJOB (thereby creating an On Spool job). See the Control-M for z/OS User Guide for more information about On Spool jobs.
-
If conversion option ORDEREX is set to the REXX exec name, all DO FORCEJOB actions are converted to DO TSO actions with the REXX exec name of ORDEREX, to perform the CTMAPI ORDER process.
-
Processing of External jobs is affected by the setting of the IGNREXT conversion option. For details, see Appendix A, Conversion Parameters.
-
Any time hh.mm parameters in External SCHEDULED statements are ignored.
46. CMDNAME, SCRIPTNAME, CLPNAME, FILENAME
The CA ESP CMDNAME (COMMANDNAME), SCRIPTNAME, FILENAME, and CLPNAME are statements used in distributed job definitions.
CMDNAME identifies Agent-platform commands to run when defining jobs for the Agents running on Windows and UNIX platforms.
The SCRIPTNAME statement specifies the UNIX shell script to run for distributed job definitions. CLPNAME is used when defining jobs for the OS/400 Agent to identify the OS/400 program to run.
FILENAME specifies the name of a file (on a distributed platform) to monitor for activity within a file-trigger job. FILENAME triggers the release of the job named in the CA ESP FILE_TRIGGER statement. See 9. [xxx_]JOB name above for details on how this FILE_TRIGGER events are converted to Control-M File-Watcher jobs.
The SCRIPTNAME and CLPNAME, parameters are split into the Control-M MEMLIB (path) and MEMNAME (program name) parameters with a TASKTYPE=Job.
When an ESP job specifies a CMDNAME statement accompanied by ARGS, as in the example below:
SUN_JOB BSN524
CMDNAME /usr/openv/netbackup/bin/bpbackup
BSN524NODE = 'nsun700.wfm.wegmans.com'
ARGS -p Solaris_File_RDC_Prod -i -h %BSN524NODE -s Incremental -w
ENDJOB
the conversion tool will convert it as follows when creating the XML file:
TASKTYPE=”Command”
CMDLINE="/usr/openv/netbackup/bin/bpbackup %%PARM1 %%PARM2 %%PARM3 %%PARM4 %%PARM5 %%PARM6 %%PARM7 %%PARM8”
<AUTOEDIT EXP="%%PARM1=-p" />
<AUTOEDIT EXP="%%PARM2=Solaris_File_RDC_Prod" />
<AUTOEDIT EXP="%%PARM3=-i" />
<AUTOEDIT EXP="%%PARM4=-h" />
<AUTOEDIT EXP="%%PARM5=%%BSN524NODE" />
<AUTOEDIT EXP="%%PARM6=-s" />
<AUTOEDIT EXP="%%PARM7=Incremental" />
<AUTOEDIT EXP="%%PARM8=-w" />
The number of %%PARMn on the command-line is derived from the number of arguments on the ESP ARGS command. No %%PARMn’s are generated on the CMDLINE if there are no ARGS.
CMDNAME values enclosed in delimiters (quotes/apostrophes) are copied with their accompanying delimiters. Any ESP symbolic variables contained in the values of these statements are converted to Control-M auto-edit format.
ESP System variables embedded in distributed CMDNAME, SCRIPTNAME, or ARGs statements are supported. For further details, see Post Step 2 – Perform Final Adjustments, item 4.
47. AGENT
The CA ESP AGENT statement identifies the specific distributed platform where the job runs. The conversion sets the Control-M NODEID parameter (host name of an agent computer) to the agent name.
Symbolic Agent name values are supported.
48. SHELL
The CA ESP SHELL statement specifies the shell used to run the script named in the SCRIPTNAME statement. The SHELL statement is converted to a Control-M AutoEdit variable H of the form:
EXP="%%H=shell%%BLANK%%.-c"
The AutoEdit variable H is then specified as the first parameter of the Control-M CMDLINE statement as follows:
CMDLINE="%%H script-name"
The –c option indicates that a command string (in this case, the script-name) follows and runs command as if it were an input line to the shell.
49. ENVAR
The ENVAR statement passes environment variables to a batch file, script, command, or program for distributed job definitions. These variables are converted to Control-M AutoEdit variables of the form:
AUTOEDIT EXP="%%variable-name=variable-value"
In addition, if the variable name is STDOUT, then the following Control-M statement is created:
ONPGM,STEP=ANYSTEP,CODES=OK
DO=SYSOUT,SYSOUT-OP=F (copy)
SYSOUT-PRM="%%STDOUT"
If the variable name is STDERR then the following Control-M statement is created:
ONPGM,STEP=ANYSTEP,CODES=NOTOK
DO=SYSOUT,SYSOUT-OP=F (copy)
SYSOUT-PRM="%%STDERR"
50. ARGS
The ESP ARGS statement specifies an argument string of positional operands to pass to a batch file, script, command, or program for distributed job definitions. The conversion tool splits up all the ARG values and assigns each one of them sequentially to a Control-M AutoEdit job submission variable %%PARMnn (nn=1-51).
Argument values enclosed in delimiters (quotes/apostrophes) are copied with their accompanying delimiters. Any ESP symbolic variables contained in the argument values are converted to Control-M auto-edit format.
Argument values that are very long may be split into 2 or more auto-edit variables of the form %%x=partial-value (x=0-9,A-Z, ….), which are then concatenated into the corresponding %%PARMnn variable.
See item 46. CMDNAME, SCRIPTNAME, CLPNAME, FILENAME for further details.
51. COREQ
The ESP COREQ statement specifies the names of any other job that is selected automatically whenever the specified job is selected. The specified job and all of its co-requisites are allowed to execute simultaneously. The conversion tool creates a Control-O ON JOBARRIVAL rule, which monitors the system for the arrival of the specified job and then issues a DO FORCEJOB for required co-requisite jobs.
If conversion option ORDEREX is set to the REXX exec name, all DO FORCEJOB actions are converted to DO TSO actions with the REXX exec name of ORDEREX, to perform the CTMAPI ORDER process.
52. STARTING/ENDING date
The STARTING/ENDING date parameter used as part of the SCHEDULE statement in a CA ESP event specifies the earliest/latest date on which the event should be active.
The Control-O rule into which the event is converted is created with following conditional logic:
IF %%$DATE LT yymmdd (or GT for ENDING criteria)
RETURN
ENDIF
to prevent the rule from being active outside its starting/ending dates.
53. /* (Comments)
CA ESP comments in job scripts begin with ‘/*’.
When the conversion parameter COMMENT is set to N(o) these statements are ignored by the conversion tool. In addition, when comment statements are continued on additional lines by a continuation character (‘-’ or ‘+’), then these lines are also ignored regardless of whether they begin with ‘/*’ or not.
When the conversion parameter COMMENT is set to Y(es) these statements are converted to the Control-M DESC parameter. When the comment statements are continued on additional lines by a continuation character (‘-’ or ‘+’), then these lines are likewise converted to a multi-line DESC parameter.
When the conversion parameter COMMENT is set to A (All) both ESP comments and TAGs statements are treated as comments and are converted to DESC parameters as above.
When the conversion parameter COMMENT is set to T (Tag) only the ESP TAGs are treated as comments and are converted to DESC parameters as above.
Warning: A comment line (/*) that ends with a ‘-’ or ‘+’, whether intended as a continuation character or not, causes the next line to be considered as a comment line (and ignored or processed, as indicated by the COMMENT conversion option). When not intended as a continuation character, you must delete this comment line from the source procedure member to prevent loss of data and/or errors during the conversion process.
54. COPYJCL
The CA ESP COPYJCL statement is used to generate a copy of the JCL for each job CA ESP submits. The COPYJCL statement specifies the library that is to receive the copy, followed by either the JOBNAME or JOBID keyword. This working copy of the JCL can be used for job re-submission. CA ESP keeps track from where the job was submitted and the JCL that was used. In Control-M, the History AJF provides the parallel functionality. If COPYJCL is commonly used in the CA ESP job definitions, then set the HIST parameter to Y in the CTMPARM member of the IOA PARM library. For more information about the History file, see the Control-M for z/OS User Guide.
55. USER/USERID/APPL OWNER/EVENT NAME prefix
The CA ESP USER statement identifies the user ID under which to run the Agent (distributed) job. The conversion sets the Control-M OWNER parameter to the user name.
For ESP Events that invoke an ESP Procedure, see item 26. EVENT ID (prefix.descriptor), which describes how the Control-M OWNER parameter is determined.
Note that for FILE_TRIGGERING events, a USER(xxx) subparameter overrides the OWNER determined above.
If an ESP APPL statement specifies the OWNER sub-parameter, the OWNER value is used as the CTM global OWNER parameter for the jobs in the Control-M table. The APPL OWNER sub-parameter takes precedence over the event ID prefix.
Symbolic user name values are supported.
56. NOTWITH
The CA ESP NOTWITH parameters specifies jobs that are mutually exclusive with the current job. The conversion tool creates corresponding Control-M CONTROL parameter definitions for this dependency with the format: procmambername-jobname[.qualifier] E(xclusive)/S(hare)
The conversion tool inserts a Shared CONTROL resource into all jobs that match the (masked) jobname. When the NOTWITH parameter specifies a generic qualifier-name (of the form jobname.-) the conversion simply omits the qualifier and inserts a Shared CONTROL resource into all jobs which match the jobname regardless of the qualifier name.
When the NOTWITH parameter is specified with an application name (of the form job.qual/appl) then the Share CONTROL resource is only written in a job of the Control-M table corresponding to the ESP Application.
A NOTWITH parameter which precludes a job from running with itself causes an Exclusive CONTROL resource to be created in the Control-M job definition without a corresponding Share resource.
In ESP the HOLD attribute of the NOTWITH statement means that if the current job does not complete successfully, all resources are held. The job specified in the NOTWITH statement waits until the current job is forced complete, restarted successfully, or rerun successfully. In Control-M this is converted to the CONTROL onFail attribute K, which means keep the CONTROL resource allocated to the job until one of the following occurs:
-
The job is rerun and ends OK
-
The job is deleted
-
The job is FORCEd OK
CONTROL resources are not added to jobs converted from ESP EXTERNAL jobs.
57. SQL
The CA ESP SQL statement specifies the SQL query to run against a database table.
To convert the SQL statement the conversion sets MEMNAME of the SQL job to SQL_Job and defines the following Control-M/EM fields:
-
CM_VER=7.0.00
-
APPL_FORM=Databases
-
APPL_TYPE=DATABASE
-
APPL_VER=ANY
In addition, the following AutoEdit variables are defined:
-
%%DB-ACCOUNT=DB_ACCOUNT
-
%%DB-EXEC_TYPE=Open Query
-
%%DB-QTXT-N001-SUBQTXT=%%Q
-
%%DB-QTXT-N001-SUBQLENGTH=nnn
-
%%Q=sql-statement
-
where nnn is the length of the SQL query statement.
See item 9. [xxx_]JOB name for more information on the SQL command.
58. TEXT_MON
The CA ESP TEXT_MON monitors the contents of a text file to search for a text string. Based upon the specified operands, TEXT_MON controls the execution of a job, for example, to monitor for an error message in a log file after execution of a script.
To convert the Text Monitoring job to a distributed job, the conversion sets MEMNAME of the job to TextSearch and creates the following embedded script to perform the text search and produce a return code indicating whether the text search was successful or not:
#!/bin/sh
OUT_FILE="/tmp/out_$$.out"
Cawk ''{if( NR >= ''$SEARCHRANGE-FROM'' && NR<= ''$SEARCHRANGE-TO'') print $0
;else exit}'' $TEXTFILE > $OUT_FILE 2>&&1
grep $TEXTSTRING $OUT_FILE > /dev/null 2>&&1
rc=$?
rm -f $OUT_FILE
exit $rc
if [ $rc == 0 ]
then
exit 1
else
exit 0
fi
-
where the script variables $TEXTSTRING, $TEXTFILE, $SEARCHRANGE-FROM/TO are derived from the corresponding CA ESP commands.
-
When the TEXTSTR NOTEXIST option is specified, the ‘exit $rc’ statement above is removed.
59. SETVAR
The CA ESP SETVAR statement is used to define variables in a data object. The conversion tool treats the data object as a Control-M job definition and converts the ESP SETVAR statements to Control-M SETVAR definitions within the job definition.
60. ANY, TODAY, NOW, YESTERDAY scheduling criteria
The following RUN scheduling criteria are converted to SCHEDULE-RBC=*:
-
ANY
-
TODAY
-
NOW
These scheduling criteria are similarly converted if they are specified within a ‘SCHEDULED’ keyword parameter coded on an ESP JOB statement.
These scheduling criteria indicate a job is either:
-
triggered by an event (converted to a CTO rule) and will be scheduled according to the event's scheduling criteria
or
-
manually forced (in which case any scheduling criteria in the job definition are ignored)
If the YESTERDAY criteria is specified within a ‘SCHEDULED’ keyword parameter coded on an ESP JOB statement, this indicates that any jobs which are RELEASED by this job are triggered by the previous occurrence of this job (that is, they have a pre-requisite IN condition with date of -001, instead of ODAT).
When ANY, NOW, and TODAY are specified in a standalone NORUN statement (not part of an IF block), then the Control-M ‘DEFINITION ACTIVE UNTIL current-date’ is added to the job scheduling definition, and this inactivates the job definition while at the same time retaining any of the other scheduling criteria specified in the ESP job definition.
61. SUBAPPL
The CA ESP SUBAPPL statement identifies the logical name of a subapplication within an application. A global SUBAPPL statement (not in a job definition) is applicable to all succeeding jobs until another SUBAPPL statement is encountered or the end of the member.
The conversion tool creates the Control-M GROUP parameter, used to supply a common descriptive name to a set of related jobs, from the CA ESP SUBAPPL statement.
62. %ESPSTIME, %ESPSHH/%ESPSMN
The ESP %ESPSTIME and %ESPSHH/%ESPSMN are scheduled time of day variables. When used in job definitions in the context of an IF statements such as:
"IF %ESPSTIME = hh.mm THEN RUN ANY" or"
IF %ESPSHH = hh & ESPSMN = mm THEN RUN ANY"
the conversion tool creates the Control-M job definition as CYCLIC job and for each IF statement coded as above creates a ‘SPECIFIC TIMES’ parameter for it.
If, instead of an ‘=’ operator in the above IF statement, a ‘>’ or ‘<’ is specified then the conversion will create a Control-M FROM TIME or UNTIL TIME parameter respectively. However, if the action specifies ‘THEN NORUN ANY’ with the above inequalities, the conversion will create a Control-M UNTIL TIME or FROM TIME parameter respectively.
63. VGET/VPUT/VSET
The ESP VGET command is used to retrieve global variables from a global variable table. The ESP VPUT command is used to store one or more variables in a global variable table. The ESP VSET command is used to create a new global variable or change the value of an existing global variable.
In Control-M the VGET is converted to a SETVAR statement that retrieves the global variable varname as follows:
SETVAR=%%varname=%%\\TABLE-name\varname
The VPUT is converted to a SETVAR statement that sets the global variable varname as follows:
SETVAR=%%\\TABLE-name\varname=%%varname
The VSET is converted to a SETVAR statement that sets a value for the global variable varname as follows:
SETVAR=%%\\TABLE-name\varname=value
The variables are defined as Named Pool variables. They refer to variables defined in the IOA Database as %%\M\POOLS\TABLE-name\varname, where the TABLE is the name of the pool. This definition is compatible also with named pool variables of Distributed jobs, which are accessible with the common %%\\TABLE-name\varname syntax.
For a description of the output file that contains the pool variable control statements for the CTMVAR utility, see JOB1 Output. For information on how to load ESP variables into a named variable pool in a distributed environment, see the ctmvar command in Post Step 2 – Perform Final Adjustments. For more information about named pool variables, see the Control-M documentation.
The ESP VTLIST file defines all the variable TABLEs and the variables and their default values contained in them.
64. Time zones
The following time zones are supported when specified in ESP scheduling criteria:
-
ADT (Atlantic Daylight)
-
AST or ATLANTIC (Atlantic Standard)
-
BRZ (Brazil)
-
BST (British Summer)
-
CDT (Central Daylight
-
CST or CENTRAL (Central Standard)
-
CET (Central Europe)
-
EDT (Eastern Daylight)
-
EST or EASTERN (Eastern Standard)
-
GMT (Greenwich Mean)
-
IST (India Standard)
-
JST (Japan Standard)
-
MDT (Mountain Daylight)
-
MST or MOUNTAIN (Mountain Standard)
-
NFNDLAND
-
PDT (Pacific Daylight)
-
PST or PACIFIC (Pacific Standard)
-
SGT (Singapore Standard)
-
UK (United Kingdom)
-
UTC (Coordinated Universal)
The conversion tool creates the Control-M TIME-ZONE parameter with the ESP time zone value. Any time zones which are in actual usage must also be added to the TIMEZONE member in the IOA PARM library with their proper definitions.
Time zone names of less than 3 characters are converted with trailing underscore characters.
66. %INCLUDE/%EXCLUDE/%ENDINCL/%ENDEXCL
ESP can include or exclude portions of JCL it submits by using %INCLUDE and %EXCLUDE statements imbedded in JCL. In JCL, you can use the following criteria with inclusion and exclusion statements:
-
All scheduling criteria (including NOT and symbolic variables) specified inside a TODAY function
-
Day of week specified in a DAY function
-
Dates specified in FROM/TO functions
-
Time
-
Event ID
-
JCL being submitted or JCL being copied to COPYJCL
-
Value of a logical expression
%INCLUDE/%EXCLUDE statements imbedded in symbolic variable members are not supported.
The conversion tool converts INCLUDEs specifying logical expressions as follows:
%INCLUDE IF(varname oper varvalue) is converted to:
%%SET %%0=%%varname
%%SET %%1= varvalue
%%IF %%0 oper %%1
varname may or may not have a leading symbolic character sign (%).
If varvalue is null, a leading 'X' is inserted in front of %%0 and %%1.
ESP operators =, ¬=, <, <=, >, >= are replaced by EQ, NE LT, LE, GT, GE.
If varvalue is not enclosed in quotes and is numeric, then the operator oper is replaced by oper#.
If varvalue is not enclosed in quotes and is not numeric, then varvalue is replaced by %%varvalue (it is treated as a symbolic variable)
Symbolic variable substrings of the form varname(n:m) are supported through the %%SUBSTR function.
Processing of Compound Boolean expressions
-
Compound 'AND' expressions:
IF (
var1
EQ val1) AND (var2 NE val2)is converted to:%%SET %%0 = %%
var2
%%SET %%1 =
val2
%%IF %%0 NE %%1
%%SET %%0 = %%
var1
%%SET %%1 = val1
%%IF %%0 EQ %%1
%%ELSE (for EXCLUDE)
-
Compound 'OR' expressions:
IF (var1 EQ val1) OR (var2 NE val2)is converted to:
%%SET %%0 = %%var2
%%SET %%1 = val2
%%IF %%0 NE %%1
%%GOTO LABELnnn
%%ENDIF
%%SET %%0 = %%var1
%%SET %%1 = val1
%%IF %%0 EQ %%1
%%LABEL LABELnnn
%%ELSE (for EXCLUDE)
%INCLUDE DAY(xxx) or IF(TODAY(xxx) [{AND|OR} (TODAY(xxx)]), where xxx is any combination of scheduling criteria, is converted to Control-M auto-edit statements using %%IF/%%ELSE/%%ENDIF together with various system date auto-edit variables and computational date functions, including %%$ODATE, %%OWDAY, %%$CALCDTE, %%$WCALC, %%$WEEKDAY, etc. The combinations of scheduling criteria which are supported by the conversion tool are those discussed in item 13. RUN/SCHEDULE, NORUN/NOSCHED. %INCLUDE IF(…) statements that contain combinations of logical variable evaluations and TODAY clauses are also supported.
%INCLUDE IF(DEFINED(var)) is converted to the following:
%%RESOLVE NO
%%SET %%0=%%var
%%SET %%1=%%SUBSTR %%0 1 2
%%IF %%1 NE %%
.... <- INCLUDEd statements
%%ENDIF
%%RESOLVE YES
%INCLUDE FROM('
date1
') TO('date2
’) is converted as follows:%%IF %%$ODATE GE
date1
%%IF %%$ODATE LT
date2
Not all combinations of TODAY sub-parameters or combinations of INCLUDE and EXCLUDE statements in the same block are currently supported. A warning message is issued in such cases.
67. ENCPARM
The ENCPARM statements control various ESP job restart features. See Conceptual Overview for full details.
68. Calendar Special days names
ESP Calendar Special days define a specific day or days in a calendar which can be referenced in job definitions scheduling criteria. The conversion tool converts the Special days into IOA periodic Calendars using the ESP calendar name with a ‘#’ prefixed as the IOA calendar name. Each Special day group is assigned a unique period indicator in the calendar. These calendars can span across two years. If Special days groups within a calendar overlap on any dates, then multiple periodic calendars are created using the name of the Special days (truncated to 8 characters if necessary) as the IOA Calendar name (without ‘#’ prefixed) for those groups which overlap.
Periodic scheduling criteria are created in the DAYS job scheduling definition in the format [-][D|L]xPy. The ‘-’ is specified for NORUN criteria and the ‘L’ is specified for LAST type criteria. If the Special day consists of a single date then x is set to 1, otherwise, if the Special days consists of a group of dates then y is set to ‘*’ (indicating all days of the period y).
If a Special days name consists of a group of dates and it is specified with the NORUN criteria, the -[D|L]*Py format is not supported by Control-M. In such a case, the Special days are converted as if they were specified as part of a RUN statement and placed into an RBC in the IOA RBC library whose name is the Special day name. This RBC is then placed into the job definition as an EXCLUDE RBC (name prefixed with ‘!’) along with the ‘ALL’ RBC, and the RBC RELATIONSHIP is set to A. In addition, the Special day name RBC is placed in the table entity as a CTM LEVEL RBC.
69. APPLEND
The ESP APPLEND statement specifies a self-completing workload object and is used to automatically perform processing at the end of an application.
The conversion converts the APPLEND events as DUMMY jobs and with an IN condition name of tablename-applendjobname-APPLEND.
It is the user's responsibility to add the above condition as an OUT condition to each job in an ESP procedure which contains an APPLEND event when the jobs do not specify any successors (except for jobs which are triggered by the APPLEND event).
70. DURATION
The DURATION statement is used to tell ESP what duration to use when calculating Critical Path.
The conversion converts the DURATION statement as a SETVAR %%CONV-ELAPSED =nnn. This value can be used in Control-M Forcecast whenever the job’s estimated elapsed time is required.
71. ABSORB
The ESP ABSORB statement is used to reserve a quantity of resources for jobs that require a large resource count. Resource Absorption reserves the resources that are available at the time the job is next in the queue and holds them while waiting to accumulate the remainder of resources required for that job. Jobs with smaller resource requirements cannot use the reserved resource. The ABSORB statement prevents jobs with large resource requirements from incurring a processing delay.
The conversion converts the ABSORB statement to a Control-M PRIORITY=* statement which makes the job into a critical path job. Critical path priority applies to contention for Quantitative resources and for Control resources required in exclusive state.
72. ESP TR[IGGER]
The TRIGGER command is used to trigger the execution of an event. TRIGGER may or may not be preceded by the OPER statement depending on whether or not the user requires OPER authority to issue the TRIGGER command.
The conversion converts the TRIGGER statement to an in-stream invocation of the CTMAPI utility, which issues an ORDER command to order the Control-M scheduling table specified by the triggered eventid.
In JCL ESP utility steps, ESP TRIGGER statements specifying USERx(yyy) (x=1,2,3,4) keyword parameters are converted to CTMAPI ORDER SETVAR=%%USERx=yyy parameters.
In JCL ESP utility steps, ESP TRIGGER statements specifying a ROOT(xxx,yyy,…) keyword parameter are converted to CTMAPI CTM ORDER MEM=xxx … and AJF BYPCOND MEM=xxx statements. Multiple ORDER/AJF statements are created when necessary.
ROOT jobnames of the format jobname+ are not supported.
73. ESP RESDEF
The RESDEF command defines, displays, deletes and updates resources.
The Control-M conversion supports the following formats of the REDEF command:
RESDEF name ADD|SET|DELETE [MAXIMUM(n)|AVAIL(n)]
For Dummy jobs:
For distributed job definitions, this command is converted to the CTM/EM ecaqrtab utility as follows:
ecaqrtab {ADD|UPDATE|DELETE} quantitative-resource-name [<max>]
See the Control-M/EM Utilities Guide for further details.
The Filename of the resultant job is ECAQRTAB.cmd.
For mainframe job definitions, this command is converted to the IOA IOACND utility as instream JCL in the job definition as follows:
// EXEC IOACND,PARM='[CHANGE|ADD|DELETE] RESOURCE quantitative-resource-namen’
Multiple RESDEF definitions in an ESP task are supported.
For non-Dummy jobs:
A duplicate job definition is created. This job definition contains an embedded script (for distributed jobs) or in-stream JCL (for mainframe jobs), as described above.
74. JOBATTR
The JOBATTR statement is used to change a job's attributes within the scope of a JOB statement.
The Control-M conversion supports the following parameters of JOBATTR:
-
[EXTERNAL|NOEXTERNAL]
-
[MANUAL|NOMANUAL]
-
[LINK|NOLINK]
-
[TASK|NOTASK]
-
[REQUEST|NOREQUEST]
-
[PROCESS|NOPROCESS]
-
[CONDITIONAL|NOCONDITIONAL]
-
[HOLD|NOHOLD]
-
[SCHEDULED('criteria')]
-
[APPLID(applname)]
-
[SELFCOMPLETING]
-
[HELD_MANUAL]
See Table 8 in the Component conversion summary section for how each of the above individual parameter is converted.
75. APPLSTART
The ESP APPLSTART statement specifies a self-completing workload object and is used to automatically perform processing at the start of an application.
The conversion converts the APPLEND events as DUMMY jobs.
It is the user's responsibility to add any IN or OUT conditions to each job in an ESP procedure that contains an APPLSTART event to ensure proper job flow in the procedure.
76. HELD_MANUAL
The ESP HELD_MANUAL sub-parameter defines a held-manual job, which is a job defined in an ESP application that is submitted externally to ESP with TYPRUN=HOLD in its JCL. The JOB HELD_MANUAL statement causes a held-submitted job to be matched to a ready, held-manual job in an application.
The conversion process converts HELD_MANUAL to a CMEM On Spool ON JOBARRIVAL DO FORCEJOB rule. For further information on On Spool job processing, see the Control-M for z/OS User Guide.
77. INHERIT|NOINHERIT
The ESP OPTIONS NOINHERIT indicates that job relationships are not inherited.
Jobs in an Application may not have the same run frequency. ESP can select any jobs in a job stream and instruct them to run in the correct order. It bases the order of job execution on implied job relationships. When ESP selects the jobs, it checks to see if there are any inherited relationships between the jobs. Any job that possesses the (default) INHERIT attribute allows a dependency chain to flow through it, even when the job itself is not selected.
When the NOINHERIT job option is specified for a job,it has a different effect on the job relationships within its Application, depending on whether it is selected:
-
An unselected NOINHERIT job prevents any dependencies passing through it. Any job it releases, either directly or indirectly, runs independently of the NOINHERIT job’s predecessors. An unselected NOINHERIT job breaks a dependency chain.
-
A selected NOINHERIT job releases any selected immediate successors, but does not pursue dependencies through any unselected successors.
The conversion only supports the INHERIT|NOINHERIT options at the application level, not at the job level.
In Control-M, the ADJUST CONDS parameter determines how Control-M handles a requirement for a prerequisite condition by successor jobs in a SMART Table. The ADJUST CONDS parameter can be set to Y to ignore prerequisite conditions normally set by predecessor jobs, if the relevant predecessor jobs are not scheduled. However, this can cause dependent jobs to run out of order.
The conversion tool supports the (default) INHERIT option to maintain the Job order by setting the ADJUST CONDS parameter to B(ridge), which causes Control-M to bridge the scheduled jobs to keep their order and dependencies in the SMART table when jobs within a logical flow are not scheduled to run on the current ODATE.
These jobs may be filtered by using a SHOW screen filter.
For jobs running on Control-M distributed platforms, the ADJUST_COND parameter is set to ‘Y’ and the Control-M/Server CTM_FOLDER_ADJUST_DUMMY configuration parameter controls the creation of dummy jobs that run in place of unscheduled prerequisite jobs.
-
If CTM_FOLDER_ADJUST_DUMMY is set to Y, a dummy job waits for the prerequisite conditions expected by the job it is replacing, and performs the post processing of the job.
-
If CTM_FOLDER_ADJUST_DUMMY is set to N, Out conditions of the jobs that were not ordered are ignored by the ordered jobs in the SMART Table. (Default)
The conversion converts the NOINHERIT option to ADJUST CONDITIONS=Yes, which causes Control-M to ignore, for each job in the group, any IN prerequisite condition that is triggered by a predecessor job that will not be ordered during the current day. For further information, see the Control-M for z/OS User Guide.
78. AJ or APPLJOB action
The ESP AJ taskname action command indicates that the taskname should be be modified according to the specified action. The following actions are supported by the conversion tool and the corresponding CTMAPI command to which they are converted:
Table 17 AJ or APPLJOB actions
ESP action |
CTMAPI command |
---|---|
COMPLETE |
FORCEOK |
BYPASS |
BYPJCL |
HOLD(ESP) |
HOLD |
RELEASE(ESP) |
FREE |
CANCEL |
KILL |
REQUEST |
CONFIRM |
WITHDRAW |
DELETE |
DROPDEP(ALL)|DROPDEP |
BYPCOND |
The conversion checks that all of the following conditions are satisfied:
-
The home task is a mainframe and DUMMY job
-
The taskname is not longer than 8 characters
-
The taskname is not qualified (has a '.')
If all these conditions are satisfied, the conversion creates the following IN-STREAM JCL in the home task, to change the status of taskname to the action specified in the above table:
//jobname JOB
// EXEC CTMAPI,PARM='AJF ctmapi-command MEM=taskname TBL=table-name ODATE=ODATE'
When the taskname specifies ALL, the EXEC statement is changed to the following:
// EXEC CTMAPI,PARM='AJF ctmapi-command TBL=table-name ODATE=ODATE'
79. RELDELAY
The ESP RELDELAY nnn statement is used to delay job submission by nnn minutes at the time that a job becomes eligible for submission.
For mainframe jobs, the following Control-M auto-edit variable is created, and it provides the equivalent functionality:
%%CTM_PRE_SUB_WAIT=nnnM
For distributed jobs, the following pre-command auto-edit variable is added: %%PRECMD=sleep nnnn, where nnnn is expressed in seconds.
80. ENQUEUE
The ESP ENQUEUE statement specifies a resource name that a job must enqueue on with either SHARED or EXCLUSIVE attributes. The conversion tool creates corresponding Control-M CONTROL parameter definitions for these resources with the following format:
resourcename E(xclusive)/S(hare)
If the ESP resourcename exceeds 20 characters, it is truncated to 20 characters.
81. SUSPEND/RESUME
When used in an ESP Event definition, the SUSPEND command increments the suspend count of the Event. While the suspend count is greater than zero, Event execution is bypassed.
The RESUME command is used in conjunction with the SUSPEND command to make a previously bypassed Event eligible for execution.
The conversion supports the SUSPEND/RESUME statements when an ESP Event specifies a cyclic interval scheduling criteria via an EVERY or HOURLY keyword.
The SUSPEND/RESUME commands are then converted to Control-M UNTIL/FROM times.
Multiple SUSPEND/RESUME statements within the same ESP Event definition are not supported.
When used outside an Event definition, the SUSPEND command increments the suspend count associated with an Event. When the suspend count is greater than zero, event execution is bypassed.
The RESUME command is used in conjunction with the SUSPEND command to make a previously bypassed Event eligible for execution.
When the ESP job definition is a dummy task, the conversion converts these commands to a job with Instream JCL, which executes the CTMAPI utility and issues the AJF HOLD/FREE commands, respectively.
82. PGM=ESP
The ESP program provides batch services to perform various ESP functions and commands.
The CTMAPI Control-M utility provides similar functionality. This utility is described in detail in the Control-M for z/OS User Guide.
The ESP commands that are supported and the CTMAPI commands to which they are converted are listed in the following table.
Table 18 ESP Program command conversion
ESP command |
CTMAPI command |
---|---|
COMPLETE |
AJF FORCEOK |
BYPASS |
AJF BYPJCL |
HOLD |
AJF HOLD |
RELEASE |
AJF FREE |
CANCEL |
AJF KILL |
REQUEST |
AJF CONFIRM |
WITHDRAW |
AJF DELETE |
RESUB |
AJF RERUN |
TR(IGGER) |
ORDER (see 72. ESP TR[IGGER] for details) |
Batch commands converted are those in non-concatenated SYSIN statements (with or without a stepname qualification). Only one Batch command is recognized in each line. It can appear in any one of the following contexts:
-
a PDS member
-
a sequential data set
-
instream, for example, following the statements //SYSIN DD * or //SYSIN DD DATA, or no SYSIN statement at all
-
Temporary data sets are NOT supported
For more information, see the description of PNIBTSD in Conversion Parameters. Unsupported Batch commands in SYSIN and extraneous DD statements are deleted. Non-DD JCL statements in the ESP step, such as IF, SET, or INCLUDE, are not deleted.
83. SYMBOL
In ESP it is possible to set an alternate ESP variable symbol sign at the application, job, and JCL member level by specifying the SYMBOL statement at the application or job level and the //*ESPSYMBOL statement in JCL members.
The conversion process converts all alternate symbols to the Control-M %% format (where appropriate) at the appropriate level and overrides the global VSYMBOL conversion option.
SYMBOL statements at the application or job level are not propagated by the conversion to apply to JCL members invoked by the job.
84. Exit
In ESP it is possible to use the EXIT instruction to quit from a current point in a Procedure. The conversion process converts the EXIT statement to the ControlM END-TABLE=Y parameter at job level.
This sets the job as an end point for the SMART table. After the end point job completes, no additional jobs in the SMART table are submitted and the table is marked as complete as soon as executing jobs end.
Unique Control-M parameters
Several unique Control-M job scheduling definition parameters that do not have corresponding CA ESP features can be set by the conversion tool during the creation of the Control-M tables.
The ESPDEF defaults member in the conversion source library contains these unique parameter settings, and must be reviewed and modified to specify your local Control-M preferences. For additional information regarding these parameters, see Conversion Parameters and the Control-M for z/OS User Guide.
DO SYSOUT
Specifies how the job output must be handled. At job completion, Control-M analyzes the job output. To enable Control-M to locate the output of the job on the system spool, Control-M modifies the JCL MSGCLASS parameter of the job at time of submission to the automatically held output class defined during installation, through the Control-M HLDCLAS parameter. After analyzing the sysout, Control-M may be ordered to requeue the sysout. For more information regarding DO SYSOUT options, see the Control-M for z/OS User Guide.
The conversion tool can be instructed to specify various actions using the Control-M DO SYSOUT facility via the TOCLS, FRMCLS, and RELEASE conversion parameters described in Conversion Parameters"