ESP Workload Manager. Version 5.5. Examples Cookbook ESP-5.5-EC-01

Transcription

1 ESP Workload Manager Version 5.5 Examples Cookbook ESP-5.5-EC-01

2 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 , , and (c)(1) - (2) and DFARS Section (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.

3 Contents About this document vii Using this document... viii Summary of changes... x ESP Workload Manager examples 1 Scheduling a weekly job and adjusting it for holidays... 2 Scheduling a job within a month... 3 Scheduling a job to run based on a different day s holiday status... 4 Scheduling a job to run based on a previous day s holiday status... 5 Scheduling a job to run within a specific date range... 6 Scheduling a job to run on selected workdays only... 7 Scheduling a job relative to a special day... 8 Scheduling a monthly job and delaying it for non-workdays... 9 Scheduling a job based on the day of the week for the 1st day of month Scheduling a job to run on the last five workdays of the month Scheduling a job based on when another job was scheduled Scheduling a job based on the workday status of the last day of the previous month Determining if a day in the past was a workday Scheduling a job to run every two days Scheduling a job to run every two weeks and advancing it for holidays Scheduling a job to run every two weeks and delaying it for holidays ESP-5.5-EC-01 iii

4 Scheduling different jobs to run based on the calendar quarter Scheduling a job on a random day of the month Scheduling an hourly Application within a time range Scheduling an hourly job within a time range Scheduling a different job to run every hour Scheduling a job in an Application to run based on day and time Scheduling an ad hoc job to run multiple times Scheduling a job to run every two hours Scheduling a job to run multiple times within a time range Running ad hoc sequential jobs Dynamically defining and scheduling an Event Scheduling a weekly Application based on the number of workdays in the week Running the next scheduled Application early Running an Application for any future date Delaying job submission until the next hour Setting up a dependency with a job s previous run Using date-qualified file names Processing a changing file name Copying a file to another location upon the file s creation Ensuring a file exists before processing Bypassing a job based on the status of another job Bypassing non-critical jobs when jobs are late Taking different actions based on 1 of 3 successful return codes Running different jobs based on the return code of a predecessor job Auto-triggering an Event for a reoccurring job Scheduling a job to run based on its previous run status Scheduling a cyclic Application Incrementing a cycle number Building Applications dynamically based on an input file Running a job based on resource availability Running or completing a job based on the order in which its predecessors complete Scheduling a job based on a data set, time, and weekdays Using the Application name in the script path Identifying critical jobs for disaster recovery planning Using a one-time job section in Applications Using the same Application for different locations Merging Applications into a single PDS member Consolidating data set triggers to minimize the number of Event definitions Resubmitting a job 5 minutes after it fails Resubmitting a failed job a maximum of two times Providing notification when a job exceeds its maximum run time Providing notification for a long-running Application Providing notification if a job is late starting relative to a data set closure iv ESP-5.5-EC-01

5 Contents Sending notification for job failures Sending a message when an Agent becomes inactive Displaying job details from CSF Bypassing a job across multiple Applications Holding all incomplete generations of an Application Listing a job plus its successor chains in an active Application Creating a variable for the day of week number Creating a variable for the accounting year Calculating the week number Providing a variable for all data sets in a DSTRIG Event Running jobs using ESP Encore s SCAN mode Setting COPYJCL as the default JCL library for resubmission Using date-qualified TEMPLIBs Index 103 ESP-5.5-EC-01 v

6 vi ESP-5.5-EC-01

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

8 Section Using this document Using this document Instructions for copying code The code in the examples is meant to be copied and used as needed. You can use the code in the examples by copying and pasting it from the PDF. If you need to download the Adobe Acrobat PDF reader, you can download it for free from the Adobe website at 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. viii ESP-5.5-EC-01

9 About this document Continuation Statements cannot extend beyond column 72. To continue lines longer than 72 characters, type either a hyphen (-) or a plus sign (+) as the last non-blank character on a line to continue a line of input. The hyphen attaches the next line including any leading blank positions. The plus sign strips leading blanks from a continuation line. Blanks preceding the hyphen or the plus sign are retained. Note: A hyphen can also be used as a wildcard character in some commands. Wildcards and masking Many statements, commands, and initialization parameters permit the use of the following wildcard characters (also called masking): An asterisk matches a specific single character. A hyphen matches zero or more characters. It can only be used as the last character of the operand. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */). Comments Enclose comments between /* and */. Comments can be written anywhere in an ESP Procedure. Data sets Enclose all data set names in single quotation marks; otherwise, ESP Workload Manager adds your TSO data set prefix to the name. Use ROS-, LIB- or PANprefixes to identify Roscoe, Librarian, and Panvalet data sets respectively. Delimiters Use single quotation marks when you want to denote character strings and literal data in expressions, assignment statements, and built-in functions. You must include single quotation marks around a string that contains blanks. Indentation You can use indentation to improve readability. ESP-5.5-EC-01 ix

10 Section Summary of changes Naming Conventions The following shortened names are used in place of their respective full names: Full Name ESP Application ESP Event ESP Procedure Short Name Application Event Procedure 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 x ESP-5.5-EC-01

11 About this document Conditional release expressions Taking different actions based on 1 of 3 successful return codes on page 52 Running different jobs based on the return code of a predecessor job on page 54 ESP-5.5-EC-01 xi

12 Section Summary of changes xii ESP-5.5-EC-01

13 ESP Workload Manager examples ESP-5.5-EC-01 1

14 Scheduling a weekly job and adjusting it for holidays 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. Use the following RUN statement for the job: RUN MONDAY LESS 0 WORKDAYS 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 2 ESP-5.5-EC-01

15 ESP Workload Manager examples Scheduling a job within a month Run a job on the 5th Friday of the month but only in months that have 5 Fridays. Use the following run criteria for the job: RUN 5th friday within month This solution runs the job on the 5th Friday of the month in months that contain 5 Fridays. ESP-5.5-EC-01 3

16 Scheduling a job to run based on a different day s holiday status 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. Use the following statements for the job: JOB A RUN SAT IF DAYS_TO('HOLIDAY') = 2 THEN NORUN TODAY 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. 4 ESP-5.5-EC-01

17 ESP Workload Manager examples Scheduling a job to run based on a previous day s holiday status Schedule a job to run every Monday, except when the previous Friday is a holiday. Workdays are Monday through Friday. Use the following statements for the job: JOB A IF TODAY('MON') AND DAYS_FROM('TODAY LESS 1 WORKDAY')=3 THEN - RUN TODAY This solution checks to see if today is a Monday and the number of days from the previous workday is 3 (in other words, Friday was a workday). If both conditions are true, the job is selected to run. Variations Another way of coding this, assuming that holidays do not fall on Saturday or Sunday, is: IF TODAY('MON') AND NOT TODAY('HOLIDAY PLUS 1 WEEKDAY') THEN - RUN TODAY Or, you can use the following run criteria: RUN MONDAY NORUN HOLIDAY PLUS 1 WEEKDAY For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15. ESP-5.5-EC-01 5

18 Scheduling a job to run within a specific date range Run a job every Thursday between April 17, 2005 and November 6, 2005, inclusively. Use the following statements for the job: JOB A IF DAYS_FROM('APR 17,2005') GE 0 - AND DAYS_TO('NOV 6,2005') GE 0 - THEN RUN THURSDAY 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. 6 ESP-5.5-EC-01

19 ESP Workload Manager examples Scheduling a job to run on selected workdays only Run a job from the 15 th day to 25 th day of the month, but only on workdays. Use the following statements for the job: JOB A IF TODAY('15TH-25TH DAY OF MONTH') THEN RUN WORKDAYS This solution uses the TODAY built-in function to determine if today is within the required day range. If it is, the job is selected to run on workdays. ESP-5.5-EC-01 7

20 Scheduling a job relative to a special day Run a job on the first Saturday on or after a special day. Use the following run criteria for the job: RUN 1ST SATURDAY OF SPECIAL_DAY This solution selects the job to run on the first instance of Saturday on or after SPECIAL_DAY. 8 ESP-5.5-EC-01

21 ESP Workload Manager examples Scheduling a monthly job and delaying it for non-workdays 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. Use the following statements for the job: JOB A GENTIME AA 5TH DAY OF MONTH GENTIME BB 5TH DAY OF MONTH PLUS 0 WORKDAYS IF AADATE = BBDATE THEN RUN %AADATE ELSE RUN %AADATE PLUS 1 DAY This solution uses two GENTIME commands to generate date and time variables for the 5th day of the month and for the first workday on or after the 5th day of the month. If these dates are equal, then the 5th day of a month is a workday, and job A runs on the 5th day of the month. Otherwise, job A runs 1 day after the 5th day of the month. For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15. ESP-5.5-EC-01 9

22 Scheduling a job based on the day of the week for the 1st day of month 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. Use the following statements for the job: JOB A GENTIME ONE 1ST DAY OF MONTH STARTING TODAY IF ONEDAY='SATURDAY' OR ONEDAY='SUNDAY' THEN - RUN 2ND MONDAY OF MONTH ELSE RUN 1ST MONDAY OF MONTH This solution uses the GENTIME command to generate date and time variables for the 1st day of the current month. If the day-of-week variable from the GENTIME (in other words, ONEDAY) is Saturday or Sunday, job A runs on the 2nd Monday of the month. Otherwise, job A runs on the 1st Monday of the month. 10 ESP-5.5-EC-01

23 ESP Workload Manager examples Scheduling a job to run on the last five workdays of the month Schedule a job to run only on the last 5 workdays of each month. Use the following statements for the job: JOB A GENTIME LAST5 LAST WORKDAY OF MONTH LESS 4 WORKDAYS IF LAST5DD <= ESPSDD AND TODAY('WORKDAY') THEN RUN TODAY 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 If workdays are Monday through Friday and there are no holidays at the end of October 2005, then the 5th last workday of the month falls on October 25. The LAST5DD variable has a value of 25. This means that in October 2005, the job would be scheduled only on October 25, 26, 27, 28, and 31 (not on October 29 or 30, which fall on a weekend). ESP-5.5-EC-01 11

24 Variation Another solution is to use the following run criteria for the job: RUN LAST WORKDAY OF MONTH RUN LAST WORKDAY OF MONTH LESS 1 WORKDAY RUN LAST WORKDAY OF MONTH LESS 2 WORKDAYS RUN LAST WORKDAY OF MONTH LESS 3 WORKDAYS RUN LAST WORKDAY OF MONTH LESS 4 WORKDAYS 12 ESP-5.5-EC-01

25 ESP Workload Manager examples Scheduling a job based on when another job was scheduled 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. Use the following statements for the jobs: GENTIME A WEDNESDAY STARTING TODAY LESS 2 DAYS GENTIME B %ADATE PLUS 0 WORKDAYS JOB A RUN WEDNESDAY IFHOLIDAYPLUS 1 DAY JOB B IF NOT SELECTED('A') THEN RUN THURSDAY IF TODAY('FRIDAY') AND ADATE NE BDATE THEN RUN TODAY 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. For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page 15. ESP-5.5-EC-01 13

26 Scheduling a job based on the workday status of the last day of the previous month Run a job on the 2nd workday of each month, but only if the last day of the previous month was a workday. Use the following statements for the job: JOB A GENTIME LD LAST DAY OF MONTH STARTING TODAY LESS 1 MONTH GENTIME LWD LAST WORKDAY OF MONTH STARTING TODAY LESS 1 MONTH IF %LDDATE EQ %LWDDATE THEN RUN 2ND WORKDAY OF MONTH This solution uses two GENTIME commands to generate date and time variables for the last day of the previous month and for the last workday of the previous month. If these two dates are equal, then the last day of the previous month was a workday, and the job is selected to run on the 2nd workday of the month. For a general approach to determining whether a day in the past was a workday, refer to Determining if a day in the past was a workday on page ESP-5.5-EC-01

27 ESP Workload Manager examples Determining if a day in the past was a workday 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. The following code sets the variable VALUE to either true or false based on whether or not May 13, 2004 was a workday. GENTIME ONE MAY 13, 2004 GENTIME TWO %ONEDATE PLUS 0 WORKDAYS IF ONEDATE=TWODATE THEN VALUE='TRUE' ELSE VALUE='FALSE' 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, The second GENTIME generates date and time variables for the first workday on, or after, your first criteria. It uses the DATE variable from your first GENTIME (in other words, %ONEDATE) and adds PLUS 0 WORKDAYS. The two dates from the GENTIMEs are then compared. If they are equal then the day in the past was a workday; otherwise, it was a non-workday. Note: The default retain count for holidays is 2 days. Since holidays affect what is considered a workday, you may need to retain some holidays for a longer period if you need to refer back to them after two days. ESP-5.5-EC-01 15

28 Scheduling a job to run every two days 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. Use the following run criteria for the job: RUN EVERY 2 DAYS STARTING APR 1ST 2004 This solution selects the job to run every two days starting on April 1, ESP-5.5-EC-01

29 ESP Workload Manager examples Scheduling a job to run every two weeks and advancing it for holidays A job in an Application needs to run every two weeks on Friday. If this falls on a nonworkday, run the job on the previous workday instead. Use Friday, August 1, 2003 as the starting point for the schedule. Use the following run criteria for the job: RUN EVERY 2 WEEKS STARTING AUG 1ST 2003 LESS 0 WORKDAYS This solution selects the job to run every two weeks starting on Friday, August 1, If the Friday is a holiday, ESP Workload Manager selects the job to run on the previous workday instead. ESP-5.5-EC-01 17

30 Scheduling a job to run every two weeks and delaying it for holidays 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. Use the following run criteria for the job: RUN EVERY 2 WEEKS STARTING APR 7TH 2004 IFHOLIDAYPLUS 1 DAY This solution selects the job to run every two weeks starting on Wednesday, April 7, If the Wednesday falls on a holiday, ESP Workload Manager selects the job to run on Thursday instead. 18 ESP-5.5-EC-01

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

32 Scheduling a job on a random day of the month A job needs to run at 11 AM on a random day each month. 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 This Procedure runs on the last day of the month and determines when the job should run in the following month. GENTIME creates date and time variables, prefixed with NUM, for the next month. The NUMDD variable represents the number of days in the next month. This solution uses REXX to generate a random number between 1 and NUMDD. The Application builds with the job delayed for the random number of days at 11 AM. 20 ESP-5.5-EC-01

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

34 Scheduling an hourly job within a time range 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. One solution is to use a template within your Application definition. Take the following steps: 1. Use a template in your Application to define multiple instances of the job. For example: APPL CYBER JCLLIB 'CYBER.JCLLIB' TEMPLATE HOURLY (1,OFFSET) JOB A.%OFFSET RUN WORKDAYS DELAYSUB 8AM PLUS %OFFSET HOURS ENDTEMPL HOURLY 0 HOURLY 1 HOURLY 2 HOURLY 3 HOURLY 4 HOURLY 5 HOURLY 6 HOURLY 7 HOURLY 8 2. Schedule an Event prior to 8 AM that invokes this Application. This solution uses a template called HOURLY. Instead of creating separate job definitions for each instance of job A in the Application, the template defines the job requirements for all instances of the job in a few statements. The template accepts one parameter for the offset from 8 AM (0 hours, 1 hour, 2 hours, and so on). This offset is used as a job qualifier for the job to ensure uniqueness within each generation of the Application. It is also used in the DELAYSUB statement to specify the time dependency relative to 8 AM. 22 ESP-5.5-EC-01

35 ESP Workload Manager examples The code generated through calling the template is shown below: JOB A.0 RUN WORKDAYS DELAYSUB 8AM PLUS 0 HOURS JOB A.1 RUN WORKDAYS DELAYSUB 8AM PLUS 1 HOURS... JOB A.8 RUN WORKDAYS DELAYSUB 8AM PLUS 8 HOURS Note: If the Application contains only the one job that needs to run each hour, you can simply schedule the Event each hour between these times and invoke an Application containing the job to be run. ESP-5.5-EC-01 23

36 Scheduling a different job to run every hour A one-job Application runs each hour. The name of the job in the Application depends upon its scheduled time. The jobnames are called MYJOB followed by a letter of the alphabet which is based on the scheduled hour. At 1 AM use the letter A, at 2 AM use the letter B, and so on, as shown in the following table: Time Jobname 1 AM MYJOBA 2 AM MYJOBB 3 AM MYJOBC PM MYJOBW 12 AM MYJOBX Take the following steps: 1. Use the following Application: LETTERS='ABCDEFGHIJKLMNOPQRSTUVWX' INTEGER HOUR IF ESPSHH='00' THEN HOUR=24 ELSE HOUR=ESPSHH CHAR='%LETTERS(%HOUR:%HOUR)' APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB MYJOB%CHAR RUN ANY 2. Schedule an Event hourly to submit the one-job Application. The solution uses a symbolic variable called LETTERS, which is assigned a string representing the letters of the alphabet from A to X. Each hour, ESP Workload Manager uses a different substring of this variable based on the scheduled hour (ESPSHH). The HOUR variable is used as an integer variable to enable substrings since substring notation requires numbers and not characters. If the scheduled hour is midnight then ESPSHH has the value of 00, and the HOUR variable is assigned the value of 24 to 24 ESP-5.5-EC-01

37 ESP Workload Manager examples enable the correct substring. Otherwise, HOUR is assigned the value of the ESPSHH variable. The CHAR variable is assigned the letter to be used based on the scheduled hour. For example, at 4 AM, CHAR is determined by %LETTERS(4:4), which has the value D. Job MYJOBD is submitted. Variation If you want to use the same JCL member for all of the jobs, you can use a MEMBER statement for the job and specify this common member. For example: JOB MYJOB%CHAR RUN ANY MEMBER MYJOB In the MYJOB JCL member, you can use %ESPAPJOB in place of the job name. ESP Workload Manager substitutes the correct job name at the time of submission. For example: //%ESPAPJOB JOB ESP-5.5-EC-01 25

38 Scheduling a job in an Application to run based on day and time 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. Take the following steps: 1. Use the following statements for the job: JOB X IF TODAY('FRI') AND ESPSHH = '15' THEN RUN TODAY 2. Schedule an hourly Event to run the Application. For example: EVENT ID(PROD.HOURLY) SYSTEM(-) REPLACE SCHEDULE HOURLY DAILY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF 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). 26 ESP-5.5-EC-01

39 ESP Workload Manager examples Scheduling an ad hoc job to run multiple times 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. One solution is to use a task to dynamically insert the jobs. Take the following steps: 1. Use the following Application: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB INSERT.JOBS TASK SELFCOMPLETING RUN ANY TIME='%ESPAHH%ESPAMN%ESPASS' IF ESPREEXEC# LT 8 THEN DO ESP AJ %USER1..T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN) REEXEC AT('REALNOW PLUS 30 MINUTES') ENDDO 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') This solution uses a self-completing task named INSERT.JOBS to insert the ad hoc job every 30 minutes into this Application. A variable called TIME uniquely qualifies the job with a time stamp (actual hours, minutes, and seconds) as it is inserted into the Application. The Procedure uses the ESPREEXEC# built-in symbolic variable to check the number of re-executions, and does one of the following: If ESPREEXEC# is less than 8, the task issues an AJ command to insert another instance of the job. The task re-executes in 30 minutes. Otherwise, the task completes itself automatically. Note: The AJ command uses the ESPAPPL and ESPAPGEN variables to ensure the correct generation of the correct Application is used. This example inserts a z/os job. For an example of inserting a UNIX job at a regular interval, refer to Scheduling a job to run every two hours on page 29. ESP-5.5-EC-01 27

40 Example If you pass MYJOB as the USER1 variable and the actual time is , the jobnames are: MYJOB.T MYJOB.T MYJOB.T Variation The AJ command can also be prefixed with ESPNOMSG. For example: ESPNOMSG AJ %USER1..T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN) Using ESPNOMSG suppresses responses from the command (such as a message indicating the job was inserted). Warning and error messages are not suppressed. 28 ESP-5.5-EC-01

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

42 Scheduling a job to run multiple times within a time range 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. One solution is to use a template in your Application definition. A sample template is shown below: TEMPLATE MULTIRUN (1,TIME) UNIX_JOB A.%TIME AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS %TIME MINUTES RUN ANY ENDTEMPL REXXON DO I=0 TO 240 BY 10 "MULTIRUN "I END REXXOFF 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,..., ESP-5.5-EC-01

43 ESP Workload Manager examples The code generated through calling the template is shown below: UNIX_JOB A.0 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 0 MINUTES RUN ANY UNIX_JOB A.10 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 10 MINUTES RUN ANY... UNIX_JOB A.240 AGENT AGENT SCRIPTNAME /export/home/jsmith/scripts/a DELAYSUB 10PM PLUS 240 MINUTES RUN ANY Note: If the Application contains only the one job that needs to run every 10 minutes within the time range, you can simply schedule the Event every 10 minutes between these times and invoke an Application containing the job to be run. ESP-5.5-EC-01 31

44 Running ad hoc sequential jobs 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. 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 IF J2 = '' THEN JUMPTO JDONE JOB %J2 RUN ANY AFTER %J1 IF J3 = '' THEN JUMPTO JDONE JOB %J3 RUN ANY AFTER %J2 IF J4 = '' THEN JUMPTO JDONE JOB %J4 RUN ANY AFTER %J3 IF J5 = '' THEN JUMPTO JDONE JOB %J5 RUN ANY AFTER %J4 32 ESP-5.5-EC-01

45 ESP Workload Manager examples IF J6 = '' THEN JUMPTO JDONE JOB %J6 RUN ANY AFTER %J5 JDONE: EXIT Users can trigger an ad hoc Event and pass a list of 8-character jobnames as the USER1 parameter. The Procedure parses the USER1 parameter into jobnames, J1 to J6, and builds the Application of sequential jobs. AFTER statements are used to set up relationships between jobs, since the number of jobs to be run varies. The following shows the generated code and the Application that builds after specifying four jobnames in the USER1 field: USER1 Parameter CYBBP01A CYBBP01B CYBBP01C CYBBP01D Job Statements JOB CYBBP01A RUN ANY JOB CYBBP01B RUN ANY AFTER CYBBP01A JOB CYBBP01C RUN ANY AFTER CYBBP01B JOB CYBBP01D RUN ANY AFTER CYBBP01C Application CYBBP01A CYBBP01B CYBBP01C CYBBP01D ESP-5.5-EC-01 33

46 Variation There are many different ways you can adapt this approach. For example, you could have the user enter the jobnames into a panel or have the user update a data set. Either of these could cause a data set-triggered Event to invoke a Procedure similar to the one shown here. 34 ESP-5.5-EC-01

47 ESP Workload Manager examples Dynamically defining and scheduling an Event Job B needs to run at 9 PM 45 days after job A completes successfully. 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) REPLACE ESPNOMSG SCHEDULE 9PM TODAY PLUS 45 DAYS ONCE ESPNOMSG SUBMIT 'CYBER.JCLLIB(B)' ESPNOMSG ENDDEF The job monitor Procedure checks the return code for job A. If the return code is not 0, then the Procedure exits. Otherwise, the Procedure defines a one-time Event to execute at 9 PM 45 days later, which will submit job B. ONCE is used on the SCHEDULE statement so that the Event will be automatically deleted 24 hours after it has scheduled. ESP-5.5-EC-01 35

48 Scheduling a weekly Application based on the number of workdays in the week 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. Take the following steps: 1. Use the following Application: IF TODAY('FRI') THEN DO ESP TR %ESPEVENT ADD AT('16:00 TODAY PLUS 1 WORKDAY') EXIT ENDDO APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY 2. Schedule an Event for 4 PM on the 2nd last workday of each week. For example: EVENT ID(PROD.CYBER) SYSTEM(ESPM) REPLACE SCHEDULE LAST WORKDAY OF EACH WEEK LESS 1 WORKDAY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF 36 ESP-5.5-EC-01

49 ESP Workload Manager examples 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 are holidays and July 19 is a workday, then the week of July contains only one workday. When the Event schedules on July 15, the last workday of the next week less 1 workday is Friday July 16. On Friday, July 16, ESP Workload Manager retriggers the Event with the ADD option for the next workday, which will be July 19. The next scheduled occurrence after that will be the last workday of the following week less 1 workday (in other words, July 29). ESP-5.5-EC-01 37

50 Running the next scheduled Application early Run the next day s version of an Application today. 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. 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 ESP-5.5-EC-01

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

52 Delaying job submission until the next hour 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. One solution is to use an Application like that shown below: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RELEASE B RUN DAILY JOB B IF ESPREEXEC#=0 THEN - REEXEC AT('HOURLY ROUND STARTING REALNOW') RUN DAILY 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. 40 ESP-5.5-EC-01

53 ESP Workload Manager examples Setting up a dependency with a job s previous run 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: A X.MON B X.TUE Y 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. ESP-5.5-EC-01 41

54 The following is a sample Application: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY RELEASE B JOB B RUN DAILY RELEASE Y GENTIME PREV YESTERDAY JOB X.%PREVDAY(1:3) EXTERNAL SCHEDULED('YESTERDAY') - APPLID(CYBER) RUN DAILY RELEASE X.%ESPSDAY(1:3) JOB X.%ESPSDAY(1:3) RUN DAILY RELEASE Y JOB Y RUN DAILY 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 WAIT RUN DAILY RELEASE Y 42 ESP-5.5-EC-01

55 ESP Workload Manager examples Using date-qualified file names 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. On the FILENAME statement for the file trigger jobs, you can use built-in symbolic variables for the date and concatenate the literal at the end. For example: FILE_TRIGGER file1 RUN DAILY FILENAME /batch/interfaces/file1.%espsmm%espsdd%espsyy._ok 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/file _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 ESP-5.5-EC-01 43

56 Processing a changing file name 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 file The following Application shows how to define the file trigger job, CREATE, and the successor job, PROCESS. APPL CYBER AGENT AGENT FILE_TRIGGER CREATE RUN DAILY FILENAME /export/home/jsmith/scripts/file* CREATE RELEASE PROCESS UNIX_JOB PROCESS RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/echoit ARGS %ESPFTFILE The built-in variable, ESPFTFILE, is assigned a value of the full file name whenever file trigger activity takes place. You can pass this variable as an argument to the UNIX script run after the file trigger completes. Note: There is only one ESPFTFILE variable per generation of an Application. When additional file triggers take place in the same generation of the Application, the previous ESPFTFILE variable is overwritten. 44 ESP-5.5-EC-01

57 ESP Workload Manager examples Copying a file to another location upon the file s creation When a file is created, copy the file to another location. 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 COPYFILE AGENT AGENT FILE_TRIGGER CREATE RUN DAILY FILENAME C:\env.txt CREATE RELEASE COPY NT_JOB COPY RUN DAILY CMDNAME C:\Windows\system32\cmd.exe ARGS /C "copy C:\env.txt C:\test\env.txt" When the file is created, ESP Workload Manager completes the CREATE file trigger job and releases the COPY job. The COPY job uses the Windows command interpreter cmd.exe to copy the file to another location. To pass an argument to cmd.exe, such as the copy command in this example, enclose the argument in double quotation marks and precede the argument with the /C switch. Note: The path to the Windows command interpreter cmd.exe depends on your Windows operating system version. On Windows NT, the path would be C:\WINNT\system32\cmd.exe. For the path your Windows operating system uses, see your Windows administrator. For more information on running Windows operating-system commands using cmd.exe, see the CMDNAME statement in the ESP Workload Manager Reference Guide. ESP-5.5-EC-01 45

58 Ensuring a file exists before processing Check to ensure a file exists before processing it. If the file does not exist, run a script to create it. The dependencies look like this: CHECK4.FILE CREATE.FILE PROCESS.FILE The following Application shows how to define the different workload objects. APPL CYBER AGENT AGENT FILE_TRIGGER CHECK4.FILE CONDITIONAL RUN DAILY FILENAME /export/home/jsmith/scripts/myfile EXIST RELEASE (CREATE.FILE(A),PROCESS.FILE) UNIX_JOB CREATE.FILE CONDITIONAL RUN DAILY SCRIPTNAME /export/home/jsmith/scripts/create.file RELEASE PROCESS.FILE UNIX_JOB PROCESS.FILE RUN DAILY RELCOUNT 1 SCRIPTNAME /export/home/jsmith/scripts/process.file 46 ESP-5.5-EC-01

59 ESP Workload Manager examples This solution uses a file trigger job, CHECK4. FILE, to check for the existence of a file. There are two possible outcomes: The file trigger fails. This means the file does not exist. Job CREATE.FILE is released upon failure to create the file. Once this job completes, job PROCESS.FILE is released to process the file. At the end of the Application, job CHECK4.FILE is bypassed to enable the Application to complete. The file trigger completes successfully. This means the file exists. Job PROCESS.FILE is released to process the file. At the end of the Application, job CREATE.FILE is bypassed to enable the Application to complete. Job PROCESS.FILE uses RELCOUNT 1 because it can be run when either CHECK4.FILE or CREATE.FILE are successful. CHECK4.FILE and CREATE.FILE are conditional jobs. This allows them to be bypassed automatically, if necessary, at the end of the Application. ESP-5.5-EC-01 47

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

61 ESP Workload Manager examples Bypassing non-critical jobs when jobs are late 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. Using ESP Workload Manager, this bypass can be automatically scheduled by taking the following steps: 1. Define a link (for example, CRITICAL.POINT) as a successor to the important jobs. 2. Specify an overdue DUEOUT EXEC time for this link of 6AM. 3. Identify an Alert to be triggered if the link becomes overdue. 4. Define the Alert. 5. Set up an ESP Procedure invoked by the Alert Event to bypass the non-critical jobs. 6. Define the Alert Event to run the Procedure. Application Description In the following Application: Jobs A and B are important jobs and should be complete by 6 AM If they are not complete by 6 AM, then jobs C and E should be bypassed. ESP-5.5-EC-01 49

62 The Application looks like this: A B CRITICAL.POINT C D E F Application Definition The following is the definition of the Application: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY RELEASE CRITICAL.POINT JOB B RUN DAILY RELEASE CRITICAL.POINT JOB CRITICAL.POINT LINK RUN DAILY NOTIFY OVERDUE ALERT(CRIT) DUEOUT EXEC 6AM RELEASE (C,D,E) JOB C RUN DAILY RELEASE F JOB D RUN DAILY RELEASE F JOB E RUN DAILY RELEASE F 50 ESP-5.5-EC-01

63 ESP Workload Manager examples JOB F RUN DAILY 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) Jobs A and B are important jobs. Each of these jobs releases a link called CRITICAL.POINT. If CRITICAL.POINT is not complete by 6 AM, it becomes overdue and an Alert called CRIT triggers. The Alert runs an ESP Procedure that issues ESP AJ commands to bypass jobs C and E. This solution uses monitor variables for the Application name (%MNAPPL) and for the Application generation number (%MNAPPLGEN) to ensure the jobs are bypassed in the correct generation of the correct Application. ESP-5.5-EC-01 51

64 Taking different actions based on 1 of 3 successful return codes A monthly Application is scheduled for 10 AM on the last workday of each month. The first job, job A, can issue a return code of 0, 1, or 2. Different actions are required based on this return code, as described below. Return Code for Job A Action 0 Run job B 1 Complete Application and run it again at 10 AM the next workday 2 Cancel this month s run The requirements look like this: A Run job B Run again next workday Cancel this month's run The following is a sample Application you can schedule at 10 AM on the last workday of each month: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANYDAY RELEASE ADD(B) COND(RC(0)) RELEASE ADD(RUNAGAIN) COND(RC(1)) RELEASE ADD(CANCEL) COND(RC(2)) JOB B RUN ANYDAY 52 ESP-5.5-EC-01

65 ESP Workload Manager examples 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') JOB CANCEL LINK PROCESS RUN ANYDAY SEND 'THE PROCEDURE WILL RUN NEXT MONTH' U(*) ESP AJ ALL COMPLETE APPL(%ESPAPPL..%ESPAPGEN) 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. ESP-5.5-EC-01 53

66 Running different jobs based on the return code of a predecessor job Run job B if job A ends with a return code of 0, and run job C if job A ends with a return code of 1. The dependencies look like this: A 0 1 B C Use the following Application: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A CCCHK RC(2:4095) FAIL RUN DAILY RELEASE ADD(B) COND(RC(0)) RELEASE ADD(C) COND(RC(1)) JOB B RUN DAILY JOB C RUN DAILY Job A uses two conditional release expressions to release job B on return code 0 and job C on return code ESP-5.5-EC-01

67 ESP Workload Manager examples Auto-triggering an Event for a reoccurring job 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. Take the following steps: 1. Set up a one-job Application. Use a schedule frequency of RUN DAILY, and define the special job on hold. 2. Use a TRIGGER command within the scope of the JOB statement to retrigger the Event. For example: APPL HELDJOB JCLLIB 'CYBER.JCLLIB' JOB SPECIAL HOLD RUN DAILY ESPNOMSG TRIGGER %ESPEVENT 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. Once the first generation of the Application is built, an operator can release job SPECIAL from hold whenever it needs to run. This causes the job to run, and the TRIGGER command retriggers the same Event to build another generation with the job on hold again. ESP-5.5-EC-01 55

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

69 ESP Workload Manager examples Scheduling a cyclic Application 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. Take the following steps: 1. Use the following Application. APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A.T%ESPSHH RUN DAILY RELEASE B.T%ESPSHH JOB B.T%ESPSHH RUN DAILY... APPLEND RETRIG.EVENT RELDELAY 60 IF ESPAHH < '19' AND ESPSDATE=ESPADATE THEN - ESPNOMSG TRIGGER %ESPEVENT ADD 2. Schedule the following Event to run the Application: EVENT ID(PROD.CYBER) SYSTEM(-) REPLACE SCHEDULE DAILY INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF The Event is scheduled at midnight each day to run the first group of jobs. The Application uses a time-based qualifier to distinguish each group of jobs for ease of monitoring. ESP-5.5-EC-01 57

70 An APPLEND object, called RETRIG.EVENT, waits for all jobs in the Application to complete successfully before it retriggers the Event. It is automatically a successor to all jobs in the Application that do not have any successors. This allows you to add jobs to the Application without defining those jobs as predecessors to the object that will bring in the next generation. After all of the jobs have completed successfully, the RETRIG.EVENT object waits 60 minutes (RELDELAY 60) before it becomes ready. It then checks the actual time and if the time is before 7 PM on the same day, it re-triggers the original Event. The TRIGGER command with the ADD option is used so that the regular daily scheduled Event at midnight is not affected. 58 ESP-5.5-EC-01

71 ESP Workload Manager examples Incrementing a cycle number 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 The Application waits for two data sets to be created: BUS.BCnumber and RES.BCnumber, where number represents the cycle number. Take the following steps: 1. The cycle number is passed to the Event using a User Parameter. Use the following code to assign the value of the User Parameter to a variable called THIS_CYCLE. THIS_CYCLE=USER1 2. Define the two data set trigger jobs. Use %THIS_CYCLE as part of the data set names for these jobs. For example: BUS.BC%THIS_CYCLE and RES.BC%THIS_CYCLE. 3. Use a link at the end of the Application to increment the cycle number and trigger the next occurrence of the Event with the USER1 parameter as the new cycle number. 4. Use %THIS_CYCLE in the JCL for jobs that use the cycle number. ESP-5.5-EC-01 59

72 Application The following is a sample Application definition: APPL CYBER JCLLIB 'CYBER.JCLLIB' THIS_CYCLE=USER1 DSTRIG BUS RUN ANY DSNAME BUS.BC%THIS_CYCLE RELEASE A DSTRIG RES RUN ANY DSNAME RES.BC%THIS_CYCLE RELEASE A JOB A RUN ANY RELEASE Z JOB Z RUN ANY RELEASE CHANGE.CYCLE JOB CHANGE.CYCLE LINK PROCESS RUN DAILY /* INCREMENT 4-DIGIT CYCLE NUMBER AND RESET TO 1 AFTER 9999 INTEGER CYCLE CYCLE=THIS_CYCLE IF CYCLE=9999 THEN CYCLE=1 ELSE CYCLE=CYCLE+1 NEW_CYCLE='%CYCLE(F4)' ESPNOMSG TRIGGER %ESPEVENT USER1('%NEW_CYCLE') 60 ESP-5.5-EC-01

73 ESP Workload Manager examples The flow looks like this: File=RES.BC1234 File=BUS.BC1234 A Z CHANGE.CYCLE File=RES.BC1235 File=BUS.BC1235 You will need to trigger this Event manually the first time and pass the four-digit cycle number. After that, each new generation of the Application will be automatically triggered when one generation completes. 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 The link retriggers the Event and passes this new cycle number in the USER1 field. This enables the new cycle number to be used in the next generation of the Application. ESP-5.5-EC-01 61

74 Building Applications dynamically based on an input file 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. Use the following Application: APPL CYBER JCLLIB 'CYB.JCL' REXXON "ALLOCX DSN('CYBER.INPUT') F(INDD) SHR" IF RC \= 0 THEN DO "SEND 'UNABLE TO ALLOCATE CYBER.INPUT' U(USER01)" "EXIT" EXIT END ADDRESS z/os "EXECIO * DISKR " INDD "(STEM LINE. FINIS" IF LINE.0 = 0 THEN DO "SEND 'NO JOBS TO RUN' U(USER01)" "FREEX FILE("INDD")" "EXIT" EXIT END LAST = LINE.0 DO I = 1 TO LAST PARSE VAR LINE.I JOBNAME JOBNAME=STRIP(JOBNAME) "JOB "JOBNAME "RUN NOW" "" END "FREEX FILE("INDD")" REXXOFF You can schedule an Event to run the Application or set up a data set-triggered Event that runs when the input file is updated. 62 ESP-5.5-EC-01

75 ESP Workload Manager examples This solution uses REXX to read the input file. If the file is empty, a message is sent indicating that there are no jobs to run. If the file is not empty, each line is read and corresponding JOB statements are created. For example: CYBER.INPUT File ADHOCJ12 CLEANUP1... Application APPL CYBER JCLLIB 'CYB.JCL' JOB ADHOCJ12 RUN NOW JOB CLEANUP1 RUN NOW... ESP-5.5-EC-01 63

76 Running a job based on resource availability Run a job if only one unit of a resource is available, otherwise bypass the job. Use a task in an Application to check the resource availability prior to running the job. APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB CHKRES TASK SELFCOMPLETING REXXON PROC X=TRAPOUT('LINE.') "ESP RESDEF CART LIST" X=TRAPOUT('OFF') STATUS=SUBWORD(LINE.3,4) IF STATUS = 'Avail=1' THEN "ESP AJ B REQUEST APPL(CYBER.%ESPAPGEN)" REXXOFF RUN DAILY RELEASE B JOB B REQUEST RUN DAILY Note: 'Avail=1' must be entered in mixed case, exactly as shown above. Job B is defined as a REQUEST job. If job B is not explicitly requested, it does not run. This solution uses a task called CHKRES that does the following: Traps the output of the RESDEF command that lists the current status of the CART resource. Determines whether one unit of the CART resource is available. If one unit of CART is available, issues an AJ command that requests job B. Completes itself automatically. Note: The ESPAPGEN variable is used to ensure the AJ command is issued against the correct generation. 64 ESP-5.5-EC-01

77 ESP Workload Manager examples Running or completing a job based on the order in which its predecessors complete 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. This solution uses an Alert to check the status of the data set trigger when job A completes. The dependencies look like this: A WAIT4DS CHECK.STATUS B Take the following steps: 1. Set up an Application such that an Alert runs when job A ends. For example: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY RELEASE B NOTIFY JOBEND ALERT(CHCK) DSTRIG WAIT4DS DSNAME 'CYBER.THAT.DATASET' ANYCLOSE RUN ANY RELEASE B JOB B RUN ANY ESP-5.5-EC-01 65

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

79 ESP Workload Manager examples Scheduling a job based on a data set, time, and weekdays 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. The solution involves the use of a resource to control when the job runs. 1. Define a renewable resource. In this example, the resource is called CYBERDSN. 2. Set up an Application that submits the job. Use WAIT on the APPL statement. Use RUN ANYDAY as the run frequency for the job as the Application should build regardless of when the data set is created. Assign 1 unit of the CYBERDSN resource to the job. Set up the job to release a link that sets the availability of the CYBERDSN resource to 0. For example: APPL CYBER WAIT JCLLIB 'CYBER.JCLLIB' JOB A RESOURCE (1,CYBERDSN) RUN ANYDAY RELEASE CYBERDSN.OFF JOB CYBERDSN.OFF LINK PROCESS RUN ANYDAY ESPNOMSG RESDEF CYBERDSN SET AVAIL(0) 3. Set up a data set-triggered Event to wait for the data set and invoke the Application. For example: EVENT ID(PROD.CYBER) SYSTEM(ESPM) REPLACE INVOKE 'PROD.PROCLIB(CYBER)' DSTRIG CYBER.DATASET.G- ENDDEF ESP-5.5-EC-01 67

80 4. Set up Events to turn on the resource (in other words, set the Avail count to 1) at 22:30 weekdays, and turn off the resource (in other words, set the Avail count to 0) at 23:30 weekdays. For example: EVENT ID(PROD.CYBERDSN_ON) SYSTEM(ESPM) REPLACE SCHEDULE WEEKDAYS VS 'F ESP,RESDEF CYBERDSN SET AVAIL(1)' ENDDEF EVENT ID(PROD.CYBERDSN_OFF) SYSTEM(ESPM) REPLACE SCHEDULE WEEKDAYS VS 'F ESP,RESDEF CYBERDSN SET AVAIL(0)' ENDDEF Two Events and a link control the availability of the resource: At 22:30 on weekdays, an Event is scheduled that issues the RESDEF command to make the resource available. At 23:30 on weekdays, an Event is scheduled that issues the RESDEF command to make the resource unavailable. After the job completes successfully, a link issues the RESDEF command to make the resource unavailable. This ensures the job only runs between 22:30 and 23:30 on weekdays. Also, once the job runs, the link sets the resource to 0. This ensures the job will run only once a day. If another generation of the Application has been created when one generation completes, then the job waits for the resource to be available the next weekday. 68 ESP-5.5-EC-01

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

82 Identifying critical jobs for disaster recovery planning 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. Take the following steps: 1. Define a special day in your calendar. As there must be at least one entry in the calendar for this special day to avoid syntax errors on simulation, reference a date in the future. For example: DEFSPEC DISASTER ON('MAY 16, 2040') CALENDAR(SYSTEM) 2. Use a NORUN DISASTER statement in the Application for all jobs deemed to be non-essential. For example: JOB B RUN DAILY NORUN DISASTER RELEASE (C) Using this solution, you can identify which jobs should not run in the case of a disaster. In the event of a real disaster or a disaster test, another occurrence of the special day can be added with the appropriate date. When the Application builds, jobs with NORUN DISASTER will not be selected to run. You can simulate your Application for the DISASTER date to verify the correct selection of jobs. 70 ESP-5.5-EC-01

83 ESP Workload Manager examples Using a one-time job section in Applications 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. The following Application shows a ONE_TIME_CHANGES section that you can use for temporary changes. APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN DAILY DELAYSUB 5PM RELEASE B JOB B RUN DAILY RELEASE C /* USE THIS SECTION FOR ONE-TIME CHANGES ONE_TIME_CHANGES: JOB A IF TODAY('APR 23, 2004') THEN - DELAYSUB 7PM You can use the same JOB statement in an Application. When the Application builds, the Job statements for the same job are merged together in the order in which they are read. The Procedure in this solution shows a ONE_TIME_CHANGES section that allows you to override requirements temporarily. This section could be in the same Application or it could be invoked as a separate PDS member after invoking the Application. ESP-5.5-EC-01 71

84 In this example, job A has a DELAYSUB time of 7PM on April 23, This overrides its normal DELAYSUB time of 5PM on that day only. JOB A RUN DAILY DELAYSUB 5PM RELEASE B... JOB A IF TODAY('APR 23, 2004') THEN DELAYSUB 7PM JOB A RUN DAILY DELAYSUB 5PM RELEASE B IF TODAY('APR 23, 2004') THEN DELAYSUB 7PM 72 ESP-5.5-EC-01

85 ESP Workload Manager examples Using the same Application for different locations Use the same Application to process work for different processing locations, even where there are different job requirements for each location. 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%DC JCLLIB 'CYBER.JCLLIB' JOB RG%DC.A EARLYSUB 8PM RUN DAILY RELEASE (RG%DC.B) JOB RG%DC.B RUN DAILY RELEASE (NEW%DC.A) UNIX_JOB NEW%DC.A AGENT CYBER%DC SCRIPTNAME /export/home/demo/scripts/xyz RELEASE (NEW%DC.B) IF DC = 'CH' THEN RUN DAILY... ESP-5.5-EC-01 73

86 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) 74 ESP-5.5-EC-01

87 ESP Workload Manager examples Merging Applications into a single PDS member Merge ad hoc Applications into a single PDS member in situations where small Applications are requested periodically. Take the following steps: 1. The following ESP Procedure shows a technique to merge Applications into a single PDS member: IF %USER1 = '' THEN EXIT JUMPTO %USER1 PAYREQ: APPL PAYREQ JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY RELEASE B JOB B RUN ANY EXIT FINREQ: APPL FINREQ JCLLIB 'CYBER.JCLLIB' JOB X RUN ANY EXIT 2. Set up an Event to invoke this Procedure. 3. You can manually trigger this Event and pass the name of the Application you want to run using the USER1 parameter. ESP-5.5-EC-01 75

88 This solution uses labels in the Application with the same names as the ad hoc Applications. The JUMPTO statement, with the USER1 parameter, causes the Application you specify to be generated. For example, if you trigger the Event and specify FINREQ as the USER1 parameter, then only the FINREQ Application is built. Note: It is important to code the EXIT statement between Application definitions, otherwise multiple Applications could be generated when triggering the Event. This allows you to put many of your requested Applications in one PDS member, instead of having numerous Events and PDS members. 76 ESP-5.5-EC-01

89 ESP Workload Manager examples Consolidating data set triggers to minimize the number of Event definitions 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. Take the following steps: 1. Set up the data set-triggered Event. This Event waits for the closure of any one of three different data sets: EVENT ID(PROD.CYBER) DSTRIG CYBER.PROD.SERVICES.CLASS1.G- ANYCLOSE DSTRIG CYBER.PROD.SERVICES.CLASS2.G- ANYCLOSE DSTRIG CYBER.PROD.SERVICES.CLASS3.G- ANYCLOSE INVOKE 'PROD.PROCLIB(CYBER)' ENDDEF 2. Use the following job definition to extract either the GDG base for GDG data sets, or the full data set name for non-gdgs, and submit the job: JOB A RUN ANY INTEGER SIZE ID=0 DSN=ESPTRDSN SIZE=LENGTH(%DSN) V00=SUBSTR(%SIZE-2,3,%DSN) GDG=SUBSTR(%SIZE-7,1,%DSN) IF V00='V00' AND GDG='G' THEN CHECK=SUBSTR(1,%SIZE-9,%DSN) ELSE CHECK=%DSN IF %CHECK= 'CYBER.PROD.SERVICES.CLASS1' THEN ID=1 IF %CHECK= 'CYBER.PROD.SERVICES.CLASS2' THEN ID=2 IF %CHECK= 'CYBER.PROD.SERVICES.CLASS3' THEN ID=3 3. Tailor the JCL using %INCLUDE statements: //A JOB %INCLUDE IF(ID=1) //STEP1 DD DSN=CYBER.PROD.SERVICES.CLASS1(0) %INCLUDE IF(ID=2) //STEP2 DD DSN=CYBER.PROD.SERVICES.CLASS2(0) %INCLUDE IF(ID=3) //STEP3 DD DSN=CYBER.PROD.SERVICES.CLASS3(0) %ENDINCL ESP-5.5-EC-01 77

90 All of the data set triggers are coded in one Event, minimizing the number of individual Event definitions required. The code determines the length of the data set name, checks if the data set name is a GDG, and parses it into the GDG base and the generation number. %INCLUDE statements are coded in the JCL to tailor which data set is included for each run of the job. Note: Although the names of the data sets are the same length in this example, this code can be used regardless of the length of the data set name. 78 ESP-5.5-EC-01

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

92 Resubmitting a failed job a maximum of two times 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. 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 CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY MONITOR CYBER RELEASE CHECK.A IF ESPAPSUB# GT 2 THEN DO ESP AJ CHECK.A READY APPL(CYBER.%ESPAPGEN) QUIT ENDDO JOB CHECK.A TASK SELFCOMPLETING RUN ANY REXXON PROC J=JOBONCSF('A','X') DO I=1 TO J IF XAPPL.I ='CYBER' & XSTATUS.I ='Submit Error, Quit' THEN "ESP AJ A COMPLETE APPL(CYBER.%ESPAPGEN)" END REXXOFF 2. Set up a JOBEND job monitor Event for job A that invokes the following Procedure: IF MNRC NE 0 THEN - ESP AJ %MNJOB RESUBMIT APPL(%MNAPPL..%MNAPPLGEN) 80 ESP-5.5-EC-01

93 ESP Workload Manager examples A job monitor Event is triggered when the job ends. This Event invokes a Procedure to check the return code. If the return code is not equal to 0, the Procedure issues an AJ command to resubmit the job. IF logic within the definition for the job checks the resubmission number (ESPAPSUB#). If job A has been submitted three times, the CHECK.A task is readied and a QUIT statement is processed. This causes the third submission of the job to get a submit error. When the CHECK.A task is readied, the JOBONCSF built-in function checks if the job status is Submit Error, Quit. If so, the job is forced complete and the task completes. ESP-5.5-EC-01 81

94 Providing notification when a job exceeds its maximum run time Send a message if a job exceeds its maximum run time. Use a MAXRUNTIME statement and a NOTIFY statement for the job. For example: APPL CYBER UNIX_JOB A RUN DAILY MAXRUNTIME=5 NOTIFY OVERDUE USERS(USER01) AGENT AGENT SCRIPTNAME /u1/prod/scripts/a 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 USER ESP-5.5-EC-01

95 ESP Workload Manager examples Providing notification for a long-running Application 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. Take the following steps: 1. In the Application, use a link with a DELAYSUB time of 8AM TOMORROW. The link has no job dependencies. 2. Use a SEND command to send a message when the link becomes ready. 3. Define the link as a conditional job, as it may or may not run. For example: JOB STILL.RUNNING LINK PROCESS CONDITIONAL RUN DAILY DELAYSUB 8AM TOMORROW SEND '%ESPAPPL IS STILL RUNNING' U(*) The link, which has no dependencies other than time, issues a message at 8 AM the next day if the Application is still processing. There are two possible results: If all other jobs in the Application are complete prior to 8 AM the next day, the link is bypassed (since it is a conditional job), and the Application completes. Otherwise, if jobs are still processing at 8 AM the next day, a message is sent at that time. ESP-5.5-EC-01 83

96 Providing notification if a job is late starting relative to a data set closure Provide notification if a job has not started 10 minutes after being invoked as a result of a data set trigger. Take the following steps: 1. Use a DUEOUT INPUT statement and a NOTIFY statement in the Application that contains the job, as shown below: APPL CYBER JCLLIB 'CYBER.JCLLIB' JOB A RUN ANY DUEOUT INPUT REALNOW PLUS 10 MINUTES NOTIFY OVERDUE USERS(USER1) 2. Use a data set-triggered Event that invokes the Application. EVENT ID(PROD.CYBER) INVOKE 'PROD.PROCLIB(CYBER)' DSTRIG CYBER.PROD.DSN123 ANYCLOSE ENDDEF The DUEOUT INPUT statement indicates the job is due out from the JES input queue (in other words, the job has started) 10 minutes after the data set is closed. The NOTIFY statement causes a message to be sent to a user if the job becomes overdue. 84 ESP-5.5-EC-01

97 ESP Workload Manager examples Sending notification for job failures Automatically send an if any job within Application CYBER fails. Take the following steps: 1. Set up a MAILLIST data set that contains the SMTPPARM parameter and one or more MAILBOX parameters. The following example specifies a MAILBOX called OPER that contains one address. SMTPPARM CLASS(A) JOBNAME(SMTP) MAILBOX OPER MAXLINES(50) [email protected] 2. In your Application, use the MAILBOX parameter on the NOTIFY statement, as shown below: APPL CYBER JCLLIB 'CYBER.JCLLIB' NOTIFY FAILURE MAILBOX(OPER) JOB A RUN DAILY 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 address to notify. For more information on implementing mailboxes in your environment, see the ESP Workload Manager Installation and Configuration Guide. ESP-5.5-EC-01 85

98 Variation Alternatively, ESP Workload Manager can submit a batch job from an Alert or job monitor Event. The following is some sample JCL you can use: //SENDMAIL JOB //STEP1 EXEC PGM=IEBGENER //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //SYSUT2 DD SYSOUT=(B,SMTP) //SYSUT1 DD * HELO ESP MAIL FROM: <ESP53@LOCALHOST> RCPT TO: <[email protected]> DATA FROM: ESP TO: [email protected] SUBJECT: JOB FAILURE NOTIFICATION JOB %MNJOB IN APPLICATION %MNAPPL %ESPATIME WITH A COMPLETION CODE OF %MNMXRC.. QUIT /* JCL is coded to send an via SMTP. Job monitor variables and built-in variables are passed to the JCL. These variables are resolved when the is sent informing the recipient with the name of the job that failed, the Application to which the job belongs, the time of the failure, and the maximum return code. 86 ESP-5.5-EC-01

99 ESP Workload Manager examples Sending a message when an Agent becomes inactive If a particular Agent becomes inactive, send a message to alert a user that the Agent is inactive. Take the following steps: 1. In an Application, define an AGENT_MONITOR workload object. Use the AMNOTIFY statement to trigger an Alert when the Agent becomes inactive. For example: APPL AGENTMON AGENT_MONITOR CYBUSER.WINR6SP2 AGENT WINR6SP2 AMNOTIFY EVENT(CYBUSER.AGENT_INACTIVE) STATINTV 5 MSGQLEN Define the Event to send a message to a user. For example: EVENT ID(CYBUSER.AGENT_INACTIVE) ADD SEND 'AGENT INACTIVE' USER(CYBUSER) ENDDEF When the WINR6SP2 Agent becomes inactive, ESP Workload Manager triggers an Event, CYBUSER.AGENT_INACTIVE, which sends a message to a user. The status checks occur every five minutes. The CYBUSER.WINR6SP2 workload object stores the last 10 status messages as defined by the MSGQLEN statement. ESP-5.5-EC-01 87

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

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

102 Holding all incomplete generations of an Application 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. Use the following CSF extension: /* REXX */ X = OUTTRAP("line.") "LAP" Applname() X = OUTTRAP("OFF") j= line.0 DO i = 1 TO j IF line.i = "" THEN ITERATE PARSE UPPER VAR line.i verb therest IF verb = "APPL" THEN DO PARSE VAR therest.. applgen. Applgen = STRIP(applgen) QUEUE "AJ ALL HOLD APPL(" Applname() "." Applgen ")" END END J = QUEUED() DO I = 1 TO J PULL X SAY "ISSUING: " X X END The CSF extension facility allows you to add or replace CSF line commands for your installation. For this CSF extension, if you add a new command called HAA, then issuing HAA against a job in CSF does the following: Retrieves the Application name to which the job belongs. Lists all incomplete generations of the Application. Issues a HOLD command for each of those generations. 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. 90 ESP-5.5-EC-01

103 ESP Workload Manager examples Listing a job plus its successor chains in an active Application 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. Use the following CSF extension: /* REXX */ /* Command Name: LAS */ /* CSF extension to list all successor jobs to current job */ X = Retscbd() /* Issue a SIMULATE command, trapping the output.use the ROOT */ /* keyword to generate a list of current job plus successors */ X = Outtrap( LINE. ) "SIMULATE EV("Event()") SCHED('"Sched"') ROOTJOB("Job()"+), NOLISTPROC" X = Outtrap("OFF") Do i = 1 to Line.0 if pos('job TYPE',Line.i) > 0 then leave End say "The following is a display of job" job(), "and its successors:" say "" Do j = i to Line.0 Say Line.j End The CSF extension facility allows you to add or replace CSF line commands for your installation. This CSF extension allows you to issue a command against a job, and the result is a display of that job plus all successor jobs for that particular generation of the Application. The CSF extension issues a SIMULATE command for that instance of the Event and passes the jobname as a root job. Note: This display does not include jobs inserted after the Application was built. ESP-5.5-EC-01 91

104 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), *** 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. 92 ESP-5.5-EC-01

105 ESP Workload Manager examples Creating a variable for the day of week number Jobs in an Application use a one-digit day-of-week number that begins with 1 on Wednesday and ends with 7 on Tuesday. 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. 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 ESP-5.5-EC-01 93

106 Creating a variable for the accounting year 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 GENTIME AC LAST DAY OF ACCT_YEAR 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, The accounting year for the year 2005 begins on October 2, 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 The simplest way to determine this is to use GENTIME to generate date and time variables for the last day of the accounting year. This will always give you the actual accounting year no matter what the date is in the actual year. You can then use the %ACYEAR variable, from the GENTIME, as you choose. 94 ESP-5.5-EC-01

107 ESP Workload Manager examples Calculating the week number 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. One solution is to define a special day that represents the start of each fiscal year. In this example, the criteria is the same each year, and you can use the DEFSPEC command to define many instances at once. The following command defines 11 instances of FISCAL_YEAR in the SYSTEM calendar, with each instance being retained for 2 years. DEFSPEC FISCAL_YEAR REPEAT('10 TIMES 1ST SUNDAY OF YEAR PLUS 9 DAYS STARTING TODAY') CALENDAR(SYSTEM) RETAIN(2,YEARS) To calculate the week number, use the following code: /* USING FISCAL_YEAR SPECIAL DAY WK=DAYS_BETWEEN('1ST DAY OF FISCAL_YEAR STA TODAY',- 'TOMORROW','TUESDAY'); Each FISCAL_YEAR starts on a Tuesday (for example, 9 days after the 1st Sunday of the year).the solution uses the DAYS_BETWEEN function to calculate the number of instances of Tuesday between the first day of the fiscal year (inclusive) and tomorrow (exclusive). The result is the week number, and it is assigned to a variable called WK. Variation Without defining a special day to represent the beginning of each fiscal year, you can use the following code to calculate the week number. INTEGER STYEAR,XX,N GENTIME LY TODAY LESS 1 YEAR GENTIME FY FIRST SUNDAY OF YEAR PLUS 9 DAYS STARTING TODAY N=DAYS_TO('%FYDATE') IF N>0 THEN STYEAR=LYYEAR ELSE STYEAR=ESPSYEAR GENTIME W FIRST SUNDAY OF YEAR PLUS 9 DAYS - STARTING JAN 1 %STYEAR WK=DAYS_BETWEEN('%WDATE','TOMORROW','TUESDAY') The code determines on which year to base the calculation. If the number of days to the first Sunday of the year plus 9 days is positive, then the current fiscal year started ESP-5.5-EC-01 95

108 in the previous calendar year. Otherwise, the current fiscal year started this year. GENTIME generates date and time variables for the 1st day of the fiscal year. The DAYS_BETWEEN function is then used as in the first solution. 96 ESP-5.5-EC-01

109 ESP Workload Manager examples Providing a variable for all data sets in a DSTRIG Event 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. This solution uses a global variable table to store the names of the data sets. An example using two data sets and a global variable table called MYTAB is shown below. For example, suppose you have the following data set-triggered Event that waits for all of the required data sets (as indicated by the MULTIPLE keyword), and invokes a Procedure called MAIN. EVENT ID(PROD.MAIN) INVOKE 'PROD.PROCLIB(MAIN)' DSTRIG 'PROD.FILE1.G-' MULTIPLE DSTRIG 'PROD.FILE2.G-' MULTIPLE ENDDEF Take the following steps: 1. Define a global variable table. This example uses a table called MYTAB. For example: VTDEFINE MYTAB 2. Define a data set-triggered Event for each required data set. Each Event invokes a Procedure that issues a VSET command to update the global variable table with the name of the data set that causes the trigger to occur. For example: Event EVENT ID(PROD.DSN1) INVOKE 'PROD.PROCLIB(DSN1)' DSTRIG 'PROD.FILE1.G-' ENDDEF Procedure VSET DSN1 %ESPTRDSN TABLE(MYTAB) Event EVENT ID(PROD.DSN2) INVOKE 'PROD.PROCLIB(DSN2)' DSTRIG 'PROD.FILE2.G-' ENDDEF ESP-5.5-EC-01 97

110 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) 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). 98 ESP-5.5-EC-01

111 ESP Workload Manager examples Running jobs using ESP Encore s SCAN mode 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. In your Application, you can include statements to invoke Encore in SCAN mode and then provide notification of any problems. 1. Use the following statements in your Application: OPTIONS RESTARTSTEP to add a restart step to the jobs. ENCPARM MODE SCAN to run Encore in SCAN mode. NOTIFY FAILURE ALERT(alert_id) to trigger an Alert Event for job failures. For example: APPL CYBER JCLLIB 'CYBER.JCLLIB' OPTIONS RESTARTSTEP ENCPARM MODE SCAN NOTIFY FAILURE ALERT(SCAN) JOB A RUN DAILY RELEASE B JOB B RUN DAILY 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(*) 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. ESP-5.5-EC-01 99

112 Setting COPYJCL as the default JCL library for resubmission Set COPYJCL as the default JCL library for job resubmission. 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' When a job is submitted, the submission number (ESPAPSUB# variable) is checked. If the submission number is greater than 1, the TEMPLIB statement points to the COPYJCL library, and ESP Workload Manager uses JCL from this library for job resubmission. Note: You can override this library, as required, when you resubmit the job (for example, on the Job Resubmission panel). 100 ESP-5.5-EC-01

113 ESP Workload Manager examples Using date-qualified TEMPLIBs 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. Use the following IF statement in your Application: IF DAYS_FROM('%ESPADATE') LE 7 THEN - TEMPLIB 'PROD.TEMPLIB.D%ESPSMM%ESPSDD%ESPSYY' If the difference between the simulation date and the actual date is less than 7 days, then the TEMPLIB is read in. Otherwise, it is not. This allows you to simulate the Application for any future date even though the TEMPLIB data set may not yet be created. ESP-5.5-EC

114 102 ESP-5.5-EC-01

115 Index Symbols %INCLUDE statements, 77 Numerics 1st day of month, 10 2nd last workday of week, 36 5 Fridays in month, 3 A accounting year, 94 ad hoc Applications, 75 jobs, 27, 32, 62 adding Event schedule, 37, 58 adjusting for holidays, 2, 13, 17, 18 advancing schedule, 38, 39 Agent name, as a variable, 73 Agent, sending message when inactive, 87 AGENT_MONITOR workload object, 87 AJ command bypassing a job, 48, 51, 89 completing a job, 66, 99 completing a task, 29, 48, 64 completing an Application, 53 holding an Application, 90 inserting a job, 27 requesting a job, 64 resubmitting a job, 79, 81 Alert Encore s SCAN mode, 99 job resubmission, 79 sending message, 87 APPLEND workload object, 58 Application name built-in variable, 27, 29, 53, 69, 83 in script path, 69 variable, 69, 73 Application status, 83 after 24 hours, 83 LAP command, 56 Applications based on input file, 62 common, 73 holding all generations, 90 hourly, 21, 24 merging, 75 APPLINS command, 29 ESP-5.5-EC

116 argument, passing to script, 59 automatic bypass, 49, 54, 83 Event trigger, 55, 61 resubmission of job, 79 B batch job, to send , 86 between dates, 6 times, 30 bi-weekly job, 17, 18 built-in functions DAYS_BETWEEN, 95 DAYS_FROM, 6 DAYS_TO, 4, 6 JOBONCSF, 48, 89, 90 TODAY, 7 built-in variables ESPAPGEN, 27, 29, 48, 53, 64, 66, 80 ESPAPJOB, 25 ESPAPPL, 27, 29, 53, 69, 83 ESPAPSUB#, 100 ESPEVENT, 36, 55 ESPREEXEC#, 40, 79 ESPSDOW#, 93 ESPSHH, 24, 26 ESPTRDSN, 97 monitor, 79 return code, 35, 54 scheduled hour, 24 USER1, 27, 32, 61, 75 bypassing conditional job, 83 job across Applications, 89 job based on another job s status, 48 job based on return code, 54 non-critical jobs, 49 C calendar quarter, 19 cmd.exe, 45 common Applications, 73 JCL member, 25, 74 comparing GENTIME dates, 9, 13, 14, 15 completing a task self-completing, 27, 48, 64, 81 with link, 29 concatenating variables, 43 conditional jobs, 47, 83 conditional release expressions, 53, 54 consolidating Applications, 75 data set triggers, 77 converting numbers and strings, 61 to lowercase, 69 copying file, 45 COPYJCL library, 100 CSF extension bypassing jobs, 89 holding all generations of an Application, 90 listing job details, 88 listing successors, 91 current period, 94 cycle number, 59 cyclic Application, 57 D data set dependency, 59 data set-trigger built-in variable, 97 Event, 77, 97 job, 65 date range, 6 date-qualified file name, 43 TEMPLIB, 101 day of week number, 93 DAYS_BETWEEN function, 95 DAYS_FROM function, 6, 93 DAYS_TO function, 4, 6 default library, job resubmission, 100 defining Alert, 49, 79 global variable table, 97 special day, 95 delaying job based on holidays, 13 based on workday status, 9 random number of days, 20 relative delay, 40, 58 resubmission, 79 submit time, ESP-5.5-EC-01

117 Index until next hour, 40 different actions, based on return code, 52 different jobs calendar quarter, 19 each generation, 27 each hour, 24 disaster recovery, 70 displaying job details from CSF, 88 successor jobs, 91 DUEOUT statement, 84 dynamically generated Applications, 62 E early run of Application, 38, 39 batch job, 86 notification, 85 ESP Encore, 99 ESPAPGEN variable, 27, 29, 48, 53, 64, 66, 80 ESPAPJOB variable, 25 ESPAPPL variable, 27, 29, 53, 69, 83 ESPAPSUB# variable, 100 ESPEVENT variable, 36, 55 ESPFTFILE variable, 44 ESPNOMSG command, 28 ESPREEXEC# variable, 40 ESPS* variables, 43 ESPSDOW# variable, 93 ESPSHH variable, 24, 26 ESPTRDSN variable, 97 Event data set-triggered, 77, 97 defined from Procedure, 35 retrigger, 37, 55, 58, 61 sending message to user, 87 trigger, 38, 39 trigger, with USER1 parameter, 27 Event name built-in variable, 36, 55 standard, 74 substring, 74 every 10 minutes, 30 2 days, 16 2 hours, 29 2 weeks, 17, minutes, 27 5 minutes, 56 EVERY run criteria, 16, 17, 18 except criteria, 2 existing file, 46 EXIT statement, 76 external job, 41 F failed job automatic resubmission, 80 Encore s SCAN mode, 99 file trigger, 47 notification, 85 file dependency, 43, 44, 45, 46 file name built-in variable, 44 changing, 44 date-qualified, 43 file trigger object, 43, 44, 45, 46 fiscal year, 95 five Fridays in month, 3 future schedule, 38, 39 G GDG-based data sets, 77 generation number, built-in variable, 27, 29, 48, 53, 64, 66, 80 generic Application, 73 GENTIME command 5th last workday of month, 11 comparing dates, 9, 13, 14, 15 day of week, 10 previous date/criteria, 15 global variable table, 97 H held job, 55 holding, all generations of an Application, 90 holiday scheduling, 2, 4, 5, 13 holiday status, 15 hourly Application, 21 Event, 26 job, 22 jobs, 24 ESP-5.5-EC

118 I IFHOLIDAYPLUS run criteria, 13, 18 impact on successor jobs, 91 incrementing cycle number, 59 input file, 62 inserting ad hoc job, 27 UNIX job, 29 J JCL common member, 25, 74 notification, 86 JCL errors, 99 JCL library, for job resubmission, 100 JCL tailoring, 77 job definitions, merging, 71 job monitor Event, 35, 81 job resubmission, 79, 80, 100 job selection replaced schedule, 38, 39 simulating, 70 job status using JOBONCSF, 48, 89 when QUIT encountered, 81 JOBEND Event, 35, 81 jobname based on hour, 24 built-in variable, 25 variable, 73 JOBONCSF function, 48, 89, 90 L LAP command, 56, 88, 89, 90 last 5 workdays of month, 11 day of period, 94 day of previous month, 14 workday of previous month, 14 late completion time, 82 leading zeroes, 61 less 0 workdays, 2, 17 libraries COPYJCL, 100 TEMPLIB, 100, 101 link completing Application, 53 increasing cycle number, 59 overdue time, 49 retrigger Event, 53, 59 setting resource, 67 submit time, 83 listing successor jobs, 91 long-running Application, 83 lowercase, 69 M MAILBOX parameter, 85 maintaining job definitions, 71 maximum run time, 82 MAXRUNTIME statement, 82 MEMBER statement, 25, 74 merging Application definitions, 75 job definitions, 71 MNRC variable, 35, 54 Mondays except holidays, 2 monitor variables, 79 monthly job, 10 multiple data sets, 97 multiple runs of a job, 30 N non-critical jobs, 49, 70 non-existent file, 47 NORUN criteria, 2, 5, 70 notification failed job, 85 long-running Application, 83 overdue job, 82 NOTIFY statement, 82, 84, 85 O ONCE criteria, 39 one-time changes, 71 Event, 35, 39 on-request job, 32, 55, 64 order of predecessor completion, 65 ordinal numbers, 7, 9, 10 overdue job, 84 link, ESP-5.5-EC-01

119 Index notification, 82 overriding DELAYSUB time, 72 library for job resubmission, 100 P parsing input file, 62 output, using SUBWORD, 56, 64 path to UNIX scripts, 69 plus 0 workdays, 2, 9, 15 preventing backlog of Applications, 56 previous date, 15 month, 14 run of a job, 41 Q quarterly jobs, 19 QUIT statement, 81 R random schedule, 20 range date, 6 day, 7 time, 21, 22 reading input file, 63 recovery, from disaster, 70 REEXEC command, 40, 79 re-executing a Procedure, 40, 79 re-execution number, built-in variable, 40 relative time delay, 40, 58 RELCOUNT statement, 47 RELDELAY statement, 58 releasing job based on predecessor s return code, 54 from hold, 55 replacing next scheduled Event, 38 scheduled Event, 39 request job, 32, 64 resource availability, 67 dependency, 68 status, 64 resubmitting a job 2 times, 80 from COPYJCL, 100 with time delay, 79 retriggering Event, 37, 55, 58, 61 return code checking, 52 dependency, 54 variable, 35, 54 REXX converting to lower case, 69 CSF extensions, 88, 89, 90 job status, 48, 66, 81 multiple runs of a job, 30 random number, 20 reading file, 62 resource status, 64 trapping output, 56, 64 running an Application early, 38, 39 S Saturday, after special day, 8 SCAN mode, ESP Encore, 99 scheduled hour, 24, 26 resume of Event, 21 suspend of Event, 21 time variables, 24 script path, 69 self-completing task, 27, 48, 64, 81 sequential jobs, ad hoc, 32 setting resources, 68 similar jobs, 73 simulation error, TEMPLIB, 101 special day, 8, 70 special period, 94 start of month, 10 subapplication WAIT, 42 submission number, built-in variable, 100 substring alphabet, 24 Event name, 74 successor jobs, listing, 91 suppressing response, ESPNOMSG, 28 T task ESP-5.5-EC

120 checking job status, 48, 80 checking resource status, 64 completing with link, 29 inserting jobs, 27, 29 self-completing, 27, 48, 64, 81 template, 22, 30 TEMPLIB statement, 100, 101 temporary changes, 71 temporary library, 100, 101 time and date stamp, 44 delay, 40, 58 qualifier, 27 range, 21, 22 window, 67 time-based job, 26 TODAY function, 7 trapping output, 56, 64 TRIGGER command ADD option, 37, 58 REPLACE option, 38, 39 within Application, 55, 58 triggering Event adding schedule, 37, 58 one-time Event, 39 replacing schedule, 38, 39 with USER1 parameter, 27, 32, 61, 75 U updating, global variable table, 98 user parameter, 61 USER1 parameter, 27, 32, 61, 75 USER1 variable, 61 V variable based on special period, 94 cycle number, 59 day of week number, 93 file name, 43 in JCL, 74 padding with zeroes, 61 part of Agent name, 73 part of Application name, 73 part of jobname, 24 variable resolution, replaced schedule, 38, 39 variables, built-in Application name, 27, 29, 53, 69, 83 data set trigger, 97 date, 43 day of week number, 93 Event name, 36, 55 file name, 44 generation number, 27, 29, 48, 53, 64, 66, 80 jobname, 25 monitor, 79 re-execution number, 40, 79 return code, 35, 54 submission number, 100 USER1, 27, 32, 61, 75 VGET command, 98 VSET command, 97 VTDEFINE command, 97 W WAIT options, 42 week number, 95 weekly job, within date range, 6 window, time, 67 Windows command interpreter, 45 within criteria, 3 workday scheduling advance/delay/ignore, 2 advancing, 17 day of month, 9 delaying, 18 last 5 workdays of month, 11 number of workdays in week, 36 range, 7 workday status, 5, ESP-5.5-EC-01