esp workload manager cookbook

ESP Workload Manager

Version 5.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 user’s 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 user’s 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 user’s 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.

ESP-5.5-EC-01 iii

Contents

About this document viiUsing this document ....................................................................................... viiiSummary of changes .......................................................................................... x

ESP Workload Manager examples 1Scheduling a weekly job and adjusting it for holidays ......................................... 2Scheduling a job within a month........................................................................ 3Scheduling a job to run based on a different day’s holiday status ........................ 4Scheduling a job to run based on a previous day’s holiday status ........................ 5Scheduling a job to run within a specific date range ........................................... 6Scheduling a job to run on selected workdays only............................................. 7Scheduling a job relative to a special day ............................................................ 8Scheduling a monthly job and delaying it for non-workdays .............................. 9Scheduling a job based on the day of the week for the 1st day of month .......... 10Scheduling a job to run on the last five workdays of the month........................ 11Scheduling a job based on when another job was scheduled ............................. 13Scheduling a job based on the workday status of the last day

of the previous month.................................................................................... 14Determining if a day in the past was a workday................................................ 15Scheduling a job to run every two days............................................................. 16Scheduling a job to run every two weeks and advancing it for holidays ............ 17Scheduling a job to run every two weeks and delaying it for holidays ............... 18

iv ESP-5.5-EC-01

Scheduling different jobs to run based on the calendar quarter......................... 19Scheduling a job on a random day of the month .............................................. 20Scheduling an hourly Application within a time range ..................................... 21Scheduling an hourly job within a time range .................................................. 22Scheduling a different job to run every hour..................................................... 24Scheduling a job in an Application to run based on day and time .................... 26Scheduling an ad hoc job to run multiple times ............................................... 27Scheduling a job to run every two hours........................................................... 29Scheduling a job to run multiple times within a time range.............................. 30Running ad hoc sequential jobs........................................................................ 32Dynamically defining and scheduling an Event ................................................ 35Scheduling a weekly Application based on the number

of workdays in the week................................................................................. 36Running the next scheduled Application early.................................................. 38Running an Application for any future date ..................................................... 39Delaying job submission until the next hour .................................................... 40Setting up a dependency with a job’s previous run ........................................... 41Using date-qualified file names......................................................................... 43Processing a changing file name ....................................................................... 44Copying a file to another location upon the file’s creation................................ 45Ensuring a file exists before processing ............................................................. 46Bypassing a job based on the status of another job............................................ 48Bypassing non-critical jobs when jobs are late .................................................. 49Taking different actions based on 1 of 3 successful return codes....................... 52Running different jobs based on the return code of a predecessor job............... 54Auto-triggering an Event for a reoccurring job ................................................. 55Scheduling a job to run based on its previous run status................................... 56Scheduling a cyclic Application ........................................................................ 57Incrementing a cycle number ........................................................................... 59Building Applications dynamically based on an input file................................. 62Running a job based on resource availability .................................................... 64Running or completing a job based on the order

in which its predecessors complete ................................................................. 65Scheduling a job based on a data set, time, and weekdays................................. 67Using the Application name in the script path ................................................. 69Identifying critical jobs for disaster recovery planning ...................................... 70Using a one-time job section in Applications.................................................... 71Using the same Application for different locations ........................................... 73Merging Applications into a single PDS member ............................................. 75Consolidating data set triggers to minimize the number of Event definitions ... 77Resubmitting a job 5 minutes after it fails ........................................................ 79Resubmitting a failed job a maximum of two times.......................................... 80Providing notification when a job exceeds its maximum run time .................... 82Providing notification for a long-running Application...................................... 83Providing notification if a job is late starting relative to a data set closure ......... 84

Contents

ESP-5.5-EC-01 v

Sending email notification for job failures ........................................................ 85Sending a message when an Agent becomes inactive......................................... 87Displaying job details from CSF....................................................................... 88Bypassing a job across multiple Applications .................................................... 89Holding all incomplete generations of an Application ...................................... 90Listing a job plus its successor chains in an active Application .......................... 91Creating a variable for the day of week number................................................ 93Creating a variable for the accounting year ....................................................... 94Calculating the week number........................................................................... 95Providing a variable for all data sets in a DSTRIG Event.................................. 97Running jobs using ESP Encore’s SCAN mode................................................ 99Setting COPYJCL as the default JCL library for resubmission ....................... 100Using date-qualified TEMPLIBs .................................................................... 101

Index 103

vi ESP-5.5-EC-01

ESP-5.5-EC-01 vii

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.

Section–Using this document

viii ESP-5.5-EC-01

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 User’s Guide• ESP Workload Manager Operator’s Guide• ESP Workload Manager Advanced User’s Guide• ESP Workload Manager Installation and Configuration Guide• ESP Workload Manager Reference Guide• ESP Encore User’s 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.

About this document

ESP-5.5-EC-01 ix

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 PAN- prefixes 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.

Section–Summary of changes

x ESP-5.5-EC-01

Naming Conventions

The following shortened names are used in place of their respective full names:

Summary of changes

This book contains information previously presented in Examples Cookbook, ESP-5.4-EC-01, which supports ESP Workload Manager 5.4.

What’s New

This edition includes the following new examples:

• “Copying a file to another location upon the file’s creation” on page 45• “Sending a message when an Agent becomes inactive” on page 87

What’s 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

Full Name Short Name

ESP Application Application

ESP Event Event

ESP Procedure Procedure

About this document

ESP-5.5-EC-01 xi

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

Section–Summary of changes

xii ESP-5.5-EC-01

ESP-5.5-EC-01 1

ESP Workload Manager examples

2 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 didn’t 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 3

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.

4 ESP-5.5-EC-01

Scheduling a job to run based on a different day’s 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 TODAYENDJOB

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 5

Scheduling a job to run based on a previous day’s 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 TODAYENDJOB

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 MONDAYNORUN 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.

6 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 7

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 WORKDAYSENDJOB

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.

8 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 9

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 DAYENDJOB

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.


10 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 MONTHENDJOB

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.


ESP-5.5-EC-01 11

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 TODAYENDJOB

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).

12 ESP-5.5-EC-01

Variation

Another solution is to use the following run criteria for the job:

RUN LAST WORKDAY OF MONTHRUN LAST WORKDAY OF MONTH LESS 1 WORKDAYRUN LAST WORKDAY OF MONTH LESS 2 WORKDAYSRUN LAST WORKDAY OF MONTH LESS 3 WORKDAYSRUN LAST WORKDAY OF MONTH LESS 4 WORKDAYS


ESP-5.5-EC-01 13

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 DAYSGENTIME B %ADATE PLUS 0 WORKDAYSJOB A RUN WEDNESDAY IFHOLIDAYPLUS 1 DAYENDJOBJOB B IF NOT SELECTED('A') THEN RUN THURSDAY IF TODAY('FRIDAY') AND ADATE NE BDATE THEN RUN TODAYENDJOB

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 Wednesday’s 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.


14 ESP-5.5-EC-01

Scheduling a job based on the workday status of the last dayof 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 MONTHENDJOB

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.



ESP-5.5-EC-01 15

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, 2004GENTIME TWO %ONEDATE PLUS 0 WORKDAYSIF 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.

16 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 17

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 non-workday, 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.

18 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 19

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 CYBERJCLLIB 'CYBER.JCLLIB'

JOB A.QTR1 RUN ANYDAY OF JAN FEB MARENDJOB

JOB B.QTR2 RUN ANYDAY OF APR MAY JUNENDJOB

JOB C.QTR3 RUN ANYDAY OF JUL AUG SEPENDJOB

JOB D.QTR4 RUN ANYDAY OF OCT NOV DECENDJOB

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.

20 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 21

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 TODAYSUSPEND 4:01PM WORKDAYSRESUME 7:59AM WORKDAYSINVOKE '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 WORKDAYSSCHEDULE 9AM WORKDAYS...SCHEDULE 4PM WORKDAYS

22 ESP-5.5-EC-01

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:


TEMPLATE HOURLY (1,OFFSET)JOB A.%OFFSETRUN WORKDAYSDELAYSUB 8AM PLUS %OFFSET HOURS

ENDJOBENDTEMPL

HOURLY 0HOURLY 1HOURLY 2HOURLY 3HOURLY 4HOURLY 5HOURLY 6HOURLY 7HOURLY 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.


ESP-5.5-EC-01 23

The code generated through calling the template is shown below:

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.

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

24 ESP-5.5-EC-01

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:

Solution


1. Use the following Application:

LETTERS='ABCDEFGHIJKLMNOPQRSTUVWX'INTEGER HOURIF ESPSHH='00' THEN HOUR=24ELSE HOUR=ESPSHH

CHAR='%LETTERS(%HOUR:%HOUR)'


JOB MYJOB%CHARRUN 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

Time Jobname

1 AM MYJOBA

2 AM MYJOBB

3 AM MYJOBC

... ...

11 PM MYJOBW

12 AM MYJOBX


ESP-5.5-EC-01 25

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 MYJOBENDJOB

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 …

26 ESP-5.5-EC-01

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


1. Use the following statements for the job:

JOB XIF 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(-) REPLACESCHEDULE 00.00 HOURLY DAILYINVOKE 'PROD.PROCLIB(CYBER)'ENDDEF

Explanation

Job X is selected to run only if it is Friday and the Event’s scheduled hour (ESPSHH) is 15 (in other words, the Event was scheduled at 3 PM).


ESP-5.5-EC-01 27

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:



JOB INSERT.JOBS TASK SELFCOMPLETINGRUN ANYTIME='%ESPAHH%ESPAMN%ESPASS'IF ESPREEXEC# LT 8 THEN DOESP AJ %USER1..T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN)REEXEC AT('REALNOW PLUS 30 MINUTES')

ENDDOENDJOB

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.

28 ESP-5.5-EC-01

Example

If you pass MYJOB as the USER1 variable and the actual time is 10.32.45, the jobnames are:

MYJOB.T103245MYJOB.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.


ESP-5.5-EC-01 29

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 CYBERJOB 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')ENDJOBJOB 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.

30 ESP-5.5-EC-01

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.%TIMEAGENT AGENTSCRIPTNAME /export/home/jsmith/scripts/aDELAYSUB 10PM PLUS %TIME MINUTESRUN ANY

ENDJOBENDTEMPL

REXXONDO I=0 TO 240 BY 10"MULTIRUN "I

ENDREXXOFF

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.


ESP-5.5-EC-01 31

The code generated through calling the template is shown below:

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.

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

32 ESP-5.5-EC-01

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





ESP-5.5-EC-01 33


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:

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

CYBBP01A CYBBP01B CYBBP01C CYBBP01D

USER1 Parameter

Job Statements Application

CYBBP01A

CYBBP01B

CYBBP01C

CYBBP01D

34 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 35

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 EVENT ID(PROD.SUB_B) REPLACEESPNOMSG SCHEDULE 9PM TODAY PLUS 45 DAYS ONCEESPNOMSG SUBMIT 'CYBER.JCLLIB(B)'ESPNOMSG 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.

36 ESP-5.5-EC-01

Scheduling a weekly Application based on the numberof 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 DOESP TR %ESPEVENT ADD AT('16:00 TODAY PLUS 1 WORKDAY')EXIT

ENDDO


JOB ARUN 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) REPLACESCHEDULE 16.00 LAST WORKDAY OF EACH WEEK LESS 1 WORKDAYINVOKE 'PROD.PROCLIB(CYBER)'ENDDEF


ESP-5.5-EC-01 37

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).

38 ESP-5.5-EC-01

Running the next scheduled Application early

Objective

Run the next day’s 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 Friday’s 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.


ESP-5.5-EC-01 39

Running an Application for any future date

Objective

Run a future version of an Application today.

Solution


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.

40 ESP-5.5-EC-01

Delaying job submission until the next hour

Objective

When a job’s 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 CYBERJCLLIB 'CYBER.JCLLIB'JOB A RELEASE B RUN DAILYENDJOBJOB B IF ESPREEXEC#=0 THEN -

REEXEC AT('HOURLY ROUND STARTING REALNOW') RUN DAILYENDJOB

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 job’s predecessors are all complete (for example, RELDELAY 30).

In this example, you do not know what time the job’s 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.


ESP-5.5-EC-01 41

Setting up a dependency with a job’s 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 day’s Application is not complete.

The dependencies look like this:

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 day’s day-of-week variable as a qualifier for the external job.

• Set up this job to release today’s 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.

X.TUE

X.MON

B

A

Y

42 ESP-5.5-EC-01

The following is a sample Application:


JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE Y ENDJOBGENTIME PREV YESTERDAYJOB X.%PREVDAY(1:3) EXTERNAL SCHEDULED('YESTERDAY') -APPLID(CYBER)

RUN DAILY RELEASE X.%ESPSDAY(1:3)ENDJOBJOB X.%ESPSDAY(1:3) RUN DAILY RELEASE YENDJOBJOB Y RUN DAILYENDJOB

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 day’s 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 day’s run as an external dependency to today’s 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 day’s runs to complete.

For example:

JOB X SUBAPPL PREVDAY WAITRUN DAILYRELEASE Y

ENDJOB


ESP-5.5-EC-01 43

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._okENDJOB

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

44 ESP-5.5-EC-01

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 CYBERAGENT AGENTFILE_TRIGGER CREATE RUN DAILY FILENAME /export/home/jsmith/scripts/file* CREATE RELEASE PROCESSENDJOBUNIX_JOB PROCESS RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/echoit ARGS %ESPFTFILEENDJOB

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.


ESP-5.5-EC-01 45

Copying a file to another location upon the file’s 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 file’s creation and a successor job, COPY, to copy the newly created file to another location.

APPL COPYFILEAGENT AGENTFILE_TRIGGER CREATE RUN DAILY FILENAME C:\env.txt CREATE RELEASE COPYENDJOBNT_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.

46 ESP-5.5-EC-01

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.


Solution

The following Application shows how to define the different workload objects.

APPL CYBERAGENT AGENTFILE_TRIGGER CHECK4.FILE CONDITIONAL RUN DAILY FILENAME /export/home/jsmith/scripts/myfile EXIST RELEASE (CREATE.FILE(A),PROCESS.FILE)ENDJOBUNIX_JOB CREATE.FILE CONDITIONAL RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/create.file RELEASE PROCESS.FILEENDJOB

UNIX_JOB PROCESS.FILE RUN DAILY RELCOUNT 1 SCRIPTNAME /export/home/jsmith/scripts/process.fileENDJOB

CHECK4.FILE

CREATE.FILE

PROCESS.FILE


ESP-5.5-EC-01 47

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.

48 ESP-5.5-EC-01

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 CYBERJCLLIB '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 ENDENDREXXOFFRELEASE B

ENDJOB

JOB BRUN 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.


ESP-5.5-EC-01 49

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.

50 ESP-5.5-EC-01

The Application looks like this:

Application Definition

The following is the definition of the Application:

APPL CYBERJCLLIB 'CYBER.JCLLIB'JOB A RUN DAILY RELEASE CRITICAL.POINTENDJOBJOB B RUN DAILY RELEASE CRITICAL.POINTENDJOBJOB CRITICAL.POINT LINK RUN DAILY NOTIFY OVERDUE ALERT(CRIT) DUEOUT EXEC 6AM RELEASE (C,D,E)ENDJOBJOB C RUN DAILY RELEASE FENDJOBJOB D RUN DAILY RELEASE FENDJOBJOB E RUN DAILY RELEASE F

B A

CRITICAL.POINT

E C

F

D


ESP-5.5-EC-01 51

ENDJOBJOB F RUN DAILYENDJOB

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.

52 ESP-5.5-EC-01

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.

The requirements look like this:

Solution

The following is a sample Application you can schedule at 10 AM on the last workday of each month:

APPL CYBERJCLLIB 'CYBER.JCLLIB'JOB A RUN ANYDAY RELEASE ADD(B) COND(RC(0)) RELEASE ADD(RUNAGAIN) COND(RC(1)) RELEASE ADD(CANCEL) COND(RC(2))ENDJOBJOB B RUN ANYDAYENDJOB

Return Code for Job A Action

0 Run job B

1 Complete Application and run it again at 10 AM the next workday

2 Cancel this month’s run

Run job B Run again nextworkday

Cancel this month'srun

A

0 1 2


ESP-5.5-EC-01 53

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')ENDJOBJOB 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 month’s run.

The AJ commands use the ESPAPPL and ESPAPGEN variables to ensure the correct generation of the correct Application is used.

54 ESP-5.5-EC-01

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.


Solution



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 DAILYENDJOB

JOB C RUN DAILYENDJOB

Explanation

Job A uses two conditional release expressions to release job B on return code 0 and job C on return code 1.

1 0

A

B C


ESP-5.5-EC-01 55

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


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 HELDJOBJCLLIB 'CYBER.JCLLIB'

JOB SPECIAL HOLDRUN DAILYESPNOMSG 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.

56 ESP-5.5-EC-01

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 GENX=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 CYBERJCLLIB 'CYBER.JCLLIB'JOB ARUN 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).


ESP-5.5-EC-01 57

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


1. Use the following Application.


JOB A.T%ESPSHHRUN DAILYRELEASE B.T%ESPSHH

ENDJOB

JOB B.T%ESPSHHRUN DAILY

ENDJOB

...

APPLEND RETRIG.EVENTRELDELAY 60IF 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(-) REPLACESCHEDULE 00.00 DAILYINVOKE '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.

58 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 59

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


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.

60 ESP-5.5-EC-01

Application

The following is a sample Application definition:

APPL CYBERJCLLIB 'CYBER.JCLLIB'THIS_CYCLE=USER1DSTRIG BUS RUN ANY DSNAME BUS.BC%THIS_CYCLE RELEASE AENDJOBDSTRIG RES RUN ANY DSNAME RES.BC%THIS_CYCLE RELEASE AENDJOBJOB A RUN ANY RELEASE ZENDJOBJOB Z RUN ANY RELEASE CHANGE.CYCLEENDJOBJOB 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


ESP-5.5-EC-01 61

The flow looks like this:

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.

Z

A

CHANGE.CYCLE

File=RES.BC1234 File=BUS.BC1234

File=RES.BC1235 File=BUS.BC1235

62 ESP-5.5-EC-01

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 CYBERJCLLIB '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 ENDADDRESS 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 ENDLAST = 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.


ESP-5.5-EC-01 63

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:

ADHOCJ12 CLEANUP1 . . .

CYBER.INPUT File

APPL CYBER JCLLIB 'CYB.JCL' JOB ADHOCJ12 RUN NOW ENDJOB JOB CLEANUP1 RUN NOW ENDJOB . . .

Application

64 ESP-5.5-EC-01

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 CYBERJCLLIB '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 BENDJOBJOB B REQUEST RUN DAILYENDJOB

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.


ESP-5.5-EC-01 65

Running or completing a job based on the orderin 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.



1. Set up an Application such that an Alert runs when job A ends. For example:

APPL CYBERJCLLIB 'CYBER.JCLLIB'JOB A RUN ANY RELEASE B NOTIFY JOBEND ALERT(CHCK)ENDJOBDSTRIG WAIT4DS DSNAME 'CYBER.THAT.DATASET' ANYCLOSE RUN ANY RELEASE BENDJOBJOB B RUN ANYENDJOB

CHECK.STATUS

A WAIT4DS

B

66 ESP-5.5-EC-01

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 REXXOFFENDDO

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.


ESP-5.5-EC-01 67

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 WAITJCLLIB 'CYBER.JCLLIB'

JOB ARESOURCE (1,CYBERDSN)RUN ANYDAYRELEASE CYBERDSN.OFF

ENDJOB

JOB CYBERDSN.OFF LINK PROCESSRUN ANYDAYESPNOMSG 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) REPLACEINVOKE 'PROD.PROCLIB(CYBER)'DSTRIG CYBER.DATASET.G-ENDDEF

68 ESP-5.5-EC-01

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) REPLACESCHEDULE 22.30 WEEKDAYSVS 'F ESP,RESDEF CYBERDSN SET AVAIL(1)'ENDDEF

EVENT ID(PROD.CYBERDSN_OFF) SYSTEM(ESPM) REPLACESCHEDULE 23.30 WEEKDAYSVS '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.


ESP-5.5-EC-01 69

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.

REXXONAPP = 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 ABCDUNIX_JOB MYJOB AGENT AGENT SCRIPTNAME /export/home/jsmith/%appl/sleep60 RUN DAILYENDJOB

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.

70 ESP-5.5-EC-01

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


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 BRUN DAILYNORUN DISASTERRELEASE (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.


ESP-5.5-EC-01 71

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 CYBERJCLLIB 'CYBER.JCLLIB'JOB A RUN DAILY DELAYSUB 5PM RELEASE BENDJOBJOB B RUN DAILY RELEASE CENDJOB/* USE THIS SECTION FOR ONE-TIME CHANGESONE_TIME_CHANGES:JOB AIF 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.

72 ESP-5.5-EC-01

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


ESP-5.5-EC-01 73

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 '%ESPEVENT(9:12)' = 'DALL' THEN DC = 'DA'IF '%ESPEVENT(9:12)' = 'CHIC' THEN DC = 'CH'IF '%ESPEVENT(9:12)' = 'TORO' THEN DC = 'TO'IF '%ESPEVENT(9:12)' = 'SAND' THEN DC = 'SD'

APPL CYBER%DCJCLLIB '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 DAILYENDJOB...

74 ESP-5.5-EC-01

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 JOB CYB1000,'GENERIC JOB',MSGCLASS=Z,CLASS=B//STEP1 EXEC PGM=IEFBR14//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=RG%DC.100.ESPTST.DATA,// DISP=(NEW,CATLG,DELETE),// UNIT=SYSDA,SPACE=(TRK,1)


ESP-5.5-EC-01 75

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


1. The following ESP Procedure shows a technique to merge Applications into a single PDS member:

IF %USER1 = '' THEN EXITJUMPTO %USER1

PAYREQ:APPL PAYREQJCLLIB 'CYBER.JCLLIB'JOB ARUN ANYRELEASE B

ENDJOBJOB BRUN ANY

ENDJOBEXIT

FINREQ:APPL FINREQJCLLIB 'CYBER.JCLLIB'JOB XRUN ANY

ENDJOBEXIT

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.

76 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 77

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


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- ANYCLOSEDSTRIG CYBER.PROD.SERVICES.CLASS2.G- ANYCLOSEDSTRIG CYBER.PROD.SERVICES.CLASS3.G- ANYCLOSEINVOKE '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 ARUN ANYINTEGER SIZEID=0DSN=ESPTRDSNSIZE=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=1IF %CHECK= 'CYBER.PROD.SERVICES.CLASS2' THEN ID=2IF %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

78 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 79

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


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 ANYDAYENDJOB

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)ENDDOELSE 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.

80 ESP-5.5-EC-01

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 Manager’s 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 CYBERJCLLIB 'CYBER.JCLLIB'JOB ARUN ANY

MONITOR CYBER RELEASE CHECK.A IF ESPAPSUB# GT 2 THEN DO ESP AJ CHECK.A READY APPL(CYBER.%ESPAPGEN) QUIT ENDDOENDJOBJOB 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 REXXOFFENDJOB

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)


ESP-5.5-EC-01 81

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.

82 ESP-5.5-EC-01

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 CYBERUNIX_JOB A RUN DAILY MAXRUNTIME=5 NOTIFY OVERDUE USERS(USER01) AGENT AGENT SCRIPTNAME /u1/prod/scripts/aENDJOB

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.


ESP-5.5-EC-01 83

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


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.

84 ESP-5.5-EC-01

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


1. Use a DUEOUT INPUT statement and a NOTIFY statement in the Application that contains the job, as shown below:


JOB ARUN ANYDUEOUT INPUT REALNOW PLUS 10 MINUTESNOTIFY 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 ANYCLOSEENDDEF

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.


ESP-5.5-EC-01 85

Sending email notification for job failures

Objective

Automatically send an email if any job within Application CYBER fails.

Solution


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 [email protected]

2. In your Application, use the MAILBOX parameter on the NOTIFY statement, as shown below:

APPL CYBERJCLLIB 'CYBER.JCLLIB'NOTIFY FAILURE MAILBOX(OPER)

JOB ARUN 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 Manager’s 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.

86 ESP-5.5-EC-01

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 ESPMAIL FROM: <ESP53@LOCALHOST>RCPT TO: <[email protected]>DATAFROM: ESPTO: [email protected]: 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.


ESP-5.5-EC-01 87

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


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.

88 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 89

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")" ENDEND

Explanation


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.


90 ESP-5.5-EC-01

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.0DO i = 1 TO jIF line.i = "" THEN ITERATEPARSE UPPER VAR line.i verb therestIF verb = "APPL" THENDOPARSE VAR therest . . applgen .Applgen = STRIP(applgen)QUEUE "AJ ALL HOLD APPL("|| Applname() ||"."|| Applgen || ")"

ENDEND

J = QUEUED()DO I = 1 TO JPULL XSAY "ISSUING: " XX

END

Explanation


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.



ESP-5.5-EC-01 91

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 leaveEnd

say "The following is a display of job" job(), "and its successors:"say ""

Do j = i to Line.0 Say Line.jEnd

Explanation


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.

92 ESP-5.5-EC-01

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),***



ESP-5.5-EC-01 93

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 1

Thursday 2

Friday 3

Saturday 4

Sunday 5

Monday 6

Tuesday 7

94 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 95

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 DAYWK=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,NGENTIME LY TODAY LESS 1 YEARGENTIME FY FIRST SUNDAY OF YEAR PLUS 9 DAYS STARTING TODAYN=DAYS_TO('%FYDATE')IF N>0 THEN STYEAR=LYYEAR ELSE STYEAR=ESPSYEAR GENTIME W FIRST SUNDAY OF YEAR PLUS 9 DAYS -

STARTING JAN 1 %STYEARWK=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

96 ESP-5.5-EC-01

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.


ESP-5.5-EC-01 97

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-' MULTIPLEDSTRIG 'PROD.FILE2.G-' MULTIPLEENDDEF


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

98 ESP-5.5-EC-01

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).

2. Otherwise, if the last received data set is DSN2, then:

• 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).


ESP-5.5-EC-01 99

Running jobs using ESP Encore’s SCAN mode

Objective

Run a series of jobs in an Application and use ESP Encore’s 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 CYBERJCLLIB 'CYBER.JCLLIB'OPTIONS RESTARTSTEPENCPARM MODE SCANNOTIFY FAILURE ALERT(SCAN)

JOB ARUN DAILYRELEASE B

ENDJOBJOB BRUN 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 job’s SYSOUT.

100 ESP-5.5-EC-01

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).


ESP-5.5-EC-01 101

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.

102 ESP-5.5-EC-01

ESP-5.5-EC-01 103

Index

Symbols%INCLUDE statements, 77

Numerics1st day of month, 102nd last workday of week, 365 Fridays in month, 3

Aaccounting year, 94ad hoc

Applications, 75jobs, 27, 32, 62

addingEvent schedule, 37, 58

adjusting for holidays, 2, 13, 17, 18advancing schedule, 38, 39Agent name, as a variable, 73Agent, sending message when inactive, 87AGENT_MONITOR workload object, 87AJ command

bypassing a job, 48, 51, 89completing a job, 66, 99

completing a task, 29, 48, 64completing an Application, 53holding an Application, 90inserting a job, 27requesting a job, 64resubmitting a job, 79, 81

AlertEncore’s SCAN mode, 99job resubmission, 79sending message, 87

APPLEND workload object, 58Application name

built-in variable, 27, 29, 53, 69, 83in script path, 69variable, 69, 73

Application status, 83after 24 hours, 83LAP command, 56

Applicationsbased on input file, 62common, 73holding all generations, 90hourly, 21, 24merging, 75

APPLINS command, 29

104 ESP-5.5-EC-01

argument, passing to script, 59automatic

bypass, 49, 54, 83Event trigger, 55, 61resubmission of job, 79

Bbatch job, to send email, 86between

dates, 6times, 30

bi-weekly job, 17, 18built-in functions

DAYS_BETWEEN, 95DAYS_FROM, 6DAYS_TO, 4, 6JOBONCSF, 48, 89, 90TODAY, 7

built-in variablesESPAPGEN, 27, 29, 48, 53, 64, 66, 80ESPAPJOB, 25ESPAPPL, 27, 29, 53, 69, 83ESPAPSUB#, 100ESPEVENT, 36, 55ESPREEXEC#, 40, 79ESPSDOW#, 93ESPSHH, 24, 26ESPTRDSN, 97monitor, 79return code, 35, 54scheduled hour, 24USER1, 27, 32, 61, 75

bypassingconditional job, 83job across Applications, 89job based on another job’s status, 48job based on return code, 54non-critical jobs, 49

Ccalendar quarter, 19cmd.exe, 45common

Applications, 73JCL member, 25, 74

comparing GENTIME dates, 9, 13, 14, 15completing a task

self-completing, 27, 48, 64, 81with link, 29

concatenating variables, 43conditional jobs, 47, 83conditional release expressions, 53, 54consolidating

Applications, 75data set triggers, 77

convertingnumbers and strings, 61to lowercase, 69

copying file, 45COPYJCL library, 100CSF extension

bypassing jobs, 89holding all generations of an Application, 90listing job details, 88listing successors, 91

current period, 94cycle number, 59cyclic Application, 57

Ddata set dependency, 59data set-trigger

built-in variable, 97Event, 77, 97job, 65

date range, 6date-qualified

file name, 43TEMPLIB, 101

day of week number, 93DAYS_BETWEEN function, 95DAYS_FROM function, 6, 93DAYS_TO function, 4, 6default library, job resubmission, 100defining

Alert, 49, 79global variable table, 97special day, 95

delaying jobbased on holidays, 13based on workday status, 9random number of days, 20relative delay, 40, 58resubmission, 79submit time, 40

Index

ESP-5.5-EC-01 105

until next hour, 40different actions, based on return code, 52different jobs

calendar quarter, 19each generation, 27each hour, 24

disaster recovery, 70displaying

job details from CSF, 88successor jobs, 91

DUEOUT statement, 84dynamically generated Applications, 62

Eearly run of Application, 38, 39email

batch job, 86notification, 85

ESP Encore, 99ESPAPGEN variable, 27, 29, 48, 53, 64, 66, 80ESPAPJOB variable, 25ESPAPPL variable, 27, 29, 53, 69, 83ESPAPSUB# variable, 100ESPEVENT variable, 36, 55ESPFTFILE variable, 44ESPNOMSG command, 28ESPREEXEC# variable, 40ESPS* variables, 43ESPSDOW# variable, 93ESPSHH variable, 24, 26ESPTRDSN variable, 97Event

data set-triggered, 77, 97defined from Procedure, 35retrigger, 37, 55, 58, 61sending message to user, 87trigger, 38, 39trigger, with USER1 parameter, 27

Event namebuilt-in variable, 36, 55standard, 74substring, 74

every10 minutes, 302 days, 162 hours, 292 weeks, 17, 1830 minutes, 27

5 minutes, 56EVERY run criteria, 16, 17, 18except criteria, 2existing file, 46EXIT statement, 76external job, 41

Ffailed job

automatic resubmission, 80Encore’s SCAN mode, 99file trigger, 47notification, 85

file dependency, 43, 44, 45, 46file name

built-in variable, 44changing, 44date-qualified, 43

file trigger object, 43, 44, 45, 46fiscal year, 95five Fridays in month, 3future schedule, 38, 39

GGDG-based data sets, 77generation number, built-in

variable, 27, 29, 48, 53, 64, 66, 80generic Application, 73GENTIME command

5th last workday of month, 11comparing dates, 9, 13, 14, 15day of week, 10previous date/criteria, 15

global variable table, 97

Hheld job, 55holding, all generations of an Application, 90holiday scheduling, 2, 4, 5, 13holiday status, 15hourly

Application, 21Event, 26job, 22jobs, 24

106 ESP-5.5-EC-01

IIFHOLIDAYPLUS run criteria, 13, 18impact on successor jobs, 91incrementing cycle number, 59input file, 62inserting

ad hoc job, 27UNIX job, 29

JJCL

common member, 25, 74email notification, 86

JCL errors, 99JCL library, for job resubmission, 100JCL tailoring, 77job definitions, merging, 71job monitor Event, 35, 81job resubmission, 79, 80, 100job selection

replaced schedule, 38, 39simulating, 70

job statususing JOBONCSF, 48, 89when QUIT encountered, 81

JOBEND Event, 35, 81jobname

based on hour, 24built-in variable, 25variable, 73

JOBONCSF function, 48, 89, 90

LLAP command, 56, 88, 89, 90last

5 workdays of month, 11day of period, 94day of previous month, 14workday of previous month, 14

late completion time, 82leading zeroes, 61less 0 workdays, 2, 17libraries

COPYJCL, 100TEMPLIB, 100, 101

linkcompleting Application, 53

increasing cycle number, 59overdue time, 49retrigger Event, 53, 59setting resource, 67submit time, 83

listing successor jobs, 91long-running Application, 83lowercase, 69

MMAILBOX parameter, 85maintaining job definitions, 71maximum run time, 82MAXRUNTIME statement, 82MEMBER statement, 25, 74merging

Application definitions, 75job definitions, 71

MNRC variable, 35, 54Mondays except holidays, 2monitor variables, 79monthly job, 10multiple data sets, 97multiple runs of a job, 30

Nnon-critical jobs, 49, 70non-existent file, 47NORUN criteria, 2, 5, 70notification

failed job, 85long-running Application, 83overdue job, 82

NOTIFY statement, 82, 84, 85

OONCE criteria, 39one-time

changes, 71Event, 35, 39

on-request job, 32, 55, 64order of predecessor completion, 65ordinal numbers, 7, 9, 10overdue

job, 84link, 49

Index

ESP-5.5-EC-01 107

notification, 82overriding

DELAYSUB time, 72library for job resubmission, 100

Pparsing

input file, 62output, using SUBWORD, 56, 64

path to UNIX scripts, 69plus 0 workdays, 2, 9, 15preventing backlog of Applications, 56previous

date, 15month, 14run of a job, 41

Qquarterly jobs, 19QUIT statement, 81

Rrandom schedule, 20range

date, 6day, 7time, 21, 22

reading input file, 63recovery, from disaster, 70REEXEC command, 40, 79re-executing a Procedure, 40, 79re-execution number, built-in variable, 40relative time delay, 40, 58RELCOUNT statement, 47RELDELAY statement, 58releasing job

based on predecessor’s return code, 54from hold, 55

replacingnext scheduled Event, 38scheduled Event, 39

request job, 32, 64resource

availability, 67dependency, 68status, 64

resubmitting a job2 times, 80from COPYJCL, 100with time delay, 79

retriggering Event, 37, 55, 58, 61return code

checking, 52dependency, 54variable, 35, 54

REXXconverting to lower case, 69CSF extensions, 88, 89, 90job status, 48, 66, 81multiple runs of a job, 30random number, 20reading file, 62resource status, 64trapping output, 56, 64

running an Application early, 38, 39

SSaturday, after special day, 8SCAN mode, ESP Encore, 99scheduled

hour, 24, 26resume of Event, 21suspend of Event, 21time variables, 24

script path, 69self-completing task, 27, 48, 64, 81sequential jobs, ad hoc, 32setting resources, 68similar jobs, 73simulation error, TEMPLIB, 101special day, 8, 70special period, 94start of month, 10subApplication WAIT, 42submission number, built-in variable, 100substring

alphabet, 24Event name, 74

successor jobs, listing, 91suppressing response, ESPNOMSG, 28

Ttask

108 ESP-5.5-EC-01

checking job status, 48, 80checking resource status, 64completing with link, 29inserting jobs, 27, 29self-completing, 27, 48, 64, 81

template, 22, 30TEMPLIB statement, 100, 101temporary changes, 71temporary library, 100, 101time

and date stamp, 44delay, 40, 58qualifier, 27range, 21, 22window, 67

time-based job, 26TODAY function, 7trapping output, 56, 64TRIGGER command

ADD option, 37, 58REPLACE option, 38, 39within Application, 55, 58

triggering Eventadding schedule, 37, 58one-time Event, 39replacing schedule, 38, 39with USER1 parameter, 27, 32, 61, 75

Uupdating, global variable table, 98user parameter, 61USER1 parameter, 27, 32, 61, 75USER1 variable, 61

Vvariable

based on special period, 94cycle number, 59day of week number, 93file name, 43

in JCL, 74padding with zeroes, 61part of Agent name, 73part of Application name, 73part of jobname, 24

variable resolution, replaced schedule, 38, 39variables, built-in

Application name, 27, 29, 53, 69, 83data set trigger, 97date, 43day of week number, 93Event name, 36, 55file name, 44generation number, 27, 29, 48, 53, 64, 66, 80jobname, 25monitor, 79re-execution number, 40, 79return code, 35, 54submission number, 100USER1, 27, 32, 61, 75

VGET command, 98VSET command, 97VTDEFINE command, 97

WWAIT options, 42week number, 95weekly job, within date range, 6window, time, 67Windows command interpreter, 45within criteria, 3workday scheduling

advance/delay/ignore, 2advancing, 17day of month, 9delaying, 18last 5 workdays of month, 11number of workdays in week, 36range, 7

workday status, 5, 14

esp workload manager cookbook

Documents

ca copyright notices

proprietary information

related software

applicable law

partial copies

licensed users

users responsibility

internal use