ESP Workload Manager Cookbook

ESP Workload Manager Version 5.
Examples Cookbook
ESP-5.5-EC-01
First Edition (June 2007)

This documentation and any related computer software help programs (hereinafter referred to as the Documentation) is for the end users informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the documentation for their own internal use, and may make one copy of the related software as reasonably required for back-up and disaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the product are permitted to have access to such copies. The right to print copies of the documentation and to make a copy of the related software is limited to the period during which the applicable license for the Product remains in full force and effect. Should the license terminate for any reason, it shall be the users responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE. The use of any product referenced in the Documentation is governed by the end users applicable license agreement. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. Copyright 2007 CA. All rights reserved.
Contents
About this document vii Using this document ....................................................................................... viii Summary of changes .......................................................................................... x ESP Workload Manager examples 1 Scheduling a weekly job and adjusting it for holidays ......................................... 2 Scheduling a job within a month........................................................................ 3 Scheduling a job to run based on a different days holiday status ........................ 4 Scheduling a job to run based on a previous days holiday status ........................ 5 Scheduling a job to run within a specific date range ........................................... 6 Scheduling a job to run on selected workdays only............................................. 7 Scheduling a job relative to a special day ............................................................ 8 Scheduling a monthly job and delaying it for non-workdays .............................. 9 Scheduling a job based on the day of the week for the 1st day of month .......... 10 Scheduling a job to run on the last five workdays of the month........................ 11 Scheduling a job based on when another job was scheduled ............................. 13 Scheduling a job based on the workday status of the last day of the previous month.................................................................................... 14 Determining if a day in the past was a workday................................................ 15 Scheduling a job to run every two days............................................................. 16 Scheduling a job to run every two weeks and advancing it for holidays ............ 17 Scheduling a job to run every two weeks and delaying it for holidays ............... 18
ESP-5.5-EC-01
iii
Scheduling different jobs to run based on the calendar quarter......................... 19 Scheduling a job on a random day of the month .............................................. 20 Scheduling an hourly Application within a time range ..................................... 21 Scheduling an hourly job within a time range .................................................. 22 Scheduling a different job to run every hour..................................................... 24 Scheduling a job in an Application to run based on day and time .................... 26 Scheduling an ad hoc job to run multiple times ............................................... 27 Scheduling a job to run every two hours........................................................... 29 Scheduling a job to run multiple times within a time range.............................. 30 Running ad hoc sequential jobs........................................................................ 32 Dynamically defining and scheduling an Event ................................................ 35 Scheduling a weekly Application based on the number of workdays in the week................................................................................. 36 Running the next scheduled Application early.................................................. 38 Running an Application for any future date ..................................................... 39 Delaying job submission until the next hour .................................................... 40 Setting up a dependency with a jobs previous run ........................................... 41 Using date-qualified file names......................................................................... 43 Processing a changing file name ....................................................................... 44 Copying a file to another location upon the files creation................................ 45 Ensuring a file exists before processing ............................................................. 46 Bypassing a job based on the status of another job............................................ 48 Bypassing non-critical jobs when jobs are late .................................................. 49 Taking different actions based on 1 of 3 successful return codes....................... 52 Running different jobs based on the return code of a predecessor job............... 54 Auto-triggering an Event for a reoccurring job ................................................. 55 Scheduling a job to run based on its previous run status................................... 56 Scheduling a cyclic Application ........................................................................ 57 Incrementing a cycle number ........................................................................... 59 Building Applications dynamically based on an input file................................. 62 Running a job based on resource availability .................................................... 64 Running or completing a job based on the order in which its predecessors complete ................................................................. 65 Scheduling a job based on a data set, time, and weekdays................................. 67 Using the Application name in the script path ................................................. 69 Identifying critical jobs for disaster recovery planning ...................................... 70 Using a one-time job section in Applications.................................................... 71 Using the same Application for different locations ........................................... 73 Merging Applications into a single PDS member ............................................. 75 Consolidating data set triggers to minimize the number of Event definitions ... 77 Resubmitting a job 5 minutes after it fails ........................................................ 79 Resubmitting a failed job a maximum of two times.......................................... 80 Providing notification when a job exceeds its maximum run time .................... 82 Providing notification for a long-running Application...................................... 83 Providing notification if a job is late starting relative to a data set closure ......... 84
iv
ESP-5.5-EC-01
Contents
Sending email notification for job failures ........................................................ 85 Sending a message when an Agent becomes inactive......................................... 87 Displaying job details from CSF....................................................................... 88 Bypassing a job across multiple Applications .................................................... 89 Holding all incomplete generations of an Application ...................................... 90 Listing a job plus its successor chains in an active Application .......................... 91 Creating a variable for the day of week number................................................ 93 Creating a variable for the accounting year....................................................... 94 Calculating the week number........................................................................... 95 Providing a variable for all data sets in a DSTRIG Event.................................. 97 Running jobs using ESP Encores SCAN mode................................................ 99 Setting COPYJCL as the default JCL library for resubmission ....................... 100 Using date-qualified TEMPLIBs .................................................................... 101 Index 103
ESP-5.5-EC-01
vi
ESP-5.5-EC-01
About this document

This document contains real-life examples of using ESP Workload Manager to solve common workload scheduling challenges. You can adapt these examples to meet your own business requirements. Many of these examples come from our users work experience and are being used in their installations.
ESP-5.5-EC-01
vii
SectionUsing this document
Using this document

Instructions for copying code
The code in the examples is meant to be copied and used as needed. You can use the code in the examples by copying and pasting it from the PDF. If you need to download the Adobe Acrobat PDF reader, you can download it for free from the Adobe website at www.adobe.com.
To copy and paste code from Adobe PDF
1. Activate the Select Text Tool by clicking this button 2. Click and drag to select text. 3. Copy selected text by pressing Ctrl+C. 4. Paste text by pressing Ctrl+V.
Intended audience
The examples in this document are intended for users who have a basic working knowledge of ESP Workload Manager. A wide range of examples is provided and will be of use to beginners through to advanced users. For more information on ESP Workload Manager, see the following guides: ESP Workload Manager Users Guide ESP Workload Manager Operators Guide ESP Workload Manager Advanced Users Guide ESP Workload Manager Installation and Configuration Guide ESP Workload Manager Reference Guide ESP Encore Users Guide
Conventions for using commands and statements

ESP Workload Manager commands may be entered in line mode, page mode, batch or loaded from a data set (using the LOAD command). In ESP Workstation or the ESP Workload Manager Web Interface, commands can be entered from the line mode interface. Many commands can also be entered from a system console. ESP Workload Manager statements must be entered into a Procedure within a data set, specific to the type of statement used. The following conventions apply to entering statements, as well as to entering commands and initialization parameters that are contained in a data set.
viii
ESP-5.5-EC-01
About this document
Continuation
Statements cannot extend beyond column 72. To continue lines longer than 72 characters, type either a hyphen (-) or a plus sign (+) as the last non-blank character on a line to continue a line of input. The hyphen attaches the next line including any leading blank positions. The plus sign strips leading blanks from a continuation line. Blanks preceding the hyphen or the plus sign are retained.
Note: A
hyphen can also be used as a wildcard character in some commands.
Wildcards and masking
Many statements, commands, and initialization parameters permit the use of the following wildcard characters (also called masking): An asterisk matches a specific single character. A hyphen matches zero or more characters. It can only be used as the last character of the operand. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */).
Comments
Enclose comments between /* and */. Comments can be written anywhere in an ESP Procedure.
Data sets
Enclose all data set names in single quotation marks; otherwise, ESP Workload Manager adds your TSO data set prefix to the name. Use ROS-, LIB- or PANprefixes to identify Roscoe, Librarian, and Panvalet data sets respectively.
Delimiters
Use single quotation marks when you want to denote character strings and literal data in expressions, assignment statements, and built-in functions. You must include single quotation marks around a string that contains blanks.
Indentation
You can use indentation to improve readability.
ESP-5.5-EC-01
ix
SectionSummary of changes
Naming Conventions
The following shortened names are used in place of their respective full names:
Full Name Short Name
ESP Application ESP Event ESP Procedure
Application Event Procedure
Summary of changes
This book contains information previously presented in Examples Cookbook, ESP-5.4EC-01, which supports ESP Workload Manager 5.4.
Whats New
This edition includes the following new examples: Copying a file to another location upon the files creation on page 45 Sending a message when an Agent becomes inactive on page 87
Whats Changed
The solutions for the following examples have been rewritten to take advantage of new features in ESP Workload Manager 5.5.
IFHOLIDAYPLUS run criteria
Scheduling a job based on when another job was scheduled on page 13 Scheduling a job to run every two weeks and delaying it for holidays on page 18
EVERY run criteria
Scheduling a job to run every two days on page 16 Scheduling a job to run every two weeks and advancing it for holidays on page 17 Scheduling a job to run every two weeks and delaying it for holidays on page 18
Self-completing tasks
Scheduling an ad hoc job to run multiple times on page 27 Bypassing a job based on the status of another job on page 48 Running a job based on resource availability on page 64 Resubmitting a failed job a maximum of two times on page 80
ESP-5.5-EC-01
About this document
Conditional release expressions
Taking different actions based on 1 of 3 successful return codes on page 52 Running different jobs based on the return code of a predecessor job on page 54
ESP-5.5-EC-01
xi
SectionSummary of changes
xii
ESP-5.5-EC-01
ESP Workload Manager examples
ESP-5.5-EC-01
Scheduling a weekly job and adjusting it for holidays

Objective
Schedule a job to run every Monday, unless Monday is a holiday. If Monday is a holiday, then run the job on the previous workday.
Solution
Use the following RUN statement for the job:
RUN MONDAY LESS 0 WORKDAYS
Explanation
The job always runs on Mondays that are workdays. When Monday is a holiday, and thus a non-workday, the job runs on the previous workday. Variation If, instead, you wanted to run the job on the first workday after the holiday, use the following RUN statement for the job:
RUN MONDAY PLUS 0 WORKDAYS
Variation If, instead, you didnt want to run the job at all when Monday falls on a holiday, you can use the following RUN statement for the job:
RUN MONDAY EXCEPT HOLIDAYS
ESP-5.5-EC-01
Scheduling a job within a month

Objective
Run a job on the 5th Friday of the month but only in months that have 5 Fridays.
Solution
Use the following run criteria for the job:
RUN 5th friday within month
Explanation
This solution runs the job on the 5th Friday of the month in months that contain 5 Fridays.
ESP-5.5-EC-01
Scheduling a job to run based on a different days holiday status

Objective
Schedule a job to run every Saturday, unless the following Monday falls on a holiday. If the following Monday falls on a holiday, the job should not run.
Solution
Use the following statements for the job:
JOB A RUN SAT IF DAYS_TO('HOLIDAY') = 2 THEN NORUN TODAY ENDJOB
Explanation
The job is scheduled to run on Saturdays. However, if the number of days to the next holiday is 2, the job is not scheduled.
Note: It
is assumed in this example that Sunday cannot be defined as a holiday.
ESP-5.5-EC-01
Scheduling a job to run based on a previous days holiday status

Objective
Schedule a job to run every Monday, except when the previous Friday is a holiday. Workdays are Monday through Friday.
Solution
JOB A IF TODAY('MON') AND DAYS_FROM('TODAY LESS 1 WORKDAY')=3 THEN RUN TODAY ENDJOB
Explanation
This solution checks to see if today is a Monday and the number of days from the previous workday is 3 (in other words, Friday was a workday). If both conditions are true, the job is selected to run. Variations Another way of coding this, assuming that holidays do not fall on Saturday or Sunday, is:
IF TODAY('MON') AND NOT TODAY('HOLIDAY PLUS 1 WEEKDAY') THEN RUN TODAY
Or, you can use the following run criteria:

RUN MONDAY NORUN HOLIDAY PLUS 1 WEEKDAY
For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15.
ESP-5.5-EC-01
Scheduling a job to run within a specific date range

Objective
Run a job every Thursday between April 17, 2005 and November 6, 2005, inclusively.
Solution
JOB A IF DAYS_FROM('APR 17,2005') GE 0 AND DAYS_TO('NOV 6,2005') GE 0 THEN RUN THURSDAY ENDJOB
Explanation
This solution uses the DAYS_FROM and DAYS_TO built-in functions to check if the current day is within the required date range. If it is, the job is selected to run on Thursdays.
ESP-5.5-EC-01
Scheduling a job to run on selected workdays only

Objective
Run a job from the 15th day to 25th day of the month, but only on workdays.
Solution
JOB A IF TODAY('15TH-25TH DAY OF MONTH') THEN RUN WORKDAYS ENDJOB
Explanation
This solution uses the TODAY built-in function to determine if today is within the required day range. If it is, the job is selected to run on workdays.
ESP-5.5-EC-01
Scheduling a job relative to a special day

Objective
Run a job on the first Saturday on or after a special day.
Solution
RUN 1ST SATURDAY OF SPECIAL_DAY
Explanation
This solution selects the job to run on the first instance of Saturday on or after SPECIAL_DAY.
ESP-5.5-EC-01
Scheduling a monthly job and delaying it for non-workdays

Objective
Run a job on the 5th day of the month if it is a workday. If it is not a workday, run the job on the day after the 5th day of the month, regardless of whether it is a workday.
Solution
JOB A GENTIME AA 5TH DAY OF MONTH GENTIME BB 5TH DAY OF MONTH PLUS 0 WORKDAYS IF AADATE = BBDATE THEN RUN %AADATE ELSE RUN %AADATE PLUS 1 DAY ENDJOB
Explanation
This solution uses two GENTIME commands to generate date and time variables for the 5th day of the month and for the first workday on or after the 5th day of the month. If these dates are equal, then the 5th day of a month is a workday, and job A runs on the 5th day of the month. Otherwise, job A runs 1 day after the 5th day of the month. For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15.
ESP-5.5-EC-01
Scheduling a job based on the day of the week for the 1st day of month
Objective
Run a job on the 1st Monday of each month. However, if the month starts on a Saturday or a Sunday, run the job on the 2nd Monday of the month instead.
Solution
JOB A GENTIME ONE 1ST DAY OF MONTH STARTING TODAY IF ONEDAY='SATURDAY' OR ONEDAY='SUNDAY' THEN RUN 2ND MONDAY OF MONTH ELSE RUN 1ST MONDAY OF MONTH ENDJOB
Explanation
This solution uses the GENTIME command to generate date and time variables for the 1st day of the current month. If the day-of-week variable from the GENTIME (in other words, ONEDAY) is Saturday or Sunday, job A runs on the 2nd Monday of the month. Otherwise, job A runs on the 1st Monday of the month.
10
ESP-5.5-EC-01
Scheduling a job to run on the last five workdays of the month

Objective
Schedule a job to run only on the last 5 workdays of each month.
Solution
JOB A GENTIME LAST5 LAST WORKDAY OF MONTH LESS 4 WORKDAYS IF LAST5DD <= ESPSDD AND TODAY('WORKDAY') THEN RUN TODAY ENDJOB
Explanation
The GENTIME command generates date and time variables for 4 workdays prior to the last workday of the month (in other words, the 5th last workday of the month). If the day of the month for the 5th last workday of the month (as indicated by the LAST5DD variable) is less than or equal to the scheduled day, and it also is a workday, then the job is selected to run. Example The calendar below shows October 2005.
If workdays are Monday through Friday and there are no holidays at the end of October 2005, then the 5th last workday of the month falls on October 25. The LAST5DD variable has a value of 25. This means that in October 2005, the job would be scheduled only on October 25, 26, 27, 28, and 31 (not on October 29 or 30, which fall on a weekend).
ESP-5.5-EC-01
11
Variation Another solution is to use the following run criteria for the job:
RUN RUN RUN RUN RUN LAST LAST LAST LAST LAST WORKDAY WORKDAY WORKDAY WORKDAY WORKDAY OF OF OF OF OF MONTH MONTH MONTH MONTH MONTH LESS LESS LESS LESS 1 2 3 4 WORKDAY WORKDAYS WORKDAYS WORKDAYS
12
ESP-5.5-EC-01
Scheduling a job based on when another job was scheduled

Objective
Job A runs every Wednesday, unless Wednesday is a holiday. If Wednesday is a holiday, job A runs on Thursday. Schedule job B to run every Thursday, except when job A runs on Thursday. When job A runs on Thursday, run job B on Friday.
Solution
Use the following statements for the jobs:
GENTIME A WEDNESDAY STARTING TODAY LESS 2 DAYS GENTIME B %ADATE PLUS 0 WORKDAYS JOB A RUN WEDNESDAY IFHOLIDAYPLUS 1 DAY ENDJOB JOB B IF NOT SELECTED('A') THEN RUN THURSDAY IF TODAY('FRIDAY') AND ADATE NE BDATE THEN RUN TODAY ENDJOB
Explanation
Two GENTIME commands are used in this solution. The first GENTIME command generates date and time variables for Wednesday of the current week. The second GENTIME command generates date and time variables for the first workday on or after Wednesdays date. If the two GENTIME dates are not equal, then Wednesday was a holiday. Job A is selected to run every Wednesday. If Wednesday falls on a holiday, ESP Workload Manager selects job A to run on Thursday instead. Job B is selected to run when either of these conditions is true: Today is Thursday and job A is not selected to run. Today is Friday and Wednesday was a holiday.
For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15.
ESP-5.5-EC-01
13
Scheduling a job based on the workday status of the last day of the previous month
Objective
Run a job on the 2nd workday of each month, but only if the last day of the previous month was a workday.
Solution
JOB A GENTIME LD LAST DAY OF MONTH STARTING TODAY LESS 1 MONTH GENTIME LWD LAST WORKDAY OF MONTH STARTING TODAY LESS 1 MONTH IF %LDDATE EQ %LWDDATE THEN RUN 2ND WORKDAY OF MONTH ENDJOB
Explanation
This solution uses two GENTIME commands to generate date and time variables for the last day of the previous month and for the last workday of the previous month. If these two dates are equal, then the last day of the previous month was a workday, and the job is selected to run on the 2nd workday of the month. For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15.
14
ESP-5.5-EC-01
Determining if a day in the past was a workday

Objective
Determine whether some day in the past was a workday. For example, you may need to determine if last Friday was a workday, or if a fixed date fell on a workday, and schedule a job based on the result.
Solution
The following code sets the variable VALUE to either true or false based on whether or not May 13, 2004 was a workday.
GENTIME ONE MAY 13, 2004 GENTIME TWO %ONEDATE PLUS 0 WORKDAYS IF ONEDATE=TWODATE THEN VALUE='TRUE' ELSE VALUE='FALSE'
Explanation
This solution shows a general approach to checking if a day in the past was a workday. The first GENTIME generates date and time variables for the day in the past. This could be a criteria, such as LAST DAY OF MONTH STARTING TODAY LESS 1 MONTH, or it could be a date such as MAY 13, 2004. The second GENTIME generates date and time variables for the first workday on, or after, your first criteria. It uses the DATE variable from your first GENTIME (in other words, %ONEDATE) and adds PLUS 0 WORKDAYS. The two dates from the GENTIMEs are then compared. If they are equal then the day in the past was a workday; otherwise, it was a non-workday.
Note: The
default retain count for holidays is 2 days. Since holidays affect what is considered a workday, you may need to retain some holidays for a longer period if you need to refer back to them after two days.
ESP-5.5-EC-01
15
Scheduling a job to run every two days

Objective
A job needs to run every two days and belongs to an Application containing jobs with many different frequencies. Use April 1, 2004 as the starting point for the schedule.
Solution
RUN EVERY 2 DAYS STARTING APR 1ST 2004
Explanation
This solution selects the job to run every two days starting on April 1, 2004.
16
ESP-5.5-EC-01
Scheduling a job to run every two weeks and advancing it for holidays
Objective
A job in an Application needs to run every two weeks on Friday. If this falls on a nonworkday, run the job on the previous workday instead. Use Friday, August 1, 2003 as the starting point for the schedule.
Solution
RUN EVERY 2 WEEKS STARTING AUG 1ST 2003 LESS 0 WORKDAYS
Explanation
This solution selects the job to run every two weeks starting on Friday, August 1, 2003. If the Friday is a holiday, ESP Workload Manager selects the job to run on the previous workday instead.
ESP-5.5-EC-01
17
Scheduling a job to run every two weeks and delaying it for holidays
Objective
Schedule a job to run every second Wednesday, unless Wednesday is a holiday. If Wednesday is a holiday, run the job on Thursday regardless of whether Thursday is a holiday. Use Wednesday, April 7, 2004, as the starting point for the schedule.
Solution
RUN EVERY 2 WEEKS STARTING APR 7TH 2004 IFHOLIDAYPLUS 1 DAY
Explanation
This solution selects the job to run every two weeks starting on Wednesday, April 7, 2004. If the Wednesday falls on a holiday, ESP Workload Manager selects the job to run on Thursday instead.
18
ESP-5.5-EC-01
Scheduling different jobs to run based on the calendar quarter

Objective
Schedule a different job to run each calendar quarter. Each calendar quarter consists of three months, and the first quarter starts on January 1.
Solution
Use the following Application:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A.QTR1 RUN ANYDAY OF JAN FEB MAR ENDJOB JOB B.QTR2 RUN ANYDAY OF APR MAY JUN ENDJOB JOB C.QTR3 RUN ANYDAY OF JUL AUG SEP ENDJOB JOB D.QTR4 RUN ANYDAY OF OCT NOV DEC ENDJOB
Explanation
Each job has a different RUN statement to reflect the quarter in which it should run. Depending on the month, one of the RUN statements applies, and the appropriate job is selected to run.
ESP-5.5-EC-01
19
Scheduling a job on a random day of the month

Objective
A job needs to run at 11 AM on a random day each month.
Solution
Schedule an Event on the last day of the month to invoke the following Procedure:
/* CALCULATE NUMBER OF DAYS IN NEXT MONTH - NUMDD /* GENTIME NUM LAST DAY OF MONTH STARTING TODAY PLUS 1 MONTH /* /* USE REXX TO GENERATE A RANDOM NUMBER BETWEEN 1 AND /* NUMBER OF DAYS IN NEXT MONTH /* REXXON DAYS_IN_MONTH=CLANGVAR('%NUMDD') DAY=RANDOM(1,DAYS_IN_MONTH) "NUMBER="DAY REXXOFF /* /* GENERATE APPLICATION - DELAY JOB UNTIL 11AM ON THE /* RANDOM DAY /* APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB RANDOM RUN ANY DELAYSUB 11AM TODAY PLUS %NUMBER DAYS ENDJOB
Explanation
This Procedure runs on the last day of the month and determines when the job should run in the following month. GENTIME creates date and time variables, prefixed with NUM, for the next month. The NUMDD variable represents the number of days in the next month. This solution uses REXX to generate a random number between 1 and NUMDD. The Application builds with the job delayed for the random number of days at 11 AM.
20
ESP-5.5-EC-01
Scheduling an hourly Application within a time range

Objective
Schedule an Application to run every hour from 8 AM to 4 PM on workdays.
Solution
Use the following Event to run your Application:
EVENT ID(PROD.HOURJOB) SCHEDULE HOURLY ROUND STARTING TODAY SUSPEND 4:01PM WORKDAYS RESUME 7:59AM WORKDAYS INVOKE 'PROD.PROCLIB(HOURJOB)' ENDDEF
Explanation
The Event is scheduled every hour on the hour. SUSPEND and RESUME commands are used within the Event to control processing. The Event is suspended just after its 4 PM execution on workdays and resumed just prior to its 8 AM execution on workdays. This enables the Event to run hourly between 8 AM and 4 PM on workdays. Variation Another solution is to schedule the Event multiple times each workday. For example:
SCHEDULE 8AM WORKDAYS SCHEDULE 9AM WORKDAYS . . . SCHEDULE 4PM WORKDAYS
ESP-5.5-EC-01
21
Scheduling an hourly job within a time range

Objective
Schedule a job to run every hour from 8 AM to 4 PM on workdays. The job belongs to an Application containing many different jobs with different frequencies.
Solution
One solution is to use a template within your Application definition. Take the following steps: 1. Use a template in your Application to define multiple instances of the job. For example:
APPL CYBER JCLLIB 'CYBER.JCLLIB' TEMPLATE HOURLY (1,OFFSET) JOB A.%OFFSET RUN WORKDAYS DELAYSUB 8AM PLUS %OFFSET HOURS ENDJOB ENDTEMPL HOURLY HOURLY HOURLY HOURLY HOURLY HOURLY HOURLY HOURLY HOURLY 0 1 2 3 4 5 6 7 8
2. Schedule an Event prior to 8 AM that invokes this Application.
Explanation
This solution uses a template called HOURLY. Instead of creating separate job definitions for each instance of job A in the Application, the template defines the job requirements for all instances of the job in a few statements. The template accepts one parameter for the offset from 8 AM (0 hours, 1 hour, 2 hours, and so on). This offset is used as a job qualifier for the job to ensure uniqueness within each generation of the Application. It is also used in the DELAYSUB statement to specify the time dependency relative to 8 AM.
22
ESP-5.5-EC-01
The code generated through calling the template is shown below:
JOB A.0 RUN WORKDAYS DELAYSUB 8AM PLUS 0 HOURS ENDJOB JOB A.1 RUN WORKDAYS DELAYSUB 8AM PLUS 1 HOURS ENDJOB . . . JOB A.8 RUN WORKDAYS DELAYSUB 8AM PLUS 8 HOURS ENDJOB
Note: If
the Application contains only the one job that needs to run each hour, you can simply schedule the Event each hour between these times and invoke an Application containing the job to be run.
ESP-5.5-EC-01
23
Scheduling a different job to run every hour

Objective
A one-job Application runs each hour. The name of the job in the Application depends upon its scheduled time. The jobnames are called MYJOB followed by a letter of the alphabet which is based on the scheduled hour. At 1 AM use the letter A, at 2 AM use the letter B, and so on, as shown in the following table:
Time Jobname
1 AM 2 AM 3 AM ... 11 PM 12 AM
MYJOBA MYJOBB MYJOBC ... MYJOBW MYJOBX
Solution
Take the following steps: 1. Use the following Application:
LETTERS='ABCDEFGHIJKLMNOPQRSTUVWX' INTEGER HOUR IF ESPSHH='00' THEN HOUR=24 ELSE HOUR=ESPSHH CHAR='%LETTERS(%HOUR:%HOUR)' APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB MYJOB%CHAR RUN ANY ENDJOB
2. Schedule an Event hourly to submit the one-job Application.
Explanation
The solution uses a symbolic variable called LETTERS, which is assigned a string representing the letters of the alphabet from A to X. Each hour, ESP Workload Manager uses a different substring of this variable based on the scheduled hour (ESPSHH). The HOUR variable is used as an integer variable to enable substrings since substring notation requires numbers and not characters. If the scheduled hour is midnight then ESPSHH has the value of 00, and the HOUR variable is assigned the value of 24 to
24
ESP-5.5-EC-01
enable the correct substring. Otherwise, HOUR is assigned the value of the ESPSHH variable. The CHAR variable is assigned the letter to be used based on the scheduled hour. For example, at 4 AM, CHAR is determined by %LETTERS(4:4), which has the value D. Job MYJOBD is submitted. Variation If you want to use the same JCL member for all of the jobs, you can use a MEMBER statement for the job and specify this common member. For example:
JOB MYJOB%CHAR RUN ANY MEMBER MYJOB ENDJOB
In the MYJOB JCL member, you can use %ESPAPJOB in place of the job name. ESP Workload Manager substitutes the correct job name at the time of submission. For example:
//%ESPAPJOB JOB
ESP-5.5-EC-01
25
Scheduling a job in an Application to run based on day and time

Objective
An Event is scheduled every hour on the hour to run an Application. Job X in the Application should only be selected to run on Fridays at 3 PM.
Solution
Take the following steps: 1. Use the following statements for the job:
JOB X IF TODAY('FRI') AND ESPSHH = '15' THEN RUN TODAY ENDJOB
2. Schedule an hourly Event to run the Application. For example:

EVENT ID(PROD.HOURLY) SYSTEM(-) REPLACE SCHEDULE 00.00 HOURLY DAILY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF
Explanation
Job X is selected to run only if it is Friday and the Events scheduled hour (ESPSHH) is 15 (in other words, the Event was scheduled at 3 PM).
26
ESP-5.5-EC-01
Scheduling an ad hoc job to run multiple times

Objective
Within the same generation of an Application, run an ad hoc job every 30 minutes for four hours (in other words, 8 times). The name of the ad hoc job is supplied by a user and may change from one generation of the Application to another.
Solution
One solution is to use a task to dynamically insert the jobs. Take the following steps: 1. Use the following Application:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB INSERT.JOBS TASK SELFCOMPLETING RUN ANY TIME='%ESPAHH%ESPAMN%ESPASS' IF ESPREEXEC# LT 8 THEN DO ESP AJ %USER1..T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN) REEXEC AT('REALNOW PLUS 30 MINUTES') ENDDO ENDJOB
2. Set up an Event (for example, PROD.CYBER) to invoke this Application. 3. To run an ad hoc job, trigger the Event and specify the name of the job as the USER1 parameter. For example:
TRIGGER PROD.CYBER USER1('MYJOB')
Explanation
This solution uses a self-completing task named INSERT.JOBS to insert the ad hoc job every 30 minutes into this Application. A variable called TIME uniquely qualifies the job with a time stamp (actual hours, minutes, and seconds) as it is inserted into the Application. The Procedure uses the ESPREEXEC# built-in symbolic variable to check the number of re-executions, and does one of the following: If ESPREEXEC# is less than 8, the task issues an AJ command to insert another instance of the job. The task re-executes in 30 minutes. Otherwise, the task completes itself automatically.
Note: The
AJ command uses the ESPAPPL and ESPAPGEN variables to ensure the correct generation of the correct Application is used. This example inserts a z/OS job. For an example of inserting a UNIX job at a regular interval, refer to Scheduling a job to run every two hours on page 29.
ESP-5.5-EC-01
27
Example If you pass MYJOB as the USER1 variable and the actual time is 10.32.45, the jobnames are:
MYJOB.T103245 MYJOB.T110245 ... MYJOB.T140245
Variation The AJ command can also be prefixed with ESPNOMSG. For example:
ESPNOMSG AJ %USER1..T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN)
Using ESPNOMSG suppresses responses from the command (such as a message indicating the job was inserted). Warning and error messages are not suppressed.
28
ESP-5.5-EC-01
Scheduling a job to run every two hours

Objective
An Application is scheduled each workday. Within the Application, a UNIX job needs to run every two hours until 00:30 the next workday.
Solution
APPL CYBER JOB INSERT.JOBS TASK RUN WORKDAYS TIME='%ESPAHH%ESPAMN%ESPASS' ESP APPLINS APPL(%ESPAPPL..%ESPAPGEN) STATEMENTS('UNIX_JOB A.T%TIME; AGENT AGENT; SCRIPTNAME /export/home/jsmith/scripts/a; ENDJOB') REEXEC AT('REALNOW PLUS 2 HOURS') ENDJOB JOB STOP.INSERTS LINK PROCESS RUN WORKDAYS DELAYSUB 00:30 TODAY PLUS 1 WORKDAY ESP AJ INSERT.JOBS COMPLETE APPL(%ESPAPPL..%ESPAPGEN) ENDJOB
Explanation
This solution uses a task called INSERT.JOBS and a link called STOP.INSERTS. The INSERT.JOBS task does the following: Builds a time symbolic variable (%TIME) for the job, consisting of the actual hour, minute, and second. Issues an APPLINS command to dynamically insert job A with a qualifier of T%TIME into the Application. Re-executes in 2 hours.
At 00:30 the next workday, the link issues an AJ command to complete the INSERT.JOBS task.
Note: The
ESPAPPL and ESPAPGEN variables are used on the APPLINS and AJ commands. This ensures the correct generation of the correct Application is used. This example inserts a UNIX job. For an example of inserting a z/OS job at a regular interval, refer to Scheduling an ad hoc job to run multiple times on page 27.
ESP-5.5-EC-01
29
Scheduling a job to run multiple times within a time range

Objective
An Application is scheduled daily. Within the Application, a UNIX job needs to run every 10 minutes between 10 PM and 2 AM inclusively. The Application contains many jobs with many different frequencies.
Solution
One solution is to use a template in your Application definition. A sample template is shown below:
TEMPLATE MULTIRUN (1,TIME) UNIX_JOB A.%TIME AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS %TIME MINUTES RUN ANY ENDJOB ENDTEMPL REXXON DO I=0 TO 240 BY 10 "MULTIRUN "I END REXXOFF
Explanation
This solution uses REXX and a template to build all instances of the job when the Application generates. Each instance of the job is qualified with the offset, in minutes, from 10 PM. For example: 0, 10, 20,..., 240.
30
ESP-5.5-EC-01
The code generated through calling the template is shown below:
UNIX_JOB A.0 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 0 MINUTES RUN ANY ENDJOB UNIX_JOB A.10 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 10 MINUTES RUN ANY ENDJOB . . . UNIX_JOB A.240 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 240 MINUTES RUN ANY ENDJOB
Note: If the Application contains only the one job that needs to run every 10 minutes
within the time range, you can simply schedule the Event every 10 minutes between these times and invoke an Application containing the job to be run.
ESP-5.5-EC-01
31
Running ad hoc sequential jobs

Objective
Users often request from one to six jobs to run one after the other as a stand-alone Application. Each jobname is 8 characters in length.
Solution
The following is a sample Application that builds a sequence of jobs based on data supplied via a USER1 parameter on an Event trigger.
APPL CYBER JCLLIB 'CYBER.JCLLIB' J1='%USER1(1:8)' J2='%USER1(10:17)' J3='%USER1(19:26)' J4='%USER1(28:35)' J5='%USER1(37:44)' J6='%USER1(46:53)' IF J1 = '' THEN JUMPTO JDONE JOB %J1 RUN ANY ENDJOB IF J2 = '' THEN JUMPTO JDONE JOB %J2 RUN ANY AFTER %J1 ENDJOB IF J3 = '' THEN JUMPTO JDONE JOB %J3 RUN ANY AFTER %J2 ENDJOB IF J4 = '' THEN JUMPTO JDONE JOB %J4 RUN ANY AFTER %J3 ENDJOB IF J5 = '' THEN JUMPTO JDONE JOB %J5 RUN ANY AFTER %J4 ENDJOB
32
ESP-5.5-EC-01
IF J6 = '' THEN JUMPTO JDONE JOB %J6 RUN ANY AFTER %J5 ENDJOB JDONE: EXIT
Explanation
Users can trigger an ad hoc Event and pass a list of 8-character jobnames as the USER1 parameter. The Procedure parses the USER1 parameter into jobnames, J1 to J6, and builds the Application of sequential jobs. AFTER statements are used to set up relationships between jobs, since the number of jobs to be run varies. The following shows the generated code and the Application that builds after specifying four jobnames in the USER1 field:
USER1 Parameter
CYBBP01A CYBBP01B CYBBP01C CYBBP01D
Job Statements
Application CYBBP01A
JOB CYBBP01A RUN ANY ENDJOB JOB CYBBP01B RUN ANY AFTER CYBBP01A ENDJOB JOB CYBBP01C RUN ANY AFTER CYBBP01B ENDJOB JOB CYBBP01D RUN ANY AFTER CYBBP01C ENDJOB
CYBBP01B
CYBBP01C
CYBBP01D
ESP-5.5-EC-01
33
Variation There are many different ways you can adapt this approach. For example, you could have the user enter the jobnames into a panel or have the user update a data set. Either of these could cause a data set-triggered Event to invoke a Procedure similar to the one shown here.
34
ESP-5.5-EC-01
Dynamically defining and scheduling an Event

Objective
Job B needs to run at 9 PM 45 days after job A completes successfully.
Solution
Use a JOBEND job monitor Event for job A to invoke the following Procedure:
IF MNRC NE 0 THEN EXIT ESPNOMSG ESPNOMSG ESPNOMSG ESPNOMSG EVENT ID(PROD.SUB_B) REPLACE SCHEDULE 9PM TODAY PLUS 45 DAYS ONCE SUBMIT 'CYBER.JCLLIB(B)' ENDDEF
Explanation
The job monitor Procedure checks the return code for job A. If the return code is not 0, then the Procedure exits. Otherwise, the Procedure defines a one-time Event to execute at 9 PM 45 days later, which will submit job B. ONCE is used on the SCHEDULE statement so that the Event will be automatically deleted 24 hours after it has scheduled.
ESP-5.5-EC-01
35
Scheduling a weekly Application based on the number of workdays in the week

Objective
Schedule an Application to run at 4 PM on the 2nd last workday of each week, unless a week has only one workday. If a week has only one workday, schedule the Application to run on that workday instead.
Solution
IF TODAY('FRI') THEN DO ESP TR %ESPEVENT ADD AT('16:00 TODAY PLUS 1 WORKDAY') EXIT ENDDO APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY ENDJOB
2. Schedule an Event for 4 PM on the 2nd last workday of each week. For example:
EVENT ID(PROD.CYBER) SYSTEM(ESPM) REPLACE SCHEDULE 16.00 LAST WORKDAY OF EACH WEEK LESS 1 WORKDAY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF
36
ESP-5.5-EC-01
Explanation
The Event is scheduled for the 2nd last workday of each week. A problem can arise if a week contains only one workday, which causes the LESS 1 WORKDAY clause to go back to the Friday of the previous week. This would cause the Application to run twice in one week. To handle this case, the IF statement in the Application (before the APPL statement) checks to see if today is Friday. In this case, you do not want to generate the Application. Instead, retrigger the same Event on the following workday, putting it back to the first and only workday of the original week containing the holidays. Example For example, in the calendar below, if July 20-23 are holidays and July 19 is a workday, then the week of July 19-23 contains only one workday. When the Event schedules on July 15, the last workday of the next week less 1 workday is Friday July 16.
On Friday, July 16, ESP Workload Manager retriggers the Event with the ADD option for the next workday, which will be July 19. The next scheduled occurrence after that will be the last workday of the following week less 1 workday (in other words, July 29).
ESP-5.5-EC-01
37
Running the next scheduled Application early

Objective
Run the next days version of an Application today.
Solution
As long as you need to replace the next scheduled instance of the Application, you can simply trigger the Event to run the Application and use the REPLACE option. For example, if an Application runs daily at 8 AM, and you want to run Fridays Application on Thursday afternoon, you can trigger the Event now and use the REPLACE option.
Explanation
ESP Workload Manager automatically selects the jobs and resolves variables based on the replaced scheduled date.
Note: If
you want to run a future version of the Application other than the next scheduled occurrence, you can use the approach discussed in Running an Application for any future date on page 39.
38
ESP-5.5-EC-01
Running an Application for any future date

Objective
Run a future version of an Application today.
Solution
Take the following steps: 1. Define another Event that invokes the Application. Schedule the Event for the particular date in the future and use the ONCE keyword on the SCHEDULE statement. 2. Trigger this Event with the REPLACE option.
Explanation
For example, if you want to run an Event today as if it was Oct. 17, 2004, take the following steps: 1. Schedule another Event to invoke the Application and specify SCHEDULE OCT 17, 2004 ONCE. 2. Trigger the Event with the REPLACE option. ESP Workload Manager triggers the Event now and replaces the Oct. 17, 2004 execution. ESP Workload Manager selects jobs and resolves criteria variables based on the Oct. 17, 2004 date. The use of ONCE ensures the Event will not be scheduled again after you have triggered it with the REPLACE option. The Event is automatically deleted 24 hours later.
Note: If
the future version of the Application is the next scheduled occurrence, you can use the approach discussed in Running the next scheduled Application early on page 38.
ESP-5.5-EC-01
39
Delaying job submission until the next hour

Objective
When a jobs predecessor is complete, the job needs to be delayed until the beginning of the next hour. For example, if job A completes at 10:17 AM then job B should be submitted at 11:00 AM.
Solution
One solution is to use an Application like that shown below:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RELEASE B RUN DAILY ENDJOB JOB B IF ESPREEXEC#=0 THEN REEXEC AT('HOURLY ROUND STARTING REALNOW') RUN DAILY ENDJOB
Explanation
Often you may need a job in an Application to wait for a particular time before submission. You can use the DELAYSUB statement to specify a delayed submission time, such as DELAYSUB 7PM or DELAYSUB NOW PLUS 30 MINUTES. You can also use the RELDELAY statement to delay submission of a job relative to the time the jobs predecessors are all complete (for example, RELDELAY 30). In this example, you do not know what time the jobs predecessors will be complete, and so it is not possible to use either a DELAYSUB or a RELDELAY statement. When job B becomes ready, the ESPREEXEC# variable is set to 0. ESP Workload Manager schedules re-execution for the beginning of the next hour. At that time, ESPREEXEC# is 1 and ESP Workload Manager submits the job.
40
ESP-5.5-EC-01
Setting up a dependency with a jobs previous run

Objective
An Application is scheduled each day. One daily job in the Application, job X, needs to wait for its previous run to complete. However, other jobs in the Application can run even if the previous days Application is not complete. The dependencies look like this:
X.MON
X.TUE
Solution
Take the following steps to set up the Application: 1. Use a variable as a qualifier for job X that is equal to the first 3 characters of the scheduled day of the week. 2. Use GENTIME to generate date and time variables for the previous day. 3. Define the previous run of job X as an external job. Use the first 3 characters of the previous days day-of-week variable as a qualifier for the external job. Set up this job to release todays run of job X. Use the SCHEDULED parameter on this external job to reflect the previous day. Use the APPLID parameter to specify the name of the Application.
ESP-5.5-EC-01
41
The following is a sample Application:

APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY RELEASE Y ENDJOB GENTIME PREV YESTERDAY JOB X.%PREVDAY(1:3) EXTERNAL SCHEDULED('YESTERDAY') APPLID(CYBER) RUN DAILY RELEASE X.%ESPSDAY(1:3) ENDJOB JOB X.%ESPSDAY(1:3) RUN DAILY RELEASE Y ENDJOB JOB Y RUN DAILY ENDJOB
Explanation
Although there are some WAIT options available at the Application level and job level, they cannot be used here. Application WAIT would cause all jobs to wait for the previous days Application to complete; JOB_ANCESTOR_WAIT would cause each job to wait for its previous run to complete. In this scenario, there is only one job that needs to wait. This solution qualifies job X, and sets up the previous days run as an external dependency to todays run of job X. This does not prevent the other jobs in the Application from running. Variation Another approach is to define job X in a subApplication and use the WAIT option on the SUBAPPL statement. This approach is useful if you have a number of jobs, but not all, that need to wait for the previous days runs to complete. For example:
JOB X SUBAPPL PREVDAY WAIT RUN DAILY RELEASE Y ENDJOB
42
ESP-5.5-EC-01
Using date-qualified file names

Objective
An Application contains some file trigger jobs where the names of the files being monitored for creation contain a date qualifier and a literal in the form: MMDDYY_ok. MM is the scheduled month, DD is the scheduled day, and YY is the scheduled year.
Solution
On the FILENAME statement for the file trigger jobs, you can use built-in symbolic variables for the date and concatenate the literal at the end. For example:
FILE_TRIGGER file1 RUN DAILY FILENAME /batch/interfaces/file1.%ESPSMM%ESPSDD%ESPSYY._ok ENDJOB
Explanation
When the Application generates, it resolves the built-in variables based on the scheduled date of the Event. For example, on November 6, 2005, the above example resolves to the following file name:
/batch/interfaces/file1.110605_ok
Variation Another approach is to define a symbolic variable representing the date qualified string. You can then use this variable in your job definitions. This is useful when you need to use this file qualifier for many file trigger jobs. Also, if the format of the file name changes, you need only to update the format in one place. For example, use the following assignment statement:
DATEQUAL=ESPSMM + ESPSDD + ESPSYY + '_ok'
On the FILENAME statement for the file trigger jobs, you can use this variable, as shown below.
FILE_TRIGGER file2 RUN DAILY FILENAME /batch/interfaces/file2.%DATEQUAL ENDJOB
ESP-5.5-EC-01
43
Processing a changing file name

Objective
When a file is created, a UNIX script needs to use the file name as input. The last 12 characters of the file name always change and are based on a date and time stamp. An example of such a filename is file092904231456.
Solution
The following Application shows how to define the file trigger job, CREATE, and the successor job, PROCESS.
APPL CYBER AGENT AGENT FILE_TRIGGER CREATE RUN DAILY FILENAME /export/home/jsmith/scripts/file* CREATE RELEASE PROCESS ENDJOB UNIX_JOB PROCESS RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/echoit ARGS %ESPFTFILE ENDJOB
Explanation
The built-in variable, ESPFTFILE, is assigned a value of the full file name whenever file trigger activity takes place. You can pass this variable as an argument to the UNIX script run after the file trigger completes.
Note: There is only one ESPFTFILE variable per generation of an Application. When
additional file triggers take place in the same generation of the Application, the previous ESPFTFILE variable is overwritten.
44
ESP-5.5-EC-01
Copying a file to another location upon the files creation

Objective
When a file is created, copy the file to another location.
Solution
The following Application shows you how to define a file trigger job, CREATE, to monitor for a files creation and a successor job, COPY, to copy the newly created file to another location.
APPL COPYFILE AGENT AGENT FILE_TRIGGER CREATE RUN DAILY FILENAME C:\env.txt CREATE RELEASE COPY ENDJOB NT_JOB COPY RUN DAILY CMDNAME C:\Windows\system32\cmd.exe ARGS /C "copy C:\env.txt C:\test\env.txt" ENDJOB
Explanation
When the file is created, ESP Workload Manager completes the CREATE file trigger job and releases the COPY job. The COPY job uses the Windows command interpreter cmd.exe to copy the file to another location. To pass an argument to cmd.exe, such as the copy command in this example, enclose the argument in double quotation marks and precede the argument with the /C switch.
Note: The
path to the Windows command interpreter cmd.exe depends on your Windows operating system version. On Windows NT, the path would be C:\WINNT\system32\cmd.exe. For the path your Windows operating system uses, see your Windows administrator. For more information on running Windows operating-system commands using cmd.exe, see the CMDNAME statement in the ESP Workload Manager Reference Guide.
ESP-5.5-EC-01
45
Ensuring a file exists before processing

Objective
Check to ensure a file exists before processing it. If the file does not exist, run a script to create it. The dependencies look like this:
CHECK4.FILE
CREATE.FILE
PROCESS.FILE
Solution
The following Application shows how to define the different workload objects.
APPL CYBER AGENT AGENT FILE_TRIGGER CHECK4.FILE CONDITIONAL RUN DAILY FILENAME /export/home/jsmith/scripts/myfile EXIST RELEASE (CREATE.FILE(A),PROCESS.FILE) ENDJOB UNIX_JOB CREATE.FILE CONDITIONAL RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/create.file RELEASE PROCESS.FILE ENDJOB UNIX_JOB PROCESS.FILE RUN DAILY RELCOUNT 1 SCRIPTNAME /export/home/jsmith/scripts/process.file ENDJOB
46
ESP-5.5-EC-01
Explanation
This solution uses a file trigger job, CHECK4. FILE, to check for the existence of a file. There are two possible outcomes: The file trigger fails. This means the file does not exist. Job CREATE.FILE is released upon failure to create the file. Once this job completes, job PROCESS.FILE is released to process the file. At the end of the Application, job CHECK4.FILE is bypassed to enable the Application to complete. The file trigger completes successfully. This means the file exists. Job PROCESS.FILE is released to process the file. At the end of the Application, job CREATE.FILE is bypassed to enable the Application to complete.
Job PROCESS.FILE uses RELCOUNT 1 because it can be run when either CHECK4.FILE or CREATE.FILE are successful. CHECK4.FILE and CREATE.FILE are conditional jobs. This allows them to be bypassed automatically, if necessary, at the end of the Application.
ESP-5.5-EC-01
47
Bypassing a job based on the status of another job

Objective
Run or bypass a job based on whether a particular job is complete in another Application.
Solution
This solution uses a task in the Application to check the completion status of job OTHERJOB in the OTHERAPP Application. If this job is not complete, then job B is bypassed.
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB CHECKJOB TASK SELFCOMPLETING RUN ANY REXXON PROC J=JOBONCSF('OTHERJOB','X') IF J > 0 THEN DO BYPASS='NO' DO I=1 TO J WHILE BYPASS='NO' IF XAPPL.I='OTHERAPP' & XCOMPLETE.I=0 THEN DO BYPASS='YES' ESP AJ B BYPASS APPL(CYBER.%ESPAPGEN) LEAVE END END END REXXOFF RELEASE B ENDJOB JOB B RUN DAILY ENDJOB
Explanation
This solution uses a self-completing task named CHECKJOB. This task does the following: Uses REXX in Application process mode and the JOBONCSF built-in function to find all instances of job OTHERJOB. If OTHERJOB is found in any generation of the OTHERAPP Application and it is not complete, then job B is bypassed. Completes itself automatically.
48
ESP-5.5-EC-01
Bypassing non-critical jobs when jobs are late

Objective
There are problems meeting a service level agreement (SLA) and the programmers recommend bypassing some non-critical jobs when a particular Application is behind. For example, if certain jobs in an Application are not complete by 6 AM, then bypass some non-critical jobs.
Solution
Using ESP Workload Manager, this bypass can be automatically scheduled by taking the following steps: 1. Define a link (for example, CRITICAL.POINT) as a successor to the important jobs. 2. Specify an overdue DUEOUT EXEC time for this link of 6AM. 3. Identify an Alert to be triggered if the link becomes overdue. 4. Define the Alert. 5. Set up an ESP Procedure invoked by the Alert Event to bypass the non-critical jobs. 6. Define the Alert Event to run the Procedure. Application Description In the following Application: Jobs A and B are important jobs and should be complete by 6 AM If they are not complete by 6 AM, then jobs C and E should be bypassed.
ESP-5.5-EC-01
49
The Application looks like this:

A B
CRITICAL.POINT
Application Definition The following is the definition of the Application:

APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY RELEASE CRITICAL.POINT ENDJOB JOB B RUN DAILY RELEASE CRITICAL.POINT ENDJOB JOB CRITICAL.POINT LINK RUN DAILY NOTIFY OVERDUE ALERT(CRIT) DUEOUT EXEC 6AM RELEASE (C,D,E) ENDJOB JOB C RUN DAILY RELEASE F ENDJOB JOB D RUN DAILY RELEASE F ENDJOB JOB E RUN DAILY RELEASE F
50
ESP-5.5-EC-01
ENDJOB JOB F RUN DAILY ENDJOB
Alert Procedure The following ESP Procedure can be invoked via the Alert Event:
/* BYPASS NON-CRITICAL JOBS IN APPLICATION ESPNOMSG AJ C BYPASS APPL(%MNAPPL..%MNAPPLGEN) ESPNOMSG AJ E BYPASS APPL(%MNAPPL..%MNAPPLGEN)
Explanation
Jobs A and B are important jobs. Each of these jobs releases a link called CRITICAL.POINT. If CRITICAL.POINT is not complete by 6 AM, it becomes overdue and an Alert called CRIT triggers. The Alert runs an ESP Procedure that issues ESP AJ commands to bypass jobs C and E. This solution uses monitor variables for the Application name (%MNAPPL) and for the Application generation number (%MNAPPLGEN) to ensure the jobs are bypassed in the correct generation of the correct Application.
ESP-5.5-EC-01
51
Taking different actions based on 1 of 3 successful return codes

Objective
A monthly Application is scheduled for 10 AM on the last workday of each month. The first job, job A, can issue a return code of 0, 1, or 2. Different actions are required based on this return code, as described below.
Return Code for Job A Action
0 1 2
Run job B Complete Application and run it again at 10 AM the next workday Cancel this months run
The requirements look like this:
Run job B
Run again next workday
Cancel this month's run
Solution
The following is a sample Application you can schedule at 10 AM on the last workday of each month:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANYDAY RELEASE ADD(B) COND(RC(0)) RELEASE ADD(RUNAGAIN) COND(RC(1)) RELEASE ADD(CANCEL) COND(RC(2)) ENDJOB JOB B RUN ANYDAY ENDJOB
52
ESP-5.5-EC-01
JOB RUNAGAIN LINK PROCESS RUN ANYDAY SEND 'THE PROCEDURE WILL RUN NEXT WORKDAY' U(*) ESP AJ ALL COMPLETE APPL(%ESPAPPL..%ESPAPGEN) ESP TRIGGER PROD.CYBER ADD AT('10AM TODAY PLUS 1 WORKDAY') ENDJOB JOB CANCEL LINK PROCESS RUN ANYDAY SEND 'THE PROCEDURE WILL RUN NEXT MONTH' U(*) ESP AJ ALL COMPLETE APPL(%ESPAPPL..%ESPAPGEN) ENDJOB
Explanation
Job A uses three conditional release expressions to take the appropriate action: If job A has a return code of 0, it releases job B. If job A has a return code of 1, it releases a link called RUNAGAIN, which completes the Application and retriggers the Application again at 10 AM the next workday. If job A has a return code of 2, it releases a link called CANCEL, which completes the Application, cancelling this months run.
The AJ commands use the ESPAPPL and ESPAPGEN variables to ensure the correct generation of the correct Application is used.
ESP-5.5-EC-01
53
Running different jobs based on the return code of a predecessor job

Objective
Run job B if job A ends with a return code of 0, and run job C if job A ends with a return code of 1. The dependencies look like this:
A
0 1
Solution
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A CCCHK RC(2:4095) FAIL RUN DAILY RELEASE ADD(B) COND(RC(0)) RELEASE ADD(C) COND(RC(1)) ENDJOB JOB B RUN DAILY ENDJOB JOB C RUN DAILY ENDJOB
Explanation
Job A uses two conditional release expressions to release job B on return code 0 and job C on return code 1.
54
ESP-5.5-EC-01
Auto-triggering an Event for a reoccurring job

Objective
The Operations department runs a special stand-alone job upon request. It is always the same job and they do not want an operator to have to trigger an Event to run the job.
Solution
Take the following steps: 1. Set up a one-job Application. Use a schedule frequency of RUN DAILY, and define the special job on hold. 2. Use a TRIGGER command within the scope of the JOB statement to retrigger the Event. For example:
APPL HELDJOB JCLLIB 'CYBER.JCLLIB' JOB SPECIAL HOLD RUN DAILY ESPNOMSG TRIGGER %ESPEVENT ENDJOB
3. Define an Event without a SCHEDULE statement to invoke this Application. 4. Manually trigger the Event to create the first generation of the Application.
Explanation
Once the first generation of the Application is built, an operator can release job SPECIAL from hold whenever it needs to run. This causes the job to run, and the TRIGGER command retriggers the same Event to build another generation with the job on hold again.
ESP-5.5-EC-01
55
Scheduling a job to run based on its previous run status

Objective
Schedule a one-job Application to run every five minutes. If the previous run of the Application is not complete, then do not run the job until its next scheduled run.
Solution
REXXON GEN X=TRAPOUT('LINE.') "ESPNOMSG LAP CYBER.0" X=TRAPOUT('OFF') STATUS=SUBWORD(LINE.1,5) IF LINE.0 \= 0 & STATUS='' THEN "QUIT" IF STATUS='' THEN "QUIT" REXXOFF APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY ENDJOB
2. Schedule an Event every 5 minutes to run this Application.
Explanation
This solution uses REXX during Application generation mode to check the status of the current generation (in other words, the last generation that was created). The status of the Application is displayed as the 5th word in the first line of the LAP output. If this is the first time that the Application runs, there is no output (in other words, LINE.0=0), and the Application builds to submit job A. Otherwise, the status is either blank or COMPLETE. If the status is blank, the last generation is not complete and the new generation is not created. This approach prevents a backlog of Applications when problems arise with the job (for example, if the job fails).
56
ESP-5.5-EC-01
Scheduling a cyclic Application

Objective
A group of jobs runs multiple times a day. The first run is at midnight. Once all of the jobs have completed successfully, the next generation should be run 60 minutes later. The last run each day should occur no later than 7 PM.
Solution
Take the following steps: 1. Use the following Application.
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A.T%ESPSHH RUN DAILY RELEASE B.T%ESPSHH ENDJOB JOB B.T%ESPSHH RUN DAILY ENDJOB ... APPLEND RETRIG.EVENT RELDELAY 60 IF ESPAHH < '19' AND ESPSDATE=ESPADATE THEN ESPNOMSG TRIGGER %ESPEVENT ADD ENDJOB
2. Schedule the following Event to run the Application:

EVENT ID(PROD.CYBER) SYSTEM(-) REPLACE SCHEDULE 00.00 DAILY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF
Explanation
The Event is scheduled at midnight each day to run the first group of jobs. The Application uses a time-based qualifier to distinguish each group of jobs for ease of monitoring.
ESP-5.5-EC-01
57
An APPLEND object, called RETRIG.EVENT, waits for all jobs in the Application to complete successfully before it retriggers the Event. It is automatically a successor to all jobs in the Application that do not have any successors. This allows you to add jobs to the Application without defining those jobs as predecessors to the object that will bring in the next generation. After all of the jobs have completed successfully, the RETRIG.EVENT object waits 60 minutes (RELDELAY 60) before it becomes ready. It then checks the actual time and if the time is before 7 PM on the same day, it re-triggers the original Event. The TRIGGER command with the ADD option is used so that the regular daily scheduled Event at midnight is not affected.
58
ESP-5.5-EC-01
Incrementing a cycle number

Objective
When an Application processes, it uses a four-digit cycle number. This cycle number is used as part of the data set names for two data set trigger jobs, and extensively in JCL for jobs that run after the data set triggers complete. The cycle number increments each time the Application runs, and it ranges from 0001 to 9999. The Application waits for two data sets to be created: BUS.BCnumber and RES.BCnumber, where number represents the cycle number.
Solution
Take the following steps: 1. The cycle number is passed to the Event using a User Parameter. Use the following code to assign the value of the User Parameter to a variable called THIS_CYCLE.
THIS_CYCLE=USER1
2. Define the two data set trigger jobs. Use %THIS_CYCLE as part of the data set names for these jobs. For example: BUS.BC%THIS_CYCLE and RES.BC%THIS_CYCLE. 3. Use a link at the end of the Application to increment the cycle number and trigger the next occurrence of the Event with the USER1 parameter as the new cycle number. 4. Use %THIS_CYCLE in the JCL for jobs that use the cycle number.
ESP-5.5-EC-01
59
Application The following is a sample Application definition:

APPL CYBER JCLLIB 'CYBER.JCLLIB' THIS_CYCLE=USER1 DSTRIG BUS RUN ANY DSNAME BUS.BC%THIS_CYCLE RELEASE A ENDJOB DSTRIG RES RUN ANY DSNAME RES.BC%THIS_CYCLE RELEASE A ENDJOB JOB A RUN ANY RELEASE Z ENDJOB JOB Z RUN ANY RELEASE CHANGE.CYCLE ENDJOB JOB CHANGE.CYCLE LINK PROCESS RUN DAILY /* INCREMENT 4-DIGIT CYCLE NUMBER AND RESET TO 1 AFTER 9999 INTEGER CYCLE CYCLE=THIS_CYCLE IF CYCLE=9999 THEN CYCLE=1 ELSE CYCLE=CYCLE+1 NEW_CYCLE='%CYCLE(F4)' ESPNOMSG TRIGGER %ESPEVENT USER1('%NEW_CYCLE') ENDJOB
60
ESP-5.5-EC-01
The flow looks like this:
File=RES.BC1234
File=BUS.BC1234
CHANGE.CYCLE
File=RES.BC1235
File=BUS.BC1235
You will need to trigger this Event manually the first time and pass the four-digit cycle number. After that, each new generation of the Application will be automatically triggered when one generation completes.
Explanation
When the Application is generated, ESP Workload Manager assigns the cycle number, which is passed as the USER1 parameter, to a variable called THIS_CYCLE. The data set trigger jobs wait for the latest cycle of the BUS.BC and RES.BC data sets. The CHANGE.CYCLE link at the end of the Application takes the current cycle number, adds 1, and pads the result with leading zeroes, as necessary. After cycle 9999, the cycle is reset to 0001. The link retriggers the Event and passes this new cycle number in the USER1 field. This enables the new cycle number to be used in the next generation of the Application.
ESP-5.5-EC-01
61
Building Applications dynamically based on an input file

Objective
An Application needs to be built dynamically based on an input file supplied by a user. The input file contains a list of jobnames with one jobname per line.
Solution
APPL CYBER JCLLIB 'CYB.JCL' REXXON "ALLOCX DSN('CYBER.INPUT') F(INDD) SHR" IF RC \= 0 THEN DO "SEND 'UNABLE TO ALLOCATE CYBER.INPUT' U(USER01)" "EXIT" EXIT END ADDRESS z/OS "EXECIO * DISKR " INDD "(STEM LINE. FINIS" IF LINE.0 = 0 THEN DO "SEND 'NO JOBS TO RUN' U(USER01)" "FREEX FILE("INDD")" "EXIT" EXIT END LAST = LINE.0 DO I = 1 TO LAST PARSE VAR LINE.I JOBNAME JOBNAME=STRIP(JOBNAME) "JOB "JOBNAME "RUN NOW" "ENDJOB" END "FREEX FILE("INDD")" REXXOFF
You can schedule an Event to run the Application or set up a data set-triggered Event that runs when the input file is updated.
62
ESP-5.5-EC-01
Explanation
This solution uses REXX to read the input file. If the file is empty, a message is sent indicating that there are no jobs to run. If the file is not empty, each line is read and corresponding JOB statements are created. For example:
CYBER.INPUT File
Application APPL CYBER JCLLIB 'CYB.JCL' JOB ADHOCJ12 RUN NOW ENDJOB JOB CLEANUP1 RUN NOW ENDJOB . . .
ADHOCJ12 CLEANUP1 . . .
ESP-5.5-EC-01
63
Running a job based on resource availability

Objective
Run a job if only one unit of a resource is available, otherwise bypass the job.
Solution
Use a task in an Application to check the resource availability prior to running the job.
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB CHKRES TASK SELFCOMPLETING REXXON PROC X=TRAPOUT('LINE.') "ESP RESDEF CART LIST" X=TRAPOUT('OFF') STATUS=SUBWORD(LINE.3,4) IF STATUS = 'Avail=1' THEN "ESP AJ B REQUEST APPL(CYBER.%ESPAPGEN)" REXXOFF RUN DAILY RELEASE B ENDJOB JOB B REQUEST RUN DAILY ENDJOB Note: 'Avail=1'
must be entered in mixed case, exactly as shown above.
Explanation
Job B is defined as a REQUEST job. If job B is not explicitly requested, it does not run. This solution uses a task called CHKRES that does the following: Traps the output of the RESDEF command that lists the current status of the CART resource. Determines whether one unit of the CART resource is available. If one unit of CART is available, issues an AJ command that requests job B. Completes itself automatically.
Note: The
ESPAPGEN variable is used to ensure the AJ command is issued against the correct generation.
64
ESP-5.5-EC-01
Running or completing a job based on the order in which its predecessors complete
Objective
Job B has two predecessors: job A and a data set trigger. If the data set trigger completes before job A, job B should run. If job A completes before the data set trigger, job B and the data set trigger job should both be forced complete.
Solution
This solution uses an Alert to check the status of the data set trigger when job A completes. The dependencies look like this:
WAIT4DS
CHECK.STATUS
B
Take the following steps: 1. Set up an Application such that an Alert runs when job A ends. For example:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY RELEASE B NOTIFY JOBEND ALERT(CHCK) ENDJOB DSTRIG WAIT4DS DSNAME 'CYBER.THAT.DATASET' ANYCLOSE RUN ANY RELEASE B ENDJOB JOB B RUN ANY ENDJOB
ESP-5.5-EC-01
65
2. Set up an Alert that invokes the following ESP Procedure:

IF MNJOB EQ 'A' AND MNMXCMPC EQ 0 THEN DO REXXON J=JOBONCSF('WAIT4DS','X') DO I = 1 TO J IF XAPPL.I = 'CYBER' & XCOMPLETE.I = 0 THEN DO "ESP AJ B COMPLETE APPL(CYBER.%ESPAPGEN)" "ESP AJ WAIT4DS COMPLETE APPL(CYBER.%ESPAPGEN)" END END REXXOFF ENDDO
Explanation
The NOTIFY statement in the Application specifies that an Alert Event is triggered when job A ends. The Procedure invoked by this Alert Event uses the JOBONCSF function to check if the WAIT4DS job is complete. If WAIT4DS is not complete, then job A has completed first, and two AJ commands force jobs B and WAIT4DS complete. Otherwise, WAIT4DS has completed before job A, and job B will then run.
66
ESP-5.5-EC-01
Scheduling a job based on a data set, time, and weekdays

Objective
A job waits for a data set to be created. This data set is normally created once or twice per week. However, the job should only run between 22:30 and 23:30 on weekdays, regardless of when the data set is created. Also, the job should never run more than once per day. If the job has already run in the 22:30 to 23:30 time window, then the next instance of the job should wait until the same time period on the next weekday.
Solution
The solution involves the use of a resource to control when the job runs. 1. Define a renewable resource. In this example, the resource is called CYBERDSN. 2. Set up an Application that submits the job. Use WAIT on the APPL statement. Use RUN ANYDAY as the run frequency for the job as the Application should build regardless of when the data set is created. Assign 1 unit of the CYBERDSN resource to the job. Set up the job to release a link that sets the availability of the CYBERDSN resource to 0.
For example:
APPL CYBER WAIT JCLLIB 'CYBER.JCLLIB' JOB A RESOURCE (1,CYBERDSN) RUN ANYDAY RELEASE CYBERDSN.OFF ENDJOB JOB CYBERDSN.OFF LINK PROCESS RUN ANYDAY ESPNOMSG RESDEF CYBERDSN SET AVAIL(0) ENDJOB
3. Set up a data set-triggered Event to wait for the data set and invoke the Application. For example:
EVENT ID(PROD.CYBER) SYSTEM(ESPM) REPLACE INVOKE 'PROD.PROCLIB(CYBER)' DSTRIG CYBER.DATASET.GENDDEF
ESP-5.5-EC-01
67
4. Set up Events to turn on the resource (in other words, set the Avail count to 1) at 22:30 weekdays, and turn off the resource (in other words, set the Avail count to 0) at 23:30 weekdays. For example:
EVENT ID(PROD.CYBERDSN_ON) SYSTEM(ESPM) REPLACE SCHEDULE 22.30 WEEKDAYS VS 'F ESP,RESDEF CYBERDSN SET AVAIL(1)' ENDDEF EVENT ID(PROD.CYBERDSN_OFF) SYSTEM(ESPM) REPLACE SCHEDULE 23.30 WEEKDAYS VS 'F ESP,RESDEF CYBERDSN SET AVAIL(0)' ENDDEF
Explanation
Two Events and a link control the availability of the resource: At 22:30 on weekdays, an Event is scheduled that issues the RESDEF command to make the resource available. At 23:30 on weekdays, an Event is scheduled that issues the RESDEF command to make the resource unavailable. After the job completes successfully, a link issues the RESDEF command to make the resource unavailable.
This ensures the job only runs between 22:30 and 23:30 on weekdays. Also, once the job runs, the link sets the resource to 0. This ensures the job will run only once a day. If another generation of the Application has been created when one generation completes, then the job waits for the resource to be available the next weekday.
68
ESP-5.5-EC-01
Using the Application name in the script path

Objective
The path to a number of UNIX scripts needs to include the name of the Application in lowercase. For example: /export/home/payroll/batch, for the Payroll Application. /export/home/billing/batch, for the Billing Application.
Solution
Use the following code, either for the Application or for specific jobs within the Application. You can have different Applications invoke this code or imbed the code in your Application definition. The code converts the Application name to lower case using REXX.
REXXON APP = CLANGVAR('%ESPAPPL') APP=TRANSLATE(APP,'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ') "APPL='"APP"'" REXXOFF
For the location of the script, use %appl (or %APPL) in the path. For example:
APPL ABCD UNIX_JOB MYJOB AGENT AGENT SCRIPTNAME /export/home/jsmith/%appl/sleep60 RUN DAILY ENDJOB
Explanation
ESPAPPL is a built-in variable representing the Application name but it resolves to an uppercase name (for example, PAYROLL). While you can hardcode the Application name in lowercase, a generic routine that converts the name allows you to simplify maintenance should the name of the Application change. Or, if the name of the Application is dynamically generated, this solution converts that name. This solution uses the REXX TRANSLATE function to convert the value of the ESPAPPL variable to a lowercase variable. Each uppercase letter is mapped to the corresponding lowercase letter. The result is assigned to a REXX variable called APP, which is then assigned to an ESP Workload Manager variable called APPL. You can use the APPL variable in the path to your scripts.
ESP-5.5-EC-01
69
Identifying critical jobs for disaster recovery planning

Objective
In the case of a disaster, certain jobs in an Application must run while other jobs are deemed non-essential and should not be selected to run. As part of your disaster planning, you want to set up the Application in advance so that changes to it are not required in the event of a real, or planned, disaster.
Solution
Take the following steps: 1. Define a special day in your calendar. As there must be at least one entry in the calendar for this special day to avoid syntax errors on simulation, reference a date in the future. For example:
DEFSPEC DISASTER ON('MAY 16, 2040') CALENDAR(SYSTEM)
2. Use a NORUN DISASTER statement in the Application for all jobs deemed to be non-essential. For example:
JOB B RUN DAILY NORUN DISASTER RELEASE (C) ENDJOB
Explanation
Using this solution, you can identify which jobs should not run in the case of a disaster. In the event of a real disaster or a disaster test, another occurrence of the special day can be added with the appropriate date. When the Application builds, jobs with NORUN DISASTER will not be selected to run. You can simulate your Application for the DISASTER date to verify the correct selection of jobs.
70
ESP-5.5-EC-01
Using a one-time job section in Applications

Objective
One-time changes to an Application are made frequently. The objective is to separate these changes so that the job definitions are left intact and are easier to maintain.
Solution
The following Application shows a ONE_TIME_CHANGES section that you can use for temporary changes.
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY DELAYSUB 5PM RELEASE B ENDJOB JOB B RUN DAILY RELEASE C ENDJOB /* USE THIS SECTION FOR ONE-TIME CHANGES ONE_TIME_CHANGES: JOB A IF TODAY('APR 23, 2004') THEN DELAYSUB 7PM ENDJOB
Explanation
You can use the same JOB statement in an Application. When the Application builds, the Job statements for the same job are merged together in the order in which they are read. The Procedure in this solution shows a ONE_TIME_CHANGES section that allows you to override requirements temporarily. This section could be in the same Application or it could be invoked as a separate PDS member after invoking the Application.
ESP-5.5-EC-01
71
In this example, job A has a DELAYSUB time of 7PM on April 23, 2004. This overrides its normal DELAYSUB time of 5PM on that day only.
JOB A RUN DAILY DELAYSUB 5PM RELEASE B ENDJOB ... JOB A IF TODAY('APR 23, 2004') THEN DELAYSUB 7PM ENDJOB
JOB A RUN DAILY DELAYSUB 5PM RELEASE B IF TODAY('APR 23, 2004') THEN DELAYSUB 7PM ENDJOB
72
ESP-5.5-EC-01
Using the same Application for different locations

Objective
Use the same Application to process work for different processing locations, even where there are different job requirements for each location.
Solution
The following is a common Application that can be used for different processing locations:
IF IF IF IF '%ESPEVENT(9:12)' '%ESPEVENT(9:12)' '%ESPEVENT(9:12)' '%ESPEVENT(9:12)' = = = = 'DALL' 'CHIC' 'TORO' 'SAND' THEN THEN THEN THEN DC DC DC DC = = = = 'DA' 'CH' 'TO' 'SD'
APPL CYBER%DC JCLLIB 'CYBER.JCLLIB' JOB RG%DC.A EARLYSUB 8PM RUN DAILY RELEASE (RG%DC.B) ENDJOB JOB RG%DC.B RUN DAILY RELEASE (NEW%DC.A) ENDJOB UNIX_JOB NEW%DC.A AGENT CYBER%DC SCRIPTNAME /export/home/demo/scripts/xyz RELEASE (NEW%DC.B) IF DC = 'CH' THEN RUN DAILY ENDJOB . . .
ESP-5.5-EC-01
73
Explanation
Different Events for the different locations invoke the same generic Procedure. The Events use a naming standard that identifies the location associated with them. A user-defined symbolic variable named DC is defined to represent the location, and it uses a substring of the built-in variable for the Event name. The DC variable is used in the Application in many different ways. Some examples are shown below: Part of the Application name: CYBER%DC Part of the Agent name: CYBER%DC Part of the jobnames: RG%DC.A
The following diagram shows how a jobname is resolved based on the Event name:
You can also use IF logic to handle different requirements for different locations. For example, job NEW%DC.A runs only if DC='CH'. Variation This example could be extended further by using the DC variable in the JCL, UNIX scripts, NT batch files, and so on. For example, you can use a MEMBER statement to point to a common JCL member such as the following:
//RG%DC.A //STEP1 //SYSPRINT //SYSUT1 // // JOB CYB1000,'GENERIC JOB',MSGCLASS=Z,CLASS=B EXEC PGM=IEFBR14 DD SYSOUT=* DD DSN=RG%DC.100.ESPTST.DATA, DISP=(NEW,CATLG,DELETE), UNIT=SYSDA,SPACE=(TRK,1)
74
ESP-5.5-EC-01
Merging Applications into a single PDS member

Objective
Merge ad hoc Applications into a single PDS member in situations where small Applications are requested periodically.
Solution
Take the following steps: 1. The following ESP Procedure shows a technique to merge Applications into a single PDS member:
IF %USER1 = '' THEN EXIT JUMPTO %USER1 PAYREQ: APPL PAYREQ JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY RELEASE B ENDJOB JOB B RUN ANY ENDJOB EXIT FINREQ: APPL FINREQ JCLLIB 'CYBER.JCLLIB' JOB X RUN ANY ENDJOB EXIT
2. Set up an Event to invoke this Procedure. 3. You can manually trigger this Event and pass the name of the Application you want to run using the USER1 parameter.
ESP-5.5-EC-01
75
Explanation
This solution uses labels in the Application with the same names as the ad hoc Applications. The JUMPTO statement, with the USER1 parameter, causes the Application you specify to be generated. For example, if you trigger the Event and specify FINREQ as the USER1 parameter, then only the FINREQ Application is built.
Note: It
is important to code the EXIT statement between Application definitions, otherwise multiple Applications could be generated when triggering the Event. This allows you to put many of your requested Applications in one PDS member, instead of having numerous Events and PDS members.
76
ESP-5.5-EC-01
Consolidating data set triggers to minimize the number of Event definitions

Objective
There are many data set triggers that can cause a job to be submitted. Some of these data sets are GDG-based. When one of these data sets closes, a job should run. This job is always the same and the only thing that should change is the data set name in the JCL.
Solution
Take the following steps: 1. Set up the data set-triggered Event. This Event waits for the closure of any one of three different data sets:
EVENT ID(PROD.CYBER) DSTRIG CYBER.PROD.SERVICES.CLASS1.G- ANYCLOSE DSTRIG CYBER.PROD.SERVICES.CLASS2.G- ANYCLOSE DSTRIG CYBER.PROD.SERVICES.CLASS3.G- ANYCLOSE INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF
2. Use the following job definition to extract either the GDG base for GDG data sets, or the full data set name for non-GDGs, and submit the job:
JOB A RUN ANY INTEGER SIZE ID=0 DSN=ESPTRDSN SIZE=LENGTH(%DSN) V00=SUBSTR(%SIZE-2,3,%DSN) GDG=SUBSTR(%SIZE-7,1,%DSN) IF V00='V00' AND GDG='G' THEN CHECK=SUBSTR(1,%SIZE-9,%DSN) ELSE CHECK=%DSN IF %CHECK= 'CYBER.PROD.SERVICES.CLASS1' THEN ID=1 IF %CHECK= 'CYBER.PROD.SERVICES.CLASS2' THEN ID=2 IF %CHECK= 'CYBER.PROD.SERVICES.CLASS3' THEN ID=3 ENDJOB
3. Tailor the JCL using %INCLUDE statements:

//A JOB %INCLUDE IF(ID=1) //STEP1 DD DSN=CYBER.PROD.SERVICES.CLASS1(0) %INCLUDE IF(ID=2) //STEP2 DD DSN=CYBER.PROD.SERVICES.CLASS2(0) %INCLUDE IF(ID=3) //STEP3 DD DSN=CYBER.PROD.SERVICES.CLASS3(0) %ENDINCL
ESP-5.5-EC-01
77
Explanation
All of the data set triggers are coded in one Event, minimizing the number of individual Event definitions required. The code determines the length of the data set name, checks if the data set name is a GDG, and parses it into the GDG base and the generation number. %INCLUDE statements are coded in the JCL to tailor which data set is included for each run of the job.
Note: Although
the names of the data sets are the same length in this example, this code can be used regardless of the length of the data set name.
78
ESP-5.5-EC-01
Resubmitting a job 5 minutes after it fails

Objective
If a particular job fails, it should be resubmitted from the top after a 5-minute delay.
Solution
Take the following steps: 1. When you define the job, use a NOTIFY statement that identifies the Alert to be triggered if the job fails. For example:
JOB A NOTIFY FAILURE ALERT(BAD) RUN ANYDAY ENDJOB
2. Define the Alert using the ALERTDEF command or initialization parameter. For example:
OPER ALERTDEF ID(BAD) EVENT(CYBER.RESUB_JOB)
3. Set up the Alert Procedure and Event. The Alert Event invokes the following Procedure:
IF ESPREEXEC#=0 THEN DO SEND '%MNJOB HAS FAILED WITH %MNCMPC' U(*) SEND 'AUTOMATIC RESUBMISSION IN 5 MINUTES' U(*) REEXEC IN(5) ENDDO ELSE ESP AJ %MNJOB RESUB APPL(%MNAPPL..%MNAPPLGEN)
Explanation
When the Alert Procedure is invoked, the ESPREEXEC# variable is 0. Two SEND messages are sent to the user. The Procedure is then scheduled to re-execute 5 minutes later. At that time, ESPREEXEC# is 1, and an AJ command resubmits the failed job. Monitor variables are used to ensure the job is resubmitted in the correct generation (MNAPPLGEN) of the correct Application (MNAPPL). Variation Another approach is to have the Alert Procedure build a one-job Application that contains a link with a DELAYSUB time of NOW PLUS 5 MINUTES. The link can issue the ESP AJ command to resubmit the failed job when the DELAYSUB time is met.
ESP-5.5-EC-01
79
Resubmitting a failed job a maximum of two times

Objective
If job A fails, it can be resubmitted up to a maximum of two times. If the job is still not successful, then it should be considered complete.
Solution
This solution uses ESP Workload Managers job monitoring facility for the job and a task within the Application to check the job status after two re-submissions. 1. Set up an Application similar to that shown below:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY MONITOR CYBER RELEASE CHECK.A IF ESPAPSUB# GT 2 THEN DO ESP AJ CHECK.A READY APPL(CYBER.%ESPAPGEN) QUIT ENDDO ENDJOB JOB CHECK.A TASK SELFCOMPLETING RUN ANY REXXON PROC J=JOBONCSF('A','X') DO I=1 TO J IF XAPPL.I ='CYBER' & XSTATUS.I ='Submit Error, Quit' THEN "ESP AJ A COMPLETE APPL(CYBER.%ESPAPGEN)" END REXXOFF ENDJOB
2. Set up a JOBEND job monitor Event for job A that invokes the following Procedure:
IF MNRC NE 0 THEN ESP AJ %MNJOB RESUBMIT APPL(%MNAPPL..%MNAPPLGEN)
80
ESP-5.5-EC-01
Explanation
A job monitor Event is triggered when the job ends. This Event invokes a Procedure to check the return code. If the return code is not equal to 0, the Procedure issues an AJ command to resubmit the job. IF logic within the definition for the job checks the resubmission number (ESPAPSUB#). If job A has been submitted three times, the CHECK.A task is readied and a QUIT statement is processed. This causes the third submission of the job to get a submit error. When the CHECK.A task is readied, the JOBONCSF built-in function checks if the job status is Submit Error, Quit. If so, the job is forced complete and the task completes.
ESP-5.5-EC-01
81
Providing notification when a job exceeds its maximum run time

Objective
Send a message if a job exceeds its maximum run time.
Solution
Use a MAXRUNTIME statement and a NOTIFY statement for the job. For example:
APPL CYBER UNIX_JOB A RUN DAILY MAXRUNTIME=5 NOTIFY OVERDUE USERS(USER01) AGENT AGENT SCRIPTNAME /u1/prod/scripts/a ENDJOB
Explanation
The MAXRUNTIME statement sets the maximum run time for job A to 5 minutes. When the job starts, ESP Workload Manager adds 5 minutes to the current time and sets the late end time for the job. If the job does not complete successfully by this time, it becomes overdue, and a message is sent to USER01.
82
ESP-5.5-EC-01
Providing notification for a long-running Application

Objective
A long-running Application is scheduled to run at 8 AM each day. If the Application is not complete by 8 AM the next day, then issue a warning message to indicate the Application is still processing.
Solution
Take the following steps: 1. In the Application, use a link with a DELAYSUB time of 8AM TOMORROW. The link has no job dependencies. 2. Use a SEND command to send a message when the link becomes ready. 3. Define the link as a conditional job, as it may or may not run. For example:
JOB STILL.RUNNING LINK PROCESS CONDITIONAL RUN DAILY DELAYSUB 8AM TOMORROW SEND '%ESPAPPL IS STILL RUNNING' U(*) ENDJOB
Explanation
The link, which has no dependencies other than time, issues a message at 8 AM the next day if the Application is still processing. There are two possible results: If all other jobs in the Application are complete prior to 8 AM the next day, the link is bypassed (since it is a conditional job), and the Application completes. Otherwise, if jobs are still processing at 8 AM the next day, a message is sent at that time.
ESP-5.5-EC-01
83
Providing notification if a job is late starting relative to a data set closure

Objective
Provide notification if a job has not started 10 minutes after being invoked as a result of a data set trigger.
Solution
Take the following steps: 1. Use a DUEOUT INPUT statement and a NOTIFY statement in the Application that contains the job, as shown below:
APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY DUEOUT INPUT REALNOW PLUS 10 MINUTES NOTIFY OVERDUE USERS(USER1) ENDJOB
2. Use a data set-triggered Event that invokes the Application.

EVENT ID(PROD.CYBER) INVOKE 'PROD.PROCLIB(CYBER)' DSTRIG CYBER.PROD.DSN123 ANYCLOSE ENDDEF
Explanation
The DUEOUT INPUT statement indicates the job is due out from the JES input queue (in other words, the job has started) 10 minutes after the data set is closed. The NOTIFY statement causes a message to be sent to a user if the job becomes overdue.
84
ESP-5.5-EC-01
Sending email notification for job failures

Objective
Automatically send an email if any job within Application CYBER fails.
Solution
Take the following steps: 1. Set up a MAILLIST data set that contains the SMTPPARM parameter and one or more MAILBOX parameters. The following example specifies a MAILBOX called OPER that contains one email address.
SMTPPARM CLASS(A) JOBNAME(SMTP) MAILBOX OPER MAXLINES(50) EMAIL jsmith@ca.com
2. In your Application, use the MAILBOX parameter on the NOTIFY statement, as shown below:
APPL CYBER JCLLIB 'CYBER.JCLLIB' NOTIFY FAILURE MAILBOX(OPER) JOB A RUN DAILY ENDJOB
Explanation
The NOTIFY statement specifies that a mailbox called OPER is used if any job within the Application fails. This mailbox is defined in ESP Workload Managers initialization parameters and contains an email address to notify. For more information on implementing mailboxes in your environment, see the ESP Workload Manager Installation and Configuration Guide.
ESP-5.5-EC-01
85
Variation Alternatively, ESP Workload Manager can submit a batch job from an Alert or job monitor Event. The following is some sample JCL you can use:
//SENDMAIL JOB //STEP1 EXEC PGM=IEBGENER //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT2 DD SYSOUT=(B,SMTP) //SYSUT1 DD * HELO ESP MAIL FROM: <ESP53@LOCALHOST> RCPT TO: <JDOE@CA.COM> DATA FROM: ESP TO: JDOE@CA.COM SUBJECT: JOB FAILURE NOTIFICATION JOB %MNJOB IN APPLICATION %MNAPPL FAILED @ %ESPATIME WITH A COMPLETION CODE OF %MNMXRC. . QUIT /*
JCL is coded to send an email via SMTP. Job monitor variables and built-in variables are passed to the JCL. These variables are resolved when the email is sent informing the recipient with the name of the job that failed, the Application to which the job belongs, the time of the failure, and the maximum return code.
86
ESP-5.5-EC-01
Sending a message when an Agent becomes inactive

Objective
If a particular Agent becomes inactive, send a message to alert a user that the Agent is inactive.
Solution
Take the following steps: 1. In an Application, define an AGENT_MONITOR workload object. Use the AMNOTIFY statement to trigger an Alert when the Agent becomes inactive. For example:
APPL AGENTMON AGENT_MONITOR CYBUSER.WINR6SP2 AGENT WINR6SP2 AMNOTIFY EVENT(CYBUSER.AGENT_INACTIVE) STATINTV 5 MSGQLEN 10 ENDJOB
2. Define the Event to send a message to a user. For example:

EVENT ID(CYBUSER.AGENT_INACTIVE) ADD SEND 'AGENT INACTIVE' USER(CYBUSER) ENDDEF
Explanation
When the WINR6SP2 Agent becomes inactive, ESP Workload Manager triggers an Event, CYBUSER.AGENT_INACTIVE, which sends a message to a user. The status checks occur every five minutes. The CYBUSER.WINR6SP2 workload object stores the last 10 status messages as defined by the MSGQLEN statement.
ESP-5.5-EC-01
87
Displaying job details from CSF

Objective
The LA line command in CSF displays information about all jobs in an Application. The objective of this example is to issue a CSF command similar to LA, but to limit the display of information to a particular job.
Solution
The following CSF Extension builds, then issues, the appropriate command.
/* REXX */ CMD = "LAP " APPL() "JOB("JOB()")" X = PAGEMODE(CMD)
Explanation
The CSF extension facility allows you to add or replace CSF line commands for your installation. To limit the display of information to a particular job, the solution issues an LAP (or LISTAPPL) command with the JOB keyword. The APPL() function resolves to the full qualified name of the Application, and the JOB() function resolves to the name of the current job. If the extension is invoked using a command called LAJ, for example, then entering LAJ next to a job in CSF will display information about that job, such as its predecessors, successors, time dependencies, and other requirements. To implement this extension you will need to code it in a REXX library, update the CYBESCSU member, and run the CYBESTBG exec (supplied by CA) to generate an ISPF table. For more information on implementing CSF extensions in your environment, see the ESP Workload Manager Installation and Configuration Guide.
88
ESP-5.5-EC-01
Bypassing a job across multiple Applications

Objective
When bypassing a job from CSF, the job should be bypassed across all active Applications the job belongs to if the job is not complete.
Solution
Use the following CSF extension:
/* REXX */ N=JOBONCSF(''JOBNAME()'','X') DO I=1 TO N IF XQUAL.I = JOBQUAL() & XCOMPLETE.I='0' THEN DO APPLNAME=STRIP(XAPPL.I) || '.' || XAPPLG.I "AJ "JOB() "BYPASS APPL("APPLNAME")" END END
Explanation
The CSF extension facility allows you to add or replace CSF line commands for your installation. For this CSF extension, if you add a new command called BYA, then issuing BYA against a job in CSF does the following: Uses the JOBONCSF built-in function to return information about all instances of the job that are found on the CSF. For each instance of the job, the code checks if the job qualifier matches and the job is not complete. If so, the code extracts the Application name and generation number, and then issues an AJ command to bypass that instance of the job.
To implement this extension you will need to code it in a REXX library, update the CYBESCSU member, and run the CYBESTBG exec (supplied by CA) to generate an ISPF table. For more information on implementing CSF extensions in your environment, see the ESP Workload Manager Installation and Configuration Guide.
ESP-5.5-EC-01
89
Holding all incomplete generations of an Application

Objective
Multiple generations of an Application can process at the same time. When problems arise, it is sometimes necessary to hold all incomplete generations at the same time.
Solution
/* REXX */ X = OUTTRAP("line.") "LAP" Applname() X = OUTTRAP("OFF") j= line.0 DO i = 1 TO j IF line.i = "" THEN ITERATE PARSE UPPER VAR line.i verb therest IF verb = "APPL" THEN DO PARSE VAR therest . . applgen . Applgen = STRIP(applgen) QUEUE "AJ ALL HOLD APPL("|| Applname() ||"."|| Applgen || ")" END END J = QUEUED() DO I = 1 TO J PULL X SAY "ISSUING: " X X END
Explanation
The CSF extension facility allows you to add or replace CSF line commands for your installation. For this CSF extension, if you add a new command called HAA, then issuing HAA against a job in CSF does the following: Retrieves the Application name to which the job belongs. Lists all incomplete generations of the Application. Issues a HOLD command for each of those generations.
90
ESP-5.5-EC-01
Listing a job plus its successor chains in an active Application

Objective
When monitoring jobs using the Consolidated Status Facility (CSF), it would be useful to see the impact a job has on downstream jobs when the job fails or is late.
Solution
/* REXX */ /* Command Name: LAS */ /* CSF extension to list all successor jobs to current job */ X = Retscbd() /* Issue a SIMULATE command, trapping the output.Use the ROOT */ /* keyword to generate a list of current job plus successors */ X = Outtrap(LINE.) "SIMULATE EV("Event()") SCHED('"Sched"') ROOTJOB("Job()"+), NOLISTPROC" X = Outtrap("OFF") Do i = 1 to Line.0 if pos('JOB TYPE',Line.i) > 0 then leave End say "The following is a display of job" job(), "and its successors:" say "" Do j = i to Line.0 Say Line.j End
Explanation
The CSF extension facility allows you to add or replace CSF line commands for your installation. This CSF extension allows you to issue a command against a job, and the result is a display of that job plus all successor jobs for that particular generation of the Application. The CSF extension issues a SIMULATE command for that instance of the Event and passes the jobname as a root job.
Note: This
display does not include jobs inserted after the Application was built.
ESP-5.5-EC-01
91
For example, if you type this new command beside job B, ESP Workload Manager simulates the Event with a root job of B+ and displays the output. Here is some sample output: The following is a display of job B and its successors:
JOB TYPE-JOBNAME--HC-RELEASES, JOB B 0 E, X, C, JOB E 1 F, JOB F 1 (NONE), JOB X 1 Y, JOB Y 1 (NONE), JOB C 1 D, JOB D 1 (NONE), ***
92
ESP-5.5-EC-01
Creating a variable for the day of week number

Objective
Jobs in an Application use a one-digit day-of-week number that begins with 1 on Wednesday and ends with 7 on Tuesday.
Solution
Use the DAYS_FROM built-in function to define a variable that calculates the number of days from last Tuesday until today. For example, you can use the following code:
DAYNUM=DAYS_FROM('TUESDAY LESS 1 WEEK')
You can then use the variable %DAYNUM in JCL or pass it as an argument to distributed jobs.
Explanation
Although ESP Workload Manager has day-of-week number variables (for example, ESPSDOW#), they represent the number for the day of the week as follows: 1 for Sunday, 2 for Monday, and so on. This is independent of calendar settings. This solution defines a variable, DAYNUM, that represents the number of days since the previous Tuesday. This number corresponds to the day of the week when the week starts on Wednesday. For example:
Day DAYNUM
Wednesday Thursday Friday Saturday Sunday Monday Tuesday
1 2 3 4 5 6 7
ESP-5.5-EC-01
93
Creating a variable for the accounting year

Objective
Create a symbolic variable for the accounting year, to be used whenever you need to reference the current accounting year. For example, from October 4, 2003 until October 1, 2004, inclusively, the accounting year symbolic variable should have the value 2004.
Solution
GENTIME AC LAST DAY OF ACCT_YEAR
Explanation
In this example, there are a number of special days called ACCT_YEAR. The accounting year is the period between two ACCT_YEAR special days. Each accounting year starts near the beginning of October. For example, the accounting year for the year 2004 begins on October 4, 2003. The accounting year for the year 2005 begins on October 2, 2004. At any point in the year, you need ESP Workload Manager to determine which accounting year you are in. For example, from October 4, 2003 until October 1, 2004 (inclusively) you want an accounting year variable to have the value 2004. The simplest way to determine this is to use GENTIME to generate date and time variables for the last day of the accounting year. This will always give you the actual accounting year no matter what the date is in the actual year. You can then use the %ACYEAR variable, from the GENTIME, as you choose.
94
ESP-5.5-EC-01
Calculating the week number

Objective
Many jobs require the week number. The week numbers start from 1 in one calendar year and carry over into the next year. For example, this may be based on a fiscal year that starts 9 days after the 1st Sunday of the year.
Solution
One solution is to define a special day that represents the start of each fiscal year. In this example, the criteria is the same each year, and you can use the DEFSPEC command to define many instances at once. The following command defines 11 instances of FISCAL_YEAR in the SYSTEM calendar, with each instance being retained for 2 years.
DEFSPEC FISCAL_YEAR REPEAT('10 TIMES 1ST SUNDAY OF YEAR PLUS 9 DAYS STARTING TODAY') CALENDAR(SYSTEM) RETAIN(2,YEARS)
To calculate the week number, use the following code:

/* USING FISCAL_YEAR SPECIAL DAY WK=DAYS_BETWEEN('1ST DAY OF FISCAL_YEAR STA TODAY','TOMORROW','TUESDAY');
Explanation
Each FISCAL_YEAR starts on a Tuesday (for example, 9 days after the 1st Sunday of the year).The solution uses the DAYS_BETWEEN function to calculate the number of instances of Tuesday between the first day of the fiscal year (inclusive) and tomorrow (exclusive). The result is the week number, and it is assigned to a variable called WK. Variation Without defining a special day to represent the beginning of each fiscal year, you can use the following code to calculate the week number.
INTEGER STYEAR,XX,N GENTIME LY TODAY LESS 1 YEAR GENTIME FY FIRST SUNDAY OF YEAR PLUS 9 DAYS STARTING TODAY N=DAYS_TO('%FYDATE') IF N>0 THEN STYEAR=LYYEAR ELSE STYEAR=ESPSYEAR GENTIME W FIRST SUNDAY OF YEAR PLUS 9 DAYS STARTING JAN 1 %STYEAR WK=DAYS_BETWEEN('%WDATE','TOMORROW','TUESDAY')
The code determines on which year to base the calculation. If the number of days to the first Sunday of the year plus 9 days is positive, then the current fiscal year started
ESP-5.5-EC-01
95
in the previous calendar year. Otherwise, the current fiscal year started this year. GENTIME generates date and time variables for the 1st day of the fiscal year. The DAYS_BETWEEN function is then used as in the first solution.
96
ESP-5.5-EC-01
Providing a variable for all data sets in a DSTRIG Event

Objective
In a data set-triggered Event where multiple data sets are required, the ESPTRDSN symbolic variable resolves only to the last PRIMED data set. Some jobs require the names of all of the data sets that caused a data set-triggered Event to occur.
Solution
This solution uses a global variable table to store the names of the data sets. An example using two data sets and a global variable table called MYTAB is shown below. For example, suppose you have the following data set-triggered Event that waits for all of the required data sets (as indicated by the MULTIPLE keyword), and invokes a Procedure called MAIN.
EVENT ID(PROD.MAIN) INVOKE 'PROD.PROCLIB(MAIN)' DSTRIG 'PROD.FILE1.G-' MULTIPLE DSTRIG 'PROD.FILE2.G-' MULTIPLE ENDDEF
Take the following steps: 1. Define a global variable table. This example uses a table called MYTAB. For example:
VTDEFINE MYTAB
2. Define a data set-triggered Event for each required data set. Each Event invokes a Procedure that issues a VSET command to update the global variable table with the name of the data set that causes the trigger to occur. For example: Event
EVENT ID(PROD.DSN1) INVOKE 'PROD.PROCLIB(DSN1)' DSTRIG 'PROD.FILE1.G-' ENDDEF
Procedure
VSET DSN1 %ESPTRDSN TABLE(MYTAB)
Event
EVENT ID(PROD.DSN2) INVOKE 'PROD.PROCLIB(DSN2)' DSTRIG 'PROD.FILE2.G-' ENDDEF
ESP-5.5-EC-01
97
Procedure
VSET DSN2 %ESPTRDSN TABLE(MYTAB)
3. Update the MAIN Procedure to retrieve all of the data set names, as shown below.
DSN1 = '' DSN2 = '' N = '1' IF SUBSTR(10,1,%ESPTRDSN) = '1' THEN N = '2' ESPTRD = 'DSN%N' VGET %ESPTRD TABLE(MYTAB)
Explanation
Instead of having only the last data set value available, this solution makes all of the data set names available in a global variable table. The names can then be retrieved from the table as needed. A separate data set-triggered Event is coded for each required data set. These Events invoke Procedures that simply issue the VSET command to update the global variable table with the value of the data set that triggered the Event (in other words, the ESPTRDSN built-in symbolic variable). In the main data set-triggered Event, CYBER.MAIN, coding MULTIPLE on each DSTRIG command indicates that this Event is not triggered until both data sets have been created. Once triggered, it invokes a Procedure that gets both data set names from the global variable table using the following process: 1. The SUBSTR function determines if the last received data set is DSN1 or DSN2. If it is DSN1, then: The ESPTRD variable is assigned the value DSN2. A VGET command is issued to retrieve the full data set name of DSN2. ESPTRD now contains the value of DSN2 (the first received data set), while ESPTRDSN contains the value of DSN1 (the second received data set). The ESPTRD variable is assigned the value DSN1. A VGET command is issued to retrieve the full data set name of DSN1. ESPTRD now contains the value of DSN1 (the first received data set), while ESPTRDSN contains the value of DSN2 (the second received data set).
2. Otherwise, if the last received data set is DSN2, then:
98
ESP-5.5-EC-01
Running jobs using ESP Encores SCAN mode

Objective
Run a series of jobs in an Application and use ESP Encores SCAN mode to determine if any jobs within the Application have JCL errors.
Solution
In your Application, you can include statements to invoke Encore in SCAN mode and then provide notification of any problems. 1. Use the following statements in your Application: OPTIONS RESTARTSTEP to add a restart step to the jobs. ENCPARM MODE SCAN to run Encore in SCAN mode. NOTIFY FAILURE ALERT(alert_id) to trigger an Alert Event for job failures.
For example:
APPL CYBER JCLLIB 'CYBER.JCLLIB' OPTIONS RESTARTSTEP ENCPARM MODE SCAN NOTIFY FAILURE ALERT(SCAN) JOB A RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY ENDJOB
2. Set up an Alert to invoke the following ESP Procedure:

IF %MNHIRC = 0 THEN ESP AJ %MNJOB..%MNQUAL COMPLETE APPL(%MNAPPL..%MNAPPLGEN) ELSE SEND 'REVIEW SYSOUT FOR JOB %MNJOB.(%MNJOBNO)' U(*)
Explanation
This solution uses ESP Encore to scan the JCL for each job. Only the Encore step in the job runs, and the remainder of the job is flushed. The NOTIFY statement specifies that an Alert Event is triggered when any job within the Application fails. The Procedure invoked by the Alert Event checks the highest return code and issues an AJ command to complete the job if the return code is zero, or sends a message prompting the user to check the ESP Encore report in the jobs SYSOUT.
ESP-5.5-EC-01
99
Setting COPYJCL as the default JCL library for resubmission

Objective
Set COPYJCL as the default JCL library for job resubmission.
Solution
As long as you are storing your COPYJCL library by jobname rather than by job number, you can use the following code before your JOB statements in an Application.
IF ESPAPSUB# > 1 THEN TEMPLIB 'CYBER.ESP.COPYJCL'
Explanation
When a job is submitted, the submission number (ESPAPSUB# variable) is checked. If the submission number is greater than 1, the TEMPLIB statement points to the COPYJCL library, and ESP Workload Manager uses JCL from this library for job resubmission.
Note: You
can override this library, as required, when you resubmit the job (for example, on the Job Resubmission panel).
100
ESP-5.5-EC-01
Using date-qualified TEMPLIBs

Objective
An Application uses date-qualified TEMPLIBs to stage temporary JCL changes. For example: PROD.TEMPLIB.D%ESPSMM%ESPSDD%ESPSYY. TEMPLIBs are created 7 days in advance. Currently, a simulation or a forecast ABENDs if the date is beyond that which has been created for the TEMPLIB. Create a Procedure to avoid this problem.
Solution
Use the following IF statement in your Application:
IF DAYS_FROM('%ESPADATE') LE 7 THEN TEMPLIB 'PROD.TEMPLIB.D%ESPSMM%ESPSDD%ESPSYY'
Explanation
If the difference between the simulation date and the actual date is less than 7 days, then the TEMPLIB is read in. Otherwise, it is not. This allows you to simulate the Application for any future date even though the TEMPLIB data set may not yet be created.
ESP-5.5-EC-01
101
102
ESP-5.5-EC-01
Index
Symbols
%INCLUDE statements, 77 completing a task, 29, 48, 64 completing an Application, 53 holding an Application, 90 inserting a job, 27 requesting a job, 64 resubmitting a job, 79, 81 Alert Encores SCAN mode, 99 job resubmission, 79 sending message, 87 APPLEND workload object, 58 Application name built-in variable, 27, 29, 53, 69, 83 in script path, 69 variable, 69, 73 Application status, 83 after 24 hours, 83 LAP command, 56 Applications based on input file, 62 common, 73 holding all generations, 90 hourly, 21, 24 merging, 75 APPLINS command, 29
Numerics
1st day of month, 10 2nd last workday of week, 36 5 Fridays in month, 3
A
accounting year, 94 ad hoc Applications, 75 jobs, 27, 32, 62 adding Event schedule, 37, 58 adjusting for holidays, 2, 13, 17, 18 advancing schedule, 38, 39 Agent name, as a variable, 73 Agent, sending message when inactive, 87 AGENT_MONITOR workload object, 87 AJ command bypassing a job, 48, 51, 89 completing a job, 66, 99
ESP-5.5-EC-01
103
argument, passing to script, 59 automatic bypass, 49, 54, 83 Event trigger, 55, 61 resubmission of job, 79
B
batch job, to send email, 86 between dates, 6 times, 30 bi-weekly job, 17, 18 built-in functions DAYS_BETWEEN, 95 DAYS_FROM, 6 DAYS_TO, 4, 6 JOBONCSF, 48, 89, 90 TODAY, 7 built-in variables ESPAPGEN, 27, 29, 48, 53, 64, 66, 80 ESPAPJOB, 25 ESPAPPL, 27, 29, 53, 69, 83 ESPAPSUB#, 100 ESPEVENT, 36, 55 ESPREEXEC#, 40, 79 ESPSDOW#, 93 ESPSHH, 24, 26 ESPTRDSN, 97 monitor, 79 return code, 35, 54 scheduled hour, 24 USER1, 27, 32, 61, 75 bypassing conditional job, 83 job across Applications, 89 job based on another jobs status, 48 job based on return code, 54 non-critical jobs, 49
self-completing, 27, 48, 64, 81 with link, 29 concatenating variables, 43 conditional jobs, 47, 83 conditional release expressions, 53, 54 consolidating Applications, 75 data set triggers, 77 converting numbers and strings, 61 to lowercase, 69 copying file, 45 COPYJCL library, 100 CSF extension bypassing jobs, 89 holding all generations of an Application, 90 listing job details, 88 listing successors, 91 current period, 94 cycle number, 59 cyclic Application, 57
D
data set dependency, 59 data set-trigger built-in variable, 97 Event, 77, 97 job, 65 date range, 6 date-qualified file name, 43 TEMPLIB, 101 day of week number, 93 DAYS_BETWEEN function, 95 DAYS_FROM function, 6, 93 DAYS_TO function, 4, 6 default library, job resubmission, 100 defining Alert, 49, 79 global variable table, 97 special day, 95 delaying job based on holidays, 13 based on workday status, 9 random number of days, 20 relative delay, 40, 58 resubmission, 79 submit time, 40
C
calendar quarter, 19 cmd.exe, 45 common Applications, 73 JCL member, 25, 74 comparing GENTIME dates, 9, 13, 14, 15 completing a task
104
ESP-5.5-EC-01
Index
until next hour, 40 different actions, based on return code, 52 different jobs calendar quarter, 19 each generation, 27 each hour, 24 disaster recovery, 70 displaying job details from CSF, 88 successor jobs, 91 DUEOUT statement, 84 dynamically generated Applications, 62
5 minutes, 56 EVERY run criteria, 16, 17, 18 except criteria, 2 existing file, 46 EXIT statement, 76 external job, 41
F
failed job automatic resubmission, 80 Encores SCAN mode, 99 file trigger, 47 notification, 85 file dependency, 43, 44, 45, 46 file name built-in variable, 44 changing, 44 date-qualified, 43 file trigger object, 43, 44, 45, 46 fiscal year, 95 five Fridays in month, 3 future schedule, 38, 39
E
early run of Application, 38, 39 email batch job, 86 notification, 85 ESP Encore, 99 ESPAPGEN variable, 27, 29, 48, 53, 64, 66, 80 ESPAPJOB variable, 25 ESPAPPL variable, 27, 29, 53, 69, 83 ESPAPSUB# variable, 100 ESPEVENT variable, 36, 55 ESPFTFILE variable, 44 ESPNOMSG command, 28 ESPREEXEC# variable, 40 ESPS* variables, 43 ESPSDOW# variable, 93 ESPSHH variable, 24, 26 ESPTRDSN variable, 97 Event data set-triggered, 77, 97 defined from Procedure, 35 retrigger, 37, 55, 58, 61 sending message to user, 87 trigger, 38, 39 trigger, with USER1 parameter, 27 Event name built-in variable, 36, 55 standard, 74 substring, 74 every 10 minutes, 30 2 days, 16 2 hours, 29 2 weeks, 17, 18 30 minutes, 27
G
GDG-based data sets, 77 generation number, built-in variable, 27, 29, 48, 53, 64, 66, 80 generic Application, 73 GENTIME command 5th last workday of month, 11 comparing dates, 9, 13, 14, 15 day of week, 10 previous date/criteria, 15 global variable table, 97
H
held job, 55 holding, all generations of an Application, 90 holiday scheduling, 2, 4, 5, 13 holiday status, 15 hourly Application, 21 Event, 26 job, 22 jobs, 24
ESP-5.5-EC-01
105
I
IFHOLIDAYPLUS run criteria, 13, 18 impact on successor jobs, 91 incrementing cycle number, 59 input file, 62 inserting ad hoc job, 27 UNIX job, 29
increasing cycle number, 59 overdue time, 49 retrigger Event, 53, 59 setting resource, 67 submit time, 83 listing successor jobs, 91 long-running Application, 83 lowercase, 69
J
JCL common member, 25, 74 email notification, 86 JCL errors, 99 JCL library, for job resubmission, 100 JCL tailoring, 77 job definitions, merging, 71 job monitor Event, 35, 81 job resubmission, 79, 80, 100 job selection replaced schedule, 38, 39 simulating, 70 job status using JOBONCSF, 48, 89 when QUIT encountered, 81 JOBEND Event, 35, 81 jobname based on hour, 24 built-in variable, 25 variable, 73 JOBONCSF function, 48, 89, 90
M
MAILBOX parameter, 85 maintaining job definitions, 71 maximum run time, 82 MAXRUNTIME statement, 82 MEMBER statement, 25, 74 merging Application definitions, 75 job definitions, 71 MNRC variable, 35, 54 Mondays except holidays, 2 monitor variables, 79 monthly job, 10 multiple data sets, 97 multiple runs of a job, 30
N
non-critical jobs, 49, 70 non-existent file, 47 NORUN criteria, 2, 5, 70 notification failed job, 85 long-running Application, 83 overdue job, 82 NOTIFY statement, 82, 84, 85
L
LAP command, 56, 88, 89, 90 last 5 workdays of month, 11 day of period, 94 day of previous month, 14 workday of previous month, 14 late completion time, 82 leading zeroes, 61 less 0 workdays, 2, 17 libraries COPYJCL, 100 TEMPLIB, 100, 101 link completing Application, 53
O
ONCE criteria, 39 one-time changes, 71 Event, 35, 39 on-request job, 32, 55, 64 order of predecessor completion, 65 ordinal numbers, 7, 9, 10 overdue job, 84 link, 49
106
ESP-5.5-EC-01
Index
notification, 82 overriding DELAYSUB time, 72 library for job resubmission, 100
P
parsing input file, 62 output, using SUBWORD, 56, 64 path to UNIX scripts, 69 plus 0 workdays, 2, 9, 15 preventing backlog of Applications, 56 previous date, 15 month, 14 run of a job, 41
Q
quarterly jobs, 19 QUIT statement, 81
resubmitting a job 2 times, 80 from COPYJCL, 100 with time delay, 79 retriggering Event, 37, 55, 58, 61 return code checking, 52 dependency, 54 variable, 35, 54 REXX converting to lower case, 69 CSF extensions, 88, 89, 90 job status, 48, 66, 81 multiple runs of a job, 30 random number, 20 reading file, 62 resource status, 64 trapping output, 56, 64 running an Application early, 38, 39
S
Saturday, after special day, 8 SCAN mode, ESP Encore, 99 scheduled hour, 24, 26 resume of Event, 21 suspend of Event, 21 time variables, 24 script path, 69 self-completing task, 27, 48, 64, 81 sequential jobs, ad hoc, 32 setting resources, 68 similar jobs, 73 simulation error, TEMPLIB, 101 special day, 8, 70 special period, 94 start of month, 10 subApplication WAIT, 42 submission number, built-in variable, 100 substring alphabet, 24 Event name, 74 successor jobs, listing, 91 suppressing response, ESPNOMSG, 28
R
random schedule, 20 range date, 6 day, 7 time, 21, 22 reading input file, 63 recovery, from disaster, 70 REEXEC command, 40, 79 re-executing a Procedure, 40, 79 re-execution number, built-in variable, 40 relative time delay, 40, 58 RELCOUNT statement, 47 RELDELAY statement, 58 releasing job based on predecessors return code, 54 from hold, 55 replacing next scheduled Event, 38 scheduled Event, 39 request job, 32, 64 resource availability, 67 dependency, 68 status, 64
T
task
ESP-5.5-EC-01
107
checking job status, 48, 80 checking resource status, 64 completing with link, 29 inserting jobs, 27, 29 self-completing, 27, 48, 64, 81 template, 22, 30 TEMPLIB statement, 100, 101 temporary changes, 71 temporary library, 100, 101 time and date stamp, 44 delay, 40, 58 qualifier, 27 range, 21, 22 window, 67 time-based job, 26 TODAY function, 7 trapping output, 56, 64 TRIGGER command ADD option, 37, 58 REPLACE option, 38, 39 within Application, 55, 58 triggering Event adding schedule, 37, 58 one-time Event, 39 replacing schedule, 38, 39 with USER1 parameter, 27, 32, 61, 75
in JCL, 74 padding with zeroes, 61 part of Agent name, 73 part of Application name, 73 part of jobname, 24 variable resolution, replaced schedule, 38, 39 variables, built-in Application name, 27, 29, 53, 69, 83 data set trigger, 97 date, 43 day of week number, 93 Event name, 36, 55 file name, 44 generation number, 27, 29, 48, 53, 64, 66, 80 jobname, 25 monitor, 79 re-execution number, 40, 79 return code, 35, 54 submission number, 100 USER1, 27, 32, 61, 75 VGET command, 98 VSET command, 97 VTDEFINE command, 97
W
WAIT options, 42 week number, 95 weekly job, within date range, 6 window, time, 67 Windows command interpreter, 45 within criteria, 3 workday scheduling advance/delay/ignore, 2 advancing, 17 day of month, 9 delaying, 18 last 5 workdays of month, 11 number of workdays in week, 36 range, 7 workday status, 5, 14
U
updating, global variable table, 98 user parameter, 61 USER1 parameter, 27, 32, 61, 75 USER1 variable, 61
V
variable based on special period, 94 cycle number, 59 day of week number, 93 file name, 43
108
ESP-5.5-EC-01

ESP Workload Manager Cookbook

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ESP Workload Manager Cookbook

Uploaded by

Copyright:

Available Formats

ESP Workload Manager Version 5.

First Edition (June 2007)

About this document

SectionUsing this document

Using this document

Conventions for using commands and statements

About this document

hyphen can also be used as a wildcard character in some commands.

Wildcards and masking

You can use indentation to improve readability.

ESP Application ESP Event ESP Procedure

Application Event Procedure

EVERY run criteria

About this document

Conditional release expressions

ESP Workload Manager examples

Scheduling a weekly job and adjusting it for holidays

ESP Workload Manager examples

Scheduling a job within a month

Scheduling a job to run based on a different days holiday status

is assumed in this example that Sunday cannot be defined as a holiday.

ESP Workload Manager examples

Scheduling a job to run based on a previous days holiday status

Or, you can use the following run criteria:

Scheduling a job to run within a specific date range

ESP Workload Manager examples

Scheduling a job to run on selected workdays only

Scheduling a job relative to a special day

ESP Workload Manager examples

Scheduling a monthly job and delaying it for non-workdays

ESP Workload Manager examples

Scheduling a job to run on the last five workdays of the month

ESP Workload Manager examples

Scheduling a job based on when another job was scheduled

ESP Workload Manager examples

Determining if a day in the past was a workday

Scheduling a job to run every two days

ESP Workload Manager examples

ESP Workload Manager examples

Scheduling different jobs to run based on the calendar quarter

Scheduling a job on a random day of the month

ESP Workload Manager examples

Scheduling an hourly Application within a time range

Scheduling an hourly job within a time range

2. Schedule an Event prior to 8 AM that invokes this Application.

ESP Workload Manager examples

The code generated through calling the template is shown below:

Scheduling a different job to run every hour

MYJOBA MYJOBB MYJOBC ... MYJOBW MYJOBX

2. Schedule an Event hourly to submit the one-job Application.

ESP Workload Manager examples

Scheduling a job in an Application to run based on day and time

2. Schedule an hourly Event to run the Application. For example:

ESP Workload Manager examples

Scheduling an ad hoc job to run multiple times

ESP Workload Manager examples

Scheduling a job to run every two hours

Scheduling a job to run multiple times within a time range

ESP Workload Manager examples

The code generated through calling the template is shown below:

Running ad hoc sequential jobs

ESP Workload Manager examples