Upload
others
View
18
Download
0
Embed Size (px)
Citation preview
ESP Workload Manager Version 5.4
User’s Guide
ESP-5.4-UG-05
Fifth Edition (April 2005)
This edition applies to Version 5 Release 4 of ESP Workload Manager documentation. The software and related manuals are protected by copyright law.
Trademark Notice
Cybermation and ESP Workload Manager are registered trademarks of Cybermation, Inc.
IBM, AS/400, and z/OS are registered trademarks of IBM.
All other brand and product names are trademarks or registered trademarks of their respective companies.
ESP Workload Manager documentation© 2005 Cybermation Inc. All rights reserved.
No portion of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written permission of
Cybermation International Distribution SRLwww.cybermation.com
U.S. Government Users. RESTRICTED RIGHTS—Use, duplication or disclosure restricted by the GSA ADP Schedule Contract with Cybermation USA, Inc., a subsidiary of Cybermation International Distribution SRL.
ESP-5.4-UG-05 iii
Contents
About this guide 1Who should read this guide................................................................................ 2How to use this guide ........................................................................................ 2Entering commands ........................................................................................... 2Entering statements............................................................................................ 2Examples............................................................................................................ 4Conventions used in this guide .......................................................................... 5Summary of changes .......................................................................................... 6
1 Introduction to ESP Workload Manager Concepts 7Functions of ESP Workload Manager ................................................................ 8Time and date scheduling .................................................................................. 9ESP Workload Manager Events ......................................................................... 9Data-set triggering............................................................................................ 10Global-variable-table triggering ........................................................................ 12ESP Procedures ................................................................................................ 12Applications ..................................................................................................... 13Inheriting job relationships .............................................................................. 14Mutually exclusive run requirements................................................................ 15On-request jobs................................................................................................ 16Links ................................................................................................................ 16Tasks................................................................................................................ 17APPLEND workload object ............................................................................. 18
iv ESP-5.4-UG-05
Distributed workload objects ........................................................................... 19Job documentation........................................................................................... 19Consolidated Status Facility (CSF)................................................................... 20Graphical user interface.................................................................................... 20Symbolic variables ............................................................................................ 21Tailoring Job Control Language....................................................................... 22Resources ......................................................................................................... 23Tracking jobs ................................................................................................... 24Job monitoring and alert processing ................................................................. 25System message interception ............................................................................ 26REXX interface ................................................................................................ 27Reporting......................................................................................................... 27Modeling ......................................................................................................... 29Security ............................................................................................................ 30
2 Getting Started 31Accessing ESP Workload Manager ................................................................... 32Accessing ESP Workload Manager as an ISPF option ...................................... 32Accessing ESP Workload Manager through a batch program ........................... 38Invoking ESP Workload Manager as a program in TSO .................................. 39Accessing ESP Workload Manager through
a TSO command processor............................................................................ 40Exiting ESP Workload Manager ...................................................................... 40Loading commands.......................................................................................... 40Alternative input data sets ................................................................................ 42
3 Schedule Criteria 43Where you can use schedule criteria ................................................................. 44Specifying schedule criteria............................................................................... 44Schedule terms ................................................................................................. 50Using other techniques for schedule criteria ..................................................... 57Testing schedule criteria ................................................................................... 57Using calendars ................................................................................................ 58Using calendar terms........................................................................................ 59Working with calendars ................................................................................... 60Defining holidays............................................................................................. 65Defining special days........................................................................................ 67Special periods ................................................................................................. 68Working with periods ...................................................................................... 70
4 Processing ESP Events 73Defining an ESP Event .................................................................................... 74Specifying data-set-triggered Events ................................................................. 81Specifying FTP data-set triggered Events.......................................................... 84Specifying explicit-data-set triggers................................................................... 87Specifying the function of an Event.................................................................. 91
Contents
ESP-5.4-UG-05 v
Issuing operator commands.............................................................................. 95Specifying other requirements .......................................................................... 96Displaying the schedule.................................................................................... 98Displaying when an Event will execute............................................................. 99Working with defined Events......................................................................... 100
5 Working with ESP Procedures 107Overview of ESP Procedures .......................................................................... 108Invoking an ESP Procedure............................................................................ 108ESP Procedure syntax..................................................................................... 109Using ESP Workload Manager control language in Procedures...................... 110Using symbolic variables in Procedures .......................................................... 113Using expressions and strings in Procedures ................................................... 114Built-in functions........................................................................................... 117Using calendaring functions ........................................................................... 118Using functions for job selection .................................................................... 122Using functions for symbolic variables ........................................................... 123Using system activity functions ...................................................................... 124Combining functions ..................................................................................... 127Re-executing an ESP Procedure ..................................................................... 128Using templates.............................................................................................. 129Using Event definition commands in Procedures ........................................... 131CLANG examples .......................................................................................... 132Caching an ESP Workload Manager Procedure ............................................. 135
6 Using Applications 137Introducing Applications................................................................................ 138Identifying the Application ............................................................................ 142Identifying JCL libraries................................................................................. 143Identifying jobs .............................................................................................. 149Defining job requirements ............................................................................. 155Specifying time dependencies ......................................................................... 155Specifying job relationships ............................................................................ 165Using Implicit Resources................................................................................ 166Selecting jobs for submission.......................................................................... 175Using different job types ................................................................................ 177Defining external jobs .................................................................................... 178Defining manual jobs..................................................................................... 182Using links ..................................................................................................... 184Using tasks ..................................................................................................... 188Using APPLEND workload object................................................................. 190Changing job attributes.................................................................................. 192Using data-set-trigger workload objects .......................................................... 193Using FTP data-set-trigger workload objects .................................................. 198Using explicit-data-set-trigger workload objects ............................................. 201
vi ESP-5.4-UG-05
Tagging jobs .................................................................................................. 205Providing notification on Job status ............................................................... 206Using critical-path analysis ............................................................................. 208Issuing ESP Workload Manager commands ................................................... 211Using subApplications.................................................................................... 212Working with Applications ............................................................................ 215Displaying an Application .............................................................................. 215Controlling an Application ............................................................................ 216Changing an Application definition ............................................................... 218Invoking an ESP Application ......................................................................... 219
7 Consolidated Status Facility (CSF) 221Setting up CSF views ..................................................................................... 222CSF fields ...................................................................................................... 223Defining a view .............................................................................................. 226Customizing a view ........................................................................................ 227Updating a view ............................................................................................. 231Deleting a view .............................................................................................. 232Selecting views ............................................................................................... 232Commands .................................................................................................... 232Inserting a job ................................................................................................ 235Resubmitting a job......................................................................................... 237Rerunning multiple jobs................................................................................. 238Removing job dependencies ........................................................................... 239Resetting a time dependency .......................................................................... 240Bypassing and completing jobs....................................................................... 242Adding job dependencies ............................................................................... 243Adding a job with a time dependency ............................................................ 243Adding a job relationship in an Application ................................................... 243Adding a LINK process .................................................................................. 244Setting and resetting the user status field ........................................................ 244Modifying a Job Resources or Enqueues......................................................... 245Using other commands .................................................................................. 247Extensions to CSF.......................................................................................... 247Freeform filtering ........................................................................................... 247
8 Job Documentation 257Contents of job documentation...................................................................... 258Control information....................................................................................... 258User description ............................................................................................. 259Creating job documentation .......................................................................... 260Using the jobs option..................................................................................... 261Updating job documentation ......................................................................... 262Using job documentation............................................................................... 263Using the control information........................................................................ 264
Contents
ESP-5.4-UG-05 vii
Referencing job-documentation members ...................................................... 265Overriding job documentation....................................................................... 265Using job documentation for qualified jobs.................................................... 266Using job documentation for links and tasks.................................................. 267Retrieving information................................................................................... 269Converting existing job documentation.......................................................... 271Other uses of job documentation ................................................................... 273
9 Creating Reports 275History reporting ........................................................................................... 276Structuring the report .................................................................................... 276Reporting fields.............................................................................................. 277Field formats .................................................................................................. 278Invoking the report function .......................................................................... 281Specifying input criteria ................................................................................. 281Specifying output criteria ............................................................................... 284Ending the report definition........................................................................... 287ESP Workload Manager history reporting fields............................................. 289Accumulating reporting fields ........................................................................ 297Reporting on scheduled activity ..................................................................... 298Generating data.............................................................................................. 298Extracting data ............................................................................................... 299Generating scheduled versus actual report ...................................................... 301Generating projected versus actual data .......................................................... 302Extracting tape information ........................................................................... 302Using job mapping......................................................................................... 303Producing a job-descendent report ................................................................. 309Putting it all together ..................................................................................... 311ESP Workload Manager FLOWDOC ........................................................... 312Flowcharting .................................................................................................. 318Generating flowcharts using MS Project......................................................... 319Generating flow charts with ESP Workload Manager and Timeline............... 321
10 Using Resources 325What is a resource?......................................................................................... 326Types of resources .......................................................................................... 326Scope of resources .......................................................................................... 328Using real devices ........................................................................................... 328Routing jobs to other systems......................................................................... 329Managing jobs................................................................................................ 329Requesting resources ...................................................................................... 330Default resources............................................................................................ 333Working with resources.................................................................................. 335Defining resources.......................................................................................... 335Setting resources............................................................................................. 337
viii ESP-5.4-UG-05
Modifying Resources...................................................................................... 338WLM Workload Balancing............................................................................ 338Agent Workload Balancing ............................................................................ 339Deleting resources .......................................................................................... 339Displaying resource information .................................................................... 340Step-level resource release............................................................................... 341Resource absorption ....................................................................................... 342Example: Controlling mutually exclusive jobs ................................................ 345Example: Controlling access to an online system............................................ 346Example: Time periods for low priority jobs .................................................. 347Example: Using a resource for a self-completing task...................................... 348Example: Controlling access to a data base ..................................................... 349Example: Running jobs on a particular system ............................................... 349Example: Controlling mutually exclusive groups of jobs................................. 350Example: Planning for a system shutdown - Part 1......................................... 353Example: Planning for a system shutdown - Part 2......................................... 354Example: Schedule dependency...................................................................... 356
11 Optimizing ESP Applications to UseDistributed Manager 359Planning Applications to optimize Distributed Manager ................................ 360Establishing ownership of a workload object .................................................. 364Creating distributed Applications................................................................... 365Defining ownership of an Application............................................................ 366Changing ownership of an Application .......................................................... 367Changing ownership of an Application dynamically....................................... 368
12 Using XCF with ESP Workload Manager 369Commands .................................................................................................... 370XCF Services .................................................................................................. 370State awareness............................................................................................... 373Trace.............................................................................................................. 374
13 ESP Workload Manager High Performance Option 377Expedite ......................................................................................................... 378Resource Balancing ........................................................................................ 382Workload Balancing....................................................................................... 382XCF Status Monitoring ................................................................................. 387XCF Routing Service ..................................................................................... 388XCF Scoreboard Service................................................................................. 390
14 ESP Workload Manager High Availability Option 393Shadow Manager............................................................................................ 394ARM Registration .......................................................................................... 398XCF Status Monitoring ................................................................................. 399XCF Routing Service ..................................................................................... 400
Contents
ESP-5.4-UG-05 ix
XCF Scoreboard Service................................................................................. 402
Glossary 405
Index 413
x ESP-5.4-UG-05
ESP-5.4-UG-05 1
About this guide
This guide provides you with an intermediate level of instruction for using Enterprise Systems Platform (ESP) Workload Manager, a powerful and versatile system for scheduling jobs and managing workload.
2 ESP-5.4-UG-05
Who should read this guide
This guide’s audience is users whose activities involves scheduling and managing jobs. Because this guide expects users to already have a basic understanding of ESP Workload Manager, Cybermation recommends that new users work through the ESP Workload Manager Getting Started guide first.
How to use this guide
The preliminary chapters, “Introduction to ESP Workload Manager Concepts” on page 7 and “Getting Started” on page 31, provide important background information as a starting point. These sections, along with the glossary and index, are useful reference tools both now and when you are more familiar with the aspects of ESP Workload Manager discussed in this guide. The remaining chapters, Processing ESP Events to ESP Workload Manager High Performance Option, explain ESP Workload Manager in more detail.
Entering commands
ESP Workload Manager commands can be entered in Line mode, Page mode, batch, loaded from a data set (using the LOAD command), or ESP Workstation. Many can also be entered from a system console.
ESP Workload Manager statements must be entered in a data set specific to the type of statement used.
Entering statements
Note: The content of this section also applies to commands and initialization parameters when contained in a data set.
Continuation
Type either a hyphen or a plus sign as the last non-blank character on a line to continue a line of input. If you use a hyphen, leading blanks on the next line are included. If you use a plus sign, leading blanks on the next line are deleted. Blanks preceding the hyphen or the plus sign are retained. Statements cannot extend beyond column 72. The continuation character can be placed in column 72 or before.
About this guide
ESP-5.4-UG-05 3
Note: A hyphen can also be used as a wildcard character. 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: (/* */).
Wildcards and masking
Many statements, commands, or initialization parameters permit the use of the following wildcard characters (also called masking.):
• An asterisk matches a specific single character.• An hyphen matches zero or more characters. It must be used as the last character
of the value 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 Workload Manager Procedure or initialization parameter files.
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 LIB- or PAN- prefixes to identify Librarian and Panvalet data sets.
Delimiters
Use single quotation marks when you want to denote character strings in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks.
Indentation
You can use indentation to improve readability.
Types of commands
The most frequent types of commands are:
• General commands—issued without general restrictions• OPER commands—must be preceded by the word OPER• Authorized commands—can be issued by users authorized in the security system• Authorized OPER commands—can be issued by users authorized in the security
system and must be preceded by the word OPER
4 ESP-5.4-UG-05
Examples
Issuing console commands
To issue a command from the system console, use the MODIFY command, as in F ESP, where ESP is the started task name. For example:
F ESP,STATUS
Issuing commands in batch
To issue a command in batch, use the following JCL after your job card:
//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *ESP command...ESP command
Subsystem name
If the subsystem name for ESP is not ESP, you need to type the subsystem name when entering a command in batch. For example, if the subsystem name is ESPA, type:
//EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K
Steplib
If the TSO command processor is not in a LINKLIST library, you need a STEPLIB or JOBLIB statement in your JCL. Your statement looks like:
//STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR
Wildcards and masking
To display all calendars:
LISTCAL –
To display all calendars with names containing XY in character positions three and four:
LISTCAL **XY-
To display all calendars with two-character names:
LISTCAL **
About this guide
ESP-5.4-UG-05 5
Conventions used in this guide
Input
ESP Workload Manager is not case sensitive. Even though this guide shows commands in uppercase, when you type a command on the command line, you do not need to type the command in uppercase letters.
Syntax conventions
The syntax diagrams in this guide use the following conventions:
Notation Meaning
Quote marks '' or ' Must be entered as shown.
Comma , Must be entered as shown.
Ellipsis … The operand can be repeated. Do not enter ellipsis.
Lower Case Italics operand
An operand must be substituted. User supplied variable or character string.
Uppercase operand The operand must be spelled as shown. You can enter the command and the operand in either upper or lower case.
OR-bar ( | ) Indicates an exclusive value on left or right of bar. You must enter one of the items. You cannot enter more than one.
Underline _______ If you do not enter one of the operands, the system supplies the underlined operand, this is the default
Parentheses ( ) and special characters
Operand enclosed in parentheses is mandatory and must be entered as shown.
Single operand in square brackets [ ]
Optional operand, do not type the brackets.
Stacked operands in braces { } { }
Mandatory, you must enter one of the operands. You cannot enter more than one.
Stacked operands in square brackets [ ] [ ]
Optional operand, you can enter one value, or none.
Operands with OR-bars ( | ) and square brackets [ ]|[ ]
Optional, mutually exclusive operands. Enter one or none.
Stacked operands in square brackets within braces {[ ]}
Mandatory, you must enter one of these operands. You can enter more than one.
6 ESP-5.4-UG-05
Summary of changes
Changes in edition five
• PTFs SU01813, SU01814, and SU1815; defect DEF12612:
Implement limits for
• Defining a holiday and a special day with the same name• Defining holidays with the same name, start date, and start time
See “Defining holidays” and “Defining special days” in the “Schedule Criteria chapter.
• RFE 2978: Added note about updating a cached procedure. See “Changing an Application definition” section
Changes in edition four
• Corrected screen shot in “Working with periods” on page 70. The third entry, “4 TIMES EVERY 13 WEEKS STARTING AUG 23”should read, “5 TIMES EVERY 13 WEEKS STARTING AUG 23”.
• Changed note in “Using Implicit Resources” on page 166.
ESP-5.4-UG-05 7
Introduction to ESP Workload Manager Concepts
ESP Workload Manager is a flexible and versatile job-scheduling and workload-management system. Many of its basic features are outlined in this guide. Other, more complex and lesser-used functions, are covered in the ESP Workload Manager Advanced User’s Guide.
This chapter contains the following topics:
• Functions of ESP Workload Manager• Time and date scheduling• ESP Workload Manager Events• Data-set triggering• Global-variable-table triggering• ESP Procedures• Applications• Inheriting job relationships• Mutually exclusive run requirements• On-request jobs• Links• Tasks• APPLEND workload object• Distributed workload objects• Job documentation• Consolidated Status Facility (CSF)
Section–Functions of ESP Workload Manager
8 ESP-5.4-UG-05
• Graphical user interface• Symbolic variables• Tailoring Job Control Language• Resources• Tracking jobs• Job monitoring and alert processing• System message interception• REXX interface• Reporting• Modeling• Security
Functions of ESP Workload Manager
You can automate and manage workload in your installation through a variety of functions. They include:
• Scheduling production and non-production jobs• Managing job dependencies• Monitoring and controlling workload on many other platforms in addition to
z/OS• Tailoring JCL• Tracking jobs and started tasks• Providing critical path analysis• Intercepting system messages• Sending messages• Automating start up and shut down of systems• Reporting on jobs• Forecasting future workload• Assessing the impact of a new job or Application• Providing online documentation• Issuing operator commands
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 9
Time and date scheduling
With ESP Workload Manager, you use simple, everyday English to schedule work. It has a built-in understanding of common scheduling terms and can handle any variety and combination of schedule statements, such as:
9AM DAILY2PM 1ST WEEKDAY OF EACH MONTH7PM 3RD 13TH AND 23RD DAY OF MONTH5PM 10TH-19TH DAY OF MONTH2ND AND LAST FRIDAY OF EACH MONTHEVERY 30 MINUTES STARTING 6PM TODAY
Using calendars
Although ESP Workload Manager is familiar with the standard calendar, you can use scheduling terms that are specific to your installation. To define your own customized set of scheduling terms, you can define one or more calendars. A calendar can contain:
• A list of holidays. Holidays can span one day, several days, or just parts of a day.• Lists of special processing dates.• Descriptions of periods, such as fiscal months, fiscal years, 4-4-5 periods.• A specification as to which days of the week are eligible to be workdays. The
default is Monday to Friday.
After defining your unique scheduling terms, you can use schedule criteria like these:
8AM LAST DAY OF FISCAL_MONTH5PM INVENTORY_DAYCHRISTMAS PLUS 1 WORKDAY8AM 8TH-10TH WORKDAY OF FISCAL_YEAR2ND WORKDAY OF 3RD FISCAL_MONTH OF FISCAL_YEAR
ESP Workload Manager Events
An Event is a basic unit of work. Information in an Event defines:
• When the work must be performed• What actions perform the work
Section–Data-set triggering
10 ESP-5.4-UG-05
Triggers for an Event
• A scheduled date and time • A data-set trigger• A global-variable-table trigger• A manual trigger• A job monitor or alert trigger• A signal with a scheduled date and time
Performing tasks
ESP Workload Manager can perform a variety of tasks through the Events you define. An Event must do one of the following:
• Send a message to you, other users, or operator consoles• Submit JCL • Invoke an ESP Procedure• Issue an operating-system command
Example
An example of an Event appears below. The Event is scheduled at 8 am each day that invokes a Procedure.
EVENT ID(USER.MESSAGE) SCHEDULE 8AM DAILY INVOKE 'SYS1.PROCLIB(PAYJOB1)'ENDDEF
Additional information
For more information on Events, see “Processing ESP Events” on page 73.
Data-set triggering
You can tell ESP Workload Manager when to process your Events depending on data-set activity. This feature is called data-set triggering. You can use it in conjunction with, or instead of, time-and-date scheduling.
Triggers for a data set
An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of job-names. Events can also be made to wait for triggers from activity in more than one data set.
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 11
Example
An example of a data-set-triggered Event follows. This Event sends a message to a user each time the data set CYB.APPL.BASKET closes.
EVENT ID(USER.APPL_RECEIVE) DSTRIG CYB.APPL.BASKET ANYCLOSE SEND 'APPLICATION RECEIVED FROM ESP WORKSTATION' USER(BP)ENDDEF
You can also use data-set triggering for establishing individual job dependencies within your ESP Applications.
FTP data set trigger
An FTP data-set-trigger Event is triggered when a successful FTP file transfer or FTP rename completes. The closure of a data set through an FTP transfer requires special handling to ensure that the transfer is successful and complete.
Example
The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged-on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.
EVENT ID (USER.APPL_RECEIVE) DSTRIG CYBER.DATA.SET USER(CYB-) FTP(RECEIVE) HOST(AIXHOST)- LOGON(aixuser) SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDDEF
Explicit data-set trigger
An explicit data-set trigger is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.
The feature consists of two parts:
• The explicit data-set trigger notification utility program (CYBESDT1)• The parameter EXPLICIT in the DSTRIG command or in the DSNAME
statement
Additional information
For more information on data-set triggering, see “Processing ESP Events” on page 73 and “Using Applications” on page 137.
Section–Global-variable-table triggering
12 ESP-5.4-UG-05
Global-variable-table triggering
You can set a global-variable-table trigger to trigger an Event when a specified variable changes.
Example
In this example, the Event CYBER.MYEVENT is triggered when the global variable VT1 of the global-variable table named MYTABLE changes.
For the Event to be triggered, the table MYTABLE, the variable VT1, and the (optional) trigger ID TR07 are set as follows:
VTDEFINE MYTABLEVT1='ONE'VTPUT VT1 TABLE(MYTABLE)VTRDEF ID(TR07) VARIABLE(VT1) TABLE(MYTABLE)- EVENT(CYBER.MYEVENT)
Any change of the value of the global variable VT1 will trigger the CYBER.MYEVENT Event. For example, setting the value of VT1 to TWO as follows:
VSET VT1 TWO TABLE(MYTABLE)
Additional information
For more information on the use of global-variable tables including the triggering of Events when a global variable changes, see the ESP Workload Manager Advanced User’s Guide.
ESP Procedures
An ESP Procedure is a set of stored instructions that ESP Workload Manager invokes. Part or all of these instructions can define a group of jobs and tasks as an ESP Application. Although you use an ESP Procedure to define all ESP Applications, not all ESP Procedures contain an ESP Application definition.
Controlling processing requirements
Using a combination of CLANG (ESP Workload Manager Control LANGuage), ESP Workload Manager built-in functions, job specification statements, templates, and symbolic variables in a Procedure, you can control any processing requirements.
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 13
Uses of an ESP Procedure
The main uses of an ESP Procedure are to:
• Define processing requirements for a group of jobs and tasks in an ESP Application
• Define and work with symbolic variables• Take different actions based on other criteria, such as a job failure
Example
The following is an example of using CLANG. In this example, ESP Workload Manager:
• Sends a message on workdays• Submits job PAYJOB on the last workday of each month
IF TODAY('WORKDAY') THEN - SEND 'ANOTHER DAY OF HARD LABOR' U(BOSS)IF TODAY('LAST WORKDAY OF MONTH') THEN - SUBMIT 'SYS1.JCLLIB(PAYJOB)'
Additional information
For more information on Procedures, see “Working with ESP Procedures” on page 107.
Applications
An ESP Application consists of one or more workload objects (for example: job, message, command, script, manual task). An ESP Procedure describes an Application to ESP Workload Manager. A Procedure consists of a series of statements to:
• Identify the Application• Tell ESP Workload Manager where the appropriate JCL is located• Identify the jobs• Describe the job relationships• Describe when ESP Workload Manager should select the jobs to run• Describe other job dependencies, such as time and resources• Optionally, it may also state such things as a job documentation library and what
condition codes cause a job to fail
Section–Inheriting job relationships
14 ESP-5.4-UG-05
Application definition
An Application definition looks like this:
APPL PAYROLLJCLLIB 'CYBER.ESP.JCL'JOB A RUN DAILY RELEASE (B,C)ENDJOBJOB B RUN DAILY RELEASE DENDJOBJOB C RUN DAILY RELEASE DENDJOBJOB D RUN DAILY RELEASE EENDJOBJOB E RUN FRIDAY RELEASE FENDJOBJOB F RUN LAST WORKDAY OF THE MONTHENDJOB
Streamlining Applications
You can streamline the way you schedule and manage entire Applications. When ESP Workload Manager creates an Application, it assigns a generation number to it. One generation does not need to complete before the next one starts. Several generations of the Application can run concurrently. ESP Workload Manager manages dependencies within the Application as well as between different Applications.
Additional information
For more information on Applications, see “Using Applications” on page 137.
Inheriting job relationships
All jobs in an Application do not require to be run at the same interval. When ESP Workload Manager selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited. Once you specify your job
A
B C
E
F
D
Daily
Friday
Last workdayof month
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 15
relationships, ESP Workload Manager determines the relationships required under different processing conditions.
Example
Consider the following three jobs and their schedule frequencies:
On Fridays, all three jobs execute in order, but on any other day of the week job J2 does not run. On these other days, J1 and J3 are selected and they inherit their mutual relationships from J2. When J1 completes successfully, it releases J3.
Additional information
For more information on how ESP Workload Manager inherits job relationships, see “Inheriting job relationships” on page 176.
Mutually exclusive run requirements
ESP Workload Manager can specify mutually exclusive run requirements through Application and job-level statements. These statements provide an alternative to defining ESP Resources and the corresponding coding of ESP Resource statements to handle mutually exclusive run requirements. For information on resources, see “Resources” on page 23.
Example
In this example, jobs NWN001 and NWN003 are set up so they cannot run at the same time.
APPL NWN00CJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002
J2
J3
J1 Daily
Friday
Daily
Section–On-request jobs
16 ESP-5.4-UG-05
RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYS NOTWITH NWN001ENDJOB
Additional information
For more information on specifying mutually exclusive run requirements, see “Using Implicit Resources” on page 166.
On-request jobs
An on-request job is a job normally run on demand; it is not a regularly scheduled job. With Applications, you can identify certain jobs as on-request and define their relationships to other jobs. The on-request jobs take their place in the schedule. You can request a job any time, from the time you generate the Application up to the time the job is submitted. If you have not explicitly requested the job using a command, it is treated as a normal completion.
Additional information
For more information on request jobs, see “Identifying a job as on-request” on page 151.
Links
A link is a task that completes itself. You can use a link to process commands such as sending messages and issuing operator commands, during the processing of an ESP Application.
Uses of links
Common uses of links include:
• Simplifying job relationships• Keeping an Application active• Notifying when something happens• Notifying when something does not happen
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 17
Example
In the example below, a link is a successor to jobs A, B, and C. The link could send a message, issue an operator command, or simply link two groups of jobs together.
Additional information
For more information on using links, see “Using links” on page 184.
Tasks
You can define tasks in an Application and establish dependencies between them and other tasks and jobs. You must mark a task complete before its successors become eligible for submission.
A task can represent a manual process that requires intervention, or it can represent a process that can be automated. You can choose to use tasks for:
• Balancing reports• Receipt of input tapes• Completion of a job step• Any other special handling requirements
Example
In this example, a report needs to be checked after job J1 completes successfully. A task called CHECKRPT.J1 represents the task of checking the report.
B CA
E FD
LINK
J1(Job)
CHECKRPT.J1(Task)
J2(Job)
Section–APPLEND workload object
18 ESP-5.4-UG-05
Additional information
For more information on using tasks, see “Using tasks” on page 188.
APPLEND workload object
You can use the APPLEND workload object to automatically perform processing at the end of an Application. The APPLEND workload object acts like a self-completing task.
Note: The APPLEND workload object does not need a RUN statement because this object always runs at the end of the Application.
Example
In the following example, the APPLEND workload object named FRED will be made a successor of JOB2, because JOB2 has no other successors. However, job AFTERAE2 and AFTRAELA, which also do not have successors, are successors to APPLEND FRED, so are not made predecessors to it.
APPL TESTAE1JCLLIB 'CYBER.JCL.CNTL'
JOB JOB1 LINK RUN DAILY REL JOB2ENDJOB
JOB JOB2 LINK RUN DAILYENDJOB
APPLEND FRED REL (AFTERAE1,AFTERAE2) SE 'APPLEND RUNNING' U(*)ENDJOB
JOB AFTERAE1 LINK RUN DAILY REL AFTRAELAENDJOB
JOB AFTERAE2 LINK RUN DAILYENDJOB
JOB AFTRAELA TASK RUN DAILYENDJOB
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 19
Additional information
For more information on the use of APPLEND workload object, see “Using APPLEND workload object” on page 190.
Distributed workload objects
ESP Workload Manager extensions extend the functionality of ESP Workload Manager to other platforms. Workload is scheduled by ESP Workload Manager and run on Agents. Your workload can be automatically managed, from a single point of control, on various platforms throughout your enterprise.
ESP Distributed Manager
ESP Distributed Manager manages UNIX and Windows NT workload after it is scheduled by ESP Workload Manager. Once the workload is scheduled, if the mainframe becomes unavailable, the workload can continue processing.
Additional information
For information on scheduling workload on distributed platforms, see the ESP Workload Manager Agent documentation for the platform you are using.
Job documentation
You can use the ESP Workload Manager job-documentation facility to create a complete and centralized definition of all or any of your jobs. You can document the entire requirements of a job at the individual job level, including a job’s predecessors and successors, schedule criteria, due-out time from various processing phases, resources required by the job, and more.
Scope of job documentation
As an extension to ESP Procedures, job documentation is much more than a list of processing requirements for a job. The information you define is used to ensure that the job is processed as specified in the job documentation entry. If-then-else statements within the job documentation entry allow the job definition to fit with a variety of conditional or complex requirements.
Additional information
For more information on job documentation, see “Job Documentation” on page 257.
Section–Consolidated Status Facility (CSF)
20 ESP-5.4-UG-05
Consolidated Status Facility (CSF)
The Consolidated Status Facility (CSF) provides a real-time view of the current workload. CSF shows you which jobs have executed, which ones are currently on the system, and which jobs have yet to execute. You can zoom in on any job or workload object to find out more information. You can also manipulate jobs, edit JCL, and restart jobs while in CSF. With CSF you can create customized views where you choose what you want to see and how you want it displayed. You may want to focus on one particular Application, or view all jobs that have failed.
Example
This example demonstrates the kind of job information that CSF can provide:
Customizing CSF
Through the use of CSF Extensions, you can further customize your use of CSF by writing your own commands, or by replacing existing commands. For example, you can launch other ISPF applications, provide additional panels, and force the use of certain fields.
Additional information
For more information on CSF, see “Consolidated Status Facility (CSF)” on page 221.
Graphical user interface
Schedulers and operators sometimes find graphical presentation of the workload helpful. Graphic flows make it easier to see job dependencies and to monitor the progression of work.
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 21
ESP Workstation
ESP Workstation is a graphical user interface for ESP Workload Manager. From a single point, You can define, monitor, and control your entire workload across multiple platforms. You can:
• Use graphics to create ESP Applications• Manage workload in real time
Additional information
For more information on ESP Workload Manager graphical user interface, see the ESP Workstation User's Guide.
Symbolic variables
A symbolic variable is an object whose value can be changed during ESP Workload Manager processing. ESP Workload Manager provides powerful substitution capabilities through the use of symbolic variables. When it encounters a symbolic variable, it substitutes the current value of that variable. With symbolic variables, you have all the flexibility you need to define date operands, specify job names, and define job dependencies.
Using variables
ESP Workload Manager provides you with several built-in variables (such as times and dates) that can be substituted in Events, ESP Procedures, and the JCL input stream. Also, you can define as many of your own symbolic variables as you need.
Example
NAME, DATE, and X are some examples of variables:
NAME='PATRICK'DATE='%ESPSMM%ESPSDD%ESPSYEAR'INTEGER XX=293
Attributes of symbolic variables
Each symbolic variable has a name and a value, and starts with a symbolic introducer character. The percent sign (%) is the default introducer character, although you can change this symbol at installation to suit your requirements. There are many operations that you can perform on symbols, such as concatenation and using sub-strings.
Section–Tailoring Job Control Language
22 ESP-5.4-UG-05
Global variable tables
You can store global variables in global variable tables, retrieve them from those tables, and trigger Events when the stored variables change. See the “Global Variable Table” chapter of the ESP Workload Manager Advanced User’s Guide.
Additional information
For more information on symbolic variables and symbol libraries, see the “Symbolic Variables” chapter of the ESP Workload Manager Advanced User’s Guide.
Tailoring Job Control Language
You can selectively tailor the JCL that ESP Workload Manager submits to the JES internal reader by entering symbolic variables and control statements in JCL. For example, you can automatically include the current date in a job, or to add a job step every Monday. You can also add a restart step, route a job to another JES node, or add a condition code check step to the JCL.
Example 1
ESP Workload Manager has a number of built-in symbolic variables; many relate to dates and times. The following example shows how to represent the scheduled date of a job in the format MMDDYYYY using built-in symbolic variables. In this example, a user requests date information as data; you can use also symbolic variables as part of JCL.
//SYSIN DD *%ESPSMM%ESPSDD%ESPSYEAR
Example 2
When ESP Workload Manager submits this JCL for an Event scheduled on June 9, 2000, it substitutes the built-in symbolic variable as shown below.
You could generate another set of symbolic variables to complement the built-in set of date and time symbolic variables for any date in the future or in the past.
//SYSIN DD*%ESPSMM%ESPSDD%ESPSYEAR
//SYSIN DD*06092000
Original JCL Substituted JCL onJune 9, 2000
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 23
Additional tailoring
In addition to using symbolic variables to insert different operands, such as time, date, day of week, and data-set name into JCL, you can further tailor your JCL by using:
• Selective inclusion and exclusion of JCL and data• JCL exclusion symbols• Different symbol introducers• Secured symbols• Automatic variable insertion
Additional information
For more information on tailoring JCL, see the ESP Workload Manager Advanced User’s Guide.
Resources
A resource can be any hardware, software, or abstract condition. Within ESP Workload Manager, there is no limit to what you can define as a resource.
Examples
Common examples of resources include:
• Disk space• Scratch tapes• Execution time• An entity to control mutually exclusive jobs• Online system availability• DASD space• Time periods• Tape drives
Section–Tracking jobs
24 ESP-5.4-UG-05
Resources
ESP Workload Manager supports the three following types of resources:
Resource requirement
You can define resource requirements for any job. You can also use default resources where ESP Workload Manager automatically determines resource requirements for a job based on historical data.
Additional information
For more information on resources, see “Using Resources” on page 325.
Tracking jobs
The ESP Workload Manager job-tracking facility tracks job data in real time as jobs are being processed. You can use the job tracking facility to track your jobs and keep information on the progress of these jobs. You can track both jobs that ESP Workload Manager submits and jobs that it does not submit. Also, you can track Started Tasks (STCs) and TSO users (TSUs). You see detailed step-level statistics in real-time. ESP Workload Manager maintains completion codes for each job step, and provides data
Type of resource...
Explanation
Renewable A renewable resource is a borrowed resource. When ESP Workload Manager submits a job, the job removes the resource from the resource pool and returns it upon completion. Some examples of renewable resources include tape drives, a data base, or sort work space.
Depletable A depletable resource is a consumed resource. When ESP Workload Manager submits a job, it removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. A depletable resource could refer to the number of scratch tapes available or to permanent DASD space.
Threshold A threshold resource is a sizing resource. You can think of a threshold resource as a variable-height doorway into the system. If the resource quantity is set to two, any number of jobs requiring two or fewer units can be submitted. However, any job requiring three or more units is too high to pass through the door and so it is not submitted. In other words, ESP Workload Manager sizes the job against the current level of the threshold resource. This type of resource could be used to prevent certain jobs from executing until a NITESHFT period begins, for example.
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 25
such as CPU time, elapsed time, disk and tape I/O counts, number of tape mounts, tape drives, and so on.
Example
The following example shows a sample output from a command to display tracking data for job PAY008A:
LJ PAY008A(6308)PAY008A JO6308, COMPLETED, CC SOC1, NODE CYBJESSUBMITTED BY ESP AT 10.06 ON TUE 13APR, EVENT CYBBP01.PAYJCL FROM CYBBP01.ESP.DEMO.JCL(PAY008A)JCL COPIED TO CYBBP01.ESP.DEMO.COPYJCL(PAY008A)PROGRAMMER BOB, ACCOUNT CYBTESTJOB IS IN APPL PAYINFORMATION/MANAGEMENT RECORD 0000053 CREATED FOR THIS JOBSTEPNAME-PROCSTEP-PROGNAME—EXCEP-#T-S-N-CPU-TIME-SUNITS-REGION-CMPCENCORE ESPRM CYBRM000 30 0 0 0 0:00.48 2635 320K 0STEP01 IEFBR14 0 0 0 0 0:00.00 0 4K 0STEP02 IEBGENER 0 0 0 0 0:00.00 0 72K 0STEP03 SOC1 1 0 0 0 0:00.13 428 8K SOC1STEP04 IEFBR14 0 0 0 0 0:00.00 0 0K -STEP05 IEBGENER 0 0 0 0 0:00.00 0 0K -ESPCCFCK IEFBR14 0 0 0 0 0:00.00 0 0K -PNODE----OUT---QTIME-POST_BY—SYS-|PNODE----OUT---QTIME-POST_BY—SYSINPUT 10.06 5 CYB1|EXEC 10.06 12 SYSTEM CYB1OUTPUT 10.06 13 SYSTEM CYB1
Tracking models
You can define a tracking model to track a group of jobs with similar characteristics. This tracking model enables you to define and modify the tracking characteristics of multiple jobs at the same time. You can, for example, use a tracking model to identify jobs where you want to keep long-term historical data and then use the data with ESP Workload Manager history reporting facility. For more information on setting up your job-tracking environment, see the ESP Workload Manager Installation and Configuration Guide.
Job monitoring and alert processing
The ESP Workload Manager job-monitor facility and alert processing facility can automatically take action at different processing points, for example, stepend, jobend, and overdue.
Section–System message interception
26 ESP-5.4-UG-05
Uses
For example, you can use job monitoring and alert processing to:
• Automatically start a subsystem• Restart a job by automatically resubmitting it• Automatically restart an abended job• Create a problem record in an information/management data base.• Submit a recovery job• Activate or deactivate resources by issuing the appropriate command.• Cause SNMP traps to be sent by an ESP Management Agent appearing as if they
were sent from ESP Workload Manager
You can use a number of symbolic variables with either facility.
Additional information
For more information on job monitoring and alert processing, see the ESP Workload Manager Advanced User’s Guide.
System message interception
ESP Workload Manager can intercept any message while it is being written to the JES system message data set belonging to an individual JOB STC or TSU.
The JES system message data set constitutes the job’s log, containing JES messages about the job's processing, allocations, job/step statistics, and data set disposition. The JES system message data set (JESYSMSG) is subject to installation parameters that can affect content and creation.
ESP Workload Manager does not intercept data written to other JES data sets, the data sets belonging to the operating system (for example SYSLOG), or console messages.
This message interception happens in real time and can be used to detect conditions such as NOT CATLGD and other important message portions or message identifiers. ESP Workload Manager can cancel the job, fail the job with a JCL error or Condition code failure, trigger an Event, or rebroadcast the message as a WTO (write-to-operator).
Example
The following example requests the cancellation of a job whenever a NOT CATLGD message starting anywhere between column 50 and 60 is generated for that job. It also
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 27
specifies to route this message to consoles with the default route code two. Descriptor code two is used to make the message non-deletable:
SYSMSGS 'NOT CATLGD' COL(50:60) CANCEL DESC(2)
Additional information
For more information on intercepting system messages, see the ESP Workload Manager Advanced User’s Guide.
REXX interface
You can use the IBM high-level, procedural language called Restructured EXtended eXecutor language (REXX) with ESP Workload Manager. REXX extends its capabilities by providing it with another powerful command language. You can use REXX anywhere you use ESP Workload Manager Command Language (CLANG), or you can mix the two languages together to provide powerful functions in an easy-to-use fashion.
Uses of REXX
You can use REXX with ESP Workload Manager to:
• Perform repetitive tasks, such as defining a static holiday• Trap output from ESP Workload Manager commands• Extend the functions of the Consolidated Status Facility• Build ESP Workload Manager Application code• Perform data set I/O
Additional information
For more information on using REXX with ESP Workload Manager, see the ESP Workload Manager Advanced User’s Guide.
Reporting
The ESP Workload Manager reporting facilities can give you up-to-date information about scheduled jobs that executed in the past or will execute in the future. Reporting facilities include:
• History• Scheduled activity• Job mapping
Section–Reporting
28 ESP-5.4-UG-05
History reporting
A powerful and versatile generalized reporting facility provides details about the progress of your jobs at any time up to the present. This facility extracts and formats data from the ESP Workload Manager history files to meet a variety of requirements. The reports specified can be as detailed or as simple as you require. You can include a variety of job aspects such as job name, status, tape allocation, and so on. The report formats you define can be named and used repeatedly. In addition, reports are available online and in hard-copy.
Fields to use as selection criteria
ESP Workload Manager retains over 60 items of history data for each tracked job. The fields you can use as selection criteria and for display in your reports include, but are not limited to:
• Execution queue time• Print time• Start and end dates• Start and end times• Overdue times• EXCP counts• Number of job steps
Example
The following is an example of a report on all PAY- jobs that executed on May 8, 2001:
JOBNAME JOB COMP EXEC START EXEC END CPUTIME NO CODE START DATE END DATEPAYD001A 2221 0 11.56 TUE 08MAY01 12.02 TUE 08MAY01 0:01PAYD002A 2227 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00PAYD003A 2226 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00PAYD004A 2229 0 12.02 TUE 08MAY01 12.07 TUE 08MAY01 0:04PAYD100A 2232 0 12.07 TUE 08MAY01 12.07 TUE 08MAY01 0:00PAYD006A 2233 0 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00PAYD008A 2234 SOC1 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00PAYD008A 2270 SOC1 12.57 TUE 08MAY01 12.57 TUE 08MAY01 0:00PAYD008A 2271 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00PAYD009A 2272 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00PAYD010A 2273 SOC1 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00PAYD010A 2275 0 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00PAYD011A 2276 0 12.59 TUE 08MAY01 13.04 TUE 08MAY01 0:01SUBTOTAL (13) 0:06TOTAL (13) 0:06
Chapter 1–Introduction to ESP Workload Manager Concepts
ESP-5.4-UG-05 29
Additional information
For more information on history reporting, see “History reporting” on page 276.
Scheduled activity reporting
The scheduled-activity-reporting facility forecasts, at the job level, the system workload for a future time period. You can generate both hard-copy and online reports displaying a variety of statistics about jobs that ESP Workload Manager scheduled, including:
• Execution time• CPU time• Print lines• Tape requirements• Application name
Additional information
For more information on scheduled activity reporting, see “Reporting on scheduled activity” on page 298.
Job mapping
Job mapping is a reporting facility you use to produce detailed job information. You can generate the following reports:
• Job activity report. This report contains detailed information on jobs including job name, Application name, job type, Event name, ESP Procedure name, JCL library, execution time, CPU time, and predecessor and successor jobs.
• Job descendent report. This report shows a job and its successors.
Additional information
For more information on using job mapping, see “Using job mapping” on page 303.
Modeling
ESP Workload Manager has a modeling feature that forecasts how it processes a group of jobs in your particular systems environment. Scheduled activity reporting provides you with information based on what is scheduled. Modeling takes this one step further. ESP Workload Manager combines the schedule with what it knows about the scheduling environment to predict future activity. You define your environment and then ESP Workload Manager creates a picture showing how a future schedule period
Section–Security
30 ESP-5.4-UG-05
looks. Modeling allows ESP Workload Manager to forecast the influence of factors such as CPUs, initiators, and resources.
Modeling reports
Modeling generates reports on jobs, resources, and exceptions. For example, you can generate a report that shows you all jobs that will not meet their scheduled due out time.
Use of modeling reports
You can use the data shown on the modeling reports to:
• Assist you in capacity planning• Test the effects of underinitiating or overinitiating• Determine the impact of changes to a schedule• Uncover potential resource problems
Additional information
For more information on modeling, see the ESP Workload Manager Advanced User’s Guide.
Security
Whether you have schedulers and operators scheduling all of the work or end users submitting their work, ESP Workload Manager gives you security that ensures the integrity of your system. Work is performed according to the security attributes of the user. Before the ESP Workload Manager server executes the requested routines, it checks to see if the user is authorized for the requested work. This method of security works for any type of user: individuals, production groups, or service bureau customers.
Host security programs
ESP Workload Manager supports RACF, CA-ACF2, and CA-TOP SECRET. It manages support for these host security programs without the need to use exits or modify JCL.As well, ESP Workload Manager SAF interface provides granular security over all functions and resources.
Additional information
For more information on security, see the ESP Workload Manager Security Guide.
ESP-5.4-UG-05 31
Getting Started
This chapter gives you some general information on how you can use ESP Workload Manager.
When you have finished this chapter you should be able to access ESP Workload Manager, load commands into it, and use different data set types as input.
This chapter contains the following topics:
• Accessing ESP Workload Manager• Accessing ESP Workload Manager as an ISPF option• Accessing ESP Workload Manager through a batch program• Invoking ESP Workload Manager as a program in TSO• Accessing ESP Workload Manager through a TSO command processor• Exiting ESP Workload Manager• Loading commands• Alternative input data sets
Section–Accessing ESP Workload Manager
32 ESP-5.4-UG-05
Accessing ESP Workload Manager
You can access ESP Workload Manager in one of several ways:
• An ISPF Option• A Batch Program• A Program in TSO• A TSO Command Processor
Accessing ESP Workload Manager as an ISPF option
If your z/OS system has ISPF you can use the menus and panels of ESP Workload Manager. The panels step you through the definition of Events, Applications, calendars, and jobs. You use other panels to display job tracking information and for reporting scheduled activity. The ISPF interface uses the dialog manager for functions such as split screen, edit, and multiple sessions. As well as menus and panels, Page mode provides scrollable data, and the ability to edit and save any portion of an ESP Workload Manager session. The method for accessing ESP Workload Manager from ISPF differs with each installation. Check with your administrator for the method that your site uses.
Screens for ISPF interface
The layout of each screen is designed to look like the panels you are already accustomed to when using ISPF. The Command or Option field is always at the left of the second panel line. Short messages are displayed top right, while long messages occupy line three, which is otherwise blank. The maximum length of most panels is 23 lines. This facilitates the use of split-screen mode where it is available. Panels with scrollable data will extend to the entire screen capacity.
Main Menu screen
The screen below shows the ESP Workload Manager Main Menu.
Chapter 2–Getting Started
ESP-5.4-UG-05 33
When you invoke ESP Workload Manager, the Main Menu appears. It displays the available options including Events, Calendars, Consolidated Status Facility. Many ESP Workload Manager commands are available through menu mode. There is a wide choice of menus, entry panels and help screens.
Menu panels in ESP Workload Manager
To use a command, first select an option from any menu or selection panel. Then specify your requirements by entering appropriate data in labeled fields on the entry panel. All entry fields are indicated with an arrow (===>).
Required fields are indicated, and you are prompted if you omit required information or make a recognized error in any of your entries. If a short message prompt is insufficient to clarify an error or omission, you can display a longer message by entering the HELP command (PF1).
Main Menu options
The Main Menu is the first ISPF panel. It provides the following options:
Option Use this option to...
O Set your ESP Workload Manager defaults
• Display information about a user or group of users• Set security parameters• Set (CSF) display options• Specify default names for data sets that you use frequently
during your ISPF sessions. Your input is automatically transferred to the appropriate panels. For example, ESP Workload Manager can use a default ESP Procedure Library when you define an Event. You can override information in any field.
E Events • Test schedule criteria• Add a new Event definition• Display the next execution times of an Event• Alter, browse, delete, edit, simulate, hold, release,
suspend, resume, or trigger an Event you have already defined
• Obtain a list of Events by prefix
L Calendars • Define and display calendar information including holidays, special days, and special periods
J Jobs • Set up job documentation. You can specify processing requirements for any job as well as user information such as ABEND codes and messages.
Section–Accessing ESP Workload Manager as an ISPF option
34 ESP-5.4-UG-05
T Job Tracking • Display job status• Access commands to display job tracking information• Display tracking models• Use Pnodes• Display the number of jobs on each Pnode queue• Display the names of jobs on Pnode queues• Display jobs on the ABEND queue
S Scheduled Activity • View information on the scheduled activities you want performed. This information gives you a snapshot of which jobs will be on the schedule during a specified future time. It also provides some additional information about the jobs, such as estimates on:
• Execution time• CPU time• Print lines• Tape specifications• CPU absorption
C Consolidated Status Facility (CSF)
• View information on jobs and Applications that ESP Workload Manager tracks. Once you have chosen a display, you can use commands to manipulate jobs, Applications, subApplications, or any of the related ESP Workload Manager definitions.
U ESP Workload Manager Utilities
• Load a series of ESP Workload Manager commands• Display information on key ESP Workload Manager data
sets, tracking cells, data set triggers and system attributes
G Page Mode • Switch directly into the Page mode method of communicating with ESP Workload Manager. In this mode you can use the command line for input, while receiving scrollable output in return. See “Using ESP Workload Manager Page mode” on page 36 for detailed information on using this option.
Option Use this option to...
Chapter 2–Getting Started
ESP-5.4-UG-05 35
USE command sample
This screen shows the result of the USE command:
ESP ---------------------------------- Usage ----------------- Row 1 to 4 of 4 Command ===> Scroll ===> PAGE
This This This Since LastActivity Year Month Day ESP Start------------------------------------------------------------------------------Applications completed 75 23 4 2Applications created 77 25 4 1Events executed 183 81 13 5Jobs submitted 99 55 8 3 **END**
Using the Help option
While you work with ESP Workload Manager you can access the online, panel-specific Help screens at any time. By pressing the Help key (PF1/PF13) you access Help about the particular screen on which you are working.
M ESP Workload Manager Administration
• This option is only available to the ESP Workload Manager Administrator and departmental administrators. The administrator can use this option to define and update users, groups, and calendars, and to test and modify job tracking definition tables. If your installation uses your host security system for ESP Workload Manager security, you do not use this option to define users and groups.
R ESP Encore • Take you to the Job List Panel of ESP Encore, Cybermation’s rerun/restart product. This option only appears on your menu if you have ESP Encore installed.
USE Command • Enter the USE command on the OPTION line, from the ESP Workload Manager main menu, to display statistics on various activities. These statistics are reset to zero following an ESP Workload Manager cold start.
Option Use this option to...
Section–Accessing ESP Workload Manager as an ISPF option
36 ESP-5.4-UG-05
Using ESP Workload Manager Page mode
To use Page mode, type the information in free format, line by line, on the command entry line. The data and resultant output appear in a scrollable field below the command line.
Example: Page mode screen
The following is an example of using Page mode:
Input line entry
Each time you complete an input line, press Enter. The line is highlighted and added to the bottom of the input display.
To re-enter a previous line:
1. Move the cursor to that line using the arrow keys.
2. Press Enter. The line appears on the command line.
3. Edit the line.
4. Press Enter.
Similarities to ISPF Browse
Page mode appears very similar to ISPF Browse. However, not all Browse commands are available. If you want to use the delete and find features, you must type EDIT on the command line. The EDIT command lets you delete or change the Page mode output and store it.
When you use the EDIT command, all the session’s data is copied into a temporary work file that is displayed immediately. You can write the data into a more permanent existing data set or a new member of a PDS using the CREATE or REPLACE commands.
Chapter 2–Getting Started
ESP-5.4-UG-05 37
To write session data:
1. Use the CC or MM block commands to select the lines you want to copy to the data set.
2. Type either CREATE or REPLACE on the command line. CREATE makes a new member for the data. REPLACE overwrites an existing data set with the new information.
3. Press Enter.
4. Respond to the prompt for a data-set name:
• If you used the CREATE command, enter the name for your new member and the existing data set to which it will belong.
OR
• If you use the REPLACE command, enter the name of the existing data set that you want to overwrite.
Important: Do not use the SAVE command. The SAVE command writes the data back to the temporary work file that is discarded at the end of your session.
Using the Page mode screen
In Page mode, ESP Workload Manager retains your entire session on the screen. As you enter more data, the screen scrolls up to make room. You can scroll the screen up or down to view all of the data. If any headings are attached to your input, the headings remain in view at the top of your screen while the data scrolls below them. Also, any informational, warning, and error messages appear in the short message fields at the top of the screen, as in ISPF.
Note:
• To scroll, use the standard scroll keys: PF7 to move up, and PF8 to move down.• To scroll more quickly, enter TOP or BOTTOM in the command line.• To access a specific line number quickly, use the LOCATE command.
To display informational messages where they occur in the input instead of at the top of the screen:
Enter on the command line:
INFOMSG SET
You can prefix these messages with a string of your choice by entering on the command line:
INFOMSG SET PR('STRING')
Section–Accessing ESP Workload Manager through a batch program
38 ESP-5.4-UG-05
To return informational messages to the top of the screen:
Type on the command line:
INFOMSG RESET
Accessing ESP Workload Manager through a batch program
Although many of ESP Workload Manager commands are available through the ISPF interface, there can be times when you want to execute ESP Workload Manager commands in batch. Perhaps you want a hardcopy report, or you need to execute a repetitive series of commands.
To execute ESP Workload Manager commands in batch:
Use the following JCL after your jobcard:
//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *ESP command...ESP command
Note: Do not end a line with a hyphen (-) else it will be treated as a continuation character. If you are using a hyphen as a mask, you should follow it with a semi-colon. For example, LTJ -;
Subsystem name
If the subsystem name for ESP is not ESP, you need to type the subsystem name. For example, if the subsystem name is ESPA, type:
//EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K
Steplib
If the TSO command processor is not in a LINKLIST library, you will need a STEPLIB or JOBLIB statement in your JCL. Your statement looks like:
//STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR
Chapter 2–Getting Started
ESP-5.4-UG-05 39
Invoking ESP Workload Manager as a program in TSO
To invoke ESP Workload Manager as a program in TSO:
Type the following at the TSO prompt:
ESP
If the subsystem name for ESP is not ESP, you will need to type the subsystem name. For example, if the subsystem name is ESPA, type:
ESP SUB(ESPA)
When you access ESP Workload Manager through TSO, TSO prompts you for input with an arrow:
==>
TSO refers to this prompt as a MODE message.
To turn on the TSO mode message, at the TSO prompt:
Type:
PROFILE MODE
You are now in ESP Workload Manager Line mode.
To work in Line mode:
Enter all of the commands for the work you want directly on the TSO command line. When you have finished, type END to exit. This method is quick and direct, but you must know the commands and their syntax. You can find the ESP Workload Manager commands and syntax in the ESP Workload Manager Reference Guide.
Example: Invoking the ESP Workload Manager command from a CLIST
The following is an example of a CLIST that invokes the ESP Workload Manager command processor directly. The CLIST:
• Prompts a user for the name of a job to be submitted • Accepts the name of the job • Invokes the ESP Workload Manager command processor• Triggers an Event, passing the name of the job as a user parameter
PROC 0WRITE Enter the name of the job you want to runREAD &JESP SUB(ESPX)TRIGGER &USER.ADDJOB USER1("&J")END
Section–Accessing ESP Workload Manager through a TSO command processor
40 ESP-5.4-UG-05
Accessing ESP Workload Manager througha TSO command processor
Calling ESP Workload Manager from a CLIST
You can also access ESP Workload Manager as a TSO command processor by using a CALL instruction to the ESP Workload Manager load library.
Note: Using this method, you can be limited by the size of the parameter list you pass on the CALL instruction.
Example: Calling ESP Workload Manager from a CLIST
The following is an example of a CLIST using a CALL instruction. In this example the subsystem name for ESP is ESPX. The CLIST:
• Prompts a user for the name of a job to be submitted • Accepts the name of the job • Calls the ESP Workload Manager TSO command processor• Triggers an Event, passing the name of the job as a user parameter
PROC 0WRITE Enter the name of the job you want to runREAD &JCALL 'CYB1.ESP510E.LOAD(ESP)' SUB(ESPX);-TRIGGER &USER.ADDJOB USER1("&J");END'
Exiting ESP Workload Manager
To exit ESP Workload Manager at any time:
Loading commands
The LOAD command lets you load a series of ESP Workload Manager commands for execution. You can enter your commands into a PDS or sequential data set. Later,
If you are... Action
using the ISPF panels... Press the END key (F3/15) until you return to the ISPF Primary Option Menu
in Line mode... Type END
in Page mode... Press F3/15
Chapter 2–Getting Started
ESP-5.4-UG-05 41
when you issue the LOAD command in Page mode, you can process this series of commands.
Example: Loading diagnostic commands from a data set
Suppose you have a member DIAG of a data set called CYB.ESP.DATA that contains a number of ESP Workload Manager diagnostic commands, like this:
SMFSTATSLISTRAKOPER LISTAPTFLISTCKPTLISTQ
You can process all of these commands by issuing the following command in Page mode:
LOAD 'CYB.ESP.DATA(DIAG)'
Sample output
SMFSTATSESP SUBSYSTEM INITIALIZED AT 12.43.58 ON MONDAY JUNE 25TH, 2001 9213 ENTRIES TO SMFWTM, 1592 BY BRANCH ENTRY AND 7621 BY SVC4863 ENTRIES TO ESP PHASE 27272 JOB STARTS, 595 STC STARTS, 645 TSU STARTS, 9051 STEP ENDS
LISTTRAKTRAKFILECYB3.ESP430NV.TRAKFILEFORMATTED AT 16.15.17 ON MONDAY SEPTEMBER 25TH, 20009296 SLOTS TOTAL, 8857 AVAILABLE, NEXT IS 6223
OPER LISTAPTFDATASET CYB3.ESP430NV.APPLFILE FORMATTED AT 15.00.54 ON MONDAY OCTOBER 16TH, 20006000 SLOTS TOTAL, 5735 AVAILABLE, NEXT IS 2504---1 ENTRY DISPLAYED
LISTCKPTPRIMARY CHECKPOINT CTB3.ESP430NV,CKPT MAX CHECKPOINT SIZE 614400HIGHEST ADDRESS USED 403280 BYTES IMBEDDED FREE SPACE
LISTQQUEUE DATASET CYB3.ESP430NV.QUEUEFORMATTED AT 13.44.57 ON MONDAY JUNE 11TH, 2001MAXIMUM SIZE 614400 BYTESHIGHEST ADDRESS USED 3888, 480 BYTES IMBEDDED FREE SPACE
Section–Alternative input data sets
42 ESP-5.4-UG-05
Alternative input data sets
In addition to standard operating system and VSAM data sets, you can input commands from Librarian and Panvalet data sets. Each of these data-set types has specific conventions.
Prefixes for data sets
You can use the following prefixes when you need to use one of these types of data sets:
Example
The following statement identifies a JCL library as a Panvalet data set.
JCLLIB PAN-PROD.JCL
Note: You cannot use ESP Workload Manager to write to Librarian and Panvalet data sets.
Prefix Type of Data set
LIB- Librarian
PAN- Panvalet
ESP-5.4-UG-05 43
Schedule Criteria
You can use free format, everyday English, to specify schedule criteria when scheduling Events and jobs. ESP Workload Manager has a built-in understanding of general scheduling terms. You can also add your own unique scheduling terms. These include special processing periods, holidays, and other special days. You can specify schedule criteria up to the year 2042.
This chapter contains the following topics:
• Where you can use schedule criteria• Specifying schedule criteria• Schedule terms• Using other techniques for schedule criteria• Testing schedule criteria• Using calendars• Using calendar terms• Working with calendars• Defining holidays• Defining special days• Special periods• Working with periods
Section–Where you can use schedule criteria
44 ESP-5.4-UG-05
Where you can use schedule criteria
You can use schedule criteria in the following ways:
• In SCHEDULE, NOSCHED, and EXPECT commands in Events• In HOLD, RELEASE, SUSPEND, RESUME, and DELETE commands in
Events • In commands that control Events (for example, HOLD, SUSPEND, TRIGGER)• In RUN/NORUN statements in an Application to specify schedule frequencies
for individual jobs• To specify other time dependencies for jobs in an Application (for example, early
start time, late submission time)• To define holidays, special days, and special processing periods in calendars• As part of the GENTIME command to generate date and time symbolic variables• To specify reporting times for history, scheduled activity, job mapping, and
modeling reports• In combination with many of the built-in functions (for example, TODAY,
DAYS_FROM) available with ESP Procedures• In CLANG
Specifying schedule criteria
Days of the week
ESP Workload Manager recognizes the following days of the week:
• Sunday• Monday• Tuesday • Wednesday• Thursday• Friday• Saturday
You can use the plural forms, such as Mondays and Fridays, and you can abbreviate the names to a minimum of three letters such as: sun, thu, fri. You can also specify multiple days of the week, for example, Monday Wednesday Friday.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 45
If you specify a day and a date that do not match each other, ESP Workload Manager automatically calculates the first specified day of the week on or after the date you requested. For example, May 14th, 2001 falls on a Monday.If you mistakenly specify the following:
TUESDAY MAY 14TH 2001you actually get this:
TUESDAY MAY 15TH 2001
Month names
ESP Workload Manager recognizes the following months of the year:
• January• February• March• April• May• June• July• August• September• October• November• December
You can abbreviate any month specification to a minimum of three letters, for example:
• APR• AUG
Section–Specifying schedule criteria
46 ESP-5.4-UG-05
Time zones
You can use the following time zone abbreviations for scheduling in ESP Workload Manager:
• LT: Local time• LOCAL: Local time• ADT: Atlantic Daylight Time• AST: Atlantic Standard Time• EDT: Eastern Daylight Time• EST: Eastern Standard Time• CDT: Central Daylight Time• CST: Central Standard Time• MDT: Mountain Daylight Time• MST: Mountain Standard Time• PDT: Pacific Daylight Time• PST: Pacific Standard Time• BST: British Summer Time• GMT: Greenwich Mean Time
You do not need to specify your own time zone in your schedule criteria. These are set in ESP Workload Manager initialization parameters.
Note: ESP Workload Manager assumes that any number preceding a time zone abbreviation is a time specification.
Time of day
The following table shows time-of-day formats that ESP Workload Manager accepts, where h and hh = hours, mm = minutes and ss = seconds.
Note: ESP Workload Manager assumes that any number preceding the letters AM or PM is a time specification, for example:
• 3AM• 6PM
Days of months
A number joined to the name of a month is recognized as a day of the month (for example jun3, 22oct, 6nov2001). The ordinal qualifiers st, nd, rd or th are also used
with a month name. For example, January21st, August29th.
Format Example
hh.mm 12.30
hh:mm 01:25
hh.mm.ss 10.47.30
hh:mm:ss 11:00:01
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 47
Julian date
A Julian date is recognized in the following formats, where yy or yyyy = year number and ddd = day number.
Date format
ESP Workload Manager recognizes the date format xx/xx/xx. The DATEFORM initialization parameter instructs ESP Workload Manager how to interpret this format. The following table shows the different formats (yy=year number, mm=month number, dd=day number) and how to express January 2, 2000 using them.
Note: Only one of these formats is valid at your installation. Check with your systems programmer or issue the DATEFORM operator command to determine which format you can use.
Ordinal numbers
Use ordinal numbers (for example, 1st or 5th) to refer to scheduling terms other than just day of month. For example, 2nd Monday of year. You can use more than one ordinal, as in 3rd and 4th month of year.
The following examples specify the first Monday of each month.
1ST MONDAY OF MONTH1ST MONDAY MONTHLY
The following example requests activity at 10 am on the third day of each month.
10AM 3RD MONTHLY
The next example requests activity at 10 am on the first Monday after the third day of each month.
10AM MONDAY 3RD MONTHLY
Date range
Use a hyphen to designate a range of dates. For example,
3RD-6TH DAY OF MONTH
Format Example
yy.ddd 01.056
yyyy.ddd 2001.056
Format Example
yy/mm/dd 00/12/28
dd/mm/yy 28/12/00
mm/dd/yy 12/28/00
Section–Specifying schedule criteria
48 ESP-5.4-UG-05
represents the 3rd, 4th, 5th, and 6th day of the month.
Implied periods
The following calendar terms are implied periods:
• WEEK• WEEKEND
Note: A weekend is defined as both Saturday and Sunday. Therefore, the first weekend
of a month starting on Sunday 1st consists of the Saturday 7th and the Sunday 8th.
• MONTH• YEAR
The following are valid:
2ND WEEKEND OF THE MONTH3RD DAY OF LAST WEEK OF YEAR5TH WORKDAY OF 2ND WEEK OF YEAR
Specifying a time and frequency
A schedule specification in an Event can consist of two parts. One part gives a starting date and time, while the other part describes an algorithm for computing subsequent dates and times. In an ESP Application, you must use separate statements to specify the time and the frequency of a job.
Starting Date and Time
• 9AM JANUARY 1ST• MIDNIGHT 9 DECEMBER 2000• 3PM
Subsequent Times
• DAILY • EVERY 2 WEEKS• MONTHLY• 4 TIMES
Matching criteria
Normally, you do not need to specify a starting time and date when you define a schedule. The first time and date that match the criteria you have entered is automatically selected.
• DAILY AT 19.00• WEDNESDAYS AT 3PM• WORKDAYS
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 49
To specify both an algorithm and a starting date and time:
Separate the two parts of the schedule specification with the scheduling term STARTING.
• 3PM DAILY STARTING JAN 1• WEEKDAYS EXCEPT WEDNESDAYS STARTING 2ND JUNE
Spaces
Spaces between words are not necessary if there are other delimiting factors in your date and time specification.
• SAT25JUN• EVERY5MINUTES
Using the first day of the week
Each calendar identifies the day that ESP Workload Manager considers the first day of the week. By default ESP Workload Manager considers Sunday to be the first day of each week. If you specify 1st day of week, ESP Workload Manager uses the calendar to determine what day this is.
Using workdays
Each calendar has its own workdays. By default workdays are Monday through Friday excluding holidays. If you specify 2nd workday of month, ESP Workload Manager looks for the second day of the month which is not a weekend or holiday.
Absolute vs. logical days
By default a day is considered to be an absolute day beginning at midnight (00:00). To override the default, you can define a calendar as logical and identify the start time of your logical day.
For example, if your logical day begins at 08:00 and you schedule an Event to execute Monday at 2 a.m., the Event actually executes Tuesday morning at 2 a.m.
Workday Weekend Weekend Holiday Workday Workday Workday
1 X X X 2 3 4
Absolute Calendar
SCHEDULE 2AM MONDAY
Event scheduled at 2 am Monday
Logical Calendar
SCHEDULE 2AM MONDAY
Event scheduled at 2 am Tuesday
Section–Schedule terms
50 ESP-5.4-UG-05
Important: Cybermation recommends you use absolute calendars because of their ease of use.
Schedule terms
You can use words and phrases other than specific dates and times to define schedule criteria. The following is a list of other terms recognized by ESP Workload Manager.
Term recognized by ESP Workload Manager
Explanation
ABSOLUTE Specifies that you are using an absolute day (that is, beginning at 00:00). This is only required when your calendar is a logical calendar, with a start time other than 00:00.
AND Specifies multiple similar scheduling terms (for example days of the month or months of the year) and ordinal numbers. For example, Monday and Tuesday, 1st, 4th, and 9th, Monday of June July and August. AND cannot be used with times of day; separate schedule commands are required.
ANYDAY Specifies that there is no day of the week restriction. You can abbreviate this term to ANY.
COMPLETE Ensures that the schedule only occurs during a complete period. Used only with the LAST scheduling term. For example, you can specify last complete week of year or last complete week of quarter If a fiscal week starts in one quarter but finishes in the next quarter, ESP Workload Manager provides a schedule for the previous complete fiscal week.
DAILY Means every day.
ENDING Allows you to specify the end date for any schedule interval, for example, daily at 9 am starting tomorrow ending 1jul2000. You cannot use this qualifier in a RUN/NORUN statement.
EACH Means every occurrence of.
EVERY n units Requests a recurrence of the Event at every n units of time. The units can be any of SECONDS, MINUTES, HOURS, WORKDAYS, DAYS, WEEKS, MONTHS, or YEARS, while n can be any number from one to 32767. For example, every one hour round less five minutes requests an Event at five minutes before the hour, every hour. Note that five minutes are subtracted from the base time (every hour on the hour). You cannot use this qualifier in a RUN/NORUN statement.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 51
EXCEPT Excludes a day of the week or holidays. For example “weekdays except Wednesdays” limits activity to Monday, Tuesday, Thursday, and Friday. “daily except holidays” limits activity to days which are not holidays. You cannot use EXCEPT with a term other than a day of the week or the term HOLIDAYS.
FIRST Specifies the first occurrence of a particular day or period. For example, you can specify “first Monday of month”, “first fiscal_month of fiscal_year”. You can also use the ordinal number 1st.
HOURLY Means every one hour. You cannot use this term in a RUN/NORUN statement.
HOLIDAYS Refers to all holidays. You can refer to specific holidays by name.
LAST Specifies the last (for example, final) occurrence of a particular day or period. For example, you can specify last holiday of year, last workday of fiscal_month, first and last Tuesday of month.
LESS n units Specifies a value to be subtracted from the base time to produce a time/date execution time. n must be a whole number. For example, you can specify less two weekdays, less one month, less zero workdays.
LOGICAL Specifies that you are using a logical as opposed to an absolute day (that is, beginning at 00:00). The start time of your logical day must be specified in a calendar. For example, you can specify 2 am logical Tuesday, 7 am first logical workday of month. LOGICAL can be set as a default at calendar definition time.
MIDDAY Specifies 12.00, noon.
MIDNIGHT Specifies 24.00, midnight. 24.00 is normally recognized as being the same as 00.00. Thus, if you specify Monday at 24.00 it will be stored as 00.00 Tuesday.
MONTHLY Means every month. You cannot use this qualifier by itself in a RUN/NORUN statement (for example, you can use RUN 15TH MONTHLY, but you cannot use RUN MONTHLY).
n TIMES Specifies the number of times you want a schedule to occur, such as daily at 9 am six times starting tomorrow. You cannot use this qualifier in a RUN/NORUN statement.
NOW Refers to the scheduled time. This is useful when you need up-to-the minute information, as when obtaining a report for example. You could request a report from any time in the past until NOW. You cannot use this qualifier in an Event definition on its own. See note at the end of this section.
Term recognized by ESP Workload Manager
Explanation
Section–Schedule terms
52 ESP-5.4-UG-05
OF Restricts the schedule action to a period such as a month.
Note: If you specify 5TH SATURDAY OF JUNE, you get results in July when June has only 4 Saturdays. Use WITHIN if you want the result absolutely restricted to the specified period.
ONCE Means that a scheduled command will be processed once only, at the time specified. If you specify a date in an Event without ONCE, the default frequency is DAILY. You cannot use this qualifier in a RUN/NORUN statement.
OR Specifies either of two similar scheduling terms, such as Monday or Tuesday. OR implies whichever happens first, and as such can only be used where it is meaningful and does not lead to ambiguity.
OVERDUE(n) Specifies how many overdue occurrences of an Event are to be initiated should an Event miss its scheduled time. ESP Workload Manager schedules the Event once for each missed occurrence, up to the number specified. You can only use this on a SCHEDULE command in an Event definition.
PLUS n units Specifies a value to be added to the base time to produce a time/date execution time. n must be a whole number. For example, you can specify plus two weekdays, plus zero workdays, plus one week.
REALNOW Refers to the actual time. You cannot use this term in an Event definition on its own. See note at the end of this section.
ROUND Specifies that the computed time is an integral multiple of the units parameter. This word can be used together with the EVERY n UNITS phrase. For example, specifying every one hour round requests every hour at the hour mark. Every six hours round requests the times 00.00, 06.00, 12.00, and 18.00. Specifying every five hours round provides the next hour that is an integral multiple of five hours starting at 00.00 on January1st, 1900.
STARTING Specifies a starting date and time. It splits the schedule specification into two parts. The first part is an algorithm, and the second part is the starting time or date. The time or date to the left of STARTING is the time when you want the Event to execute. The time or date to the right of STARTING is the time when you want the first execution to occur. Use an actual date or time after STARTING. A repetition, such as every five minutes, is not valid. You cannot use this qualifier in a RUN/NORUN statement.
TODAY Specifies today.
Term recognized by ESP Workload Manager
Explanation
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 53
Note: When working with jobs in an ESP Application, NOW refers to the scheduled time of the Event that triggered the ESP Application; REALNOW refers to the actual time the Event was triggered.
Using ordinal numbers
If you use an ordinal number as part of the STARTING operand with a special period or special day, and without using nested levels, ESP Workload Manager assumes that you mean from today. For example, 10 pm daily starting 5th payroll_day provides the fifth payroll day from now.
If you use an ordinal number with a schedule term (other than with the STARTING operand) without stating what the schedule term refers to, ESP Workload Manager assumes the following defaults:
TOMORROW Specifies tomorrow. You cannot use this term in a RUN/NORUN statement.
UNTIL Specifies the end date for any schedule interval, for example, daily at 9 am starting tomorrow until 1jul2001. You cannot use this qualifier in a RUN/NORUN statement.
WEEKDAYS Requests that the schedule actions occur only on weekdays (Monday through Friday).
WEEKENDS Requests that the scheduled actions occur only on Saturday and Sunday.
WITHIN Restricts the schedule action to be within a period such as a specific month.
WORKDAYS Requests that the schedule actions occur only on workdays. Each calendar identifies workdays. Workdays exclude holidays. Default workdays are Monday through Friday.
YEARLY Means every one year. You cannot use this qualifier in a RUN/NORUN statement.
YESTERDAY Specifies yesterday. This term is useful in reporting. You cannot use YESTERDAY in an Event definition or in a RUN/NORUN statement.
Schedule Term ESP Workload Manager Default
date, day name, or workday of month
week or month of year
holiday of year
special day or period of year
Term recognized by ESP Workload Manager
Explanation
Section–Schedule terms
54 ESP-5.4-UG-05
For example, if you specify 3rd Friday at 9 am the schedule occurs at 9 am on the third Friday of every month, while 9 am last holiday provides a schedule on the last holiday of the calendar year.
Examples of schedule criteria
Here are some examples of schedule criteria, each of which can be handled with one statement. See “Using other techniques for schedule criteria” on page 57 for information on handling more complex criteria.
Daily or multiple times a day
• 6 am each day:
6AM DAILY
• Every day in October:
ANYDAY WITHIN 10TH MONTH OF YEAR
• Every 30 minutes beginning at 2 pm today:
EVERY 30 MINUTES ROUND STARTING 2PM TODAY
Multiple times a week
• Monday, Wednesday and Friday:
MON WED FRI
• Everyday except Mondays:
DAILY EXCEPT MONDAYS
• 19:00 on Saturdays and Sundays:
19.00 WEEKENDS
• Every other workday beginning this Friday:
EVERY 2 WORKDAYS STARTING FRIDAY
Weekly
• Last workday of each week:
LAST WORKDAY OF WEEK
• Every Saturday in June:
SATURDAY OF JUNE
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 55
Monthly
• 8 am on the last Saturday of each month, beginning in October 2004:
8:00 LAST SATURDAY OF MONTH STARTING OCTOBER, 2004
• 8 am on the 3rd workday of each month:
8AM 3RD WORKDAY
• 15th day of March, June and August:
15TH DAY OF MARCH JUNE AUGUST
• 2nd last workday of each month:
LAST WORKDAY OF MONTH LESS 1 WORKDAY
• First Friday of each month. If this is not a workday, then run on the next workday after the first Friday of the month:
FIRST FRIDAY OF MONTH PLUS 0 WORKDAYS
• First weekday (for example, Monday through Friday) on or after the 15th day of the month:
15TH DAY OF MONTH PLUS 0 WEEKDAYS
• Friday after the 1st Sunday of the month:
1ST SUNDAY OF MONTH PLUS 5 DAYS
• 1st Saturday of the month. If this is also the first day of the month then run on 2nd Saturday of month:
SATURDAY 2ND MONTHLY
ESP Workload Manager interprets the above expression as the first Saturday on or after the 2nd day of the month.
• 31st day of the month, but only if there are 31 days in the month:
31ST DAY WITHIN MONTH
ESP Workload Manager interprets the above expression as the 31st of January, March, May, July, August, October, or December.
• 31st day of the month, regardless of the number of days in the month:
31ST DAY OF MONTH
ESP Workload Manager interprets the above expression as the 31st of January, 3rd of March (2nd of March for leap years), 31st of March., 1st of May, 31st of May, 1st of July, 31st of July, 31st of August, 1st of October, 31st of October, 1st of December, and 31st of December.
Section–Schedule terms
56 ESP-5.4-UG-05
Multiple times a month
• 10 am on the 3rd, 13th, and 23rd day of month:
10AM 3RD 13TH 23RD DAY OF MONTH
• 6 am from the 10th to the 20th day of each month:
6AM 10TH - 20TH DAY WITHIN MONTH
• 3rd, 9th, 10th, 11th, 12th, and 14th workday of each month:
3RD 9TH - 12TH 14TH WORKDAY WITHIN MONTH
• Every other Monday beginning next Monday:
EVERY 2 WEEKS STARTING MONDAY
• Every other Monday beginning in a week from next Monday:
EVERY 2 WEEKS STARTING MONDAY PLUS 1 WEEK
• 3rd and 4th Sunday of month if there are four Sundays in the month;3rd and 5th Sunday of month if there are five Sundays in the month:
3RD AND LAST SUNDAY OF MONTH
Yearly
• Each year on July 23:
JULY 23 YEARLY
One-time examples
• 11 pm on April 26, 2000:
11PM APRIL 26, 2000 ONCE
• 300th day of 2000:
00.300
• December 21, 2001 (assuming date format is mm/dd/yy):
12/21/01
Difference between OF and WITHIN
In most situations, you will obtain the same result when using OF or WITHIN. The following examples shows the different result between the two schedule terms:
TEST (3) 5TH SATURDAY OF AUGUST STARTING 200300.00.00 SATURDAY AUGUST 30TH 2003 DAY 24200.00.00 SATURDAY SEPTEMBER 4TH 2004 DAY 24800.00.00 SATURDAY SEPTEMBER 3RD 2005 DAY 246
TEST (3) 5TH SATURDAY WITHIN AUGUST STARTING 200300.00.00 SATURDAY AUGUST 30TH 2003 DAY 242
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 57
00.00.00 SATURDAY AUGUST 30TH 2008 DAY 24300.00.00 SATURDAY AUGUST 29TH 2009 DAY 241
Using other techniques for schedule criteria
CLANG and GENTIME
For some criteria, you can use ESP Workload Manager CLANG (Control Language) or the GENTIME command.
The ESP Workload Manager Advanced User’s Guide contains some examples of schedule criteria that use the above techniques. For instance, it describes how to:
• Run a job every two weeks in an Application• Run a job based on what day of the week a particular criteria falls on• Use symbolic variables for schedule criteria• Schedule on even days of the month
Testing schedule criteria
You can test schedule criteria, prior to actually using them, with the TEST command. This tests any date or schedule specification. ESP Workload Manager responds with the actual date and time. If you specify a number in parentheses after the command, ESP Workload Manager displays as many subsequent dates and times as you indicated. This facility is also available through option E.4 from the ESP Workload Manager Main Menu.
Example: Testing criteria
If you want to test last workday of month for the next five months, type
TEST (5) LAST WORKDAY OF MONTH
ESP Workload Manager Command
Explanation
CLANG Provides you with IF-THEN-ELSE logic and some built-in functions (for example, DAYS_TO). See “Working with ESP Procedures” on page 107 for more information.
GENTIME Allows you to generate date and time symbolic variables for any date/time.
Section–Using calendars
58 ESP-5.4-UG-05
ESP Workload Manager displays output similar to the following:
00.00.00 THURSDAY MAY 31ST, 2001, DAY 15100.00.00 FRIDAY JUNE 29TH, 2001, DAY 18000.00.00 TUESDAY JULY 31ST, 2001, DAY 21200.00.00 FRIDAY AUGUST 31ST, 2001, DAY 24300.00.00 FRIDAY SEPTEMBER 28TH, 2001, DAY 271
Using calendars
ESP Workload Manager has a built-in understanding of scheduling terms, such as dates and times, based on the Gregorian calendar. Your installation can have other scheduling terms specific to it, such as holidays, special days, and special processing periods. You must define these terms to ESP Workload Manager through an ESP Workload Manager calendar. You must be aware of the security authority necessary to perform each action.
You do not need to define most calendar terms to ESP Workload Manager to use them. ESP Workload Manager already recognizes general scheduling terms. Administrators can create calendars to store definitions of scheduling elements unique to your installation—your holidays, special days and special processing periods. A calendar also identifies workdays, the first day of the week, and the start time for a day. Your administrator defines calendars and controls access to them.
Special days and periods
A special day is useful when a particular schedule criteria is difficult to describe with an algorithm. Special periods are defined the same way as special days. A set of periods with the same name can occur at regular intervals, such as fiscal year, or a trading period. You can also define periods that have irregular intervals and then refer to these special periods when specifying a schedule. A single calendar can contain many different special days and periods.
Users at your installation need to use an ESP Workload Manager calendar to define scheduling terms that satisfy their specific processing requirements. Users can define and control their own unique scheduling terms, beyond the default calendar terms. Upon installation of ESP Workload Manager, a calendar called SYSTEM is defined. It can be sufficient for your installation. All Events have read access to this calendar.
The reasons users can define their own terms include the following:
• They need to schedule work to accommodate holidays. With ESP Workload Manager you can advance, delay, or ignore processing on holidays.
• Departments have special processing requirements at specific times of the year.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 59
Example
The accounting department:
• Can consider the period from September 01 to August 31 its fiscal year• Can then define a special period in a calendar and call that period fiscal_ year • Can have ESP Workload Manager perform specific tasks in that period by
referring to the name fiscal_year when setting up schedule criteria for the tasks
Using calendar terms
Different groups of users can have their own set of unique holidays, special days and periods. Even if they choose the same names for a set of special days or periods, the reference only applies to the special day or period in the calendar named in an Event.
A calendar can contain the following:
• A list of holidays, which can span one day, several days, or just parts of a day• Lists of special processing dates• Descriptions of periods, such as fiscal months, fiscal years, and 4-4-5 periods
SYSTEM calendar
Only global holidays and special days should be stored in the SYSTEM calendar. Department-specific holidays and special days can be stored in as many calendars as required. ESP Workload Manager always uses the system calendar.
CALENDAR command
Use a CALENDAR command in an Event to refer to a maximum of two calendars. If you do not refer to a calendar in the Event, ESP Workload Manager automatically uses the default calendars your administrator assigned to you or your group. ESP Workload Manager merges holiday definitions in all calendars associated with an Event. For special days, workdays, and the first day of the week, ESP Workload Manager uses the first definition it encounters.
Note: The system calendar is always used. For example, if
• Your system calendar defines July 1st as a holiday
• You define July 2nd in calendar A and July 3rd in calendar B as holidays• You use the CALENDAR command to refer to calendars A and B
ESP Workload Manager consider that July 1st, 2nd, and 3rd are holidays.
Section–Working with calendars
60 ESP-5.4-UG-05
Default calendar
When defining holidays, special days and special periods, specify which calendar will be used to store the definition. If you do not specify a calendar name, your first default calendar as defined in your user ID entry will be used. If you do not have a first default calendar, your second default calendar is used. If you do not have any default calendars defined, the entry automatically goes into the SYSTEM calendar.
Default values for a calendar
ESP Workload Manager provides the following default values for a calendar:
• Workdays of the week—Monday to Friday, inclusively, and excluding any holidays
• Absolute days (each day starts at midnight)• The first day of the week (Sunday)
Retaining entries
ESP Workload Manager checks for and deletes old entries only when a calendar is updated for other define and delete requests. When more than two days have gone by since holiday and special day entries have occurred, they are automatically deleted unless you specify otherwise using the RETAIN operand at definition time.
Working with calendars
Defining a calendar
Before you define ESP Workload Manager calendars, you should review:
• How many calendars you need to define• Which days you need to define as workdays• Which day will be considered the first day of the week• Which group or user will own which calendar• Who will own the SYSTEM calendar
To define a calendar:
Use the DEFCAL command.
When defining a calendar, you must specify a calendar name.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 61
Optional specifications
• An owner for the calendar• A department to which the calendar belongs• The definition of the calendar as absolute or logical (defaults to absolute if not
specified)• The start time of a logical day (defaults to midnight if not specified)• The first day of the week (defaults to Sunday if not specified)• Workdays (defaults to Monday to Friday if not specified)
Example 1
This example defines the SYSTEM calendar. By default, the week starts on Sunday, and the workdays are Monday to Friday inclusively.
DEFCAL SYSTEM
Example 2
This example defines calendar FISCAL. The first day of the week is Monday, and workdays are Monday to Saturday inclusively.
DEFCAL FISCAL WEEKSTART(MON) -WORKDAYS(MON,TUE,WED,THU,FRI,SAT)
To define a calendar using panels:
1. Select option M from the Main menu.
2. Select option 3 from the Administrator Subcommands menu. The Calendar Definitions panel appears.
Section–Working with calendars
62 ESP-5.4-UG-05
3. Type A to define a new calendar, and specify the calendar name. The Define a Calendar panel appears.
4. Specify values as applicable.
Altering a calendar
To alter a calendar
• Use the ALTCAL command.
Example
This example changes the first day of the week for the SYSTEM calendar:
ALTCAL SYSTEM WEEKSTART(MON)
Note: You can also use the Calendar Definitions panel to alter a calendar.
Displaying a calendar
After you have defined a calendar, and those users with update access have defined their scheduling terms in the calendar, you or any other user can review information about the calendar. You can review the calendar information for troubleshooting and maintenance. Other users who have read access to the calendar will find it useful to review the calendar information before using it in an Event or Application.
To display a calendar:
• Use the LISTCAL command to display information about a calendar.
To display information about a specific calendar:
• Specify its name.
If you do not specify the calendar name, ESP Workload Manager displays information about the most recent calendar it retrieved. If you did not specify a calendar name, you are prompted for one.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 63
Example 1
This example displays information about the SYSTEM calendar. Workdays are Monday through Friday. CHRISTMAS and NEW_YEARS are two holidays defined for two years. There is one definition of a special day called INVENTORY_DAY.
listcal systemCALENDAR NAME:SYSTEMDEPARTMENT:NONEDEFINED:AT 11.45 ON THU 13TH AUG 2001 BY CYBBT01OWNER:CYBBT01WORKDAYS:MON TUE WED THU FRIWEEK STARTS:MONSIZE:280 BYTESHOLIDAYS:CHRISTMAS, NEW_YEARS, CHRISTMAS, NEW_YEARSSPECIAL DAYS:INVENTORY_DAY(1)
Example 2
This example displays information about a calendar called PAYCAL. It belongs to the PAYROLL department, and workdays are Monday through Saturday. The week starts on Monday. No holidays are defined. There are 24 definitions of PAYROLL_PERIOD and one definition of PAYROLL_REVIEW.
listcal paycalCALENDAR NAME:PAYCALDEPARTMENT:PAYROLLDEFINED:AT 08.21 ON FRI 14TH SEP 2001 BY BP01OWNER:BP01WORKDAYS:MON TUE WED THU FRI SATWEEK STARTS:MONSIZE:472 BYTESHOLIDAYS:NONESPECIAL DAYS PAYROLL_PERIOD(24), PAYROLL_REVIEW(1)
Displaying holidays and special days
The LISTCAL command displays a summary of holidays and special days.
Note: You can also use the Calendar Definitions panel to display a calendar.
To display more detailed information on these calendar items:
• Use the LISTHOL command to list holiday definitions.• Use the LISTSPEC command to list special day and special period definitions.
Deleting a calendar
A calendar can exist for a specific purpose after which the user can decide to delete it.
Section–Working with calendars
64 ESP-5.4-UG-05
To delete a calendar:
• Use the DELCAL command. Specify the name of the calendar you want deleted.
Note: Deleting a calendar that is referenced from an Event causes the Event to have a processing error.
In this example, ESP Workload Manager deletes calendar CENTRAL and all of its contents.
DELCAL CENTRAL
Note: You can also use the Calendar Definitions panel to delete a calendar.
Referencing a calendar
Using the DEFCAL command, you can define as many calendars as are needed for your organization.
Users can then use a CALENDAR command in an Event to refer to a maximum of two calendars plus the SYSTEM calendar. If a user does not refer to a calendar in the Event, ESP Workload Manager automatically uses the default calendars you assigned to the user or to the group to which the user belongs.
Scheduling terms
After you create a calendar, users define their unique scheduling terms in the calendar. ESP Workload Manager merges holiday definitions in all calendars associated with an Event. For special days, workdays, and the first day of the week, it uses the first definition it encounters.
The example below shows an Event with a calendar command that references the PAYCAL calendar. When ESP Workload Manager executes this Event, it reads this calendar and the SYSTEM calendar for scheduling terms.
EVENT ID(PAYROLL.PROCESSING)CALENDAR PAYCAL
Specifying a logical day
By default, ESP Workload Manager considers each day to begin at 00:00. It refers to a day that begins at 00:00 as the absolute day. However, your organization can consider its day starting at 7:30 a.m—that is, a logical day.
To define your organization’s logical day in a calendar:
1. Specify the LOGICAL parameter on the DEFCAL or ALTCAL commands.
2. Assign a value to the SHIFT parameter on the DEFCAL or ALTCAL commands.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 65
This example defines the calendar BPCAL and specifies the start of the logical day at 7:30 am
DEFCAL BPCAL OWNER(BP) LOGICAL SHIFT(07:30)
Note: You should not need to use logical calendars. They can cause unanticipated results. Cybermation recommends you use absolute calendars because of their ease of use and because they can handle almost all scheduling requirements.
Defining holidays
To define holidays:
Use the DEFHOL command.
or
Use Option L of the Main Menu.
You can use up to 16 characters to name each holiday, and you must give a start date in each holiday definition. The time duration for a holiday is 24 hours, unless you specify otherwise.
You can define multiple holidays with the same name. However, if they are on the same calendar, each holiday must have a different starting date and time. If you are creating consecutive holidays, you may find it simpler to combine them into one holiday with the duration set to the total duration of the separate holidays.
If the holiday you define was a workday, this day is no longer considered to be a workday for scheduling purposes.
Note: For logical day processing, holidays should be defined in ABSOLUTE terms even if stored in a LOGICAL calendar.
You cannot define a holiday in a given calendar if there is a special day with the same name defined in that calendar or in the system calendar. However, if the special day is defined elsewhere, you can define a holiday with the same name as the special day. In that case, a warning appears in the audit log.
Example: Defining a holiday
This example defines a 24-hour holiday, called BANK_HOLIDAY, on the next occurrence of the 1st Monday of August:
DEFHOL BANK_HOLIDAY START('1ST MONDAY OF AUGUST') FOR(24)
Section–Defining holidays
66 ESP-5.4-UG-05
Example: Defining a holiday using a panel
This example uses Option L to define a holiday.
Example: Defining a repetitive holiday
This example shows how a batch job defines a 24-hour holiday called CHRISTMAS for three years. The subsystem name for ESP Workload Manager in this example is ESPM:
//HOLIDAY JOB ...//EXEC PGM=ESP,PARM='SUBSYS(ESPM)',REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *DEFHOL CHRISTMAS START('DEC25,2001') FOR(24)DEFHOL CHRISTMAS START('DEC25,2002') FOR(24)DEFHOL CHRISTMAS START('DEC25,2003') FOR(24)
Using holidays
Once holidays are defined, you can use them as you would any other scheduling terms. Some examples are shown below:
• 16:00 every holiday:16:00 HOLIDAY
• One workday before BANK_HOLIDAY:BANK_HOLIDAY LESS 1 WORKDAY
Event processing of holidays
In an Event definition, you can schedule on holidays. You can bypass, delay, or advance the schedule if it normally falls on a holiday or a particular day of the week. The calendars associated with the Event and the SYSTEM calendar are searched for holiday entries. If no calendars are specified in the Event, the owning group’s or user’s default calendars and the SYSTEM calendar are used.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 67
Job processing of holidays
The RUN statement identifies schedule criteria for a job in an ESP Application. For more information, see “Using Applications” on page 137.
• Run every holiday: RUN HOLIDAY
• Run on Christmas: RUN CHRISTMAS
• Run on workdays: RUN WORKDAYS
Example: Advancing / delaying a job
When specifying the frequency of a job in an ESP Application, you can advance or delay processing based on a holiday. For example:
RUN FRIDAY PLUS 0 WORKDAYSRUN FRIDAY LESS 0 WORKDAYS
• The first statement instructs ESP Workload Manager to run a job on Friday. If this is a holiday, run the job on the following workday.
• The second statement instructs ESP Workload Manager to run a job on Friday. If this is a holiday, run the job on the previous workday.
Defining special days
Your installation can consider its fiscal year to be from September 1 to August 31. You can define this special period to ESP Workload Manager in a calendar. Then, you can use the period in an ESP Event by specifying the calendar in the Event. However, you can only define the special period, or a special day, in the calendar if the calendar is one of your default calendars, or if you have access to the calendar. If neither of these conditions is true, ESP Workload Manager defines the special period, or a special day, in the SYSTEM calendar.
You cannot define a special day in a given calendar if there is a holiday with the same name defined in that calendar or in the system calendar. However, if the holiday is defined elsewhere, you can define a special day with the same name as the holiday. In that case, a warning appears in the audit log.
To define special days:
• Use the DEFSPEC command or use Option L of the Main Menu.
Section–Special periods
68 ESP-5.4-UG-05
Example
The following example defines April 20, 2000 as a special day called BALANCE_DAY:
DEFSPEC BALANCE_DAY ON('APR20,2000')
You can define more than one day as BALANCE_DAY.
For example:
DEFSPEC BALANCE_DAY ON('AUG23,2000')DEFSPEC BALANCE_DAY ON('OCT17,2000')
Using special days
Once you define a special day, you can then use it as a scheduling term. Some examples are shown below:
• 17:00 on BALANCE_DAY:17:00 BALANCE_DAY
• two workdays before BALANCE_DAY at 10 am:10AM BALANCE_DAY LESS 2 WORKDAYS
• One week after BALANCE_DAY at 4 pm:4PM BALANCE_DAY PLUS 1 WEEK
Example
If there is a pattern to the special days you are defining, use the REPEAT operand to define multiple special days using a single command.
The following example shows how to define the next 10 fiscal years on February 1st.
Each FISCAL_YEAR definition will be retained in the calendar called FISCAL for two years.
DEFSPEC FISCAL_YEAR REPEAT('10 TIMES FEB1 YEARLY') –CALENDAR(FISCAL) RETAIN(2,YEARS)
Special periods
A special period is the period between two special days. Therefore, you need at least two special days to use special periods.
To define the first day of each period:
• Use the DEFSPEC command.
When defining multiple regular periods, you can use the REPEAT operand of the DEFSPEC command. Specify either n times for the special period or until... to define
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 69
as many periods as you need. If you are not using REPEAT, include one extra period at the end of your definitions to give ESP Workload Manager a final reference point. For example, define the first day of at least two consecutive fiscal years, so that ESP Workload Manager can calculate the start and finish of the first year. Use an alphanumeric name of up to 16 characters for the name of your special period. The first character must be alphabetic, and you should not use blanks. You can also specify the name of a particular calendar to which the period definitions apply.
Example
This example defines fiscal years:
DEFSPEC FISCAL_YEAR ON(1APRIL97) RETAIN(2,YEARS)DEFSPEC FISCAL_YEAR ON(1APRIL98) RETAIN(2,YEARS)DEFSPEC FISCAL_YEAR ON(1APRIL99) RETAIN(2,YEARS)
Period intervals
Period intervals do not have to be regular. One trading period, for example, can start three weeks after the beginning of the previous trading period, and five weeks before the beginning of the next. Simply tell ESP Workload Manager when each period starts. When two special days of the same names are defined in a calendar, you have essentially defined a period from the first special day up to the second special day. In the above example, ESP Workload Manager knows that the last day of each FISCAL_YEAR is 31st March.
Use this method for any special period you want to define, regardless of the intervals between the start of each period: every five days, three weeks, or four months.
Example
This example shows how to define payroll periods every two weeks for the next year using the REPEAT operand. Each PAYROLL_PERIOD is retained on the PAYCAL calendar for one year after it occurs.
DEFSPEC PAYROLL_PERIOD REPEAT('26 TIMES EVERY 2 -WEEKS STARTING THURSDAY') CALENDAR(PAYCAL) -RETAIN(1,YEAR)
Using ISPF panels
To achieve the same result using the ISPF panels:
1. Select Option L (Calendars) from the Main Selection Menu.
2. Select Option 4 (Define a Special Day) from the Calendar Control Menu.
Section–Working with periods
70 ESP-5.4-UG-05
3. Proceed as illustrated below:
Using special periods
Once you define a special period, you can use criteria as illustrated below:
• Last day of PAYROLL_PERIOD:LAST DAY OF PAYROLL_PERIOD
• 2nd, 3rd, and 4th day of PAYROLL_PERIOD:2ND-4TH DAY OF PAYROLL_PERIOD
• 1st day of the current PAYROLL_PERIOD:FIRST DAY OF PAYROLL_PERIOD STARTING TODAY
• 1st day of the next PAYROLL_PERIOD:PAYROLL_PERIOD
Working with periods
This example illustrates the use of 4-4-5 periods, where there is a four week period, followed by a four week period, followed by a five week period.
Chapter 3–Schedule Criteria
ESP-5.4-UG-05 71
The first few periods look like this:
Option L
Using option L.4 you can define these periods, for a year, as follows:
Length of Quarter
13 weeks
13 weeks
Duration
4 weeks
4 weeks
5 weeks
4 weeks
4 weeks
5 weeks
Start of Period
June 28
July 26
August 23
Septem ber 27
October 25
Novem ber 22
Decem ber 27
ESP ------------------------------ CALENDARS ----------------------------- ESPCOMMAND ===>
Define a special day
For each occurrence of the special day you want to define, complete SPECIALDAY NAME, ON, and CALENDAR if required, then press,ENTER.The ON fields can contain specific dates and times, or schedule statementsfor special days that occur at regular intervals.
SPECIAL DAY NAME ===> PERIOD445
ON ===> 4 TIMES EVERY 13 WEEKS STARTING JUN 28 ON ===> 4 TIMES EVERY 13 WEEKS STARTING JUL 26 ON ===> 5 TIMES EVERY 13 WEEKS STARTING AUG 23 ON ===> ON ===> ON ===> ON ===> TARGET CALENDAR ===> PAYCAL SOURCE CALENDAR ===> ===>, RETAIN COUNT ===> 1 UNITS,===> Y (D=DAYS, W=WEEKS, Y=YEARS)ANY MORE? ===> (Enter Y to define more special days)
Section–Working with periods
72 ESP-5.4-UG-05
Quarters and fiscal years
You can also define quarters and fiscal years, if you need to. Once you have, you can use such criteria as shown below. You do not need to know the day of the week or the date to which each statement refers. ESP Workload Manager calculates this for you.
• First workday of PERIOD445:1ST WORKDAY OF PERIOD445
• First workday of the current PERIOD445:1ST WORKDAY OF PERIOD445 STARTING TODAY
• Last workday of the 2nd week of PERIOD445:LAST WORKDAY OF 2ND WEEK OF PERIOD445
• 4th workday of the 3rd PERIOD445 of FISCAL_YEAR:4TH WORKDAY OF 3RD PERIOD445 OF FISCAL_YEAR
ESP-5.4-UG-05 73
Processing ESP Events
An Event is a basic unit of work. Information in an Event defines when ESP Workload Manager must perform the work and the actions it must take to do so.
This chapter contains the following topics:
• Defining an ESP Event• Specifying data-set-triggered Events• Specifying FTP data-set triggered Events• Specifying explicit-data-set triggers• Specifying the function of an Event• Issuing operator commands• Specifying other requirements• Displaying the schedule• Displaying when an Event will execute• Working with defined Events
Section–Defining an ESP Event
74 ESP-5.4-UG-05
Defining an ESP Event
When you define an ESP Event, you define what you want ESP Workload Manager to perform and when you want it performed. Before saving an Event, ESP Workload Manager evaluates the schedule criteria, if any, and decides when to first schedule it. Events are saved in an EVENTSET, which is a VSAM data set defined to ESP Workload Manager. You can later display or manipulate your Event if you need to look at or change it. You can also add or delete Events at any time.
To define an Event:
Use one of the following methods:
• Use the ISPF panels • Modify and save an existing Event under a new name• Load an Event definition from a sequential data set or member of a PDS, using
the LOAD command• Define the individual commands of an Event line by line
Example
EVENT ID(PROD.FIRST_EVENT)SCHEDULE 5PM FIRST WORKDAY OF MONTHSUBMIT 'TEST.JCL.CNTL(JOB1)'ENDDEF
In this example:
• The definition begins with the EVENT command and the Event name. • The SCHEDULE command tells ESP Workload Manager when to schedule the
Event.• The SUBMIT command tells ESP Workload Manager what to do; in this case,
submit a job.• The ENDDEF command indicates the end of the definition.
When ESP Workload Manager encounters the ENDDEF command, it sends the Event to the ESP Workload Manager subsystem for processing. It also sends a message to the user who defined it, telling the date and time on which the Event will first execute, or warning the user that no schedule elements exist.
Naming an Event
The first step in defining the Event is naming. Naming an Event establishes its ownership, which is important for security. Not all users have the same authority or access to functions and resources. A security system such as RACF, CA-ACF2, or CA-Top Secret, as well as ESP Workload Manager internal security, can control the authority and access users have.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 75
Event name
An Event name has two parts:
Duplicate Events
When an Event with the same name already exists, ESP Workload Manager ignores your new definition. To replace the old definition with the new one, use the REPLACE operand.
Use of the prefix
When ESP Workload Manager triggers an Event, it must verify the security requirements of the actions the Event performs. The security identifier is determined by a number of settings. For more information on security, see the ESP Workload Manager Security Guide.
Event prefixes
In the next diagram:
• The prefix for Events TRAINING and PAYROLL is PROD.• The prefix for Event PHONE_BILL is DOROTHY.• The user DOROTHY has access to her own Events and to Events starting with
the prefix PROD.
Part of Event name Explanation
Prefix Specifies the name of a user or group containing up to 8 alphanumeric characters, including the national characters. This prefix must be a prefix you are allowed to use. Your ESP Workload Manager administrator controls which prefixes you are allowed to use.
Descriptive name Specifies a description that can contain up to 16 characters, including the national characters and the underscore. The first character must be alphabetic.
DOROTHY
PROD.TRAINING
PROD.PAYROLL
DOROTHY.PHONE_BILL
Section–Defining an ESP Event
76 ESP-5.4-UG-05
Example: Naming an Event
A production scheduling group uses a prefix of PROD. They use the descriptive name PAYROLL_PROC to describe an ESP Event:
PROD.PAYROLL_PROC
Defining where an Event will execute
In a multiple CPU environment, you should use the SYSTEM operand on the EVENT command to identify the system on which the Event is to activate. This applies to Events that are not manually triggered. This is the name by which ESP Workload Manager knows the system and can not necessarily be the same as the SMF identifier. Check with your administrator or use the LSYS command for the correct name to use.
Systems
All Events that create ESP Applications should point to the ESP Workload Manager system designated as the master system. Other Events can execute on a specific system because they need to process commands for that system. If the system does not matter, you can specify SYSTEM(-).
Note: This does not affect where jobs run; JES controls that.
Example
This example identifies a system identifier of ESPM for the Event PROD.BILLING.
EVENT ID(PROD.BILLING) SYSTEM(ESPM)
Defining when an Event will execute
Trigger for an Event
The trigger for an Event can be:
• A scheduled date and time • A data-set trigger• A global-variable-table trigger• A manual trigger• A job monitor or alert trigger• A signal with a scheduled date and time
Additional information
The next sections describe how to use schedule criteria and data-set triggering in Events and how to manually trigger an Event. For information on other types of Events, including global variable table, job monitor, alert Events, and signal, see the ESP Workload Manager Advanced User’s Guide.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 77
Specifying scheduled Events
The schedule criteria you enter specifies when to execute your Event. You can use the SCHEDULE command to specify these criteria, which generally includes a time and a frequency.
SCHEDULE command
Each command, or scheduling statement, begins with SCHEDULE followed by the time period for execution. For example:
SCHEDULE 10AM DAILY
You can specify as many SCHEDULE commands as you need. For example, you can schedule an Event at different times during a week.
SCHEDULE 4PM WEEKDAYSSCHEDULE 2PM WEEKENDS
Overlapping criteria
If the times in more than one SCHEDULE command coincide, the Event only executes once. The following example only executes once at midnight, even though the second statement also schedules an execution at midnight every fourth execution.
SCHEDULE MIDNIGHT DAILYSCHEDULE EVERY 6 HOURS ROUND WEEKDAYS
Examples: SCHEDULE commands
Some examples of schedule commands follow:
SCHEDULE 7PM DAILYSCHEDULE 10:00 LAST WORKDAY OF MONTHSCHEDULE 16:00 3RD 13TH 23RD DAY OF MONTHSCHEDULE 9AM 2ND LAST DAY OF MONTHSCHEDULE EVERY 4 HOURS ROUND
Additional information
For more information on schedule criteria, see “Schedule Criteria” on page 43.
To set a SCHEDULE command to execute only once, followed by a deletion of the Event:
Use the ONCE operand. This operand is useful if you want to schedule a one-time Event.
Section–Defining an ESP Event
78 ESP-5.4-UG-05
Example: One-time Event
The following Event executes once at 8 am on August 29, 2000. Because of the ONCE operand, the Event deletes itself 24 hours later.
EVENT ID(USER1.SPECIAL)SCHEDULE 8AM AUG29,2000 ONCESEND 'HAPPY 50TH BIRTHDAY' U(*)ENDDEF
Important: If you schedule an Event for a particular date and omit the ONCE operand, ESP Workload Manager assumes a default schedule frequency of DAILY.
Handling exceptions
An Event executes once at every time and date you specified in your SCHEDULE commands. You can use the NOSCHED command to handle exceptions.
If your SCHEDULE command has a time, then you must use the same time on the NOSCHED command.
Example: Schedule exception
This example schedules an Event at 8 am each workday, except at 8 am on the last workday of each month:
SCHEDULE 8AM WORKDAYSNOSCHED 8AM LAST WORKDAY OF MONTH
Example: Schedule exception-once
This example schedules an Event at 8 am each workday, except on February 13, 2000. The use of the operand ONCE causes the Event not be scheduled on this date only.
SCHEDULE 8AM WORKDAYSNOSCHED 8AM FEB13,2000 ONCE
Missed Events
An Event can miss its scheduled time for reasons such as:
• System trouble (system crash, power outage)• The Event is on hold• The Event class is on hold• ESP Workload Manager is placed in a suspended (quiesced) state• The Event data set is suspended at the scheduled execution time
When ESP Workload Manager cannot to execute an Event at the time you scheduled, the Event is considered overdue. When the Event becomes eligible to be processed, for
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 79
example after an outage, ESP Workload Manager checks the Event definition to determine how to process the Event. The overdue count specifies how many overdue occurrences of the Event ESP Workload Manager must process.
Advance/delay/ignore/processing
Your scheduling criteria for Event execution can create conflicts. For example, if you want the Event to execute on the second day of every month except on a weekend, tell ESP Workload Manager to either:
• Advance the Event (run it sooner than usual) by any number of days or weekdays• Delay the Event (run it later than usual) by any number of days or weekdays• Ignore the Event (do not run it at all)
You can use the ON command with a SCHEDULE command to advance, delay, or ignore Event processing if the Event falls on a holiday, weekday, weekend, or particular day of the week. You can use multiple ON commands in an Event.
Example: Changing processing
If you schedule your Event to run on the 12th day of every month, but do not want it
to run if the 12th falls on a weekend or holiday, you can delay the processing using the ON command. Type ON followed by the criteria you do not want the Event to run. Then type your DELAY operand and the amount of time you want the Event delayed.
Your Event looks like this:
EVENT ID(CYBER.TWELVE)SCHEDULE 12TH DAY OF MONTHON WEEKEND DELAY 1 WEEKDAYON HOLIDAY DELAY 1 WEEKDAYINVOKE 'TEST.ESP.PROC(MYAPPL)'ENDDEF
By indicating a delay of one weekday, you ensure that, even if the 12th falls on a Saturday, Sunday, or a Holiday, it runs during the week.
Controlling Event scheduling
There are five commands you can use when you define an Event to control the processing of that Event. For example, you can schedule a deletion of an Event or schedule an Event to be suspended at some time in the future. These commands are: DELETE, HOLD and RELEASE, SUSPEND, and RESUME.
To schedule the deletion of an Event:
Use the DELETE command.
Section–Defining an ESP Event
80 ESP-5.4-UG-05
You can use the DELETE command if, for example, you want to delete an Event that is only temporary. Perhaps you want to delete a daily Event after a particular date.
DELETE 10AM AUG 23, 2000
To hold an Event from being processed at a particular time:
Use the HOLD command in an Event.
When ESP Workload Manager encounters a HOLD command in an Event, it increases the Event’s hold count by one at the time and date specified in the command. As long as the hold count has a value of at least one, ESP Workload Manager delays the Event’s execution. This way you can use the HOLD command to postpone an Event.
Conversely, the RELEASE command decreases the Event’s hold count at the time and date specified in the command. When the hold count equals zero, the Event is eligible for execution.
If the Event’s scheduled time comes up while it is being held, ESP Workload Manager marks the Event as overdue. ESP Workload Manager adds a comment to a held Event if it misses its scheduled time, indicating that execution is pending and the time it should have executed.
For example:
//*EXECPEND AT('9:30 2000 JUN7')
See “Missed Events” on page 78 for a further explanation of the overdue count. After you release the Event, ESP Workload Manager checks the overdue count. If you specified a number other than zero, or let the count default to one, the Event executes immediately for every occurrence it missed while on hold, up to the value of the overdue count.
Example: Holding a data-set-triggered Event
You have an Event, PROD.PAYROLL, that is triggered by the close of the data set PAYROLL.INPUT, but you do not want it to run between 6 am and 10 pm To prevent the Event from executing in that time period, you can use the HOLD command to delay PROD.PAYROLL if the data set PAYROLL.INPUT closes between 6 am and 10 pm. The RELEASE command reduces the Event’s hold count to zero at 10 pm, letting the Event trigger if the data set was created:
EVENT ID(PROD.PAYROLL)DSTRIG PAYROLL.INPUTHOLD DAILY AT 6AMRELEASE DAILY AT 10PMINVOKE 'ESP.PROCS(PAYJOBS)'ENDDEF
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 81
SUSPEND and RESUME commands
The SUSPEND command works similarly to HOLD, but has a slightly different purpose. If an Event misses its scheduled execution time while suspended, ESP Workload Manager ignores the Event and does not execute it at all or mark it overdue. Each time ESP Workload Manager encounters SUSPEND, it increases the Event suspend count by one at the specified time and date. When the suspend count is greater than zero, ESP Workload Manager bypasses the Event without executing it.
The RESUME command reduces the suspend count by one at each occurrence. When the suspend count is zero, ESP Workload Manager can execute the Event at the next scheduled time.
Example: Scheduling an hourly Event during a time range
In the following example, an Event notifies the user of the time (%ESPATIME is a symbolic variable) once an hour, on the hour, workdays, from 8 am to 4 pm. The SUSPEND command stops ESP Workload Manager from sending the message after 4:01 pm, and the RESUME command restarts the message again at 7:59 am:
EVENT ID(CYBER.HOUR_MESSAGE)SCHEDULE WORKDAYS HOURLY ROUND STARTING TODAYSEND 'TIME IS %ESPATIME' U(*)SUSPEND 16:01 WORKDAYSRESUME 7:59 WORKDAYSENDDEF
Suspended and held Event
If an Event is both suspended and held at its scheduled execution time, ESP Workload Manager ignores the hold state and considers the Event suspended.
Specifying data-set-triggered Events
An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of job names. Events can also be made to wait for triggers from activity in more than one data set. When more than one DD (data definition) statement in a step references the data set, the Event is only triggered if the DD being closed is the one that specifies DISP=NEW. See “Using data-set-trigger workload objects” on page 193 for techniques on setting up data set triggering for individual jobs in an ESP Application.
You can use data-set activity to trigger an Event through the DSTRIG command.
You can also use the DSTRIG command to set FTP data-set-triggered Events. See “Specifying FTP data-set triggered Events” on page 84.
Section–Specifying data-set-triggered Events
82 ESP-5.4-UG-05
Data-set-triggered and scheduled Events
You can use this command in addition to an Event’s time and date schedule, or instead of it. When your Event contains both SCHEDULE commands as well as DSTRIG commands, executions caused by the time schedule do not affect the DSTRIG conditions. The Event executes at both the scheduled times and, in addition, when the DSTRIG conditions are satisfied.
Abnormal closures
ESP Workload Manager does not trigger a data-set-triggered Event when the data set closes during an abnormal termination of a task or job step.
Waiting for any closure of a data set
You can use the ANYCLOSE operand to trigger an Event at closure of a data set. This means the creation of a new data set or the updating of an existing data set will trigger the Event. If you do not specify ANYCLOSE, ESP Workload Manager triggers the Event only when the applicable data set is created.
Example: Any closure
If you want any closure of data set PROD.CICS.FILE1602 to trigger your Event, type:
EVENT ID(PROD.NIGHTLY)DSTRIG PROD.CICS.FILE1602 ANYCLOSEINVOKE 'CYB.ESP.PROCS(NIGHTLY)'ENDDEF
Process flow
Visually, the flow looks like this:
Limiting data set activity to a job
You can restrict the trigger to only specific data sets created by a particular job. Use the JOB operand followed by the full name or job name prefix of the job.
Example: Job specific creation
The following Event triggers when job ABC creates a generation of the data set USER1.PAYROLL.
EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- JOB(ABC)
PROD.NIGHTLY(Event)
PROD.CICS.FILE1602(data set)
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 83
INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF
Limiting data set activity to a user
You can restrict the trigger to only specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. It refers to the host security user ID of the job task closing or renaming the data set.
Example: User specific creation
The following Event triggers when user CYBER1 creates a generation of the data set USER1.PAYROLL.
EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- USER(CYBER1)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF
Waiting on multiple data sets
You can have an Event that needs multiple data sets to close before it is triggered. You can indicate each of the multiple data sets with the MULTIPLE operand. When ESP Workload Manager encounters the MULTIPLE operand, it notes the individual closures of data sets, but it does not trigger the Event until all the DSTRIG commands containing a MULTIPLE operand have been satisfied by a data set closure.
Example: Waiting on multiple data sets
EVENT ID(PROD.MULTI_CLOSE)DSTRIG USER1.PAYROLL.REPORT ANYCLOSE MULTIPLE DSTRIG USER.PAYROLL.G- MULTIPLE JOB(ABC)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF
When both of the following criteria have been met, the Event is triggered:
• Any closure of data set USER1.PAYROLL.REPORT• Job ABC creates a generation of data set USER1.PAYROLL
Note: When you display an Event definition containing the MULTIPLE operand, ESP Workload Manager shows each detected data set closure as PRIMED.
Waiting on multiple closures of the same data set
It is possible that a data set will be closed several times. You can use the COUNT operand to specify how many closures will actually trigger the Event. With each closure, ESP Workload Manager increases its internal counter by one. When the counter reaches the number you set in your COUNT statement, the Event is triggered and the counter resets to zero. You can display the Event at any time to see the current value of the counter.
Section–Specifying FTP data-set triggered Events
84 ESP-5.4-UG-05
You can specify several DSTRIG commands for one Event, and each can maintain its own separate counters.
Example: Running a compress job after 100 closures of a data set
If you want a job to submit automatically after every 100 closures of a data set, you could use the COUNT operand followed by 100 as below. This example Event submits a COMPRESS job for a COPYJCL data set after every 100 closures of that data set:
EVENT ID(CYBER.COPYJCL_COMPRESS)DSTRIG CYBER.COPY.JCL COUNT(100)SUBMIT PROD.JCL.CNTL(COMPRESS)ENDDEF
Displaying data-set-triggering information
Below are commands that relate to data-set triggering. They are useful for displaying data set trigger information.
Output from these commands looks like this:
ldxeEvent/Appl -- Wob ------------ Data set --- CYB001.EVENT.DAILY1 CYB001.DATA.SET1, AnyClose, User(CYB-)CYB002.EVENT.DAILY2 CYB002.DATA.SET2, AnyClose, Job(CYB002), User(CYB002), Ftp(Send), Logon(aixuser-), Host(AIXHOST)APPL001.26 DSTRIG1 CYBER.DATA.SET1, AnyClose, Job(FTPSERVE), User(CYB001), Ftp(Receive), Host(10.23.100.5)3 entries displayed
ldteThe following data set(s) are being checked for data set triggers: CYB001.DATA.SET1, AnyClose, User(CYB-) CYB002.DATA.SET2, AnyClose, Job(CYB002), User(CYB002), Ftp(Send) Logon(aixuser-) CYBER.DATA.SET1, AnyClose, Job(FTPSERVE), User(CYB001) Ftp(Receive)3 data set triggers found
Specifying FTP data-set triggered Events
FTP data-set-triggered Events are a particular kind of data-set-triggered Event where an Event is triggered when a successful FTP file transfer or FTP rename completes.
Command Use this command to ...
LDXE display data-set-triggered Events.
LDTE display data sets being checked for closures, creations, or renames.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 85
When setting up an FTP data-set Event, the file transfer causing the Event to be triggered can be defined by:
• Specifying the direction of the transfer• Limiting data set activity to a host• Limiting data set activity to a user ID• Limiting data-set activity to a logon ID
Specifying the direction of the transfer
You can specify that the data-file-transfer direction is from the remote FTP partner to the local mainframe FTP partner or vice versa. Use the FTP operand followed by RECEIVE or RECV if the transfer is from the remote FTP partner to the local mainframe FTP partner. Use the FTP operand followed by SEND if the transfer is from the local mainframe FTP partner to the remote FTP partner.
Examples: FTP RECEIVE and SEND
The following Event triggers when a file is successfully received from a remote FTP partner, creating a generation of the data set USER1.PAYROLL.
EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- FTP(RECEIVE)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF
The following Event triggers when the data set CYBER.XFER.001 is successfully sent from the local mainframe FTP partner to a remote FTP partner.
EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(SEND)INVOKE 'PURGE.XFER(001)'ENDDEF
Limiting data set activity to a host
You can restrict the trigger to FTP transfer from a specific host only. Use the HOST operand followed by the IP address of the specified host in dotted decimal format or DNS host name format.
Example: Host specific creation
The following Event triggers when a remote FTP partner with the IP address 10.1.3.1 successfully transfers a file creating the data set CYBER.XFER.001.
EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) HOST(10.1.3.1)INVOKE 'PROCESS.XFER(001)'ENDDEF
Section–Specifying FTP data-set triggered Events
86 ESP-5.4-UG-05
Limiting data set activity to a user ID
You can restrict the trigger to specific data sets created or renamed by a particular user ID. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the local FTP partner’s job task regardless of whether the local FTP partner is the client or the server.
Note: Because user ID always refers to a local mainframe host security user ID, lower case characters are translated to upper case.
Example: User-specific creation
The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the user ID prefix of the local FTP partner is CYB.
EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) USER(CYB-)INVOKE 'PROCESS.XFER(001)'ENDDEF
Limiting data-set activity to a logon ID
You can restrict the trigger only to specific data sets created or renamed by a particular user. Use the LOGON operand followed by the logon ID of the user.
The logon ID refers to the user ID that the FTP client uses to logon to the FTP server.
If the FTP client is the remote partner, the logon ID is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).
If the FTP client is the local partner, then logon ID is the user ID of the remote FTP partner.
Note: When logon ID is a remote user ID, it can be case sensitive, as for example on UNIX hosts. Therefore logon ID lower case characters are not translated to upper case.
Example: Logon specific creation
The following Event triggers when a remote FTP partner successfully transfer a file creating the data set CYBER.XFER.001, assuming that the remote FTP partner did logon to the FTP server with the CYBER005 user ID.
EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) LOGON(CYBER005)INVOKE 'PROCESS.XFER(001)'ENDDEF
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 87
Notes on FTP trigger operands
dsname
The data set name of the DSTRIG Event command always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).
ANYCLOSE
FTP triggers cannot distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition.
RENAME
When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename the data set to the specified data set name. Because data set name always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore, the RENAME and FTP(SEND) operands are mutually exclusive.
Example
The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.
EVENT ID (USER.APPL_RECEIVE)DSTRIG CYBER.DATA.SET USER(CYB-) FTP(RECEIVE) HOST(AIXHOST)-LOGON(aixuser)SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDDEF
Specifying explicit-data-set triggers
An explicit data-set trigger is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.
The feature consists of two parts:
• The explicit data-set trigger notification utility program (CYBESDT1).• The operand EXPLICIT in the DSTRIG command.
Section–Specifying explicit-data-set triggers
88 ESP-5.4-UG-05
You invoke CYBESDT1 in a job, as an additional step, conditionally to the successful execution of the step manipulating a specified data set. This program writes an SMF record type 132 subtype 1.
An explicit data-set trigger is defined to ESP Workload Manager via the EXPLICIT operand in the DSTRIG command.
Explicit data-set trigger SMF record requirement
An installation must cut SMF type 132 subtype 1 SMF record for explicit data-set triggering to function.
Explicit data-set trigger notification utility program (CYBESDT1)
ESP Workload Manager receives notification of an explicit data-set trigger when CYBESDT1 is executed.
CYBESDT1 requires the following input parameters:
• The DSNAME of the data set causing the activation of the data-set trigger• The volume serial number where the data set resides, if the data set is uncataloged.• The SUBSYSTEM identifier of the ESP Workload Manager that the explicit data-
set trigger will be sent to
CYBESDT1 writes a user SMF type 132 subtype 1 record containing information required for the explicit data-set trigger.
The target ESP Workload Manager subsystem examines the SMF record, and if a matching explicit data-set trigger definition is found, activates the data-set trigger.
Program CYBESDT1 can execute in a batch, TSO, started task, or run task environment (for example, Connect:Direct (NDM)). It must also be APF-authorized or the attempt to write the explicit data-set-trigger SMF record fails with an ABEND047.
Program CYBESDT1 is reentrant.
Note: If you execute CYBESDT1 with a relative GDG in a job that creates new generations, the position of the CYBESDT1 step in the job determines the generation being selected. CYBESDT1 considers that the current generation (relative generation (0)) is the latest generation created when it executes.
CYBESDT1 input parameters
The input parameters of CYBESDT1 are specified in the JCL EXEC PARM for a batch job, and as operands when running as a TSO command.
The syntax is as follows:
DSNAME|DATASET(dsname[(member)|(relgen)]) - {VOLSER|VOLUME(volser)} [SUBSYSTEM|SSID(subsystem)] - [VERIFY|NOVERIFY]
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 89
Parameter Description
DSNAME or DATASET Is the data-set name keyword.
dsname Specifies the name of a data set.
member Specifies a member name of a PDS.
relgen Specifies the relative generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in CYBESDT1 and in the corresponding DSTRIG command or DSNAME statement exactly the same, including leading zeros.
Note: you can also include the absolute generation in dsname. For example:
CYB4.ENCXX.BACKO01A.G0027V00
VOLSER or VOLUME Is the volume serial number keyword.
volser Specifies the volume serial number that the data set resides on. It is required for uncataloged data sets and optional for cataloged data sets.
SUBSYSTEM or SSID Is the ESP Workload Manager subsystem identifier keyword.This parameter is optional, if omitted, all tracking ESP Workload Manager subsystems will receive the explicit data-set trigger SMF record that program CYBESDT1 writes.
subsystem Specifies the subsystem name of a tracking ESP Workload Manager that will receive the explicit data-set trigger SMF record that program CYBESDT1 writes.
Note: A tracking ESP Workload Manager subsystem is one whose ESPPARM initialization file does not contain the following statement:
SMFINT OFF
VERIFY Specifies that CYBESDT1 will set the explicit data-set trigger only if the following criteria are met:• The specified data set is catalogued if the VOLSER or
VOLUME parameter is omitted.• The specified data set resides on the specified volume.
(From the volser parameter if specified, from the catalog if not.)
• The owning user of the job executing CYBESDT1 has update access to the data set specified.
NOVERIFY Specifies that CYBESDT1 will set the explicit data-set trigger whether or not the criteria described for the VERIFY parameter are met.
Section–Specifying explicit-data-set triggers
90 ESP-5.4-UG-05
CYBESDT1 return codes
CYBESDT1 issues a zero return code if the explicit data-set trigger SMF record was successfully written, and a non-zero return code if any error condition occurs that causes the explicit data-set trigger SMF record not to be written.
Examples
Invoking CYBESDT1 from page mode or line mode
To run CYBESDT1 from page or line mode, you must prefix the command with TSO because CYBESDT1 is external to ESP Workload Manager.
TSO command example:
TSO CYBESDT1 D(PDS.DATA.SET(MEMBER1))
TSO call example:
CALL 'CYBER.SSCPLINK(CYBESDT1)' 'D(PDS.DATA.SET(MEMBER1))'
Explicit data-set trigger notification batch example
In the following example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.
If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.
//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK
You use the following to trigger MYEVENT when the data set PDS.DATA.SET(MEMBER1) has been created or updated:
EVENT ID(MYEVENT)DSTRIG PDS.DATA.SET(MEMBER1) EXPLICITENDDEF
Explicit data-set trigger notification Connect:Direct (NDM) run task example
In the following example, STEP1 copies the data set OLD.DATA.SET from Connect:Direct node NODE1 to the local Connect:Direct node as data set NEW.DATA.SET.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 91
If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set NEW.DATA.SET has been created by the Connect:Direct copy operation.
PROCESS1 PROCESS SNODE=NODE1STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET - TO(SNODE DSN=NEW.DATA.SET DISP=(NEW,CATLG,DELETE))IF (STEP1 EQ 0) THENSTEP2 RUN TASK (PGM=CYBESDT1 - PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) SNODEEIF
Specifying the function of an Event
ESP Workload Manager can perform a variety of tasks through the Events you define. An Event must do one of the following:
• Send a message to you, other users, or operator consoles• Submit JCL • Invoke an ESP Procedure• Execute an instream Procedure• Generate a copy of the JCL for every job• Issue an operating system command
This section describes these tasks and the commands associated with each.
Sending messages
You can use an Event to send a message to yourself, another user, a group of users, or an operator console. To send a message, enter the SEND command followed by the message in single quotes, and the user ID or console identifier to which the message is being sent. You can include several SEND commands in any single Event.
Example: Sending a message
The following Event is scheduled at 8 am each day and sends a message to USER1.
EVENT ID(USER1.MESSAGE)SCHEDULE 8AM DAILYSEND 'SCHEDULING IS EASY WITH ESP' USER(USER1)ENDDEF
Submitting JCL
You can use an ESP Event to submit JCL from a data set to JES using the SUBMIT command. A single Event can submit more than one job. If there are relationships between the jobs you are submitting, you must use an ESP Procedure to submit them.
Section–Specifying the function of an Event
92 ESP-5.4-UG-05
For more information on submitting related jobs, see “Using Applications” on page 137.
You can also use ESP Workload Manager to submit jobs from Librarian and Panvalet data sets using different statements as outlined in the next section.
Note: You cannot use the Consolidated Status Facility to monitor and control jobs submitted from an Event.
Example: Submitting a job
You can create an Event PROD.INVENTORY that, at 7 am on the last workday of every month, submits member BACKUP1 of data set PROD.JCL.CNTL. The Event looks like this:
EVENT ID(PROD.INVENTORY)SCHEDULE 7AM LAST WORKDAY OF MONTHSUBMIT 'PROD.JCL.CNTL(BACKUP1)'ENDDEF
Example: Submitting multiple jobs
The following Event submits two jobs at 7 am on the last workday of each month. The jobs can run in any order or concurrently. The Event looks like this:
EVENT ID(PROD.INVENTORY)SCHEDULE 7AM LAST WORKDAY OF MONTHSUBMIT 'PROD.JCL.CNTL(BACKUP1)'SUBMIT 'PROD.JCL.CNTL(BACKUP2)'ENDDEF
Submitting JCL from Librarian and Panvalet data sets
In addition to the SUBMIT command, there are special commands to submit jobs directly from Librarian and Panvalet data sets. You can use multiple commands in an Event. ESP Workload Manager effectively concatenates the input data to form one or more jobs.
Librarian data sets
To submit a job directly from a Librarian data set:
Enter the LIBSUB command followed by the data-set name and the name of the data-set member you want to submit, like this:
LIBSUB LIB1.DATA(PRODCNTL)
ESP Workload Manager supports multiple LIBSUB commands.
Note: You do not need to specify the LIB- data-set identifier because the LIBSUB command implies a Librarian data set.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 93
Panvalet data sets
To submit a job directly from a Panvalet data set:
Enter the PANSUB command followed by the data set name and the name of the member you want to submit:
PANSUB PANDS.DATA MEMBER(DLYPAYROLL)
OR
Use this format, if the member name is no more than eight characters:
PANSUB PANDS.DATA(PAYROLL)
ESP Workload Manager supports multiple PANSUB commands.
Note: You do not need to specify the PAN- data-set identifier because the PANSUB command implies a Panvalet data set.
Invoking ESP Procedures
You can create an Event to invoke an ESP Procedure. An ESP Procedure is a set of instructions for ESP Workload Manager. The most common use of an ESP Procedure is to define an ESP Application. A Procedure can contain statements that:
• Define a group of related jobs• Define and assign values to symbolic variables• Define complex processing requirements
Invoking an ESP Procedure causes ESP Workload Manager to execute the instructions within the ESP Procedure. To invoke any ESP Procedure, you must first create the ESP Procedure, and then define an Event to invoke that ESP Procedure.
The INVOKE command invokes an ESP Procedure by specifying where the ESP Procedure is stored. In the following example, the ESP Procedure is stored in the PAYROLL member of the data set PROCS.ESP.PAY:
EVENT ID(PROD.PAYJOBS)SCHEDULE 17:00 DAILYINVOKE 'PROCS.ESP.PAY(PAYROLL)'ENDDEF
Note: ESP Workload Manager allows multiple INVOKE commands. However, an Event can only generate one Application. If you need more than one Application, you must create one Event per Application.
Executing an instream ESP Procedure
You can include an ESP Procedure in an Event. The ESP Procedure statements are enclosed between the PROC and ENDPROC commands.
Section–Specifying the function of an Event
94 ESP-5.4-UG-05
Important: You must code the ENDPROC command at the end of an instream Procedure
Note: You cannot use panels to add an instream procedures in an Event. Create the Event first with the panels and, then, add the instream procedure by editing the Event.
To browse or edit instream procedures from the CSF, use the BE and EE commands. This is because the instream procedure is inside the Event and cannot be browsed or edited independently.
The following is an example of an Event including an instream ESP Procedure:
EVENT ID(PROD.WITHPROC)SCHEDULE DAILY AT 6PMPROCAPPL WITHPROCJCLLIB PROD.JCLJOB ARUN DAILYRELEASE JOB BENDJOBJOB BRUN DAILYENDJOBENDPROCENDDEF
Additional information
For information on using ESP Procedures, see “Working with ESP Procedures” on page 107.
Copying Submitted JCL
The COPYJCL command saves a copy of the submitted JCL for every job ESP Workload Manager submits. In the submitted JCL, all symbolic parameters are resolved and other JCL tailoring statements are applied. For details, see COPYJCL in the ESP Workload Manager Reference Guide and “Tailoring JCL” in the ESP Workload Manager Advanced User’s Guide.
You can specify COPYJCL in the Event definition of any Event that submits jobs. This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved and NET cards (for DJC/JES3) included. This JCL can be used for job re-submission. ESP Workload Manager keeps track of where the job was submitted from and the JCL that was used.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 95
You can also specify COPYJCL within a Procedure to identify one or more jobs for which you want to use COPYJCL. This gives you the advantage of using COPYJCL for specific jobs.
When you use the COPYJCL command, you must also specify the library that is to receive the copy, followed by either the JOBNAME or JOBID operand. The operands you use influence the member name ESP Workload Manager assigns to the JCL copy.
Using the JOBNAME operand
The JOBNAME operand requests that the member name used for storing the JCL for a job is the same as the job name. This is the default. Each submission of a particular job overwrites the previous copy of that job JCL.
Using the JOBID operand
Use the JOBID keyword when you want ESP Workload Manager to store the copy of the JCL by job number. ESP Workload Manager creates a member name in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary. Job numbers are assigned sequentially and the sequence is restarted (“rolled over”) when the maximum number is reached. After the roll-over, member names are overwritten when the corresponding job number reoccurs.
Example: Using COPYJCL
This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by job name.
EVENT ID(EMP.MYJOBS)SCHEDULE 5PM WORKDAYSINVOKE 'EMP.ESP.PROC(WKJOBS)'COPYJCL 'CYBER.JCL.COPY' GEN(0) JOBNAMEENDDEF
Compressing COPYJCL
If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You could use a data-set-triggered Event to submit the compress job automatically after a number of closures.
Issuing operator commands
To issue an operator command:
Enter the VS command followed by the operator command you want to issue.
Section–Specifying other requirements
96 ESP-5.4-UG-05
Example: Starting tasks
If you want ESP Workload Manager to start IMS10 and IMS20 each day at 6 am, use the VS command in your definition, as shown below. The commands will be issued on the SYSB system.
EVENT ID(OPER1.START_IMS) SYSTEM(SYSB)SCHEDULE 6AM DAILYVS 'S IMS10'VS 'S IMS20'ENDDEF
There are restrictions on which users can issue operator commands. Contact your administrator to find out if you are authorized to issue any operator commands.
Specifying other requirements
When you define an Event, you can also specify:
• Symbol library names• Calendar names• Notification list (MAILLIST)• Comments
Setting symbol libraries
ESP Workload Manager has a set of built-in symbolic variables. Your ESP Workload Manager administrator can define symbol libraries to store user-defined symbolic variables. A symbol library consists of one or more data sets or data-set members. Variables can include date formats, control cards, and other information ESP Workload Manager can use when processing the workload. You can use the SYMLIB command in an Event to specify symbol libraries. If a variable is assigned more than one value, ESP Workload Manager uses the last assigned value.
Example
This example references the symbol library called DATES. When ESP Workload Manager processes the Event, it opens each data set associated with this symbol library and uses this information to perform substitution of symbolic variables.
EVENT ID(CYBER.PAYROLL)SYMLIB DATESINVOKE 'CYB.ESP.PROCS(PAYROLL)'ENDDEF
You can also define and work with symbols as part of an ESP Procedure. See the ESP Workload Manager Advanced User’s Guide for detailed information on creating and using symbolic variables.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 97
Setting special calendars
ESP Workload Manager lets you define dates that can be unique to your organization. If, for example, Labor Day is a regular holiday at your installation, you can define it as such in your calendar.
ESP Workload Manager contains an installation defined SYSTEM calendar based on the 12-month Gregorian calendar. You can use the CALENDAR command to specify up to two additional calendars for the Event, so that you can schedule Events in terms that can be unique to your calendar. If you do not specify a calendar, ESP Workload Manager uses the calendars assigned by default to the group or user that owns the Event. For more information on calendars, see “Schedule Criteria” on page 43.
ESP Workload Manager merges holiday definitions in all calendars associated with an Event. When special days or periods use the same name in different calendars, ESP Workload Manager uses the first definition it finds. ESP Workload Manager searches in this order:
1. The first calendar you define for the Event, or the first default calendar.
2. The second calendar you define for the Event, or the second default calendar.
3. The SYSTEM calendar.
Example: Specifying a calendar in an Event
If you want your Event to execute on the second day of your fiscal month, you must first set the calendar so that ESP Workload Manager knows where to look for the definition of what a fiscal month is. In the Event below, the CALENDAR command tells ESP Workload Manager which previously defined calendar (for example, FISCAL) to refer to when scheduling the Event:
EVENT ID(CYBER.FISCAL_JOBS)CALENDAR FISCALSCHEDULE 2ND DAY OF FISCAL_MONTHSUBMIT 'PROD.JCL.CNTL(FISJOB1)'ENDDEF
Notification list (MAILLIST)
If an Event needs to send messages the messages are sent to the user that owns the Event. You can redirect those messages to a notification list instead.
The notification lists are included in the MAILLIST data set. The MAILLIST data set contains any number of MAILBOX initialization parameters, each of them containing any number of TSO user IDs and email addresses. You select where the Event sends messages by coding a mailbox name in the MAILBOX operand. Messages will be sent to all TSO user IDs and email addresses specified in the mailbox. See the “MAILLIST data set” section in the ESP Workload Manager Installation and Configuration Guide for information on how to set up the MAILLIST data set and the mailboxes.
Section–Displaying the schedule
98 ESP-5.4-UG-05
Example: Using the notification list
In the following example, all messages from Event CYBER.PAYROLL are directed to all TSO user IDs and email addresses contained in the CYBERBOX mailbox.
EVENT ID(CYBER.PAYROLL) MAILBOX(CYBERBOX)SYMLIB DATESINVOKE 'CYB.ESP.PROCS(PAYROLL)'ENDDEF
Adding comments
You can use the COM command to add any number of comments, anywhere in an Event. ESP Workload Manager ignores them when it executes the Event.
Example: Using comments in an Event
If you want to include a comment in your Event that tells you the Event is a manually triggered Event to submit JOBX, you could use the COM command, like this:
EVENT ID(PROD.JOBX)COM MANUALLY TRIGGERED EVENT TO SUBMIT JOBXSUBMIT 'PROD.JCL.CNTL(JOBX)'ENDDEF
Displaying the schedule
You can use the LISTSCH command to display the Event names and times of the current schedule cycle (normally 24 hours). These elements include the names and execution times of all the Events in the schedule, and the overdue, held, or deferred queues. The LISTSCH command does not display the names or submission times for individual jobs within Events. To display the schedule for jobs, see “Reporting on scheduled activity” on page 298.
Example
For example, to display all entries on the current schedule cycle, type:
LISTSCH
Note: If an Event is scheduled more than once during the current schedule cycle, ESP Workload Manager only displays the time of the first execution. ESP Workload Manager stores only one instance of the Event and does not calculate the next execution time until it has executed the Event.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 99
Expected execution
The LISTSCH command can only display scheduled Events. If you want to display Events that do not have SCHEDULE commands, such as Events triggered by data-set activity you can use the EXPECT command.
The EXPECT command uses the same format as the SCHEDULE command, but it does not cause an Event to execute.
Example: Expected time of an Event
If your Event is usually triggered by the creation of a data set every morning at approximately 11 am, you could insert an EXPECT command in your Event definition to tell ESP Workload Manager when to expect the Event, like this:
EVENT ID(USER01.MY_EVENT)SUBMIT 'USER01.JCL.CNTL(MYJOB)'EXPECT 11AM DAILYDSTRIG MY.DATA.SET ANYCLOSEENDDEF
Triggering expected Events
The EXPECT command normally does not affect the schedule. If the data set that triggers the Event, in the above example, has not been created by the expected time, the Event continues to wait. However, if you trigger an Event that has an EXPECT command and you keep the REPLACE option, ESP Workload Manager treats the EXPECT command the same as a SCHEDULE command. ESP Workload Manager selects jobs and substitutes variables based on the expected time and date.
Displaying when an Event will execute
Using the NEXT command, you can display the next scheduled executions of an Event. The NEXT command lets you specify the number of execution times you want to test, up to a maximum of 99. As long as your Event contains at least one SCHEDULE command, ESP Workload Manager computes the execution times and dates for the number of executions you specify.
Example: Displaying the next execution times of an Event
If you want to know the next five execution dates and times for the Event PROD.LWD, you could use the NEXT command. The following shows the NEXT command and sample output from the command. ESP Workload Manager displays the next five scheduled times and dates:
NEXT 5 PROD.LWDSCHED AT 19.00.00 ON SATURDAY JANUARY 31ST, 2000
Section–Working with defined Events
100 ESP-5.4-UG-05
SCHED AT 19.00.00 ON SATURDAY FEBRUARY 28TH, 2000SCHED AT 19.00.00 ON TUESDAY MARCH 31ST, 2000SCHED AT 19.00.00 ON THURSDAY APRIL 30TH, 2000SCHED AT 19.00.00 ON SUNDAY MAY 31ST, 2000
Working with defined Events
The section “Controlling Event scheduling” on page 79 describes five commands for controlling an Event during definition. You can use ESP Workload Manager commands in Line mode, Page mode, batch, and through the ISPF interface, to control an Event after you define it.
Commands and their function
The following table summarizes the available commands and their function:
For ISPF users
To access the ISPF panels:
1. Select Option E on the Main Menu.
2. Select Option 3 on the Event Management Menu.
3. Type the appropriate code letter for the action you want to take and the Event’s name (prefix and descriptive name).
OR, you can:
1. Select Option E on the Main Menu.
2. Select Option 3 on the Event Management Menu.
Command Function
ALTER Alters the characteristics of an Event.
CLASS Controls the classes of Events (requires OPER authority; not available through panels).
DELETE Deletes an Event.
HOLD Holds an Event from processing.
LIST Lists an Event name or definition.
RELEASE Releases a held Event for processing.
RESUME Resumes processing of a suspended Event.
SIMULATE Simulates the functions of an Event.
SUSPEND Suspends an Event from processing.
TRIGGER Triggers execution of an Event.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 101
3. Type the prefix of the Event in the PREFIX field for multiple Events.
4. Press Enter. A list of Events appears.
5. Type the code letter for the action you want to take beside the Event name.
Note: The ISPF interface also provides BROWSE and EDIT options.
Listing Event names or definitions
ESP Workload Manager contains a LIST command that you can use to display:
• Event names• Next execution times• System IDs for Events• Complete Event definitions
For example, to see the names and next execution times of the defined Events starting with the prefix PROD, type the command below. The LEVEL operand identifies the Event prefix.
LIST LEVEL(PROD)
Note: In ISPF, you must abbreviate the LIST command to simply the letter L.
Simulating an Event
You can simulate the functions of any defined Event using the SIMULATE command. For the Event you select, the SIMULATE command tells you which jobs ESP Workload Manager submits, any messages it sends, how it substitutes symbolic variables, and so on. This command is particularly useful with ESP Procedures because you can use it to see how the complex and conditional components of your Procedure will run at a particular date and time. ESP Workload Manager also displays error messages if it encounters problems, such as syntax errors or successor loops in an ESP Procedure. You can simulate an Event for a day on which it is not normally scheduled; ESP Workload Manager simulates what would happen if the Event was triggered on that particular day.
Section–Working with defined Events
102 ESP-5.4-UG-05
Options
There are a number of other options available with the SIMULATE command. For example, you can:
• Suppress the printing of the ESP Procedure listing.• Simulate data-set triggers, signal processing and job monitor Events.• Simulate Procedures invoked by the simulated Procedure as well as monitor
Events and other directly invoked Events.• Invoke a JCL scan exit during simulation. An indicator will be passed to this exit
indicating that this is a simulation rather than real Event execution.• Perform full syntax checking on all ESP Workload Manager commands invoked.• Direct the JCL output to a data set.• Suppress the execution of REXX code within an ESP Procedure.• Display all successors that were inherited because a job was not selected for some
reason on the job selection report.• Display jobs that were not selected for any reason on the job selection report.
Specifying the options
You specify these options using the SIMULATE command or on the Simulate Event Execution panel.
On the SIMULATE command, specify the Event name and any schedule operands. If you do not enter any operands, ESP Workload Manager either simulates the next occurrence of the Event, or, if the Event has no schedule execution, it assumes an execution time NOW.
Example: Simulating an Event
You can simulate the results of executing an Event named CYBER.TEST1 on the last workday of the current month. Enter the following command in Page mode:
SIMULATE EVENT(CYBER.TEST1) SCHED('LAST WORKDAY OF MONTH')
Triggering an Event manually
Triggering an Event
You can manually trigger an Event at any time through the TRIGGER command. Enter the command TRIGGER, followed by the Event’s name and the time at which you want it to execute. The default time is now.
If you specify a time in the past, ESP Workload Manager triggers the Event immediately and processes the Event as if it was this prior date. ESP Workload Manager selects jobs and resolves symbolic variables as if it were this date in the past. DELAYSUB/EARLYSUB statements are ignored unless they use the term REALNOW that reflects the actual time of Event trigger.
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 103
The Event execution either replaces the next scheduled execution, or it can be a temporary addition to the schedule.
Adding executions
You can use the ADD option to schedule executions of the Event that you want to add to the Event’s normal schedule. ESP Workload Manager processes the ADD operand in the same way it processes a SCHEDULE command. A TRIGGER ADD always causes the Event to execute. If there is a HOLD or SUSPEND, ESP Workload Manager does not execute the Event and produces an error message.
For example, if you need to run an Event now in addition to its scheduled time of 7 pm, trigger the Event with the ADD option.
TRIGGER USER01.FIRST_EVENT ADD
Note: An installation can set the default on the TRIGGER command to ADD or REPLACE.
Replacing scheduled executions
When you want to process an Event at a time different than its next scheduled time, you can use the REPLACE option. REPLACE advances the execution time for an Event. For example, if you need to run an Event now instead of at 7 pm, trigger the Event with the REPLACE option.
When you use the REPLACE option, ESP Workload Manager selects jobs and resolves symbolic variables based on the replaced time and date. For example, if you have an Event that runs every Saturday and this week you want to run the Event on Friday instead, you can trigger the Event with the REPLACE option. ESP Workload Manager selects the jobs and resolves symbolic variables based on Saturday’s date.
The following example uses REPLACE to replace the next scheduled execution of an Event called PROD.PAYROLL.
TRIGGER PROD.PAYROLL REPLACE
Bypassing a scheduled Event
If you want to bypass the next execution of a scheduled Event, you can trigger the Event and specify NOXEQ. This can be used when you trigger an Event in error, and you need to undo this operation, or when you want to cancel one execution of an Event.
The following example bypasses the next scheduled execution of the Event called PROD.BAD_EVENT.
TRIGGER PROD.BAD_EVENT NOXEQ
Section–Working with defined Events
104 ESP-5.4-UG-05
Postponing execution of an Event
When you use the HOLD command outside the Event definition process, ESP Workload Manager increments the Event’s hold count immediately. When you use the HOLD command within a definition (explained in “Controlling Event scheduling” on page 79), ESP Workload Manager does not increment the count until the scheduled date and time.
Holding and releasing an Event
By issuing the HOLD command followed by an Event name, you postpone execution of that Event until its hold count is reduced to zero. Every HOLD increases the count by one; every RELEASE command reduces it by one.
When a held Event is released and it has missed a scheduled execution, ESP Workload Manager executes the Event once for each scheduled execution that the Event missed, up to the number of times in the overdue count. This count is specified by the OVERDUE operand on a SCHEDULE command and defaults to one.
Example: Holding an Event
If you have an Event with the name PROD.MYEVENT, you can place it on hold (increasing its hold count by one) by typing the following:
HOLD PROD.MYEVENT
Bypassing execution of an Event
Outside of an Event definition, the SUSPEND command immediately increases the suspend count by one, telling ESP Workload Manager to bypass the Event you name. A suspended Event remains in that state until it is resumed. All scheduled executions and manual triggers of the Event are bypassed.
Suspending and resuming an Event
By issuing the SUSPEND command followed by an Event name, you bypass the execution of that Event until its suspend count is reduced to zero. Every SUSPEND increases the count by one; every RESUME command decreases it by one. When the suspend count reaches zero, the Event is eligible for execution. If the Event misses any execution times while suspended, ESP Workload Manager ignores them and does not consider the Event overdue.
Example: Suspending an Event
If you have an Event with the name PROD.MYEVENT, you can suspend it by typing the following:
SUSPEND PROD.MYEVENT
Chapter 4–Processing ESP Events
ESP-5.4-UG-05 105
Note: If the Event is both held and suspended at a scheduled execution time, ESP Workload Manager treats the Event as suspended and therefore does not consider it overdue.
Overdue Events
Event classes
After a long system outage, ESP Workload Manager makes it easy for you to manipulate classes of Events so that the system can process high priority work first. For more information on manipulating classes of Events see the ESP Workload Manager Operator’s Guide.
Overdue Events
Add OVERDUE to the end of your SCHEDULE command, and then a number in brackets indicating how often the Event should execute if it misses its scheduled time. The default is 1.
Example: Overdue Events
If you do not want an Event to run, even if it misses its 10 am scheduled execution time, type the command below. Because you do not want it to execute, type the number zero in the brackets:
SCHEDULE 10AM WORKDAYS OVERDUE(0)
Altering Events
To change certain characteristics of one or more Events:
Use the ALTEVENT command.
Specify any number of operands to cause multiple changes to a single Event or group of Events. When the name contains asterisks or a hyphen, ESP Workload Manager alters all matching entries. If you are unsure of which Events a particular command will affect, use a LIST command to display the Events.
Use the ALTEVENT command to change calendars, classes, symbol libraries, and system identifiers, in addition to adding or subtracting hours or minutes to compute a new set of time and date schedules.
Example: Altering system identifier
The example below alters all Events prefixed by MYGROUP, with SYSTEM identifiers beginning with OLDA, to execute on the system NEWA. The SYSTEM
Section–Working with defined Events
106 ESP-5.4-UG-05
identifier corresponds to the ESP Workload Manager system identifier, defined by ESP Workload Manager SYSID initialization parameter.
ALTEVENT MYGROUP.- SYSTEM(NEWA OLDA)
Deleting Events
To delete an existing Event:
Use the DELETE command.
This removes the Event from the Event data set.
Important: If you delete an Event corresponding to an active Application, ESP Workload Manager is unable to continue processing that Application.
Example: Deleting an Event
The following example deletes the Event called TEST.FIRST_EVENT.
DELETE TEST.FIRST_EVENT
Important: If you delete an Event corresponding to an active Application, ESP Workload Manager is unable to continue processing that Application.
ESP-5.4-UG-05 107
Working with ESP Procedures
An ESP Procedure is a set of stored instructions that ESP Workload Manager invokes. When you create an ESP Procedure using CLANG, a high-level programming language. You can also use the IBM REXX language in ESP Procedures.
The main use of an ESP Procedure is to provide a framework for an ESP Application. You control an Application from one Event definition, regardless of the Application’s complexity or number of conditional requirements. You can use a single ESP Procedure to control a complete batch run or even multiple batch runs. The Procedure automatically accounts for any daily changes or month-end processing. For more information on using ESP Procedures to define Applications, see “Using Applications” on page 137.
This chapter contains the following topics:
• Overview of ESP Procedures• Invoking an ESP Procedure• ESP Procedure syntax• Using ESP Workload Manager control language in Procedures• Using symbolic variables in Procedures• Using expressions and strings in Procedures• Built-in functions• Using calendaring functions• Using functions for job selection• Using functions for symbolic variables• Using system activity functions
Section–Overview of ESP Procedures
108 ESP-5.4-UG-05
• Combining functions• Re-executing an ESP Procedure• Using templates• Using Event definition commands in Procedures• CLANG examples• Caching an ESP Workload Manager Procedure
Overview of ESP Procedures
You can code an ESP Procedure:
• In a stored Procedure that you store in a member of a PDS or PDSE, or in a sequential data set
• In an Instream Procedure that you include in an Event, starting with the PROC command and ending with the ENDPROC command
When you create an ESP Procedure, you can:
• Use as many statements as you need
• Add to or edit the Procedure
• Specify the Procedure line by line using the syntax described later in this chapter
• Invoke a stored Procedure from an Event
• Issue commands
• Set or test symbolic variables, whether built-in or user-defined
• Cache (store) the procedure in memory to improve performance
Note: You must create stored Procedures prior to creating the Event that invokes the Procedure.
Invoking an ESP Procedure
To invoke an ESP Procedure:
• Use the INVOKE command in an Event or in another ESP Procedure.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 109
The trigger for the Event can be:
• A scheduled date and time • A data set trigger• A job monitor trigger• A signal with a scheduled date and time• A manual trigger
Example: An Event invokes an ESP Procedure
The following example demonstrates how to use an Event to invoke an ESP Procedure.
The Event appearing below runs each weekday at 4 pm and invokes an ESP Procedure. The Event looks like this:
EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE 'CYBER.ESP.PROC(PAYDAILY)'ENDDEF
ESP Procedure syntax
ESP Procedures have a specific syntax that you must follow for each of the components listed below:
Syntax Rules Explanation
Name Use up to 8 alphanumeric characters for the name of an ESP Procedure. The first character must be a letter. Optionally you can use the format MYJOBS:ESPPROC.In this case, you must type a colon after the last character followed by the keyword ESPPROC.
Continuation Type either a hyphen (-) or a plus (+) sign as the last non-blank character on a line to continue a line of input. The + sign strips leading blanks from a continuation line.
Comments Enclose comments between /* and */. You can omit the last */ because a line end automatically ends the comment. 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 LIB- or PAN- prefixes to identify Librarian and Panvalet data sets.
Delimiters Use single quotation marks when you want to denote character strings and literal data in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks.
Section–Using ESP Workload Manager control language in Procedures
110 ESP-5.4-UG-05
Examples of using the above syntax rules are presented throughout this chapter.
Using ESP Workload Manager control language in Procedures
CLANG is an integral component of ESP Procedures and provides great power and flexibility. Its several language elements listed below allow you to specify conditional processing requirements.
IF
Use IF to conditionally process an instruction or group of instructions depending on the evaluation of an expression. When you use an IF statement, the expression that follows it must return a true or false value. You can use any number of nested IF statements.
Example:
IF logical-expression THEN ...
THEN
Use THEN to indicate the Procedure processed only if the expression that follows the IF statement returns a true value. If a THEN statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP Workload Manager ignores the THEN statement. You must begin and end a set of instructions with DO and ENDDO language elements.
Example:
THEN statement
ELSE
Use an ELSE statement only in conjunction with an IF statement when the expression that follows the IF statement returns a false value. If you do not include an ELSE
Indentation Use indentation to improve readability (optional).
Variables Precede all symbolic variables with a symbol introducer character (the default character is the % sign), except when you use them in an expression or as the left-hand side of an assignment statement.
Labels Use labels in a Procedure to denote different sections. Labels can have up to 18 characters. The first character must be a letter, and you must type a colon after the last character. In addition to identifying sections for editing purposes, labels can also act as targets in JUMPTO statements, where they control logical flow.
Syntax Rules Explanation
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 111
statement after an expression returning a false value, ESP Workload Manager passes control on to the next line. You must begin and end a group of instructions with DO and ENDDO language elements. If an ELSE statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP Workload Manager ignores the ELSE statement.
Example:
ELSE statement
DO
Use the DO statement in conjunction with THEN and ELSE statements to indicate the start of a set of statements. Use this statement to group a number of instructions together. You do not require a DO statement if you only have one instruction. DO must follow immediately after THEN or ELSE, or begin the continuation line. Do not use a continuation character (- or +) on a DO statement.
Example:
DO statement statement
ENDDO
Use the ENDDO statement in conjunction with the DO statement to indicate the end of a set of statements. The following example shows how you should use DO and ENDDO.
Example:
DO statement statementENDDO
EXIT
Use EXIT to quit from your current point in a Procedure. ESP Workload Manager continues to process pending requests up to the point at which you use EXIT. ESP Workload Manager also processes any action statements in the calling Event, or other ESP Procedures invoked in the same Event. ESP Workload Manager ignores EXIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, EXIT within the scope of a JOB statement causes ESP Workload Manager to process all statements up to the EXIT and submit the job.
Example:
EXIT
Section–Using ESP Workload Manager control language in Procedures
112 ESP-5.4-UG-05
QUIT
Use QUIT to quit an entire process and the Event that invoked it. If you use QUIT, ESP Workload Manager does not process any pending requests from this or any other Procedure invoked by the same Event. ESP Workload Manager ignores QUIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, QUIT within the scope of a JOB statement causes ESP Workload Manager not to process any statements for that job and does not submit the job, causing the job to fail with a SUBERROR. Therefore, any of the jobs dependencies are not released.
Example:
QUIT
JUMPTO
Use JUMPTO to search forward through the existing Procedure to find the next label of the name given in the JUMPTO statement. Use JUMPTO to skip over whole sections of a Procedure. You can use JUMPTO with or without an IF statement.
Example:
JUMPTO labelerr_handler
Note: After you specify DO, ENDDO, EXIT, or QUIT you must specify your next statement on the next line. You cannot continue these statements.
Example: Using IF-THEN-ELSE
This example uses the IF-THEN-ELSE construct.
IF A=B THEN SEND 'A AND B ARE EQUAL' U(*)ELSE SEND 'A AND B ARE NOT EQUAL' U(*)
If you use continuation characters and indentation, the above example looks like this:
IF A=B THEN - SEND 'A AND B ARE EQUAL' U(*)ELSE - SEND 'A AND B ARE NOT EQUAL' U(*)
Example: Grouping with DO-ENDDO
This example groups instructions together using DO and ENDDO:
DO SUBMIT 'CYB.ESP.JCL(PAYJOB1)' SEND 'PAYROLL IS RUNNING' CN(01)ENDDO
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 113
Example: Using QUIT and EXIT
This example uses the QUIT and EXIT instructions, as follows:
• If today is CHRISTMAS, ESP Workload Manager quits the ESP Procedure and no instructions are processed.
• If today is not CHRISTMAS but it is a holiday, ESP Workload Manager sends a message and exits the Procedure at that point.
• If none of the above conditions are true, ESP Workload Manager sends a message indicating it will continue processing.
IF TODAY('CHRISTMAS') THEN QUITIF TODAY('HOLIDAY') THEN DO SEND 'NO WORK TODAY' U(BOSS) EXITENDDOSEND 'LET US CONTINUE PROCESSING' U(USER01)
Additional information
For more examples of using CLANG, see “” on page 131.
Using symbolic variables in Procedures
You can use symbolic variables in an ESP Procedure. The different types of variables are:
Type of Variable Explanation
Built-in variables ESP Workload Manager provides a set of built-in variables for such information as the current date, time, and Event name. You can use these variables in an ESP Procedure, but their values cannot be changed. See the ESP Workload Manager Advanced User’s Guide for a complete list of these variables.
User-defined variables These are alphanumeric strings or integers that you can use in an ESP Procedure to represent character strings, literal data, and numbers. When using an integer variable, you must first define the variable with an INTEGER statement before you use it.If the variable is stored in a global variable table, you can retrieve it using a VGET statement.
Note: regardless of the type of variable stored in a global variable table, you will obtain a character string when you retrieve the variable unless you insert an INTEGER statement before retrieving it.
Section–Using expressions and strings in Procedures
114 ESP-5.4-UG-05
When you want to use the value of a symbolic variable, you use the symbol-introducer character (default is the per cent sign (%)) followed by the symbol name. For example: %NAME.
Note: Your installation can use a different symbol-introducer character. Check with your administrator to find out what symbol-introducer character is used at your site.
Example: Using symbolic variables
INTEGER NUMBERNUMBER=52NAME='FRED'SEND '%NAME IS %NUMBER YEARS OLD TODAY' U(USER01)
This example:
• Defines an integer variable called NUMBER and assigns it a value of 52.• Assigns the value FRED to the variable called NAME.• Sends a message to USER01 using these variables.
The message ESP Workload Manager sends to USER01 looks like this:
FRED IS 52 YEARS OLD TODAY
Example: Retrieving a variable from a global variable table
This example assumes that a variable containing the number of runs and named NUMOFRUN has been previously stored in a global variable table named MYTABLE.
INTEGER NUMOFRUNVGET NUMOFRUN TABLE(MYTABLE)SEND 'THE NUMBER OF RUNS IS %NUMOFRUN' U(USER01)
Additional information
See the ESP Workload Manager Advanced User’s Guide for detailed discussion of symbolic variables and global variable tables.
Using expressions and strings in Procedures
You can also use strings, expressions, and operators in your Procedures. This section outlines the syntax and use for each of these.
Using literal strings
A literal string is a group of characters enclosed in single quotes. You can embed symbolic variables in a string. ESP Workload Manager later substitutes the actual value of the variable into the string during processing.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 115
When you want to enter text and have it appear exactly as you typed it, type it enclosed in single quotes:
'THIS IS A CHARACTER STRING'
When you want to enter a text statement containing a changing variable, such as the time (%ESPATIME), you could type:
'THE TIME IS %ESPATIME'
ESP Workload Manager substitutes the actual system time in place of the symbolic-variable name %ESPATIME.
Using expressions
An expression is a variable, number, or character string connected by operators. Expression evaluation is from left to right; this is modified overridden by parentheses and by operator precedence. You can modify this order using parentheses.
A logical expression resolves to the value one if true, or zero if false. If an arithmetic expression resolves to zero, it is false. For any other value, the expression is true. If you do not enclose a logical expression in parentheses when you use an IF statement, ESP Workload Manager understands the THEN statement to be the terminator.
Examples:
• In the first statement, ESP Workload Manager processes the THEN statement if NUM=100.
• In the second statement, ESP Workload Manager processes the THEN statement if VAR1 is less than VAR2 and NUM is equal to 100.
IF NUM=100 THEN ...IF (VAR1 LT VAR2 AND NUM EQ 100) THEN ...
Using operators
You can use arithmetic operators, comparison operators, and logical operators in an expression.
Arithmetic operators
Numbers can be combined using the following arithmetic operators:
+ Add- Subtract* Multiply/ Divide// Integer Divide** PowerPrefix - Negate the following term. Same as '0-term'Prefix + Take following term as if it was '0+term'
If you use / for division, ESP Workload Manager performs the division internally using floating-point arithmetic but the resulting value is an integer. If you use // for
Section–Using expressions and strings in Procedures
116 ESP-5.4-UG-05
division, ESP Workload Manager disregards any remainder. For example, if A is an integer, then A = A/2*2 is always true, but A = A//2*2 is true only if A is even.
Comparison operators
The comparison operators return the value one if the result of the comparison is true, or zero otherwise. You can use the following operators, in either their symbol or letter form, in an expression.
>= GE greater than or equal to<= LE less than or equal to< LT less than > GT greater than= EQ equal to¬= NE not equal to
Logical operators
You can use the following logical operators in an expression:
& AND| OR
Order of precedence
The order of precedence of the operators is (highest at the top):
¬ (not), prefix + (prefix plus), prefix - (prefix minus)**(power)/(divide), // (integer divide), * (multiply)+(plus), -(minus)>= (GE), <= (LE), < (LT), > (GT),= (EQ), ¬= (NE)ANDOR
In the statement below (A = B or C > D) is a valid expression, and GO is a valid character string that ESP Workload Manager assigns to the variable E. ESP Workload Manager assigns the value GO to the variable E if either A = B or C > D.
IF (A=B OR C > D) THEN E = 'GO'
Note: If the expression A = B is true, the entire logical expression is also true. This means that ESP Workload Manager does not have to evaluate C > D. This order of precedence is useful for expressions such as IF I = 0 AND J/I > 4. This expression does not cause an error since J is divided by I only if I is non-zero.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 117
Built-in functions
A function is a sequence of instructions that can receive data, process that data, and return a value. ESP Workload Manager provides a set of built-in functions. To use a function, type the function name directly followed by one or more arguments within parentheses, like this:
function(arguments)
Note: There can be no space between the function name and the left parenthesis.
Built-in functions
The built-in functions fall into the following categories:
Summary by function
The following table summarizes the functions by category:
Category Explanation
Calendaring Tests schedule criteria and calculate time periods.
Job selection Checks if a job has already been selected for submission.
Symbolics Performs operations on symbolic variables.
System activity Checks the status of activity on the system, including jobs and tape drives.
Category Function Description
Calendaring DAYS_FROM Calculates the number of days from a date.
Calendaring DAYS_TO Calculates the number of days away from a date in the future.
Calendaring DAYS_BETWEEN Calculates the number of units (days, weekdays, workdays) between two dates.
Calendaring TODAY Tests to see if today matches a specified schedule expression.
Calendaring TOMORROW Tests to see if tomorrow matches a specified schedule expression.
Calendaring YESTERDAY Tests to see if yesterday matches a specified schedule expression.
Job selection SELECTED Checks to see if a job has been selected.
Symbolics DEFINED Checks to see if a symbolic variable has been defined.
Section–Using calendaring functions
118 ESP-5.4-UG-05
Testing for a true condition
Each one of the SELECTED, TODAY, TOMORROW, and YESTERDAY built-in functions returns a true value (1) or a false value (0). To test for a true condition, you do not have to specify the true value, since this is the default. If you want to test for a false value, you must specify either =0, EQ 0, or use the word NOT.
In the following example, both statements have the same effect. Each checks to see if today is not Monday.
IF TODAY('MONDAY') EQ 0 THEN ...IF TODAY('NOT MONDAY') THEN ...
Additional information
The following sections describe ESP Workload Manager built-in functions in detail and contain some examples of using these functions. For more examples, see “” on page 131.
Using calendaring functions
DAYS_TO
The DAYS_TO function returns a positive number representing the number of days from a specified special day, holiday, or any defined schedule criteria. If you do not use a year and the day you specified has passed, DAYS_TO assumes the next year and returns a positive number. If the date is in the past, ESP Workload Manager returns a negative number.
Symbolics LENGTH Returns the length of a symbolic variable.
Symbolics SUBSTR Returns a partial string of a symbolic variable.
System activity ACTIVE Checks to see if a job or address space is active on the current system.
System activity JOBONQ Checks to see if a job or address space is active on any system in the shared spool environment.
System activity TAPES Checks the status of tape drives.
Category Function Description
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 119
Example: DAYS_TO
If you want to determine the number of days to December 25 from the current day, and assign that number to an integer variable called X, type:
INTEGER XX=DAYS_TO('DEC 25')
DAYS_FROM
The DAYS_FROM function returns a positive number representing the number of days from a date in the past. DAYS_FROM assumes the current year if you do not specify one. If the date is in the future, ESP Workload Manager returns a negative number.
Example: DAYS_FROM
The following is an example of an expression containing the DAYS_FROM built-in function:
IF DAYS_FROM('AUGUST 1ST') GT 0 THEN
DAYS_BETWEEN
The DAYS_BETWEEN function returns a whole number representing the number of a specified unit of time (days, months, workdays, fiscal_months, and so on) between two given dates. You do not have to specify the dates explicitly; you can use a schedule expression instead.
DAYS_BETWEEN('first date','second date','restrictor')
The restrictor is an optional qualifier that defaults to DAYS. Examples of the following are other possible restrictors; HOURLY, DAILY, are WORKDAYS, and WEEKDAYS, WEEKLY, SATURDAYS, WEEKENDS, MONTHLY, YEARLYPLUS SAT. Your restrictor cannot be any unit of time less than hourly. The value that this function returns is the number of occurrences of the restrictor between the first date and the second date. If the first date is not prior to the second date, the function returns a value of zero negative number. The maximum value the function returns is 50000 for any restrictor other than DAYS.
Example: Days_Between to calculate workdays
If you want to know the number of workdays there are from January 30, 2001, up to but not including June 30, 2001, you would type:
DAYS_BETWEEN('JAN 30 2001','JUNE 30 2001','WORKDAYS')
Section–Using calendaring functions
120 ESP-5.4-UG-05
Example: Days_Between to calculate weeks
You could also determine the number of Saturdays from the 6th workday of the current month, up to but not including tomorrow, by typing:
DAYS_BETWEEN('6TH WORKDAY OF MONTH STARTING + TODAY','TOMORROW','SAT')
TODAY
The TODAY function compares the schedule expression that you specify to today’s schedule date. It returns a true or a false value, depending on whether the expression matches today. ESP Workload Manager returns a number code indicating the result:
1 = true0 = false
In the following example, ESP Workload Manager only processes the instructions following the THEN statement if today is a Friday.
IF TODAY('FRIDAY') THEN ...
When the statement is false, ESP Workload Manager skips to the next ELSE statement or to the following line.
You can check if today is not Friday like this:
IF TODAY('NOT FRIDAY') THEN ...
Example: TODAY
The following are examples of the TODAY function:
IF TODAY('MON WED FRI') THEN ...IF TODAY ('FIRST-LAST DAY OF JUNE JULY') THEN ...IF TODAY('LAST WORKDAY OF MONTH LESS 1 WORKDAY') THEN ...• The first statement checks if today is Monday, Wednesday, or Friday.• The second statement checks if today is any day in June or July.• The last statement checks if today is the second last workday of the month.
TOMORROW
The TOMORROW function compares the expression following the TOMORROW keyword to tomorrow’s date (for example, the day after the schedule date). ESP Workload Manager returns a true or false value, depending on whether the expression matches tomorrow. ESP Workload Manager returns a number code indicating the result:
1 = true0 = false
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 121
Examples: TOMORROW
The following are two examples using the TOMORROW function:
IF TOMORROW('LAST WORKDAY OF MONTH') THEN ...IF TOMORROW('HOLIDAY') THEN ...
• In the first example, ESP Workload Manager only processes the instructions following the THEN statement if tomorrow is the last workday of the month.
• In the second example, ESP Workload Manager only processes the instructions following the THEN statement if tomorrow is a holiday.
When the statement is false, ESP Workload Manager skips to the ELSE statement or the following line.
YESTERDAY
The YESTERDAY function compares the schedule expression that you specify to yesterday’s date (for example, the day before the schedule date). ESP Workload Manager returns a true or false value, depending on whether the expression matches yesterday. ESP Workload Manager returns a number code indicating the result:
1 = true0 = false
Example: YESTERDAY
In the following example, ESP Workload Manager only processes the instructions following the THEN statement when yesterday is the first workday of the month:
IF YESTERDAY('FIRST WORKDAY OF MONTH') THEN ...
When the statement is false, ESP Workload Manager skips to the ELSE statement or to the following line.
Example: YESTERDAY
In the following example, ESP Workload Manager only processes the instructions following the THEN statement when yesterday is a holiday:
IF YESTERDAY('HOLIDAY') THEN ...
When the statement is false, ESP Workload Manager skips to the ELSE statement or to the following line.
Section–Using functions for job selection
122 ESP-5.4-UG-05
Using functions for job selection
SELECTED
The SELECTED function returns a true or false value that indicates whether a job name has been selected as a result of a previously processed SELECT or RUN statement. To return a true value, ESP Workload Manager must have selected the job in this ESP Procedure or in another ESP Procedure invoked by the same Event, prior to evaluating the function. This function does not return a true value for a job selected via a POSTREQ, PREREQ, or COREQ statement.
ESP Workload Manager returns a number code for the value:
1 = true, the job name has been selected.0 = false, the job name has not been selected.
The syntax is:
SELECTED('JOBNAME')
If the job you are checking for selection is a qualified job, you will need to include the qualifier, like this:
SELECTED('jobname.qualifier')
This function is useful for scheduling jobs with the same frequency because it can eliminate the need to specify complicated criteria multiple times. The function is also useful when you want to schedule a job whenever another job is not scheduled.
Example: Selecting one job based on another
You can use the SELECTED function to select job B whenever ESP Workload Manager selects another job such as job A.
IF SELECTED('A') THEN SELECT B
Example: Selecting a job when another is not selected
In this example, ESP Workload Manager selects job Z whenever it does not select job X. ESP Workload Manager selects Z on all days except for the 3rd, 13th, and 23rd day of the month.
JOB X RUN 3RD 13TH 23RD DAY OF MONTHENDJOBJOB Z IF NOT SELECTED('X') THEN RUN TODAYENDJOB
The above results are valid only at Application generation time and not at Application process time.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 123
Using functions for symbolic variables
DEFINED
The DEFINED function checks to see if a symbolic variable has been defined and returns the following values:
1 = true0 = false
The syntax is:
DEFINED(variable)
Example: Defining an undefined variable
This example defines an integer variable called COUNT if it has not been defined.
IF NOT DEFINED(COUNT) THEN - INTEGER COUNT
LENGTH
The LENGTH function returns a number equal to the length of the variable following the LENGTH keyword in parentheses. The syntax is:
LENGTH(variable)
This function does not return a true or false value. Instead, it resolves to a whole number equal to the length of the named variable’s value.
Example: Calculating the length of a symbol
In this example, the LENGTH function assigns the length of a user-defined variable called LETTER to the integer variable SIZE. As a result, SIZE has a value of seven.
INTEGER SIZELETTER='OMICRON'SIZE=LENGTH(LETTER)
SUBSTR
The SUBSTR function resolves to a partial string from the variable string that follows the SUBSTR keyword in parentheses. The syntax is:
SUBSTR(start,length,variable_name)
Section–Using system activity functions
124 ESP-5.4-UG-05
Example: Using a substring of a time variable
The ESPATIME built-in variable represents the actual time, 19.35.42, for example. This example assigns the number of minutes in the ESPATIME symbolic variable to the symbol MIN.
MIN=SUBSTR(4,2,ESPATIME)
Example: Extracting the last character of a variable length symbol
This example uses the LENGTH and SUBSTR functions to extract the last character of the scheduled month name. The LENGTH function calculates the length of the month name. The SUBSTR function extracts the last character.
INTEGER X X=LENGTH(ESPSMONTH)LAST_CHAR=SUBSTR(%X,1,ESPSMONTH)
For example, if the scheduled month is December:
• X=8, because there are eight characters in the word December• LAST_CHAR=SUBSTR(8,1,'DECEMBER'), which resolves to R, the last
character in the word December
Using system activity functions
ACTIVE
The ACTIVE function tests to see if a job or any address space is active on the current system and returns a value based on that test. ESP Workload Manager returns a number representing the result:
address space identifier = true0 = false.
Note: If you want to verify that a job or any address space is active on any system (within the same JES node), use the JOBONQ built-in function.
Example: Checking if CICSPROD is active
This example sends a message to console identifier 01 if CICSPROD is active on the current system.
IF ACTIVE('CICSPROD') THEN + SEND 'CICSPROD IS STILL ACTIVE' CN(01)
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 125
JOBONQ
Use the JOBONQ function to determine, by checking JES, whether a job or group of jobs is currently on any JES queue. To use the JOBONQ function, use the following syntax:
JOBONQ('jobname','prefix','criteria')
This function requires three operands: a job name, a prefix, and a search criteria.
Returning values
The following list contains all the acceptable search criteria codes:
JOBONQ variables
The JOBONQ function returns the count of jobs that meet the criteria. For each job, it generates a series of four variables beginning with the specified prefix (the second operand). The variables represent the job identifier (JOBID), job number (JOBNO), whether or not the job is on hold (JOBH), and the queue the job is in (JOBQ). The suffix increments from one to the number of jobs found.
Operand Explanation
jobname Specifies the name of the job or job name prefix. You can only use a job name prefix with the U criterion.
prefix Specifies the prefix of the variables you want to generate. This operand is optional. For example, you can specify:IF JOBONQ('MYJOB', '', 'E') THEN -SEND 'MYJOB IS EXECUTING' U(*)
criteria Specifies the search criteria consists of any combination of the letter codes below. If this operand is omitted, ESP Workload Manager looks in all queues.
Search Criteria Code Explanation
I Examine the input queue.
E Examine the execution queue.
O Examine the output queue.
H Examine held jobs only.
U Treat the job name as a user ID. The search includes any job with a name consisting of the job name plus one character.
Section–Using system activity functions
126 ESP-5.4-UG-05
Example: JOBONQ
The JOBONQ function in the following example verifies the existence of any job in the input queue (I) in hold status (H). ESP Workload Manager assigns the number of jobs that meet this criteria to the integer variable JOBCOUNT.
INTEGER JOBCOUNTJOBCOUNT = JOBONQ('PAYROLL','Z','IH')
If JOBCOUNT is not equal to zero, meaning that at least one job called PAYROLL is in the input queue in hold status, ESP Workload Manager generates a set of variables for each job it finds. These variables all begin with the prefix Z.
Example
For example, for the first job it finds the variables are:
When ESP Workload Manager finds more than one job, the variables it generates for the second job are: ZJOBID2, ZJOBNO2, ZJOBH2, and ZJOBQ2. ESP Workload Manager repeats this series with the last digit incrementing by one for additional jobs it finds.
If you use the U criterion, the JOBONQ function also returns the JOBN variable, with the appropriate prefix and suffix.
Using JOBONQ with REEXEC
You can also use the JOBONQ function in conjunction with the REEXEC statement to allow you to re-execute an ESP Procedure at a specified time or after a certain time interval. In the following example, ESP Workload Manager re-executes the ESP Procedure if MYJOB is found on any queue.
IF JOBONQ('MYJOB') THEN REEXEC IN(5)
TAPES
ESP Workload Manager evaluates the TAPES function to check the status of tape drives on the system and compares the status to the resources required by the job. When you use the TAPES function at the job level for a job in an Application, you can verify the status of the tape drives before you submit a job.
Variable Explanation
ZJOBID1 JES job identifier in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary.
ZJOBNO1 JES job number (for example 123456).
ZJOBH1 Equal to zero if JES is not holding the job, or equal to one if JES is holding the job.
ZJOBQ1 Equal to I, E, or O depending on whether the job is on the input, execution, or output queue respectively.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 127
Note: To check the status of tape drives, Cybermation recommends you use resources. Resources provide you with easier, more efficient ways of defining tape requirements. For more information, see “Using Resources” on page 325.
Example: TAPES
To use this function, enter TAPES followed by two operands from the lists below:
TAPES('xy')
ESP Workload Manager evaluates both operands (x and y) of the function and returns a whole number.You can choose one of the following three options as the first operand:
You can choose one of the following as the second operand:
The default is CA.
Example: Checking available cartridge drives
If a job in an Application requires two cartridge drives, you can use the TAPES function to check that two cartridge drives are available before you submit the job. If they are not, ESP Workload Manager can check again after two minutes:
JOB TAPEJOB1IF TAPES('CA') < 2 THEN REEXEC IN(2)
Combining functions
You can combine built-in functions using the AND and OR logical operators. Specify the built-in function name each time you need to use it.
Option Explanation
C Cartridge drives.
R Reel-to-reel drives.
T Total drives.
Option Explanation
A Available.
O Online.
D Defined.
Section–Re-executing an ESP Procedure
128 ESP-5.4-UG-05
Examples
Some examples are shown below:
• Today is Friday, and today is not the last workday of the year:IF TODAY('FRIDAY' AND TODAY('NOT LAST WORKDAY OF YEAR') THEN
• Today is the last workday of the month, and CICS is active on the current system:IF TODAY('LAST WORKDAY OF MONTH') AND ACTIVE('CICS') THEN
• Yesterday was a holiday, tomorrow is Friday, and today is a workday:IF YESTERDAY('HOLIDAY') AND TOMORROW('FRIDAY') AND + TODAY('WORKDAY') THEN
• Today is Monday, Wednesday, or Friday, and either yesterday was a holiday or tomorrow is a holiday:IF TODAY('MON WED FRI') AND (YESTERDAY('HOLIDAY') OR + TOMORROW('HOLIDAY')) THEN
Re-executing an ESP Procedure
Use the REEXEC statement to request re-execution of an ESP Procedure at a specific time or after a certain time interval. ESP Workload Manager stores the number of re-executions in a symbolic variable called ESPREEXEC#. If you use REEXEC within the scope of a JOB statement in an Application, ESP Workload Manager re-executes only the code associated with that job, and maintains a separate ESPREEXEC# for each job.
Example: Checking if CICS is active
This ESP Procedure checks to see if a job or address space called CICS is active on the current system.
IF ACTIVE('CICS') THEN DO SEND 'CICS IS DUE TO COME DOWN' CN(01) NONDEL REEXEC IN(5)ENDDOELSE SUBMIT 'PROD.JCL.CNTL(CICSBKUP)'
• If CICS is active, ESP Workload Manager sends a non-deletable message to console id 01 and re-executes the Procedure in five minutes.
• If CICS is not active, ESP Workload Manager submits the member CICSBKUP from the library PROD.JCL.CNTL.
Note: If you want to set up a dependency with an online region, such as CICS, for a job in an ESP Application, the preferred method is to use ESP Workload Manager resource feature. For information on using resources, see “Using Resources” on page 325.
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 129
Example: Waiting for a job
This ESP Procedure checks to see if a job called RMTJOB is on the input queue.
INTEGER COUNTCOUNT=JOBONQ('RMTJOB','X','IH')IF COUNT=1 THEN VS '$AJ%XJOBNO1'ELSE DO IF ESPREEXEC#<5 THEN REEXEC IN(30) ELSE SEND 'I GIVE UP ON RMTJOB' U(USER01)ENDDO
• If RMTJOB is on the input queue on hold, ESP Workload Manager releases the job.
• If RMTJOB is not on the input queue on hold, ESP Workload Manager checks the number of re-executions. If the number of re-executions is less than five, ESP Workload Manager re-executes the Procedure in 30 minutes. Otherwise, ESP Workload Manager sends a message.
Using templates
A template is an element of CLANG that allows you to specify repetitious commands or statements once, such as those you use to define holidays or jobs.
This section contains a brief introduction to templates. For more information on using templates, see the ESP Workload Manager Advanced User’s Guide.
Defining a template
To define a template:
1. Use a TEMPLATE statement to give your template a name and identify operands you want to pass through the template.
2. Define the statements that make up your template.
3. End the template definition with the ENDTEMPL statement.
To use a template you have defined:
• Specify the name of the template followed by any operands you want to pass through the template.
Example - Defining a static holiday
This example uses a template to define a static holiday called CHRISTMAS, for six years. The DEFHOL command defines a holiday for a particular date.
Section–Using templates
130 ESP-5.4-UG-05
Use a template in an ESP Procedure to specify the DEFHOL command and supply the template with different years. In this example:
• The name of the template is XMAS, and it accepts one positional operand represented by the variable YEAR.
• The body of the template consists of one statement that defines CHRISTMAS as a 24 hour holiday, on December 25 each year, in the SYSTEM calendar. The year is represented by the variable YEAR.
• The ENDTEMPL statement ends the template definition.• The template XMAS is then used with the years 2001 through 2006. Each of
these years is passed to the template and substituted for the variable YEAR within the template.
TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START('DEC 25, %YEAR') + FOR(24) CAL(SYSTEM)ENDTEMPLXMAS 2001XMAS 2002XMAS 2003XMAS 2004XMAS 2005XMAS 2006
Set up an Event to invoke this ESP Procedure and trigger it manually to define your holidays.
Example - Defining similar jobs
In this example, an Application contains a number of print jobs. These jobs:
• Run daily• Belong to a subApplication called PRTJOBS• Run independently
The following is a sample definition of this Application:
APPL PAYROLLJCLLIB 'CYB.JOBS.CNTL'JOB USERA SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERB SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERC SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERD SUBAPPL PRTJOBS
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 131
RUN DAILYENDJOB
Because of the similarity of the jobs, you can define a print job template and pass one operand for the name of each job. The template contains details for the print job, such as SUBAPPL PRTJOBS and RUN DAILY.
Example - Defining similar jobs
APPL PAYROLLJCLLIB 'CYB.JOBS.CNTL'TEMPLATE PRTJOBS (1,NAME) JOB %NAME SUBAPPL PRTJOBS RUN DAILY ENDJOBENDTEMPLPRTJOBS USERAPRTJOBS USERBPRTJOBS USERCPRTJOBS USERD
The template is used for jobs USERA, USERB, USERC, and USERD. ESP Workload Manager substitutes the job name for the %NAME variable within the template.
Using Event definition commands in Procedures
You can use the following commands in an ESP Procedure:
Command Explanation
INVOKE Invokes another ESP Procedure.
LIBSUB Submits JCL from a Librarian data set.
PANSUB Submits JCL from a Panvalet data set.
SEND Sends messages to a TSO user or console.
SIGPOST Posts a complete signal.
SIGCYCLE Cycles a new generation of a signal.
SUBMIT Submits JCL from a PO, PS, or VSAM ESDS data set.
VS Issues an operator command (restricted use).
Section–CLANG examples
132 ESP-5.4-UG-05
CLANG examples
This section contains some additional examples of using CLANG.
Example: Scheduling a job on the last day of the month
In this example, ESP Workload Manager selects a job if it is the last day of the month and the month has 31 days in it. The Procedure uses the ESPSDD built-in symbolic variable that represents the number of the scheduled day of the month.
The ESP Procedure looks like this:
IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN SELECT MONTHEND
Alternatively, if you normally use RUN statements for your jobs, the ESP Procedure looks like this:
JOB MONTHEND IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN RUN TODAYENDJOB
Example: Taking different action on a weekday
In this example, ESP Workload Manager takes different actions based on whether or not the scheduled day is a weekday.
• If the scheduled day is a weekday, ESP Workload Manager sends a message and submits JOB1.
• If the scheduled day is not a weekday, ESP Workload Manager sends a different message and submits JOB2.
The ESP Procedure looks like this:
IF TODAY('WEEKDAY') THEN DO SEND 'TODAY IS A WEEKDAY' U(*) SUBMIT 'CYB.ESP.JCL(JOB1)'ENDDOELSE DO SEND 'TODAY IS A WEEKEND' U(*) SUBMIT 'CYB.ESP.JCL(JOB2)'ENDDO
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 133
Example: Taking different actions based on the status of CICS
In this example, ESP Workload Manager takes different actions based on whether or not CICS is active.
• If CICS is active on the current system, ESP Workload Manager jumps to a label called STOP. ESP Workload Manager issues an operator command, schedules a re-execution in five minutes, and exits this Procedure.
• If CICS is not active on the current system, ESP Workload Manager jumps to a label called GO and issues a command to trigger an Event.
The ESP Procedure looks like this:
IF ACTIVE('CICS') THEN JUMPTO STOPELSE JUMPTO GOSTOP:VS 'F CICS SHUTDOWN'REEXEC IN(5)EXITGO:VS 'F ESP,TRIGGER PROD.NIGHTLY'
Example: Using calendaring functions
This example uses different CLANG functions. It accomplishes the following:
• Assigns the number of days to December 25 to the integer variable X• Assigns the number of workdays between today and December 25 to the integer
variable Y• Assigns the number of days since July 20, 1969 to the integer variable Z• Sends the above values back to your terminal• Sends another message back to your terminal if today is a workday
The ESP Procedure looks like this:
INTEGER X,Y,ZX=DAYS_TO('DEC25')Y=DAYS_BETWEEN('TODAY','DEC25','WORKDAYS')Z=DAYS_FROM('JUL20,1969')SEND 'THERE ARE %X DAYS TO CHRISTMAS' U(*)SEND 'THERE ARE %Y WORKDAYS TO CHRISTMAS' U(*)SEND 'THERE HAVE BEEN %Z DAYS SINCE THE FIRST MOON WALK' U(*)IF TODAY('WORKDAY') THEN - SEND 'ANOTHER DAY OF HARD LABOR' U(*)
Example: Calculating time periods
This example calculates the number of days, from a specific time and date in the past. ESP Workload Manager sends the results back to your terminal.
Section–CLANG examples
134 ESP-5.4-UG-05
The ESP Procedure looks like this:
INTEGER X,YX=DAYS_BETWEEN('1PM JAN1,1994','NOW','HOURLY')Y=DAYS_BETWEEN('JAN1,1994','TODAY','DAILY')SEND 'ITS BEEN %X HOURS SINCE STOP HOUR' U(*)SEND 'ITS BEEN %Y DAYS SINCE STOP DAY' U(*)
Example: Overriding an ESP Procedure on a particular date
There can be occasions where you need to use an alternate ESP Procedure for a specific date. One method is illustrated below:
DAILY:ESPPROCIF TODAY('specific date') THEN - DO INVOKE 'PROD.ALT.ESPPROC(DAILYEX)' EXIT ENDDO/*REGULAR PROCEDURE*/...
The first statement checks to see if today is a specific date. If so, ESP Workload Manager invokes an alternate ESP Procedure. Otherwise, ESP Workload Manager processes the statements in the regular Procedure.
Example: Taking different action based on time
In this example, ESP Workload Manager takes different actions based on when a job becomes eligible for submission. The criteria are:
• If job THISJOB becomes ready for submission between 3 am and 3:59 am, ESP Workload Manager submits the job and sends a message indicating it is almost too late to run the job.
• If THISJOB becomes ready for submission at 4 am or later, ESP Workload Manager does not submit the job.
• Otherwise, if THISJOB becomes ready between midnight and 2:59 am, ESP Workload Manager sends a message indicating the job is on time.
The ESP Procedure is shown below. The ESPAHH symbolic variable represents the actual two-digit hour.
JOB THISJOB RUN DAILY IF ESPAHH EQ '03' THEN DO SEND 'IT IS ALMOST TOO LATE TO RUN THISJOB' U(OP1) EXIT ENDDO IF ESPAHH GE'04' THEN QUIT
Chapter 5–Working with ESP Procedures
ESP-5.4-UG-05 135
SEND 'THISJOB IS ON TIME' U(OP1)ENDJOB
Caching an ESP Workload Manager Procedure
By caching (storing) an ESP Workload Manager Procedure in memory, you can improve CPU usage and processing speed for ESP Procedures that include a large number of jobs. You can create, display and delete cache entries by using the PCACHE and CPROC commands (for details, see the ESP Workload Manager Reference Guide).
Important: If you change the contents of a Procedure, delete the cached version of the Procedure so the new version is read automatically by an active Application.
To cache an ESP Workload Manager Procedure:
• Use the PCACHE command.
To display and delete cache entries:
• Use the CPROC command.
Note: To delete a Procedure cache, you need UPDATE access to security profile APPL.applname, where applname is the name of the Application generated by your Procedure. See your ESP Workload Manager security administrator to set up access. For details, see the ESP Workload Manager Security Guide.
Section–Caching an ESP Workload Manager Procedure
136 ESP-5.4-UG-05
ESP-5.4-UG-05 137
Using Applications
An Application consists of one or more jobs, or other workload objects. A workload object can be a job, a manual task, a command you want processed, or a distributed object, such as a Unix script. For example, an Application can consist of all of your payroll jobs. You can define an Application using the Application Definition panels, ESP Workstation, or by editing a member of a PDS. All Application definitions are stored in ESP Procedures.
This chapter contains the following topics:
• Introducing Applications• Identifying the Application• Identifying JCL libraries• Identifying jobs• Defining job requirements• Specifying time dependencies• Specifying job relationships• Using Implicit Resources• Selecting jobs for submission• Using different job types• Defining external jobs• Defining manual jobs• Using links• Using tasks• Using APPLEND workload object
Section–Introducing Applications
138 ESP-5.4-UG-05
• Changing job attributes• Using data-set-trigger workload objects• Using FTP data-set-trigger workload objects• Using explicit-data-set-trigger workload objects• Tagging jobs• Providing notification on Job status• Using critical-path analysis• Issuing ESP Workload Manager commands• Using subApplications• Working with Applications• Displaying an Application• Controlling an Application• Changing an Application definition• Invoking an ESP Application
Introducing Applications
This section describes the generating and processing of Applications:
• How ESP Workload Manager manages jobs in an Application• Generating and processing an Application• Application generations
Processing an Application
ESP Workload Manager performs the following processing steps for jobs in an Application:
1. When a job’s submission time arrives, ESP Workload Manager checks for any remaining dependencies.
2. Each job has a hold count. The hold count is a number corresponding to the number of immediate predecessors for the job. A job in an Application is not eligible for submission if the hold count exceeds zero.
3. When a predecessor job terminates successfully, ESP Workload Manager subtracts one from the successor job’s hold count. For instance, if the hold count for a job is three and a predecessor job terminates successfully, the hold count decreases to two.
4. When the hold count reduces to zero, ESP Workload Manager readies the job for submission, unless the job is in another type of hold status such as Manual hold or Resource Wait.
5. ESP Workload Manager submits the job when all required resources are available.
Chapter 6–Using Applications
ESP-5.4-UG-05 139
Application phases
An Application passes through the following two phases:
• Generation• Process
Generation phase
When an Event is triggered that invokes an ESP Application definition, ESP Workload Manager must first generate the Application. ESP Workload Manager reads the definition and creates a record in a file known as the APPLFILE. This record includes the information ESP Workload Manager needs to process the jobs in the Application. The record describes the Application and all the jobs within it.
Process phase
Once ESP Workload Manager generates an Application, it then begins to process that Application as follows:
• A component of ESP Workload Manager called the Application Manager has a queue of jobs awaiting submission. Jobs can be in a waiting state because of such things as time, predecessors, and resources.
• The Application Manager looks at the jobs and assesses whether any time dependencies have been met. If so, the job goes into a job dependency state and waits until the last predecessor dependency has been met.
• The job then enters a resource wait state, which allows ESP Workload Manager resource manager to verify that the job’s resource dependencies are met.
• ESP Workload Manager re-drives the Event to submit the job when the required resources are available.
• The Application manager uses real-time SMF data to update the execution status of each job.
Phase status
You can find out the phase status of an Application by using the ESP_APPL_PROC and ESP_APPL_GEN symbolic variables in an Application definition.
ESP Workload Manager sets these symbolic variables as follows:
ESP_APPL_GEN equals:
• 1 during generation phase• 0 otherwise
ESP_APPL_PROC equals:
• 1 during process phase• 0 otherwise
Section–Introducing Applications
140 ESP-5.4-UG-05
In the following example, ESP Workload Manager sends a message to a user only during the generation phase of an Application.
IF ESP_APPL_GEN=1 THEN - SE 'ESP IS GENERATING THE PAYROLL APPLICATION' U(TAXMAN)
Application generations
Each Application has a generation number assigned by ESP Workload Manager when the Application is generated. This number increments with each generation of an Application. Using the generation number, ESP Workload Manager can identify the particular generation of an Application to which a job belongs.
A generation of an Application does not have to complete within any 24 hour period. An Application can span many days or weeks, or you can schedule an Application many times in one day. Different generations of an Application can process at the same time.
Defining an Application
You must use an ESP Procedure to describe an Application to ESP Workload Manager. See “Working with ESP Procedures” on page 107 for detailed information on ESP Procedures.
ESP Procedure statements
An ESP Procedure that defines an Application consists of a series of statements that:
• Identifies the Application• Tells ESP Workload Manager where the appropriate JCL is located• Identifies the jobs• Describes the job relationships• Describes when ESP Workload Manager should select the jobs to run • Describes other job dependencies, such as time
Chapter 6–Using Applications
ESP-5.4-UG-05 141
In addition, an ESP Procedure can also indicate which job documentation library is used, or specify what condition codes cause a job to fail.Visually, an Application looks like this:
Application definition
The corresponding Application definition looks like this:
APPL PAYROLLJCLLIB 'CYBER.ESP.JCL'JOB A RUN DAILY RELEASE (B,C)ENDJOBJOB B RUN DAILY RELEASE DENDJOBJOB C RUN DAILY RELEASE DENDJOBJOB D RUN DAILY RELEASE EENDJOBJOB E RUN FRIDAY RELEASE FENDJOBJOB F RUN LAST WORKDAY OF MONTHENDJOB
The following sections discuss how to define an Application.
A
B C
E
F
D
Daily
Friday
Last workday of month
Section–Identifying the Application
142 ESP-5.4-UG-05
Identifying the Application
Each Application must have a name. To identify the name of an Application, use the APPL statement in an ESP Procedure like this:
APPL applname
The Application name can contain up to 8 characters. Characters must be either alphanumeric, a national character ($ # @), or an underscore (_). The first character cannot be numeric. Your security administrator can require you to code other information on the APPL statement, such as the SAF_PROF_APPL keyword, to provide more granular security for the Application.
Controlling concurrent processing
Normally, if two generations of an Application are active on the system at the same time, they execute at the same time. You can control concurrent processing at different levels, as follows:
Operand Explanation Example
WAIT operand on APPL statement Specifies that a generation of an Application must wait until its previous generation is complete.
APPL PAYROLL WAIT
WAIT operand on the SUBAPPL statement
Specifies that the subApplication must wait until the same subApplication in the previous generation is complete.
SUBAPPL PAYREQ WAIT
JOB_ANCESTOR_WAIT(ANY) operand on the APPL statement
Indicates that a job is not eligible for submission if the same job in any previous generation of the Application has not completed successfully.
APPL PAYROLL + JOB_ANCESTOR_WAIT(ANY)
JOB_ANCESTOR_WAIT(LAST) operand on the APPL statement
Indicates that a job is not eligible for submission if the same job in the previous generation of the Application has not completed successfully. ESP Workload Manager only looks at the -1 generation.
APPL PAYROLL - JOB_ANCESTOR_WAIT(LAST)
None of the above operands Specifies that the Applications can process at the same time.
APPL PAYROLL
Chapter 6–Using Applications
ESP-5.4-UG-05 143
Identifying JCL libraries
You can use global statements in your Application to specify the default JCL libraries you want to use throughout an Application. This saves you the task of repeatedly specifying the same information as part of each job definition. The scope of a global statement extends from the point at which you specify it to either the end of the Application, or to the point at which you specify another global statement. This way you can change or override job defaults several times during an Application, if necessary.
You can specify any of the following: a JCL library, a temporary JCL library, and a COPYJCL library at a global level. You can override the JCL library, member name, or COPYJCL library at a job level.
Note: The rules for the JCL library differ when resubmitting or inserting a job from CSF.
Example
The following example identifies three libraries in the BILLJOBS Application. These global statements are specified prior to any JOB statements.
APPL BILLJOBSJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL'COPYJCL 'CYBER.JCL.COPY' GEN(0)
Each of these statements is described in the sections following.
Specifying a JCL library
Use the JCLLIB statement to specify the JCL library you want to use for all jobs following this statement.
For example:
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYSENDJOBJOB PAYJOB2 RUN WORKDAYSENDJOB
The JCLLIB statement cannot be used at the job level. If you code a JCLLIB statement within the scope of a JOB statement, it affects all jobs after it, or until another JCLLIB statement is specified. To override the JCL library for a particular job, use the DATASET statement. For details, see ““Specifying a JCL library for a single job” on page 145”.
Section–Identifying JCL libraries
144 ESP-5.4-UG-05
The MEMBER statement can be used to override the JCL name searched for in the JCLLIB library. For details, see “Specifying a member name for a JCL library search” on page 145.
Specifying a temporary JCL library
Use the TEMPLIB statement to specify the temporary or override JCL library you want to use as the default for all jobs following this statement. For jobs following the TEMPLIB statement, if the JCL is found in the temporary library, then that JCL is used. Otherwise, JCL from the library in the most recent JCLLIB statement is used.
For example:
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL'JOB PAYJOB1 RUN WORKDAYSENDJOB
The preceding statement instructs ESP Workload Manager to look for JCL in the temporary library first. As long as the JCL is in the temporary library specified in TEMPLIB and is not date excluded, ESP Workload Manager submits the regularly scheduled job from the temporary library. ESP Workload Manager does not automatically delete the member from the TEMPLIB data set when a job completes.
You can code TEMPLIB anywhere in a procedure and all subsequent jobs will use JCL from the temporary library. In the following example, jobs PAYJOB2 and PAYJOB3 use JCL from temporary library PROD.OVERRIDE.JCL.
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYSENDJOBTEMPLIB 'PROD.OVERRIDE.JCL'JOB PAYJOB2 RUN WORKDAYSENDJOBJOB PAYJOB3 RUN WORKDAYSENDJOB
The MEMBER statement and the JOBNAME keyword in the TEMPLIB statement affect the JCL name searched for in the TEMPLIB library. For details, see “Specifying a member name for a JCL library search”, following.
Chapter 6–Using Applications
ESP-5.4-UG-05 145
Specifying a member name for a JCL library search
By default, when ESP Workload Manager searches a library for JCL, it looks for a member name that is the same as the job name. You can use the MEMBER statement to specify a different member name from the job name. This is useful if you want to run the same JCL for different jobs. In the following example, the search is for member PJOB.
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 MEMBER PJOBJOB PAYJOB2 MEMBER PJOBENDJOB
You can have ESP Workload Manager disregard the MEMBER statement when it searches a temporary library by including the JOBNAME keyword on the TEMPLIB statement. This is useful if you want to override one job in a group of jobs that use the same JCL member, such as the jobs in the preceding example.
If you want to override PAYJOB1, you start by adding a TEMPLIB statement to the Procedure and placing the override JCL in the temporary library. However, both jobs in the preceding example run JCL from PJOB, whether it is in the JCLLIB or TEMPLIB libraries. You need to call your temporary JCL something else so it is not picked up by PAYJOB2. You do this by adding JOBNAME to the TEMPLIB statement and calling your override JCL PAYJOB1:
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL' JOBNAMEJOB PAYJOB1 MEMBER PJOBJOB PAYJOB2 MEMBER PJOBENDJOB
In the preceding example, ESP Workload Manager first searches the temporary JCL for member PAYJOB1 and runs that JCL. Next, it searches the temporary JCL for member PAYJOB2, which it does not find. It then searches the regular library for member PJOB and runs that JCL.
Specifying a JCL library for a single job
The JCLLIB and TEMPLIB statements allow you to specify the JCL library for multiple jobs. To specify the JCL library and (optionally) the member name for a single job, you use the DATASET statement. DATASET overrides the library in the JCLLIB statement (but not the library in the TEMPLIB statement) for the job it is coded under.
Section–Identifying JCL libraries
146 ESP-5.4-UG-05
Example: Using a different JCL library for a job
In the following example, the JCL for PAYJOB1 and PAYJOB3 is read from PROD.JCL.CNTL, the library from the JCLLIB statement. PAYJOB02 is read from PROD.OVERRIDE.JCL, the override library from the DATASET statement.
APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2ENDJOBJOB PAYJOB2 DATASET 'PROD.OVERRIDE.JCL' RUN DAILY RELEASE PAYJOB3ENDJOBJOB PAYJOB3 RUN DAILYENDJOB
If you want to use the JCL from PROD.OVERRIDE.JCL only on February 14, 2000, you can code the following for the PAYJOB2 in the preceding example:
JOB PAYJOB2 IF TODAY('FEB 14,2000') THEN - DATASET 'PROD.OVERRIDE.JCL' RUN DAILY RELEASE PAYJOB3ENDJOB
Controlling the use of temporary JCL
Use the following options to control the use of temporary JCL:
• Use ESP Workload Manager control statements in JCL to limit the time period for usage. This technique is described later in this section.
• Use ESP Workload Manager automatic variable insertion facility (AUTOVARS) to insert a trailer step that deletes the TEMPLIB member. For information on using AUTOVARS, see the ESP Workload Manager Advanced User's Guide.
• Use another method for cleaning out the TEMPLIB members. For example, on a daily basis, delete the members.
• Instead of using TEMPLIB, use IF logic with the DATASET statement to override the JCL library for a particular job. This technique is described later in this section.
• Instead of using TEMPLIB, use %INCLUDE and %EXCLUDE statements within the JCL. This can be practical if the differences in JCL are minimal. For information on using these statements, see the ESP Workload Manager Advanced User's Guide.
Chapter 6–Using Applications
ESP-5.4-UG-05 147
• Use different data sets. For example, you could use a different data set each day.
Example: Using a different TEMPLIB based on year and day
In the following example, ESP Workload Manager symbolic variables are used as part of the TEMPLIB data set name. %ESPSYEAR resolves to the four-digit year; %ESPSDDD resolves to the Julian day. For example, on February 28, 2001 this:
TEMPLIB 'ESP.OVERRIDE.D%ESPSYEAR%ESPSDDD'
resolves to:
ESP.OVERRIDE.D2001059
Limiting the use of temporary JCL
A job can run from a temporary JCL library (TEMPLIB) for a period of time. If you want to limit the time period in which temporary JCL is to be used for a job, you can:
Use a //* FROM statement in the job JCL to identify the beginning date and time. The default is NOW.
Use a //* UNTIL statement in the job JCL to identify the ending date and time. There is no default. ESP Workload Manager uses the TEMPLIB JCL up to, but not including, the date and time specified.
You can use either one of these statements or you can use both. Place these statements before the job card in a JCL member of the temporary library (TEMPLIB). You can use any ESP Workload Manager scheduling term that resolves to a single date and time.
Example
In the following example, ESP Workload Manager uses the temporary JCL from midnight on February 1, 2001 up to, but not including, February 14, 2001. At any time after February 13, ESP Workload Manager uses the default JCL library. Note these dates are based on the scheduled date of the Event, which may not be the actual date of job submission.
//* FROM FEB 1,2001//* UNTIL FEB 14,2001//BILLJOBA JOB . . .
To specify a COPYJCL library:
• Use the COPYJCL statement to generate a copy of the JCL for every job, as ESP Workload Manager submits it.
This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved. This JCL can be used for job re-submission. ESP Workload Manager keeps track of where the job was submitted from and the JCL that was used. ESP Workload Manager can store the copy of the
Section–Identifying JCL libraries
148 ESP-5.4-UG-05
JCL either by job name (JOBNAME operand) or by JES job number (JOBID operand).
Using the JOBNAME operand of the COPYJCL statement
The JOBNAME operand requests the member name used for storing the JCL for a job to be the same as the job name. This is the default. Each submission of a particular job overwrites the previous copy of that job JCL.
Using the JOBID operand
Use the JOBID keyword when you want ESP Workload Manager to store the copy of the JCL by job number. ESP Workload Manager creates a member name in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary. The system assigns this number sequentially. A member is not overwritten until the corresponding job ID reoccurs.
Writing the JCL to a GDG
With either the JOBID or the JOBNAME operand, you can write the JCL to a Generation Data Group (GDG). A new generation can be created each day to maintain several generations of JCL. Schedule an Event each day to submit a job that creates the next generation.
Example: Using COPYJCL
This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by job name (by default).
COPYJCL 'CYBER.JCL.COPY' GEN(0)
Suppressing COPYJCL
If you do not want to create COPYJCL for a particular job, you can specify the following:
JOB MISCCOPYJCL NONE
Compressing COPYJCL
If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You can use a data-set-triggered Event to submit the compress job automatically after a number of closures.
Chapter 6–Using Applications
ESP-5.4-UG-05 149
Identifying jobs
An ESP Application is made up of a group of related jobs and other tasks. The jobs and tasks have job names assigned to them.
Before identifying job requirements, you must use a JOB statement to identify the name of the job in an Application. You can define jobs in any order. ESP Workload Manager submits the jobs based on how you define the job relationships.
JOB statement
Once the JOB statement has been used to introduce a job to an Application, use other related job statements to:
• Define a job’s processing requirements• Override any default specifications• Specify the relationships between the named job and others included in this
Application or outside this Application
The JOB statement defines the beginning of the job definition. The ENDJOB statement or another JOB statement signifies the end of a job definition. You must use an ENDJOB statement after defining all of your jobs. Although optional, it is recommended you use an ENDJOB for each job definition.
The following is a sample job definition:
JOB PATJOB1 RUN DAILY RELEASE PATJOB2ENDJOB
Qualifying jobs
ESP Workload Manager lets you qualify job names with a qualifier consisting of up to 8 alphanumeric characters, and separated from the job name by a period,‘.’ You can qualify jobs, links, and tasks, but you cannot qualify Manual jobs. Use qualification of job names in an Application to:
• Define duplicate jobs• Give a meaningful name to other job types, such as links and tasks• Give a more descriptive name to a job• Pass a built-in symbolic variable (ESPAPQUAL), representing the qualifier, to a
job’s JCL
Symbolic variables as qualifiers
You should not use %ESPA (actual) variables as time qualifiers for jobs because the actual time differs from Application generation to the time ESP Workload Manager submits a job as part of the Application. You can use %ESPS (scheduled) variables as time qualifiers as these refer to the scheduled time of the Event.
Section–Identifying jobs
150 ESP-5.4-UG-05
Examples: Qualified jobs
The following are some examples of qualified jobs. The last example uses a qualifier that consists of the first three characters of the symbolic variable %ESPSDAY. This is the scheduled day name. For example, on Monday this resolves to MON.
JOB MYJOB.RUN1JOB STILL.RUNNINGJOB BACKUP.SYSRESJOB PAYJOB.%ESPSDAY(1:3)
Duplicate job names
Duplicate job names are not allowed in an Application. If you want to invoke the same job more than once, you must use a qualifier.
When a JOB statement is repeated with an identical name in an Application, ESP Workload Manager considers that the second and following instances continue the first instance. You can spread a job definition over many fragments in a procedure. You cannot change the workload object type (for example from a TASK to a LINK.)
When there are multiple statements of the same kind:
• The latest statement instance overrides the previous ones if only one instance is allowed. For example, the DUEOUT statement.
• All the statements are combined if more than one statement is allowed. For example the RUN statement.
Examples
Multiple runs of a job
This example shows how you can define a job more than once in an Application using a job qualifier. Job A appears twice in the Application. The qualifier of the first run is THIS; the qualifier of the second run is THAT.
APPL TESTQUALJCLLIB 'CYB.TESTJOBS.CNTL'JOB A.THIS RUN ANY RELEASE A.THATENDJOBJOB A.THAT RUN ANYENDJOB
Combined statement
The following procedure segment:
JOB A DUEOUT EXEC 23:59 RUN WEEKDAYS
Chapter 6–Using Applications
ESP-5.4-UG-05 151
NOTIFY OVERDUE ALERT(TRDY) RELEASE BENDJOB... (other job definitions)JOB A DUEOUT EXEC 13:00 RUN SUN RELEASE CENDJOB
is equivalent to:
JOB A DUEOUT EXEC 13:00 RUN WEEKDAYS AND SUN NOTIFY OVERDUE ALERT(TRDY) RELEASE B RELEASE CENDJOB
The RUN and RELEASE statements have been combined but the last instance of the DUEOUT statement has overridden the previous one. If you want to use the different DUEOUT requirements for weekdays and Sunday, you must use IF-THEN-ELSE logic.
Identifying a job as on-request
With Applications, you can identify certain jobs as on-request and define their relationships to other jobs. The on-request jobs take their place in the schedule when they are selected. From the time you generate the Application up to the time of job submission, you can use CSF or the APPLJOB command to request the job. If you have not explicitly requested the job, ESP Workload Manager bypasses it and treats it as a normal completion, releasing its successor jobs. To mark a job as on-request, use the REQUEST operand of the JOB statement.
REQUEST job
By selecting a REQUEST job, you are not requesting the job, you are only making it eligible for explicit request via CSF or the APPLJOB command. You must first generate the Application before you can request any of the Application’s jobs. To allow users to request jobs, you can generate the Application containing these jobs early in the morning and use submit time dependencies (for example, DELAYSUB statements) on the jobs with no predecessors so they are not submitted at the time ESP Workload Manager generates the Application.
Section–Identifying jobs
152 ESP-5.4-UG-05
Other methods
Other methods exist for handling on-request work. For example you can:
• Insert a job into an Application from CSF• Use a separate on-request Application with a link that keeps it active• Trigger an Event and pass it a user symbolic variable representing the job name
For information on CSF, see “Consolidated Status Facility (CSF)” on page 221.For information on using links, see “Using links” on page 184. For information on using symbolic variables, see ESP Workload Manager Advanced User’s Guide.
Example
In the following example, if job J2 is not requested at the time it is scheduled for submission, ESP Workload Manager bypasses it and submits job J3.
The Application looks like this:
APPL APPL1JCLLIB...JOB J1 RUN DAILY RELEASE J2ENDJOBJOB J2 REQUEST RELEASE J3 RUN DAILYENDJOBJOB J3 RUN DAILYENDJOB
J1 Daily
J3 Daily
J2 REQUEST
Chapter 6–Using Applications
ESP-5.4-UG-05 153
To request the job:
Use the RQ command from the Consolidated Status Facility, or use the APPLJOB (abbreviated AJ) Command.
The following example shows requesting job J2 in the current generation of APPL1, with the abbreviated APPLJOB command:
AJ J2 REQUEST APPL(APPL1.0)
To define critical jobs:
Use the CRITICAL operand on the JOB statement to identify a critical job in your Application.
If critical path analysis is turned on for the Application, ESP Workload Manager calculates the longest path to this job, based on historical execution time, and identifies this as the critical path. You can display critical path jobs using CSF or the LISTAPPL command.
The following statement defines job XYZ as critical.
JOB XYZ CRITICAL
For information on critical path analysis, see “Using critical-path analysis” on page 208.
To define held jobs:
Use the HOLD operand on the JOB statement to identify a job that you want to hold from submission until you release it.
This places the job on manual hold when ESP Workload Manager generates the Application. You can display jobs that are on manual hold using CSF or the LISTAPPL command.
The following statement defines job ABC on hold.
JOB ABC HOLD
It is not a common practice to define jobs on hold. If a job needs to wait for a manual process, it is better to use a task in the Application as a predecessor.
For information on using tasks, see “Using tasks” on page 188.
Defining conditional jobs
Normally, all jobs in an Application must complete, or be bypassed, for the Application to complete. In some situations, you could have some optional jobs (other than on-request jobs) that may or may not run as part of the Application. These jobs are referred to as conditional jobs. ESP Workload Manager completes an Application when all non-conditional jobs are complete and bypasses any incomplete conditional jobs.
Section–Identifying jobs
154 ESP-5.4-UG-05
For example, you can have a recovery job that only runs when another job in the Application abends. In this case, the recovery job is a conditional job. The recovery job may or may not run. If all other jobs in the Application are complete then you want ESP Workload Manager to complete the Application.
To define conditional jobs:
Use the CONDITIONAL operand on the JOB statement to identify a job that may or may not run as part of an Application.
The following statement defines job RECOVER as a conditional job.
JOB RECOVER CONDITIONAL
For examples of using conditional jobs, see ESP Workload Manager Advanced User’s Guide.
Scope of a JOB statement
The scope of a JOB statement includes all statements up to an ENDJOB statement or the next JOB statement. ESP Workload Manager processes commands based on where they are placed, as follows:
• ESP Workload Manager processes commands outside the scope of JOB statements when the Application is generated and every time a job becomes eligible (for example, all dependencies met).
• ESP Workload Manager processes commands within the scope of a JOB statement only when the job becomes eligible (for example, all dependencies met).
Example: Sending messages at different stages
The following Application contains three SEND commands. ESP Workload Manager sends the following messages at the following points:
• MESSAGE1, when ESP Workload Manager generates the Application and each time it submits a job in the Application.
• MESSAGE2, when ESP Workload Manager submits job A.• MESSAGE3, when ESP Workload Manager submits job B.
The Application looks like this:
APPL ABCJCLLIB . . .SEND 'MESSAGE1' U(*)JOB A SEND 'MESSAGE2' U(*) RUN DAILY RELEASE BENDJOBJOB B SEND 'MESSAGE3' U(*)
Chapter 6–Using Applications
ESP-5.4-UG-05 155
RUN DAILYENDJOB
Defining job requirements
Once you name a job, you can use different statements to define the job’s requirements. These requirements generally fall into the following three areas:
Specifying time dependencies
A job can have different types of time dependencies. These include the following:
• Delayed, or early, submission time• Late submission time• Due-out times for different stages in processing• Cut-off time for submission• Cut-off time for job dependencies• Cut-off time for resources• Minimum and maximum run times
You can refer to different times to compensate for varying conditions using CLANG.
To delay submission of a job:
• Use the EARLYSUB (early submit time) or DELAYSUB (delayed submit time) statements to mark a job for delayed submission relative to the scheduled time of the Event.
Both statements achieve the same results. Since you can specify any valid schedule criteria that resolves to a single date and time when the Application builds, you can use the EARLYSUB (or DELAYSUB) statement to allow an Application to span many days or weeks.
Dependency
SelectionTiming
Section–Specifying time dependencies
156 ESP-5.4-UG-05
Example: Identifying a delayed submission time
This example specifies that job J2 should not be submitted prior to 9 pm:
JOB J2DELAYSUB 9PM
Example: Using different submission times
This example uses CLANG to specify different DELAYSUB times for a job. The second DELAYSUB statement overrides the first on weekends only. The different times are:
• 9 pm on weekdays• 5 pm on weekends
JOB J2 RUN DAILY DELAYSUB 9PM IF TODAY('WEEKEND') THEN DELAYSUB 5PMENDJOB
To delay the release of a job using the RELDELAY statement:
• Use the RELDELAY statement to delay job submission at the time a job becomes eligible (for example, ready). This statement uses minutes as its unit of measure. You can delay submission up to 255 minutes.
Example: Delaying submission of a job from ready time
This example delays submission of job J2 by 5 minutes when it becomes ready for submission.
JOB J2 RELDELAY 5ENDJOB
Introducing anticipated end times
When ESP Workload Manager generates an Application, it calculates anticipated end times for all jobs in the Application. ESP Workload Manager adjusts anticipated end times automatically as the Application processes; for example, when a job is submitted or a job ends. You can review the Application, at any stage, and determine when any job is expected to finish. This information is displayed to you whenever you list the Application (for example LISTAPPL command).
Chapter 6–Using Applications
ESP-5.4-UG-05 157
Introducing dueout times
If a job is not complete by its anticipated end time, ESP Workload Manager continues to adjust this time. There is no indication that a job has missed its original anticipated end time. If you need to provide some awareness when jobs are late, you can identify any of the following:
• A late submission time• A late start time• A late end time
If the job has not completed the specified stage in processing by the due-out time, the status field shows OVERDUE in the Consolidated Status Facility (CSF) display of the job.
ESP Workload Manager can also send a message or trigger an Event when a job becomes overdue by using a NOTIFY statement. For more information, see “Providing notification on Job status” on page 206.
ESP Workload Manager also provides critical path analysis. For information on using critical path, see “Using critical-path analysis” on page 208.
Specifying due-out times
You can use any of the following statements to identify due-out times for a job:
Statement Explanation
LATESUB Specifies a late submission for a job. This identifies a time by which ESP Workload Manager should submit a job. The LATESUB time for a link, task, or data-set-trigger object represents the time by which all of its predecessor and time dependencies should be met (for example, the READY time).LATESUB does not force, or bypass, submission of the job. Use the ABANDON DEPENDENCIES statement to force submission of the job, regardless of dependencies; use the ABANDON SUBMISSION statement to bypass submission of the job.
DUEOUT INPUT Specifies a due-out time from the INPUT processing node. This refers to the start time.
DUEOUT EXEC Specifies a due-out time from the EXEC processing node. This refers to the successful end time. For a link, task, or data-set-trigger object, this represents the time by which it should complete.
Section–Specifying time dependencies
158 ESP-5.4-UG-05
Statements for different job types
The following table indicates the statements you can use for different job types. For more information on job types, see “Using different job types” on page 177.
Example: Specifying a late submission time for a job
In the following example, job X has a late submission time of 9 pm.
JOB X LATESUB 9PM RUN DAILYENDJOB
Example: Specifying a due-out time for a job
This example specifies that job Z is due out of the execution queue by 3 am.
JOB Z DUEOUT EXEC 3AM RUN DAILYENDJOB
Example: Specifying a due-out time for a task.
This example specifies that the task called WAIT4.TAPE should be marked complete no later than two hours after the trigger time of the corresponding Event.
JOB WAIT4.TAPE TASK DUEOUT EXEC REALNOW PLUS 2 HOURS RUN DAILYENDJOB
Propagating dueout times
ESP Workload Manager propagates dueout times, up-stream, to all predecessors of a selected job where you specified a LATESUB or DUEOUT statement. This reduces the need for you to code a lot of LATESUB or DUEOUT statements in an Application. ESP Workload Manager sets these dueout times based on historical average elapsed times.
When ESP Workload Manager propagates a time to a predecessor, it sets the DUEOUT EXEC time and adjusts this time if it is already specified. ESP Workload
Job Type LATESUB DUEOUT INPUT DUEOUT EXEC
Job X X X
External job X X X
Manual job X X X
Link X X
Task X X
Data set Trigger Object X X
Chapter 6–Using Applications
ESP-5.4-UG-05 159
Manager provides notification when this time is not met, just as it does when you specifically code a DUEOUT time. If you need to reset the time, you can use CSF or the APPLJOB command.
Note: Your administrator can have turned this propagation feature off.
Example: Propagating dueout times
In the following example, PAYJOB6 should be submitted by 7 am.
By specifying a LATESUB time for PAYJOB6, ESP Workload Manager automatically sets dueout execution times for all predecessors to this job. If any job in the PAYROLL Application is late, ESP Workload Manager highlights it on CSF. Further notification can take place using the NOTIFY statement.
A sample Application follows:
APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RELEASE PAYJOB2ENDJOBJOB PAYJOB2 RELEASE (PAYJOB3,PAYJOB4,PAYJOB5)ENDJOBJOB PAYJOB3 RELEASE PAYJOB6ENDJOBJOB PAYJOB4 RELEASE PAYJOB6ENDJOBJOB PAYJOB5 RELEASE PAYJOB6ENDJOB
PAYJOB1
PAYJOB6
PAYJOB5PAYJOB4PAYJOB3
PAYJOB2
Section–Specifying time dependencies
160 ESP-5.4-UG-05
JOB PAYJOB6 LATESUB 7AMENDJOBSELECT (PAYJOB1,PAYJOB2,PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)
Bypassing job dependencies
Use the ABANDON DEPENDENCIES job statement to drop a job’s predecessor dependencies once it meets a specified time. This does not override a manual hold, a time dependency, or a resource dependency for a job.
An example of this statement is:
ABANDON DEPENDENCIES 10PM
Bypassing jobs
Use the ABANDON SUBMISSION job statement to bypass a job after a specified time.
An example of this statement is:
ABANDON SUBMISSION 11PM
Example: Bypassing jobs and dependencies
The following example submits job J2 when job J1 completes successfully, or at 10 pm, whichever comes first. When J2 completes successfully, ESP Workload Manager checks that the time is before 11 pm. If it is, ESP Workload Manager submits job J3; otherwise, it bypasses J3 and submits job J4.
APPL APPL3JCLLIB...JOB J1 RUN DAILY RELEASE J2ENDJOBJOB J2 RUN DAILY ABANDON DEPENDENCIES 10PM RELEASE J3ENDJOBJOB J3 RUN DAILY ABANDON SUBMISSION 11PM RELEASE J4ENDJOBJOB J4 RUN DAILYENDJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 161
Example: Bypassing a job and wait for predecessor
Jobs A, B, and C are three sequential, daily jobs. Job B has a submission time of 9 am if job B is not submitted within an hour (10 am). Then job B should not run but job C should wait for job A to complete.
The following part of an Application identifies a delayed submission time of 9 am and an abandon submission time of 10 am for job B. Job B’s execution is abandoned if it is not submitted by 10 am. Job B is not actually bypassed until job A completes successfully, and job C waits until this happens.
JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AMENDJOBJOB C RUN DAILYENDJOB
Example: Bypassing a job without waiting for predecessor
Jobs A, B, and C are three sequential, daily jobs. Job B has a submission time of 9 am if job B has not been submitted within an hour (10 am), job C should start (even if job A is running), and job B should not run.
The following part of an Application identifies a delayed submission time of 9 am and an abandon submission time of 10AM for job B. Job B waits for job A to complete successfully prior to being bypassed. When you code an abandon dependencies time of just after 10 am, job B does not wait for job A to complete before it is bypassed and job C starts.
JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AM ABANDON DEPENDENCIES 10:01AMENDJOBJOB C RUN DAILYENDJOB
Section–Specifying time dependencies
162 ESP-5.4-UG-05
Removing resource dependencies
Use the ABANDON RESOURCES job statement to submit a job without its resource dependencies, once it meets a specified time. An example of this statement is:
ABANDON RESOURCES 8AM
This example indicates ESP Workload Manager should not wait for resources for the job after 6 pm.
JOB PREPJOB RESOURCE (1,NITESHFT) ABANDON RESOURCES 6PMENDJOB
Specifying minimum or maximum run times
You can use the MINRUNTIME and MAXRUNTIME built-in symbolic variables to specify a minimum or maximum run time for a workload object. MINRUNTIME and MAXRUNTIME are integer variables representing an elapsed run time in minutes. You can set a run time to a fixed value or code a calculation to determine the value.
If you want to include the average run time of prior runs in your calculation, you can use the AVGRUNTIME built-in symbolic variable. The value of this integer variable is derived from the most recent elapsed times, which are stored in the Jobindex data set. The number of sample times used in the average depends on the number of index entries kept, as defined in the job tracking model. The average includes only successful runs; unsuccessful runs are ignored. The average is rounded to the nearest minute.
MINRUNTIME, MAXRUNTIME, and AVGRUNTIME are available at Application processing time only, not at generation time.
If a value is specified for MAXRUNTIME, this value is added to the start time for the run to obtain an expected end time. This time is then used as the DUEOUT EXEC time for the run, unless there is an existing DUEOUT EXEC for an earlier time, in which case the earlier DUEOUT EXEC time takes precedence. If the DUEOUT time calculated from the MAXRUNTIME value is exceeded, normal notification and alerting processes are activated.
If a value is specified for MINRUNTIME, this value is added to the start time for the run to obtain an expected earliest end time. When the run terminates, the actual end time is compared to this anticipated time. If the actual end time is earlier than the anticipated time, the run is considered to have ended prematurely. When this occurs, standard notification and alerting processes are invoked if you have coded a NOTIFY statement with the PREMEND (Premature end) operand.
Example: Specifying application level minimum and maximum run times, with
Chapter 6–Using Applications
ESP-5.4-UG-05 163
global notification
APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'
IF %ESP_APPL_PROC THEN DOMINRUNTIME = AVGRUNTIME * 25 / 100MAXRUNTIME = AVGRUNTIME * 175 / 100ENDDO
NOTIFY OVERDUE USER(CYBER02)NOTIFY PREMEND USER(CYBER02)
JOB PAY1 RUN NOWENDJOB
JOB PAY2 RUN NOWENDJOB
In the preceding example, Application PAYROLL has two jobs, PAY1 and PAY2. The minimum run time for each job is set to 25% of its current average runtime; the maximum run time for each job is set to 175% of its current average run time. If either job runs over the maximum time or ends before having run for the specified minimum time, a notification message is sent to user CYBER02.
Example: CSF
In the following CSF display, job WAIT5, AGen 47 ended before the minimum time and job WAIT3, AGen 47 exceeded its maximum run time:
TT54 Consolidated Status: View 1 ------------ Row 1 of 6, Col 1COMMAND ===> SCR ===> CSR
Job Name Appl AGen Jobno MinRT MaxRT AvgRT Status___ WAIT3#5S TSTRFES 31 31755 7 12 16 FAILED, S222 AT 13.19 23 D___ WAIT5 TSTRFES 31 31754 7 12 5 COMPLETED AT 13.14 23 DEC___ WAIT3#5S TSTRFES 34 34969 - - 16 FAILED, S222 AT 08.47 24 D___ WAIT5 TSTRFES 34 34968 - - 5 FAILED, S222 AT 08.47 24 D___ WAIT3#5S TSTRFES 47 12220 7 12 16 EXECUTING STEP4 OVERDUE___ WAIT5 TSTRFES 47 12218 7 12 5 COMPLETED AT 14.06 09 JAN
Here are the notification messages corresponding to the preceding CSF display:
TT54_1194I Job WAIT5(JOB12218) ENDED PREMATURELY, CMPC=0 AT 14.06.02 ON 09 JAN2004, APPL TSTRFES.47
TT54_1022W JOB WAIT3#5S IN APPL TSTRFES.47, LATE END TIME EXCEEDED***
Section–Specifying time dependencies
164 ESP-5.4-UG-05
Issuing the LJE command on job WAIT5, AGen 47 in the preceding CSF screen provides the following output. Note that the minimum, maximum, and average run times are displayed:
ESP ----------------------------------------------- Row 1 of 16, Col 1 -COMMAND ===>---------------------------------- TOP OF DATA---------------------------------AJ WAIT5(12218) APPL(TSTRFES.47)Job=WAIT5(12218), Completed->CC 0 Submitted ................ 2004/01/09 14:00 Started .................. 2004/01/09 14:00 Completed ................ 2004/01/09 14:06 MinimumRunTime=7, MaximumRunTime=12, AverageRunTime=5 Class=A, Priority=7, Step=STEP1, SrvClass=JES, SysName=SYSA, Sysplex=SYSAPLEX, Asid=0082, SmfId=SYSA, JesNode=CYBJES, EspProc=CYBTT01.TEST.ESPPROC(TSTRFES)
Appl=TSTRFES.47, Completed Scheduled ................ 2004/01/09 14:00 Built .................... 2004/01/09 14:00 Completed ................ 2004/01/09 14:17 DueOutPropagation, Event=CYBTT04.TSTRFES, TrigUser=CYBTT04
Example: History Report with sample output
The following history report includes “Min Run”, “Max Run”, and “Avg Run” columns:
REPORTINPUT DATASET('CYB1.TONYT540.HISTFILE')CRITERIA JOBNAME EQ WAIT- OR JOBNAME EQ CALCFROM DEC 1 2003DISPLAY JOBNAME,JOBNO,APPLSYS,MINRUNT,MAXRUNT,AVGRUNT,EXECQT,OVDEND,EXECSDATE 12,EXECST 10SORT EXECSDATE EXECST JOBNAME EXECQTENDRCYBERMATION ESP VER 5.4.0 BATCH INTERFACE 10.47.35 FRIDAY JANUARY 9TH,
JOBNAME JOB APPLSYS Min Max Avg EXEC OVERDUE START EXEC NO Run Run Run QTIME END DATE STARTWAIT3 42148 - - - 3M01 - THU 4DEC03 14.41.38WAIT5 42299 - - - 4M59 - THU 4DEC03 17.16.56WAIT5 42305 - - - 5M00 - THU 4DEC03 17.26.23WAIT5 42326 - - - 4M59 - THU 4DEC03 17.33.01WAIT5 42370 - - - 5M01 - THU 4DEC03 17.35.18WAIT5 54085 TSTRFES 7M00 12M00 5M00 5M09 0 TUE 9DEC03 08.17.13WAIT3#5S 54086 TSTRFES 7M00 12M00 16M00 16M10 4M12 TUE 9DEC03 08.17.23WAIT5 54541 TSTRFES 7M00 12M00 5M00 5M01 0 TUE 9DEC03 08.45.55WAIT3#5S 54542 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 08.45.56WAIT5 54615 TSTRFES 7M00 12M00 5M00 5M00 0 TUE 9DEC03 09.21.50WAIT3#5S 54616 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 09.21.51WAIT3 55327 - - - 3M00 - TUE 9DEC03 15.04.20WAIT3#5S 55329 - - - 16M01 - TUE 9DEC03 15.04.28
Chapter 6–Using Applications
ESP-5.4-UG-05 165
Specifying job relationships
To specify predecessor and successor job relationships:
Include the appropriate job-dependency statements.
A list of job-dependency statements appears below:
Specifying multiple jobs
If you need to specify more than one job name, enclose the job names in parentheses. For example:
RELEASE (PAYJOB2,PAYJOB3,PAYJOB4)
If you need to continue to another line, use either a + or a - as a line continuation character. For example:
RELEASE (PAYJOB2,PAYJOB3,PAYJOB4,-PAYJOB5,PAYJOB6)
Job-Dependency Statement
Explanation
AFTER Specifies any job that is a predecessor to this job and indicates a release to this job upon its completion. (The default is successful completion.)
RELEASE Specifies successors to a job that are released upon its completion. (The default is successful completion.)
PREREQ Specifies the names of any other jobs that must be complete before this job can be allowed to execute. These are prerequisite jobs. ESP Workload Manager automatically selects the prerequisite jobs for submission whenever this job is selected for processing.
COREQ Specifies the names of any other jobs which must be selected automatically whenever this job is selected for processing. The named job and all of its co-requisites are allowed to execute simultaneously; there is no relationship between a job and its co-requisites.
POSTREQ Specifies the names of any other jobs which must run after this job has executed. These are post-requisite jobs. ESP Workload Manager automatically selects the post-requisite jobs for submission whenever this job is selected for processing.
Section–Using Implicit Resources
166 ESP-5.4-UG-05
Two methods of coding a job-dependency relationship
The following are two ways of coding a job-dependency relationship. With either method, there is no difference in the way ESP Workload Manager generates or processes the Application.
Using Implicit Resources
ESP Workload Manager can specify mutually exclusive run requirements through Application and job-level statements. These statements provide an alternative to defining ESP Workload Manager resources explicitly and the corresponding coding of ESP Workload Manager resource statements to handle mutually exclusive run requirements.
ESP ENQUEUE provides the capability for a job to request exclusive or shared use of a resource without the need to define the resource explicitly in advance. ESP Workload Manager will prevent jobs with mutually exclusive requests from executing concurrently. ESP ENQUEUE behaves like the z/OS enqueues.
The NOTWITH feature uses ESP ENQUEUE to request that certain explicitly specified jobs not execute concurrently.
Consider the following guidelines before using the ENQUEUE and NOTWITH statements:
• Use ENQUEUE when you know which resource the jobs require.
• Use NOTWITH when you know that jobs cannot run together, but you do not know why.
Note: The NOTWITH and ENQUEUE statements use resources. Therefore, a resource file (RESFILE) and the topology must be defined before you can use them.
There are four statements with the ESP ENQUEUE and NOTWITH features. All four statements are valid within and outside the scope of a job definition. When coded within a job definition, they affect that job only. When coded outside the scope of a job definition, they affect the building of a default list that applies to all subsequent jobs.
Note: The statements described in this section use resources implicitly. Therefore, a resource file (RESFILE) and the network topology must be defined before you can use these statements.
Method Code
1 JOB ARELEASE B
2 JOB BAFTER A
Chapter 6–Using Applications
ESP-5.4-UG-05 167
ENQUEUE
To specify mutually exclusive jobs (A and B) with the ENQUEUE statement:
1. Insert an ENQUEUE statement in the job workload object (job A).
2. Specify in that statement the name of a resource.
3. Specify the EXCLUSIVE operand.
4. Insert an ENQUEUE statement in the job workload object (job B).
5. Specify in that statement the name of the same resource as for job A.
6. You can specify either the SHARED (default) or the EXCLUSIVE operand.
Note: You can insert the ENQUEUE statement in an Application, outside a job workload object. In that case the statement applies to every job following it in the Application.
Examples
The following example shows job NWN001 specifying an enqueue on a resource named FRED:
APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY ENQUEUE NAME(FRED) SHAREDENDJOB
JOB NWN002 RUN DAILYENDJOB
The following example shows job NWN001 and job NWN002 specifying an enqueue on a resource named FRED. Because the operand EXCLUSIVE is specified in job NWN002, jobs NWN001 and NWN002 cannot run at the same time:
APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY ENQUEUE NAME(FRED) SHAREDENDJOB
JOB NWN002 RUN DAILY ENQUEUE NAME(FRED) EXCLUSIVEENDJOB
Section–Using Implicit Resources
168 ESP-5.4-UG-05
The following example shows job NWN001, job NWN002, and job NWN003 specifying an enqueue on a resource named FRED. Because the operand EXCLUSIVE is specified in job NWN002, job NWN002 cannot run at the same time as the other two jobs. Jobs NWN001 and NWN003 can run at the same time:
APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY ENQUEUE NAME(FRED) SHAREDENDJOB
JOB NWN002 RUN DAILY ENQUEUE NAME(FRED) EXCLUSIVEENDJOB
JOB NWN003 RUN DAILY ENQUEUE NAME(FRED) SHAREDENDJOB
To remove mutual exclusivity:
• Replace the ENQUEUE statement changing the status from EXCLUSIVE to SHARED, or
• Remove all ENQUEUE statements corresponding to a resource name.
To exclude jobs from an ENQUEUE statement at the Application level:
• Insert a DEQUEUE statement with a resource name matching exactly the resource name specified in the ENQUEUE statement.
You can insert the DEQUEUE statement in an Application, outside a job workload object. In that case, every job following it in the Application will be excluded from the ENQUEUE statement. To exclude only a specific job, you must place the DEQUEUE statement in the scope of that job.
Usage notes
The following example shows job NWN002 excluded from a specified enqueue of the resource named FRED.
APPL NWN00BJCLLIB 'CYBER.JCL.CNTL'ENQUEUE NAME(FRED) SHAREDJOB NWN001 RUN DAILYENDJOB
JOB NWN002
Chapter 6–Using Applications
ESP-5.4-UG-05 169
RUN DAILY DEQUEUE NAME(FRED)ENDJOB
JOB NWN003 RUN DAILYENDJOB
JOB NWN004 RUN DAILYENDJOB
Displaying the enqueue status
To display the enqueue status in the resource file:
• Issue the ENQUEUE command specifying the resource that you want to display.
The ENQUEUE command requires OPER authority.
Example
For each enqueue that matches nnn, ESP Workload Manager will produce a list of all outstanding requests showing the requesting job, the type of the request (exclusive or shared) and whether the enqueue is held by the job. Some jobs can be shown with requests generated by the ESP Resource Manager. This happens when a job has a generic request (one with wildcards) that matches a non-generic request by another job. Such a match will result in the generic enqueue being accompanied with a normal enqueue that the generic request implies.
Considering the following Application:
APPL NWN00GJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY ENQUEUE NAME(B-C) SHAREDENDJOB
JOB NWN002 RUN DAILY ENQUEUE NAME(BBC) EXCLUSIVEENDJOB
The ENQUEUE B- command produces the following:
BBC
(Gen) Held Shr NWN001, Appl NWN00G.1 Required Excl NWN002, Appl NWN00G.1
Section–Using Implicit Resources
170 ESP-5.4-UG-05
B-C Held Shr NWN001, Appl NWN00G.1
The display shows job NWN002 waiting behind a satisfied request of NWN001. That request was generated by the ESP Resource Manager to reflect the match between NWN001’s enqueue on B-C and NWN002’s enqueue on BBC. Generated requests are shown with (Gen).
Manipulating the enqueue list in a generated Application
To manipulate the enqueue list of a specified job in a generated Application:
• Issue JOBENQ commands in page mode specifying the job and using the appropriate operands.
The JOBENQ command is a page mode command that does not require OPER authority.
Note: You can also use the ME command in CSF.
Example
Considering the following Application:
APPL NWN00GJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY ENQUEUE NAME(B-C) SHAREDENDJOB
JOB NWN002 RUN DAILY ENQUEUE NAME(BBC) EXCLUSIVEENDJOB
The ENQUEUE B- command produces the following:
BBC (Gen) Held Shr NWN001, Appl NWN00G.1 Required Excl NWN002, Appl NWN00G.1
B-C Held Shr NWN001, Appl NWN00G.1
The display shows job NWN002 waiting behind a satisfied request of NWN001.
To release job NWN002, you can issue the following command:
JOBENQ JOB(NWN002) APPL(NWN00G) DEQUEUE BBC
Chapter 6–Using Applications
ESP-5.4-UG-05 171
ENQSELF
Before coding mutual exclusive run requirements with NOTWITH statements, you must know the ENQSELF status because ESP Workload Manager behaves differently depending on that status being ALWAYS or NOTALWAYS.
The ENQSELF command provides the option of specifying whether or not every job will have an enqueue on itself.
ENQSELF can be coded as an initialization parameter.
To display the status of ENQSELF:
• Issue the ENQSELF command without any operand.
Note: The ENQSELF command requires OPER authority.
To modify the status of ENQSELF:
• Issue the ENQSELF command with the operand corresponding to the desired status.
Note: The ENQSELF command requires OPER authority.
Example
The following is the response from issuing the ENQSELF ALWAYS command in ESP Workload Manager page mode:
OPER ENQSELF ALWAYSESP1573I ENQSELF MODE IS ALWAYS
NOTWITH
The NOTWITH statement provides a way to prevent mutually incompatible jobs to run at the same time as nothing other than the name of the other job is required.
A choice between the two following methods must be made:
• Set ENQSELF to ALWAYS. In this case every job will enqueue over itself and you will not need a matching NOTWITH statement in the other job, or
• Leave ENQSELF to NOTALWAYS. In this case you will need a matching NOTWITH statement in the other job.
The disadvantage of setting ENQSELF to ALWAYS is the overhead due to the automatic enqueuing of every job.
An alternative is the use of the ENQUEUE statement. See “ENQUEUE” on page 167.
For details about ENQSELF, see “ENQSELF” on page 171.
Section–Using Implicit Resources
172 ESP-5.4-UG-05
To specify mutually exclusive jobs (A and B) with the NOTWITH statement:
1. Insert a NOTWITH statement in the job workload object (job A).
2. Specify the name of the job (job B) that you want to prevent running concurrently with job A.
3. If the ENQSELF status is NOTALWAYS, insert an equivalent NOTWITH statement in the workload object of job B. The statement must specify job A.
Note: You can insert the NOTWITH statement in an Application, outside a job workload object. In that case the statement applies to every job following the statement in the Application.
Automatic generation of ENQUEUE commands by the NOTWITH statement
The NOTWITH statement is used to inform ESP Workload Manager the job currently being defined is mutually exclusive with job1.qual1 in appl1 (or with a list of such jobs).
NOTWITH uses ESP ENQUEUEs for each specified job. NOTWITH will build a shared enqueue request in the following form:
ESPENQ_JOB(job1.qual1)_APPL(appl.-)
The NOTWITH statement will set a flag informing ESP Workload Manager to generate an enqueue itself (the job that has the NOTWITH statement). For example:
APPL TESTJOB MYJOB NOTWITH BILLSJOB.-; RUN DAILYENDJOB
The above Application results in the JOB MYJOB having the two following enqueues:
ESPENQ_JOB(MYJOB.)_APPL(TEST.21)ExclusiveESPENQ_JOB(BILLSJOB.-)_APPL(-.-)Shared
If job BILLSJOB.qual has a NOTWITH statement or ENQSELF is set to ALWAYS, BILLSJOB.qual in BILLSAPPL.10 enqueues on itself and it will have at least the following enqueue:
ESPENQ_JOB(BILLSJOB.qual)_APPL(BILLSAPPL.10)Exclusive
This enqueue, together with the job MYJOB shared enqueue, prevents the two jobs from running together.
Chapter 6–Using Applications
ESP-5.4-UG-05 173
Examples of ESP ENQUEUES with NOTWITH
APPL NWN00CJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002 RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYS NOTWITH NWN001ENDJOB
The above ESP Application produced the following display from the ENQUEUE command. The ENQUEUE command displays the current enqueue status in the resource file. For more information, see the ENQUEUE command in ESP Workload Manager Reference Guide.
ESPENQ_JOB(NWN001.)_APPL(-.-) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN001.)_APPL(NWN00C.1) Held Excl NWN001, Appl NWN00C.1 (Gen) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN003.)_APPL(NWN00C.1) (Gen) Held Shr NWN001, Appl NWN00C.1 Required Excl NWN003, Appl NWN00C.1
In the display above, job NWN001 has an exclusive enqueue on itself and has a shared enqueue on job NWN003. Job NWN003 requests an exclusive enqueue on itself and a shared enqueue on job NWN001. This prevents the jobs from running together.
In the following example, job NWN003 has no NOTWITH statement so it will execute at the same time as job NWN001. Job NWN003 must have a NOTWITH NWN001 statement to be mutually exclusive with job NWN001.
APPL NWN00DJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002 RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYSENDJOB
You can use unmatched NOTWITH statements in combination with the ENQSELF command. For more information, see “ENQSELF” on page 171.
Section–Using Implicit Resources
174 ESP-5.4-UG-05
To remove mutual exclusivity:
• Remove the NOTWITH statements for all the jobs that are no longer mutually exclusive.
To exclude jobs from an NOTWITH statement at the Application level:
• Insert a DROPNOTW statement matching, character for character, the NOTWITH statement that created the mutual exclusivity.
You can insert the DROPNOTW statement in an Application, outside a job workload object. In that case the statement applies to every job following it in the Application.
Example
When you specify the NOTWITH statement outside the scope of a job, there can be one job in the Application that can run concurrently with the other jobs. You can use the DROPNOTW statement in the scope of the job that can run concurrently to allow it to run.
APPL NWN00EJCLLIB 'CYBER.JCL.CNTL'
JOB NWN001 RUN DAILY NOTWITH (NWN002,NWN003)ENDJOB
NOTWITH NWN001
JOB NWN002 RUN DAILYENDJOB
JOB NWN003 RUN DAILYENDJOB
JOB NWN004 RUN DAILY DROPNOTW NWN001ENDJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 175
Selecting jobs for submission
To select a job for submission:
Do one of the following:
• Specify the name of the job in a SELECT statement.• Specify a RUN statement for the job to identify its schedule frequency.• Name the job in a POSTREQ, PREREQ or COREQ statement.
You can choose to use different methods to select jobs as part of the same Application. This Guide contains more information on the schedule frequencies you can use.
Example: Method 1
The following example shows two ways of selecting jobs for submission.The first method uses a RUN statement for each job. ESP Workload Manager selects job A each time the Procedure is invoked; ESP Workload Manager selects job B if the scheduled day is Friday.
JOB A RUN DAILY RELEASE BENDJOBJOB B RUN FRIDAYENDJOB
Example: Method 2
This method uses SELECT statements after identifying specific job requirements. ESP Workload Manager selects job A each time the Procedure is invoked; ESP Workload Manager selects job B if the scheduled day is Friday.
JOB A RELEASE BENDJOBJOB BENDJOBSELECT AIF TODAY('FRIDAY') THEN SELECT B
Submit time
If a job has a time dependency for submission, you must use either an EARLYSUB or a DELAYSUB statement. The statement RUN 5PM DAILY is not valid.
Section–Selecting jobs for submission
176 ESP-5.4-UG-05
Using SELECT vs. RUN statements
Some users prefer to use RUN statements; other users prefer SELECT statements. The following are some reasons for choosing either method:
• RUN statements are used within the scope of a JOB statement. You can look at a job definition and see the schedule frequency for the job. Many criteria can be handled with RUN statements without the need for using IF TODAY type logic.
• SELECT statements allow you to easily see all the jobs with the same criteria. Changing the criteria for these jobs requires a change to a single SELECT statement. You can also select a subApplication.
To deselect jobs:
• Use the NORUN and DESELECT statements to handle exceptions to a job’s regular schedule criteria.
These statements tell ESP Workload Manager when not to select a job.
ESP Workload Manager allows multiple RUN and NORUN statements for the same job. You should normally code your NORUN statements after your RUN statements. If you specify a job with a NORUN statement and without a RUN statement, ESP Workload Manager schedules the job each time the Event executes except when it manages to satisfy the NORUN schedule criteria.
Example 1
In the following example, job X runs daily except on the first Monday of the month.
JOB X RUN DAILY NORUN FIRST MONDAY OF MONTHENDJOB
Example 2
This example uses a DESELECT statement to achieve the same results.
SELECT XIF TODAY('FIRST MONDAY OF MONTH') THEN DESELECT X
Inheriting job relationships
Jobs in an Application can not require the same run frequency. When ESP Workload Manager selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited.
Chapter 6–Using Applications
ESP-5.4-UG-05 177
Example
Consider the following three jobs and their schedule frequencies.
On Fridays all three jobs execute in order, but on any other day of the week, job J2 does not run. On these days, ESP Workload Manager selects jobs J1 and J3 and inherits their relationships with job J2. When job J1 completes successfully, it releases job J3.
Additional information
For information on overriding the inheritance of job relationships, see the ESP Workload Manager Advanced User’s Guide.
Using different job types
An Application can consist of different types of jobs. You can define the following job types in an Application by using different operands on a JOB statement or different job-like statements.
J2
J3
J1 Daily
Friday
Daily
Type Description Identification
Job JCL submitted by ESP Workload Manager (default).
Blank
External job JCL submitted by another Application. EXTERNAL operand
Manual job JCL submitted outside an ESP Application. MANUAL operand
Link Task that does not require manual completion.
LINK operand
Section–Defining external jobs
178 ESP-5.4-UG-05
The next few sections describe the job types other than job. You can also define distributed workload, such as UNIX scripts, in your ESP Application. For information on defining this type of workload, see the JOB statement in ESP Workload Manager Reference Guide.
Defining external jobs
To identify to ESP Workload Manager that the job is part of another Application:
Use the EXTERNAL operand as part of a JOB statement.
You can establish relationships between jobs in different Applications. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied.
The Application that submits the job is known as the home Application. The Application where the job is defined as external is known as the distant Application.
When you define an external job:
• You can use different frequencies in the home and distant Application.• You must use the same qualifier in each Application.• You can use the LAX command in Page mode to display external jobs in active
Applications.
Example: Inter-Application dependency
In this example, ESP Workload Manager submits job X on Fridays, as part of Application APPL1. Job Z in the Application APPL2 waits for job X. The home Application for job X is APPL1; the distant Application for job X is APPL2.
Task Task that requires manual completion. TASK operand
Data-set trigger object
Object that completes based on data set trigger activity.
DSTRIG statement
APPLEND Self completing task that runs automatically at the end of an Application.
APPLEND statement
Type Description Identification
Chapter 6–Using Applications
ESP-5.4-UG-05 179
Visually, the dependencies look like this:
The Application definition for APPL1 looks like this:
APPL APPL1JCLLIB....JOB A RUN DAILY RELEASE XENDJOBJOB X RUN FRIDAYENDJOB
The Application definition for APPL2 looks like this:
APPL APPL2JCLLIB....JOB X EXTERNAL RUN FRIDAY RELEASE ZENDJOBJOB Z RUN DAILYENDJOB
When ESP Workload Manager generates APPL2 on Fridays, job Z waits until job X completes in its home Application, APPL1.
Controlling external jobs
Under different situations, ESP Workload Manager must decide whether or not it should mark an EXTERNAL job complete. The following are some general rules ESP Workload Manager uses:
• If more than one generation of an Application is active when an external job ends, ESP Workload Manager posts the job as complete in all active and waiting Applications by default. See the APPL statement in the ESP Workload Manager Reference Guide for overriding that default.
• A job defined as EXTERNAL in an Application is normally not marked complete by ESP Workload Manager if the job is run manually.
APPL1 APPL2
X(External job)
Z(job)
X(job)
A(job)
Section–Defining external jobs
180 ESP-5.4-UG-05
Some of the ways you can control how to post external jobs complete are described below.
Specifying an Application
When you define an external job, you can use the APPLID operand to specify the name of the Application that submits the job. ESP Workload Manager does not mark the external job complete unless it was submitted by the Application specified. For example, ESP Workload Manager only marks the following job as complete when the job is submitted from the Application called ANOTHER.
JOB ABC EXTERNAL APPLID(ANOTHER)
SCHEDULED operand
You can specify a SCHEDULED operand on a JOB statement to reflect when an external job is scheduled. The Application containing the external does not have to be active when the job in the home Application ends. ESP Workload Manager automatically looks back or waits to see if the dependency has been satisfied.
The job in the example below only gets marked complete when run from another Application with the same scheduled date. This provides synchronization of Applications. See the ESP Workload Manager Advanced User’s Guide for more information.
JOB ABC EXTERNAL SCHEDULED('TODAY')
The following example shows specifying a range:
JOB ABX EXTERNAL SCHEDULED ('NOW LESS 2 HOURS ENDING NOW PLUS 2 HOURS')
SCOPE operand
You can specify a SCOPE operand on a JOB statement to control how far back ESP Workload Manager searches the Job Index data set and to limit the forward search for a job in the SADGEN data set (as a result of a RESOLVE statement in an ESP Workload Manager Procedure). See the ESP Workload Manager Advanced User’s Guide for more information.
When you select an external job, the SCOPE operand instructs ESP Workload Manager to look back in the Job Index data for the required external job with a status of COMPLETED. ESP Workload Manager does not use a look forward time unless you use a RESOLVE statement. If the job is not found, ESP Workload Manager waits for the dependency to be satisfied.
In this example, ESP Workload Manager runs job ABC on Sundays and looks back 24 hours to Saturday for its successful completion.
job abc external scope(-24:00) run sundayENDJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 181
Job qualifiers
For ESP Workload Manager to mark an external job complete, the job qualifier must match what was defined in the home Application. You can use job qualifiers to ensure that an external job does not get marked complete when it is run manually. You can qualify external jobs with the home Application name. For example:
JOB ABC.BILLING EXTERNAL
Authorization string
You can specify that ESP Workload Manager checks an authorization string for external jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a user ID or an account field. For example, ESP Workload Manager only marks the following job as complete when the job is run with an authorization string of CYBER.
JOB ABC EXTERNAL AUTHSTR(CYBER)
Posting options
Different posting options are available on the APPL statement. For example, you can select different options to control the posting of external jobs when multiple generations of an Application are active. See the ESP Workload Manager Advanced User’s Guide for more information.
Forced complete
When an external job is forced complete in a distant Application, it has no effect on the status of the same job in any other distant Application, or in the job’s home Application.
When an external job is forced complete in its home Application, this change will be transmitted to every existent Application in which the job is defined as external.
USERMOD 30
Prior to release 5.1.0, if a job defined as EXTERNAL in an Application is forced complete in the home Application, the job in the remote Application (where it is EXTERNAL) is marked complete only if the job in the home Application has actually been submitted. With release 5.1.0, 5.2.0, 5.3.0, and 5.4.0 the remote Application job is now marked complete even if the home Application job was forced complete prior to submission. This USERMOD disables this new functionality for those users who rely on the previous behavior.
Section–Defining manual jobs
182 ESP-5.4-UG-05
Defining manual jobs
To identify to ESP Workload Manager that a job is submitted outside of an ESP Application:
• Use the MANUAL operand as part of a JOB statement.
As a result, ESP Workload Manager does not look for JCL, nor does it try to submit the job. The job can be submitted by a person, an operator command, an Event, or another scheduling product.
You can use manual jobs as predecessor or successor jobs within an Application. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied.
Note: When defining a MANUAL job in an Application, keep the following in mind:
• You must define a manual job as a tracked job if you want to use it in an Application. Check with your administrator to find out about tracked jobs.
• You cannot use a job qualifier for a manual job.
Example 1
In the example below, job ZZ runs after the manually submitted job YY on Mondays, Wednesdays, and Fridays. On other days job ZZ does not wait for job YY.
JCLLIB...APPL SMALLJOB ZZ AFTER YY RUN DAILYENDJOBJOB YY MANUAL RUN MON WED FRIENDJOB
Example 2
In this example, job B is a manual job that should not complete until job A runs successfully. After job A is submitted, ESP Workload Manager has no control over the submission time for job B, because job B is a manual job. However, ESP Workload Manager can remind someone to submit the job at the time it should be submitted.
Chapter 6–Using Applications
ESP-5.4-UG-05 183
Visually, the flow of jobs looks like this:
The Application is shown below. The PROCESS operand on the manual job causes ESP Workload Manager to process the SEND command when job B is eligible for submission.
JCLLIB...APPL ABCJOB A RELEASE B RUN DAILYENDJOBJOB B MANUAL PROCESS SEND 'TIME TO SUBMIT JOB B' USER(SW) RUN DAILY RELEASE CENDJOBJOB C RUN DAILYENDJOB
Controlling manual jobs
Under different situations, ESP Workload Manager must decide whether or not it should mark a MANUAL job complete. The following are some general rules ESP Workload Manager uses:
• If more than one generation of an Application is active when an manual job ends, ESP Workload Manager posts the job as complete in all active and waiting Applications by default. See the APPL statement in the ESP Workload Manager Reference Guide for overriding that default.
• A job defined as MANUAL in an Application is normally not marked complete if the job is run as part of another Application.
Some of the ways you can control the posting complete of manual jobs are described below.
A
B
C
MANUALLYSUBMITTED
Section–Using links
184 ESP-5.4-UG-05
Authorization string
You can specify that ESP Workload Manager checks an authorization string for manual jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a user ID or an account field. For example, ESP Workload Manager only marks the following job as complete when the job is run with an authorization string of CYBER.
JOB ABC MANUAL AUTHSTR(CYBER)
Posting options
Different posting options are available on the APPL statement. For example, you can select different options to control the posting of manual jobs when multiple generations of an Application are active. See the ESP Workload Manager Advanced User’s Guide for more information.
Forced complete
When a manual job is forced complete in one Application, it has no effect on manual jobs in other Applications that just happen to refer to the same physical job instance.
If you want to modify the status of a specific manually submitted job in multiple Applications that define this job as manual, the modification will have to be performed explicitly in each of the dependent Applications.
Using links
A link is a task that does not require manual completion. Use a link when you need to take an action (for example, issuing a command or sending a message), but the Application does not need to wait for you to notify ESP Workload Manager that the action has been completed. A link can also be used as a dependency node to simplify complex dependencies.
LINK operand
The LINK operand on the JOB statement identifies a link. ESP Workload Manager does not try to submit JCL for it. You define relationships and other dependencies for a link the same way you do for a job that ESP Workload Manager would submit. A link usually has a schedule frequency, and it can have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application. If you want to use a link to process commands, you must specify LINK PROCESS, as shown in the next example.
Chapter 6–Using Applications
ESP-5.4-UG-05 185
Example
In the following example, a link is used to send a message to user BP01 after MYJOB1 and MYJOB2 complete successfully.
JOB LETME.KNOW LINK PROCESS AFTER (MYJOB1,MYJOB2) RUN DAILY SEND 'MYJOBS ARE DONE' USER(BP01)ENDJOB
Link vs. task
A link is the same as a task, except that ESP Workload Manager automatically marks a link as complete as soon as its dependencies are met, while a task requires an action.
Note: A link cannot have a resource dependency. If this is a requirement, you need to use a self-completing task.
Example: Simplifying job relationships
You have an Application that contains two groups of three jobs. The second group of jobs cannot run until all jobs in the first group have completed.
To create this dependency configuration without using a link means that dependencies must be created from all three jobs in the first group to all three jobs in the second group. While ESP Workload Manager can create an Application that includes many inter-linked dependencies like this, the Application can be hard to read and maintain.
Visually, you need to define the dependencies like this:
Solution
A better approach is to create a link that represents the completion of the first three jobs, and releases the second group of three jobs. This simplifies the definition of job relationships and makes it easier to add or delete jobs in each group.
B CA
E FD
Section–Using links
186 ESP-5.4-UG-05
Visually, the dependencies look like this:
One way of coding LINKJOB is shown below:
JOB LINKJOB LINK RUN DAILY PREREQ (A,B,C) POSTREQ (D,E,F)ENDJOB
Uses for links
Common uses of links include:
• Issuing commands• Keeping an Application active• Notifying when something happens• Notifying when something does not happen
The following examples illustrate some typical uses of links.
Example: Issuing a command
This example uses a link to start some initiators.
JOB OPEN.INITS LINK PROCESS VS '$SI1-10' RUN DAILYENDJOB
Example: Keeping an Application active
This example uses a link called KEEPOPEN to keep an Application active until 23:59. This technique is useful when you need an Application active to insert on-request jobs.
JOB KEEPOPEN LINK DELAYSUB 23:59 RUN DAILYENDJOB
B CA
E FD
LINKJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 187
Example: Notifying when an Application completes
This example sends a message at the end of an Application. The message includes the following symbolic variables:
%ESPAPPL - Represents the name of the Application
%ESPATIME - Represents the actual time the Application completes
JOB ENDAPPL LINK PROCESS AFTER LASTJOB RUN DAILY SEND '%ESPAPPL HAS COMPLETED at %ESPATIME' USER(BP01)ENDJOB
For detailed information on symbolic variables, see the ESP Workload Manager Advanced User’s Guide.
Example: Starting a task, taking action after completion
You want ESP Workload Manager to monitor a manually started task, and run a job when the started task ends. This example shows how you can set up these dependencies.
Visually the dependencies look like this:
To set up this Application:
1. Use a link to start the started task.
2. Identify the started task as a Manual job (because the task is started by an operator command).
3. Run a job when the Manual job ends successfully.
START.STC1(Link)
STC1(Manual)
BATCHJOB(Job)
Section–Using tasks
188 ESP-5.4-UG-05
Application
The Application looks like this:
APPL MYAPPLJCLLIB 'SYS1.JCL'JOB START.STC1 LINK PROCESS RUN DAILY VS 'S STC1'ENDJOBJOB STC1 MANUAL RUN DAILY RELEASE BATCHJOBENDJOBJOB BATCHJOB RUN DAILYENDJOB
Using tasks
You can define tasks in an Application and establish dependencies between them and other tasks and jobs. A task can represent a manual process such as balancing a report, or an automated process such as a step in a job completing.
You identify a task using the TASK operand on a JOB statement. ESP Workload Manager does not try and submit JCL for it. You define relationships and other dependencies for a task the same way you do for a job that ESP Workload Manager would submit. A task usually has a schedule frequency and can have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application.
When you mark a job as a TASK and select it for execution, ESP Workload Manager builds it as part of the Application. The AJ command, or the C command from CSF, can be used to mark a task complete.
Example: Checking a report
In this example, a report needs to be checked on workdays after job J1 completes successfully.
Chapter 6–Using Applications
ESP-5.4-UG-05 189
Visually, the dependencies look like this:
Identifying CHECKRPT.J1 as a TASK
The following Application identifies CHECKRPT.J1 as a TASK. When J1 completes successfully on a workday, ESP Workload Manager issues the SEND command to user BP01, indicating the actions to be taken. ESP Workload Manager submits job J2 only when CHECKRPT.J1 is marked complete. On non-workdays, J2 inherits the relationship with J1, and ESP Workload Manager submits J2 after J1 completes successfully.
JCLLIB 'CYBB.JOBS.CNTL'APPL ABC WAITJOB J1 RUN DAILY RELEASE CHECKRPT.J1ENDJOBJOB CHECKRPT.J1 TASK RUN WORKDAYS SEND 'JOB J1 HAS COMPLETED SUCCESSFULLY ' USER(BP01) SEND 'COMPLETE THE CHECKRPT.J1 TASK' USER(BP01) RELEASE J2ENDJOBJOB J2 RUN DAILYENDJOB
Uses for tasks
You can choose to use tasks for:
• Balancing reports• Input tapes• Step-level dependencies• Any other special handling jobs
J1(Job)
CHECKRPT.J(Task)
J2(Job)
Section–Using APPLEND workload object
190 ESP-5.4-UG-05
Additional information
For more examples of using tasks, see the ESP Workload Manager Advanced User’s Guide.
Using APPLEND workload object
The APPLEND workload object is a self-completing workload object. You can use APPLEND to automatically perform processing at the end of an Application.
The APPLEND object automatically succeeds any object in the Application that does not have a successor, or is not a successor to the APPLEND object itself. APPLEND forces itself to be executed after all other workload objects have completed, other than workload objects that are defined as successors to it.
The APPLEND object also detects any objects inserted into an active Application, and if they do not have successors or are not themselves successors to the APPLEND object, the APPLEND object is again made a successor to it.
Only one APPLEND workload object can exist in an Application.
Limitations of APPLEND
The following are limitations of the APPLEND object:
• You cannot insert the APPLEND workload object dynamically to an active Application. You must predefine APPLEND in the Application.
• When a workload object is inserted in an Application and becomes a predecessor of APPLEND, the Hold Count of the APPLEND workload object is incremented by one. However, the Hold Count data in CSF is not immediately updated.
• Simulation will not display the relationships between the APPLEND workload object and its predecessors.
To set an APPLEND workload object:
1. Start with an APPLEND name statement where name is the name of the APPLEND workload object.
2. Insert any statements to initiate the actions required.
3. Terminate with an ENDJOB statement.
Chapter 6–Using Applications
ESP-5.4-UG-05 191
Example
In the following example, the APPLEND workload object named FRED will be made a successor of JOB2, because JOB2 has no other successors. However, job AFTERAE2 and AFTRAELA, which also do not have successors, are successors to the APPLEND workload object, so are not also made predecessors to it.
APPL TESTAE1JCLLIB 'CYBER.JCL.CNTL'
JOB JOB1 LINK RUN DAILY REL JOB2ENDJOB
JOB JOB2 LINK RUN DAILYENDJOB
APPLEND FRED REL (AFTERAE1,AFTERAE2) SE 'APPLEND RUNNING' U(*)ENDJOB
JOB AFTERAE1 LINK RUN DAILY REL AFTRAELAENDJOB
JOB AFTERAE2 LINK RUN DAILYENDJOB
JOB AFTRAELA TASK RUN DAILYENDJOB
Additional considerations
There is an additional consideration when using the APPLEND workload object:
The APPLEND object does not generate any SMF by itself. If it has no successors, then the ESP1159I message will be the only external indication that an Application has ended.
Section–Changing job attributes
192 ESP-5.4-UG-05
To generate SMF, a S/390 job will need to be run as a successor to the APPLEND object. For example:
APPL EXAMPLEJCLLIB 'CYBER.JCL.CNTL'
JOB JOB1 RUN DAILYENDJOB
APPLEND TERMIN8 POSTREQ TERMIN8RENDJOB
JOB TERMIN8R MEMBER IEFBR14ENDJOB
Changing job attributes
In ESP Workload Manager, you can define a job with a number of different attributes using different operands on the JOB statement. Some examples of attributes are CRITICAL, HOLD, REQUEST, CONDITIONAL, LINK, and MANUAL.
A job can have different attributes based on different criteria. For example, you can define a job on hold but only for a particular date. This job has different attributes based on schedule criteria.
To define a job with different attributes:
• Use the JOBATTR statement.
This statement lets you change any attributes of a job within the scope of the JOB statement or in job documentation. Attributes include the operands you can use on the JOB statement.
Example: Changing a job attribute
In the following example, job ABC runs daily. On December 9, 2000, it needs to be defined on hold.
JOB ABC RUN DAILY IF TODAY('DEC9,2000') THEN JOBATTR HOLD ENDJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 193
Additional information
For more examples of changing job attributes, see the ESP Workload Manager Advanced User’s Guide.
Using data-set-trigger workload objects
You can use ESP Workload Manager data-set-triggering facility at the Event level or at the job level. This section describes how to use this facility at the job level. For information on using data-set-triggering at the Event level, see “Processing ESP Events” on page 73.
Data-set-trigger workload object
You can define a data-set-trigger workload object as part of an ESP Application. You can set up data-set dependencies at the job level. A data-set-trigger workload object can be completed by the successful creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. This activity can be restricted to data sets created by a specific job or group of job names.
You can also define a data-set-trigger workload object that can be completed by the successful transfer or renaming of a data set through FTP transfer. See “Using FTP data-set-trigger workload objects” on page 198.
Additional information
The next sections describe how to set up data-set-trigger objects. For more examples using these objects, and for other techniques on handling data set dependencies, see the ESP Workload Manager Advanced User’s Guide.
Preparing to use data set trigger objects
To use a data-set-trigger object, the Systems Programmer responsible for ESP Workload Manager must add a Workload Object Module (WOBDEF) statement to the ESP Workload Manager initialization parameters (for example, WOBDEF LOAD CYBESODT).
To set up a data-set-trigger object in an Application:
1. Use the DSTRIG statement to assign a name to the data-set-trigger workload object. You can use some of the same operands you use on a JOB statement. These include REQUEST, HOLD, and CONDITIONAL.
2. Use the DSNAME statement to identify the name of the data set. Quotation marks are optional. You can use a wildcard character hyphen (see “About this guide” on page 1), and you can use operands such as COUNT, ANYCLOSE,
Section–Using data-set-trigger workload objects
194 ESP-5.4-UG-05
JOBNAME, and RENAME to handle different requirements. Only one DSNAME statement is supported per workload object.
3. Use a RUN or SELECT statement to identify when you want this object to build as part of the Application.
4. Use other statements, such as DELAYSUB, DUEOUT, RELEASE to identify other requirements.
Example: Waiting for a data set creation
In this example:
• The DSTRIG statement identifies a data-set-trigger object called BIGFILE.• The DSNAME statement identifies PROD.CICS.FILE1602 as the data set.
Because no other operands are specified, ESP Workload Manager waits for this data set to be created.
• The frequency is DAILY.• The successor job is ABCJOB.
DSTRIG BIGFILE DSNAME PROD.FILE.CICS1602 RUN DAILY RELEASE ABCJOBENDJOB
Once the Application containing this object is active, ESP Workload Manager watches for the PROD.CICS.FILE1602 data set to be created. When it is created, the BIGFILE object completes and releases the successor job ABCJOB.
Visual perspective
Visually, the flow looks like this:
Waiting for any closure of a data set
You can use the ANYCLOSE operand to indicate any closure of a data set. This includes the creation of a new data set and the updating of an existing data set. If you do not specify ANYCLOSE, ESP Workload Manager waits for the data set to be created.
ABCJOB(Job)
PROD.CICS.FILE1602(data set)
Chapter 6–Using Applications
ESP-5.4-UG-05 195
Example
The following example uses a data-set-trigger workload object (WAIT4.DS) to build a dependency between any closure of a data set (PROD.WEEKLY.ACCNTS) and a job (PAYJOB1).
APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG WAIT4.DS DSNAME PROD.WEEKLY.ACCNTS ANYCLOSE RUN DAILY RELEASE PAYJOB1ENDJOBJOB PAYJOB1 RUN DAILYENDJOB
Limiting data set activity to a job
You can restrict the trigger to only specific data sets created by a particular job. Use the JOB operand followed by the full name or job name prefix of the job.
Example: Job specific creation
The following example indicates a data-set-trigger occurs when job ABC creates a generation of the data set USER1.PAYROLL.
DSTRIG USERDATA DSNAME USER1.PAYROLL.G- JOB(ABCENDJOB
Waiting on multiple data sets
To set up a dependency on multiple data sets, you need to use a separate data-set-trigger object for each.
Section–Using data-set-trigger workload objects
196 ESP-5.4-UG-05
Example: Waiting on more than one data set
In this example, job XYZ waits for two data-set-trigger objects: FILEA and FILEB.
• FILEA completes when CYBER.DATA111.CNTL closes.• FILEB completes when CYBER.DATA999.CNTL closes.
APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG FILEA DSNAME CYBER.DATA111.CNTL ANYCLOSE RUN DAILY RELEASE XYZENDJOBDSTRIG FILEB DSNAME CYBER.DATA999.CNTL ANYCLOSE RUN DAILY RELEASE XYZENDJOBJOB XYZ RUN DAILYENDJOB
Waiting on multiple closures of the same data set
It is possible for a data set to be closed several times. You can use the COUNT operand to specify how often this closure is required before the data-set-trigger object completes. The count begins when the data-set-trigger object becomes ready (for example, any time and predecessor dependencies have been met). The CSF STATUS field displays the counter and its current value once the data-set-trigger object becomes ready.
With each closure, ESP Workload Manager increases its internal counter by one. When the counter reaches the number you set in your COUNT operand, ESP Workload Manager completes the data-set-trigger object. The next time the Application gets generated, the count is set to zero.
Example: Waiting on multiple closures of a data set
In the following example, the data-set-trigger object completes after two creations of a data set:
DSTRIG DOUBLE.INPUT DSNAME SITE1.BILLING.FILE COUNT(2)ENDJOB
Limiting data set activity to a user
You can restrict the trigger to only specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the job task closing or renaming the data set
Chapter 6–Using Applications
ESP-5.4-UG-05 197
Example: User specific creation
The following Event triggers when user CYBER1 creates a generation of the data set USER1.PAYROLL.
DSTRIG PROD.PAY_DATA DSNAME USER1.PAYROLL.G- USER(CYBER1) INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF
Controlling data-set-trigger objects
A data-set-trigger object must be ready before ESP Workload Manager looks for the activity specified on the DSNAME statement. A data-set-trigger object can have a predecessor or a time dependency or be defined on hold. Each of these conditions prevents the data-set-trigger object from completing. Once a data-set-trigger object becomes ready, the only action you can take against it is complete it.
Example: Data-set-trigger has a dependency
In the following example, the data-set-trigger object INPUT.DATA has a delayed submission time of 6 pm. If the CYBER.BILLING data set is created prior to this time, the data-set-trigger object does not complete. At 6 pm, ESP Workload Manager sends a message to BOB indicating it is waiting for some data.
DSTRIG INPUT.DATA DSNAME CYBER.BILLING RUN DAILY DELAYSUB 6PM SEND 'WAITING FOR INPUT DATA NOW' U(BOB) RELEASE BILLJOB1ENDJOB
Displaying data-set-triggering information
While DSTRIG workload objects are active, you can use the LDXE command to display them. The LDXE command differentiates between Event-level and Application-level data-set triggers.
The following is an example of the output produced by the LDXE command, where:
• Application PAYROLL.1 contains a job-level data-set trigger called WAIT4.DS. It is waiting for a data set closure on a data set called CYBER.PAYROLL.DATA1.
• Event CYBER.CYCLES is waiting for data set USER.INPUT.CYCLE to be created.
LDXEEVENT/APPL (WOB)-------DATASETPAYROLL.1 (WAIT4.DS) CYBER.PAYROLL.DATA1, ANYCLOSECYBER.CYCLES USER.INPUT.CYCLE2 ENTRIES DISPLAYED
Section–Using FTP data-set-trigger workload objects
198 ESP-5.4-UG-05
Using FTP data-set-trigger workload objects
FTP data-set-trigger workload objects are a particular kind of data set trigger workload object, where an Event can be triggered when a successful FTP file transfer or FTP rename completes.
When setting up an FTP data-set workload object, the file transfer causing the Event to be triggered can be closely defined by:
• Specifying the direction of the transfer• Limiting data-set activity to a host• Limiting data-set activity to a user ID• Limiting data set activity to a logon ID
Specifying the direction of the transfer
You can specify that the data file transfer direction is from the remote FTP partner to the local mainframe FTP partner or vice versa. Use the FTP operand followed by RECEIVE or RECV if the transfer is from the remote FTP partner to the local mainframe FTP partner. Use the FTP operand followed by SEND if the transfer is from the local mainframe FTP partner to the remote FTP partner.
Examples: FTP RECEIVE and SEND
The following Event triggers when a file is successfully received from a remote FTP partner, creating a generation of the data set USER1.PAYROLL.
DSTRIG PROD.PAY_DATA RUN DAILY DSNAME USER1.PAYROLL.G- FTP(RECEIVE) RELEASE PROD.ESP.PROCS(PAYJOBS)ENDJOB
The following Event triggers when the data set CYBER.XFER.001 is successfully sent from the local mainframe FTP partner to a remote FTP partner.
DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(SEND) RELEASE PURGE.XFER(001)ENDJOB
Limiting data-set activity to a host
You can restrict the trigger to FTP transfer from only a specific host. Use the HOST operand followed by the DNS host name or the IP address of the specified host.
Chapter 6–Using Applications
ESP-5.4-UG-05 199
Example: Host specific creation
The following Event triggers when a remote FTP partner with the IP address 10.1.3.1 successfully transfers a file creating the data set CYBER.XFER.001.
DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) HOST(10.1.3.1) RELEASE PROCESS.XFER(001)ENDJOB
Limiting data-set activity to a user ID
You can restrict the trigger to specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the local FTP partner’s job task regardless of whether the local FTP partner is the client or the server.
Note: Because user ID always refers to a local mainframe host security user ID, lowercase characters are translated to uppercase.
Example: User-specific creation
The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the user ID prefix of the local FTP partner is CYB.
DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) USER(CYB-) RELEASE PROCESS.XFER(001)ENDJOB
Limiting data set activity to a logon ID
You can restrict the trigger to specific data sets created or renamed by a particular user. Use the LOGON operand followed by the logon ID of the user.
The logon ID refers to the user ID that the FTP client uses to logon to the FTP server.
If the FTP client is the remote partner, then logon ID is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).
If the FTP client is the local partner, then logon ID is the user ID of the remote FTP partner.
Note: When logon ID is a remote user ID, it can be case sensitive, as for example on UNIX hosts. Therefore, logon ID lowercase characters are not translated to uppercase.
Section–Using FTP data-set-trigger workload objects
200 ESP-5.4-UG-05
Example: Logon specific creation
The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the remote FTP partner did logon to the FTP server with the CYBER005 user ID.
DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) LOGON(CYBER005) RELEASE PROCESS.XFER(001)ENDJOB
Notes on FTP trigger operands
dsname
The data set name specified in the DSNAME Application statement always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).
ANYCLOSE
FTP triggers cannot to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition.
RENAME
When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename a data set to a specified data set name. Because data set name always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore the RENAME and FTP(SEND) operands are mutually exclusive.
Example
The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged-on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.
DSTRIG USER.APPL_RECEIVE RUN DAILY DSNAME CYBER.DATA.SET USER(CYB-) FTP(RECEIVE)- HOST(AIXHOST) LOGON(aixuser) SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDJOB
Chapter 6–Using Applications
ESP-5.4-UG-05 201
Using explicit-data-set-trigger workload objects
An explicit data-set trigger is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.
The feature consists of two parts:
• The explicit data-set trigger notification utility program (CYBESDT1).• The operand EXPLICIT in the DSNAME statement.
You invoke CYBESDT1 in a job, as an additional step, conditionally to the successful execution of the step manipulating a specified data set. This program writes an SMF record type 132 subtype 1.
An explicit data-set trigger is defined to ESP Workload Manager via the EXPLICIT operand in the DSNAME statement.
Explicit data-set trigger SMF record requirement
An installation must cut SMF type 132 subtype 1 SMF record for explicit data-set triggering to function.
Explicit data-set trigger notification utility program(CYBESDT1)
ESP Workload Manager receives notification of an explicit data-set trigger when CYBESDT1 is executed. CYBESDT1 must, at least, use the following input parameters:
• The dsname of the data set causing the activation of the data-set trigger (DSNAME)
• The volume serial number where the data set resides, if the data set is uncataloged
CYBESDT1 writes a user SMF type 132 subtype 1 record containing information required for the explicit data-set trigger.
The target ESP Workload Manager subsystem examines the SMF record, and if a matching explicit data-set trigger definition is found, satisfies the data-set trigger.
Program CYBESDT1 can execute in a batch, TSO, started task, or run task environment (for example, Connect:Direct (NDM)). It must also be APF-authorized or the attempt to write the explicit data-set-trigger SMF record fails with an ABEND047.
Program CYBESDT1 is reentrant.
Note: If you execute CYBESDT1 specifying a relative generation of a GDG in a job that creates new generations, the position of the CYBESDT1 step in the job determines the generation being selected. CYBESDT1 considers that the current generation (relative generation (0)) is the latest generation created when it executes.
Section–Using explicit-data-set-trigger workload objects
202 ESP-5.4-UG-05
CYBESDT1 input parameters
The input parameters of CYBESDT1 are specified in the JCL EXEC PARM for a batch job, and as operands when running as a TSO command.
The syntax is as follows:
DSNAME|DATASET(dsname[(member)|(relgen)]) {VOLSER|VOLUME(volser)} [SUBSYSTEM|SSID(subsystem)] [VERIFY|NOVERIFY]
Parameter Description
DSNAME(dsname) or DATASET(dsname)
Specifies the data-set name.
member Specifies a member name of a PDS.
relgen Specifies the relative generation of a generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in CYBESDT1 and in the corresponding DSTRIG command or DSNAME statement exactly the same way, including leading zeros.
Note: Alternatively, you can include the absolute generation in dsname. For example:
CYB4.ENCXX.BACKO01A.G0027V00
VOLSER(volser) or VOLUME(volser)
Specifies the volume serial number that the data set resides on. It is required for uncataloged data sets and optional for cataloged data sets.
SUBSYSTEM(subsystem) or SSID(subsystem)
Is the ESP Workload Manager subsystem identifier keyword. This parameter is optional, if omitted, all tracking ESP Workload Manager subsystems will receive the explicit data-set trigger SMF record that program CYBESDT1 writes. A tracking ESP Workload Manager subsystem is one whose ESPPARM initialization file does not contain the following statement:SMFINT OFF
VERIFY Specifies that CYBESDT1 will set the explicit data-set trigger only if the following criteria are met:• The specified data set is catalogued if the VOLSER or
VOLUME parameter is omitted.• The specified data set resides on the specified volume.
(From the volser parameter if specified, from the catalog if not.)
• The owner of the job executing CYBESDT1 has update access to the data set specified.
Chapter 6–Using Applications
ESP-5.4-UG-05 203
CYBESDT1 return codes
CYBESDT1 issues a zero return code if the explicit data-set trigger SMF record was successfully written, and a non-zero return code if any error condition occurs that causes the explicit data-set trigger SMF record not to be written.
%ESPTRGDG symbolic variable
The built-in symbolic variable, %ESPTRGDG, is generated when an event level explicit-data-set trigger is activated with a relative generation specified (relgen).
The value of %ESPTRGDG is set to the corresponding GDG base name. For example, if the data set activating the explicit data-set trigger is:
CYB4.ENCXX.BACKO01A.G0027V00
%ESPTRGDG will be set to:
CYB4.ENCXX.BACKO01A
Note: At the same time the symbolic variable %ESPTRDSN will be set to the fully qualified data-set name:
CYB4.ENCXX.BACKO01A.G0027V00
If the fully qualified data-set name cannot be determined, %ESPTRDSN is set to blanks. This can happen in the following two situations:
• The specified relative generation does not exist in the GDG index• NOVERIFY was specified as an operand of CYBESDT1
Examples
Invoking CYBESDT1 from page mode or line mode
To run CYBESDT1 from page or line mode, you must prefix the command with TSO because CYBESDT1 is external to ESP Workload Manager.
TSO command example:
TSO CYBESDT1 D(PDS.DATA.SET(MEMBER1))
TSO call example:
CALL 'CYBER.SSCPLINK(CYBESDT1)' 'D(PDS.DATA.SET(MEMBER1))'
NOVERIFY Specifies that CYBESDT1 will set the explicit data-set trigger whether or not the criteria described for the VERIFY parameter are met.
Parameter Description
Section–Using explicit-data-set-trigger workload objects
204 ESP-5.4-UG-05
Explicit data-set trigger notification batch example
In the following example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.
If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.
//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK
The following example triggers MYEVENT when the data set PDS.DATA.SET(MEMBER1) is created or updated:
EVENT ID(MYEVENT)DSTRIG PDS.DATA.SET(MEMBER1) EXPLICITENDDEF
Note: The data-set trigger, whether an Event or a workload object, must exist before you execute CYBESDT1.
Explicit data-set trigger notification Connect:Direct (NDM) run task example
In the following example, STEP1 copies the data set OLD.DATA.SET from Connect:Direct node NODE1 to the local Connect:Direct node as data set NEW.DATA.SET.
If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set NEW.DATA.SET has been created by the Connect:Direct copy operation.
PROCESS1 PROCESS SNODE=NODE1STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET - TO(SNODE DSN=NEW.DATA.SET - DISP=(NEW,CATLG,DELETE)) IF (STEP1 EQ 0) THENSTEP2 RUN TASK (PGM=CYBESDT1 - PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) - SNODE EIF
Chapter 6–Using Applications
ESP-5.4-UG-05 205
Tagging jobs
TAG statement
You can use the TAG statement to tag jobs in an Application with a character string up to 16 characters. The tag can apply to all jobs in an Application or to individual jobs depending on where you place it. You can use a tag to:
• Allow the filtering of jobs with a common characteristic using CSF• Pass information to JCL. The %ESPAPTAG symbolic variable contains the data
in the TAG statement.
Example: Tagging jobs with the scheduled day of week
The following example uses a symbolic variable to tag all jobs in an Application with the three-character day of the week:
TAG '%ESPSDAY(1:3)'APPL BILLING
Example: Tagging high priority jobs
This example tags PAYJOB as a high priority job:
JOB PAYJOB TAG 'HIGH_PRIORITY'ENDJOB
Example: Tagging jobs with Application name
This example uses the TAG statement to specify the name of the Application that submits the job. This is useful when you have an Application containing external jobs.
Construct the Application like this:
• Use a global TAG statement to identify the name of the Application.• Use a job-specific TAG statement for each external job to specify the name of the
Application submitting each external job.
Section–Providing notification on Job status
206 ESP-5.4-UG-05
Sample Application
A sample Application looks like this:
APPL PAYROLLJCLLIB . . .TAG 'PAYROLL'JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE CENDJOBJOB C RUN DAILY AFTER XENDJOBJOB X EXTERNAL TAG 'BILLING' RUN DAILYENDJOB
Providing notification on Job status
You can use the NOTIFY statement within an Application to keep yourself or other users informed about the progress of jobs in an ESP Application. The NOTIFY statement can inform you when:
• A job is submitted.• A job starts.• A job becomes overdue from different processing points.• A job execution is faster than expected.• A job ends abnormally (ABENDs).• A job fails (for example, condition code failures).• A job ends (successfully or unsuccessfully).• ESP Workload Manager resubmits a job.
Using this statement, the only type of notification you can receive for external jobs, manual jobs, data-set-trigger objects, links, and tasks is overdue. This notification is based on the LATESUB and DUEOUT statements.
Notification list (MAILLIST)
You can direct notification messages to a notification list instead of specifying the user ID directly in the NOTIFY statement.
Chapter 6–Using Applications
ESP-5.4-UG-05 207
The notification lists are included in the MAILLIST data set. The MAILLIST data set contains any number of MAILBOX initialization parameters, each of them containing any number of TSO user IDs and email addresses. You select where the NOTIFY statement sends messages by coding a mailbox name in the MAILBOX operand. Messages will be sent to all TSO user IDs and email addresses specified in the mailbox. See the “MAILLIST data set” section in the ESP Workload Manager Installation and Configuration Guide for information on how to set up the MAILLIST data set and the mailboxes.
Example: Using the notification list
In the following example, a notification that the job ending is overdue is directed to all TSO user IDs and email addresses contained in the CYBERBOX mailbox.
NOTIFY OVERDUE JOBEND MAILBOX(CYBERBOX)
Example: Notification on submit and abend
For example, suppose that you know that a programmer has modified the JCL for job D and you want to find out:
• When ESP Workload Manager submits the job• If the job ABENDs
In this example, the NOTIFY statement tells ESP Workload Manager to notify user USER01 when ESP Workload Manager submits job D and if job D ABENDs.
JOB D NOTIFY SUBMIT ABEND USERS(USER01) RELEASE E RUN DAILYENDJOB
Example: Overdue notification
This example notifies user USER02 when job LONGJOB becomes overdue. ESP Workload Manager sends a message to USER02 if LONGJOB does not complete execution successfully by 5 am.
JOB LONGJOB NOTIFY OVERDUE USER(USER02) DUEOUT EXEC 5AM RUN DAILYENDJOB
Additional information
The NOTIFY statement can notify users and trigger an Event.
For information on triggering an Event, see Chapter 3, “Job Monitoring and Alert Processing”, in the ESP Workload Manager Advanced User’s Guide.
Section–Using critical-path analysis
208 ESP-5.4-UG-05
Using critical-path analysis
Critical-path analysis, combined with the ability to set time dependencies and trigger Events automatically, provides the framework for advanced due out notification when mission critical workload does not complete within the designated time frame or window.
ESP Workload Manager allows you to identify a job within an Application that represents a critical point of that Application. The longest path to that job, based on historical execution time, is a critical path.
Example of a critical path
In the following diagram, job Z is identified as the critical point in an Application. The longest path to job Z, based on historical execution time, represents the critical path. If all jobs are selected, the critical path consists of jobs A, B, X, Y, and Z.
ESP Workload Manager determines the critical path when it generates an Application. The critical path for an Application can vary depending on which jobs are selected. Based on the previous example, the critical path can vary as follows:
Jobs Not Selected Critical Path
X, Y A, B, C, D, Z
X, Z A, B, C, D
X, Y, D A, B, E, F, Z and A, B, C, Z
Z A, B, X, Y - defaults to longest path
A
Z
D
C
Y
X
F
E
B
15 Mins
15 Mins
15 Mins
30 Mins
CRITICAL
30 Mins
10 Mins
20 Mins
60 Mins
10 Mins
Chapter 6–Using Applications
ESP-5.4-UG-05 209
Preparing to use critical path
Prior to using critical path, check with your administrator to ensure the critical-path feature is enabled. Through the CRITPATH ESP Workload Manager initialization parameter or command, an installation can disable critical path analysis for all Applications, enable critical-path analysis for selected Applications, or turn on critical-path analysis for all Applications.
To use the critical-path feature:
1. Turn on critical-path analysis for an Application.
2. Identify one or more critical jobs.
To turn on critical-path analysis for an Application:
• Use the CRITPATH ON statement as a global statement before your job definitions. For example:
APPL BILLINGJCLLIB 'CYBER.JCL'CRITPATH ONJOB A...
Critical-path analysis for all Applications
Some installations can turn on critical-path analysis for all Applications using an ESP Workload Manager initialization parameter or command. If critical-path analysis is on for all Applications:
• You do not need the CRITPATH ON statement to use critical-path analysis for an Application.
• You must use the CRITPATH OFF statement as a global statement, to turn off critical-path analysis for an Application.
To identify critical jobs:
• Use the CRITICAL operand on a job that represents a critical point in the Application, as follows:
JOB Z CRITICAL
If critical-path analysis is turned on for an Application, but no selected jobs are coded with the CRITICAL operand, ESP Workload Manager calculates the path to the job that will finish last and identifies that path as the critical path.
Section–Using critical-path analysis
210 ESP-5.4-UG-05
External jobs on critical path
Jobs defined as external jobs in an Application can be part of the critical path. However, if those external jobs have predecessors, the predecessors in the home Application are not defined as part of the critical path.
Multiple critical paths
An Application can have more than one critical path. In the following diagram, four jobs (represented by grayed boxes) are critical jobs. The longest paths to each of these jobs, based on historical execution time, are identified as critical paths.
Overriding elapsed times
There can be situations where you want to override historical elapsed times. For example, on the last day of the month, a job on the critical path can run longer than normal. Or there can be no historical information for a job on the critical path because this is the first run of the job. In these situations, you can override historical elapsed-time defaults using the DURATION statement to specify an estimated duration for the job.
The following example sets the elapsed-time estimate for job A to 120 (minutes) on the last day of the month:
JOB A RUN WORKDAYS IF TODAY('LAST DAY OF MONTH') THEN DURATION 120ENDJOB
A
L
PO
K
F
G IH
EB C D
V
TS
U
R
N Q
M
J
Chapter 6–Using Applications
ESP-5.4-UG-05 211
Displaying the critical path
After ESP Workload Manager generates an Application, you can display the critical path using CSF freeform filtering or the List Application (LAP) command.
Using the consolidated status facility (CSF)
You can use the CSF freeform filtering feature to filter jobs in an Application that are on the critical path or not on the critical path.
The following freeform filter results in a display of all critical-path jobs in the PAYROLL Application.
CRITICAL_PATH AND APPL EQ 'PAYROLL'
Additional information
For more information on freeform filtering, see “Consolidated Status Facility (CSF)” on page 221.
Using the list Application command
The LISTAPPL (LAP) command displays information about your Application. All jobs on the critical path are identified with a label of CRITICAL PATH. Any job in the Application coded with the CRITICAL operand is identified with a label of CRITICAL. You can limit your display to jobs on the critical path or jobs not on the critical path.
The following LAP command uses the CRITPATH operand to display only those jobs on the critical path for the current generation of the PAYROLL Application:
LAP PAYROLL.0 ALL CRITPATH
Issuing ESP Workload Manager commands
As part of an Application you can issue ESP Workload Manager commands. This is useful, for example, when you want to issue commands to manipulate jobs, trigger Events, and perform displays. Use the ESP or ESPNOMSG statement in an Application to issue an ESP Workload Manager command. ESPNOMSG suppresses responses from the command.
Section–Using subApplications
212 ESP-5.4-UG-05
Example: Triggering an Event
This example uses a link called MORE.WORK. It issues an ESP Workload Manager command to trigger an Event called CYB.OTHER in addition to its regular schedule. ESP Workload Manager suppresses the response (for example, EVENT TRIGGERED) from the trigger command.
JOB MORE.WORK LINK PROCESS RUN ANY ESPNOMSG TRIGGER CYB.OTHER ADDENDJOB
Example: Creating an Event, triggering an Event
This example issues a series of ESP Workload Manager commands to:
• Define a new Event called CYB.NEW_EVENT
• Trigger the new Event
JOB CREATE.EVENT LINK PROCESS RUN ANY ESP EVENT ID(CYB.NEW_EVENT) SYSTEM(ESPA) REPLACE ESP SEND 'THIS IS A NEW EVENT' USER(CYB01) ESP ENDDEF ESP TRIGGER CYB.NEW_EVENTENDJOB
Using subApplications
An Application can consist of one or more subApplications. This is useful, for example, when you have a large Application you would like to break up into smaller, easier to manage, groups of jobs. You can display, manipulate, and report on subApplications. You can control a group of jobs belonging to the same subApplication by using a single command. Use CSF or the LISTAPPL (LAP) and APPLJOB (AJ) commands to display and control subApplications respectively.
To identify a subApplication:
Use the SUBAPPL statement in an Application to identify a subApplication and choose a name different from any job name in the Application.
You can use the SUBAPPL statement within the scope of a JOB statement to associate a job with a subApplication, or outside the scope of a JOB statement to apply to multiple jobs. Use the WAIT operand if you have not used it on the APPL statement and you want a subApplication to wait on the previous generation of the subApplication.
Chapter 6–Using Applications
ESP-5.4-UG-05 213
Example
The following example shows two subApplications defined within the Application called ACJOBS. The criteria are:
• Jobs in CYB1 and CYB2 belong to the subApplication called PREPJOBS.
• Jobs CYB3 and CYB4 belong to the subApplication called NIGHTLY.
• The PREPJOBS subApplication can process even if the previous PREPJOBS subApplication is not complete; the NIGHTLY subApplication must wait until the previous generation of the corresponding subApplication completes execution.
APPL ACJOBSSUBAPPL PREPJOBSJOB CYB1 RELEASE CYB3ENDJOBJOB CYB2 RELEASE CYB3ENDJOBSUBAPPL NIGHTLY WAITJOB CYB3 RELEASE CYB4ENDJOBJOB CYB4ENDJOBSELECT (CYB1,CYB2,CYB3,CYB4)
Selecting a subApplication
If your jobs within a subApplication have the same frequency, you can choose to use a SELECT statement to select all jobs within a subApplication. This eliminates the need to use a RUN statement for each job or a SELECT statement that specifies the name of each job.
To select a subApplication:
Use the SELECT statement to specify one or more subApplication names, followed by the operand SUBAPPL.
Section–Using subApplications
214 ESP-5.4-UG-05
In the following example, subApplications PREPJOBS and NIGHTLY are selected.
APPL ACJOBSSUBAPPL PREPJOBSJOB CYB1 RELEASE CYB3ENDJOBJOB CYB2 RELEASE CYB3ENDJOBSUBAPPL NIGHTLY WAITJOB CYB3 RELEASE CYB4ENDJOBJOB CYB4ENDJOBSELECT (PREPJOBS,NIGHTLY) SUBAPPL
Similarly, you can use the DESELECT statement to deselect all jobs within a subApplication.
To display a subApplication:
Use the LS command from CSF or use the LISTAPPL (LAP) command with the SUBAPPL operand to display subApplications.
For example, the following results in a structured view of the subApplication PREPJOBS within the Application called ACJOBS.
LAP ACJOBS SUBAPPL(PREPJOBS) ALL
To control a subApplication:
Use either CSF or different operands command to control subApplications similar to the way in which you control jobs.
You can:
• Bypass a subApplication or cancel the bypass • Ready a subApplication• Request a subApplication or cancel the request• Hold or release a subApplication • Complete a subApplication • Remove a subApplication from wait status
Example: Requesting a subApplication
In the example below, ESP Workload Manager requests the subApplication called REQJOBS in the Application MYAPPL. The system requests each selected job marked as REQUEST in this subApplication. This eliminates the need to request each job individually.
AJ REQJOBS REQUEST APPL(MYAPPL.0)
Chapter 6–Using Applications
ESP-5.4-UG-05 215
Note: Requesting a subApplication is not the same as selecting each job in the subApplication.
Working with Applications
Once ESP Workload Manager generates an Application, you can display and control jobs, subApplications, and the Application itself. You can perform any of these tasks using:
• Commands in page mode, a batch job, or an ESP Procedure • The Consolidated Status Facility (CSF) • ESP Workstation
This section describes some available common commands.
Additional information
For more information on CSF, see “Consolidated Status Facility (CSF)” on page 221. For more information on ESP Workstation, see the ESP Workstation User’s Guide.
Displaying an Application
After ESP Workload Manager generates an Application, use the LISTAPPL command to display it. The short form of the command is LAP. Use the command with the ALL operand to give a structured view of an active Application or with other operands to give a summary of active or completed Applications. You can limit the display to specific generations of an Application and to specific jobs within an Application.
Section–Controlling an Application
216 ESP-5.4-UG-05
Sample output
Sample output from an LAP command looks like this:
LAP PAYROLL.23 ALLAPPL PAYROLL GEN 23 CREATED AT 09.54 ON MONDAY MAY 14TH, 2001 BY EVENT CYBBP01.PAY PAYD001A J6281, COMPLETED, CC 0 AT 10.01 ON MONDAY MAY 14TH, 2001 PAYD002A J6282, COMPLETED, CC 8 AT 10.04 ON MONDAY MAY 14TH, 2001 PAYD003A J6283, STARTED, STEP 3 PAYD004A, HC=1 SUBMISSION AT 10.15 ON MONDAY MAY 14TH, 2001 ANTICIPATED END TIME: 10.20 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD003A SUCCESSORS: PAYD100A
PAYD100A, HC=1 ANTICIPATED END TIME: 10.29 ON MONDAY MAY 14TH, 2001 DUE OUT BY 10.30 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD004A SUCCESSORS: PAYD006A
ABCJOB, HC=0 ANTICIPATED END TIME: 10.59 ON MONDAY MAY 14TH, 2001 EXTERNAL PREDECESSORS: NONE SUCCESSORS: PAYD006A
PAYD006A, HC=2 ANTICIPATED END TIME: 11.12 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD100A, ABCJOB SUCCESSORS: ENDAPPL RESOURCES: 1,CICSUP
ENDAPPL, HC=1 ANTICIPATED END TIME: 11.29 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD006A SUCCESSORS: (NONE)
----- 1 ENTRY DISPLAYED
Other options are available on the LISTAPPL command. For example, you can display particular jobs, a previous generation of an Application, or a subApplication.
Controlling an Application
APPLJOB command
The APPLJOB command controls jobs, subApplications, and Applications. The short form of this command name is AJ.
Chapter 6–Using Applications
ESP-5.4-UG-05 217
Options on APPLJOB command
Many different options are available on this command. Some of these options allow you to:
• Insert a job• Add or reset dependencies for a job• Drop dependencies for a job• Bypass a job• Complete a job, subApplication, or Application• Request a job.
Examples
Here are some examples of using the APPLJOB command with the current generation (.0) of an Application called PAYROLL.
Example: Requesting a job
This example requests MYJOB.
AJ MYJOB REQUEST APPL(PAYROLL.0)
Example: Bypassing a job
This example bypasses PAYJOB3. ESP Workload Manager bypasses the job at the time it would normally submit it.
AJ PAYJOB3 BYPASS APPL(PAYROLL.0)
Example: Inserting a link to add a job relationship
This example inserts a link called LINKME. It has a predecessor of PAYJOB1 and a successor of PAYJOB2, which means that PAYJOB1 must complete successfully prior to submitting PAYJOB2.
AJ LINKME INSERT PRED(PAYJOB1) SUCC(PAYJOB2) -ATTRIBUTES(LINK) APPL(PAYROLL.0)
Example: Completing an Application
This example completes the entire Application.
AJ ALL COMPLETE APPL(PAYROLL.0)
You will likely use the Consolidated Status Facility to perform many of these tasks. For more information on controlling jobs, subApplications, and Applications, see “Consolidated Status Facility (CSF)” on page 221.
Section–Changing an Application definition
218 ESP-5.4-UG-05
Changing an Application definition
ESP Workload Manager does not submit a job to JES until all of its dependencies have been met. You can make changes to the ESP Procedure where the Application definition resides while the Application is processing. Some changes you make take effect immediately (next job submission); others do not take effect until the next time the Application is created.
Important: If you cache a Procedure and then you update it, use the CPROC command to delete the cached version so the new version is read automatically by an active Application. For details, see “Caching an ESP Workload Manager Procedure” on page 135.
Changes that take effect immediately
You can make changes to any of the following commands and statements listed below. Global changes, outside the scope of any JOB statements, apply to all subsequent submissions. Job specific changes, within the scope of a JOB statement, apply to the next submission of that job.
CCCHK, CCFAIL, COPYJCL, DATASET, DOCLIB, DOCMEM, ESP, INVOKE, JCLLIB, MEMBER, MODEL, MONITOR, NOTIFY, PNODES, SEND, SUBMIT, TEMPLIB, VS commands and statements.
Statements related to distributed workload, for example, ARGS, CMDNAME, ENVAR, or USER, take effect immediately.
Changes that do not take effect until next generation
You can drop dependencies and change time dependencies for an active Application through CSF. However, any of the changes listed below to the coded Application definition do not take effect until the next generation.
• Job relationships: AFTER, COREQ, DEQUEUE, DROPNOTW, ENQUEUE, NOTWITH, POSTREQ, PREREQ, RELEASE
• Time dependencies: ABANDON DEPENDENCIES, ABANDON RESOURCES, ABANDON SUBMISSION, DELAYSUB/EARLYSUB, DUEOUT, LATESUB, RELCOUNT, RELDELAY
• Schedule criteria: for example, RUN/NORUN, SELECT/DESELECT statements
• APPL, CRITPATH, DURATION, JOBATTR, RESOURCE, SUBAPPL, TAG
• JOB statement operands: for example, CONDITIONAL, CRITICAL, EXTERNAL, LINK, MANUAL, REQUEST, TASK
Chapter 6–Using Applications
ESP-5.4-UG-05 219
If you need to make temporary, one-time changes, such as inserting or bypassing a job, use the Consolidated Status Facility or the AJ command.
Invoking an ESP Application
To invoke an ESP Application via an ESP Event:
• Use an ESP Event to invoke an ESP Application.
The trigger for the Event can be:
• A scheduled date and time• A data-set trigger• A job-monitor trigger• A signal with a scheduled date and time• A manual trigger
An Event can invoke more than one ESP Procedure, but it can only process one Application per Event.
Normally, you should not change an Event to invoke another Application while it is still processing an active Application.
Example: An Event invokes an ESP Procedure to create an Application
The following example demonstrates how to use an Event to invoke an ESP Application.
The Event below runs each weekday at 4 pm. It invokes an ESP Procedure that defines the Application and job relationships. The Event looks like this:
EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE 'CYBER.ESP.PROC(PAYDAILY)'ENDDEF
Section–Invoking an ESP Application
220 ESP-5.4-UG-05
ESP-5.4-UG-05 221
Consolidated Status Facility (CSF)
The Consolidated Status Facility provides a focal point for monitoring and controlling the workload. You will see which jobs have recently executed, are currently running, and are scheduled to execute. You can zoom in on any job to get greater detail, edit JCL, and restart jobs.
Note: You can use CSF for jobs in an Application, but not for jobs submitted directly from an Event.
This chapter contains the following topics:
• Setting up CSF views• CSF fields• Defining a view• Customizing a view• Updating a view• Deleting a view• Selecting views• Commands• Inserting a job• Resubmitting a job• Rerunning multiple jobs• Removing job dependencies• Resetting a time dependency• Bypassing and completing jobs• Adding job dependencies
Section–Setting up CSF views
222 ESP-5.4-UG-05
• Adding a job with a time dependency• Adding a job relationship in an Application• Adding a LINK process• Setting and resetting the user status field• Modifying a Job Resources or Enqueues• Using other commands• Extensions to CSF• Freeform filtering
Setting up CSF views
ESP Workload Manager can handle a large workload at your installation. Different people are interested in different aspects of this workload. One person can be interested in a particular Application, whereas someone else can only be interested in jobs that have failed regardless of the Application to which they belong.
Displaying data
Using the Consolidated Status Facility, you can display only relevant data in the format you want by using views. A view is a customized way of looking at ESP Workload Manager workload. Think of CSF as a kind of scoreboard where:
• Each row represents a workload object, such as a job, link, or task.• Each column represents an attribute of a workload object, such as job number and
status.
Example
For example, one row can represent a job. Each column represents some attribute of the job, such as the job name, Application generation number, Pnode (processing node), job number, and status. An example of what the CSF looks like is shown below. Here the CSF presents the current status of an Application:
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 223
CSF fields
This section describes some special fields that CSF uses.
Pnode fields
A job in an Application goes through different stages in processing. These stages are known as Pnodes. Using CSF you can filter and sort your view by Pnode and display Pnode information.
The following table describes the Pnode fields:
Note: The term Pnode is also used to describe the phases through which ESP Workload Manager tracks a job. The Pnodes described here apply only to jobs in an ESP Application and do not include post-execution phases.
Pnode Description
APPLHOLD Application hold.
APPLWAIT Application waiting on previous generation.
BYPASSED Bypassed.
COMPLETE Completed successfully.
EXEC Executing.
EXTERNAL External job submitted by another Application.
FAIL Completed unsuccessfully.
INPUT Input queue - JES number assigned.
JANCWAIT Job ancestor wait.
MANHOLD Manual hold.
MANSUB Manual submission.
PREDWAIT Predecessor wait.
READY Eligible.
RESWAIT Resource wait.
SANCWAIT SubApplication ancestor wait.
SUBDELAY Submission delayed.
SUBERROR Submission error.
SYSERROR System error.
TASK Task requiring completion.
WAITING Delayed submission time.
Section–CSF fields
224 ESP-5.4-UG-05
SUBDELAY Pnode
The following table provides more information on what you see in the Status field if a job is in the SUBDELAY Pnode.
SUBERROR Pnode
This table provides more information on what you see in the Status field if a job is in the SUBERROR Pnode.
Pnode Status Description
SUBDELAY Submit delayed by REEXEC n
The submission of the job has been delayed.
SUBDELAY Submit delayed, eventset closed
The eventset in which the Event is stored is currently closed. As soon as it is opened, the Event will be scheduled.
SUBDELAY Submit delayed, DS contention
The execution of the Event was delayed because data-set contention. It will be retried at five minute intervals.
SUBDELAY Submit delayed, DS offline The execution of the Event was delayed because a data set is offline. It will be retried at five minute intervals.
SUBDELAY Submit delayed, DS recalled The execution of the Event was delayed because a data set was in a migrated state. A recall has been requested, and the Event will be retried at five minute intervals.
Pnode Status DescriptionSUBERROR Submit eventset I/O error An I/O error has occurred in the
eventset. The Event cannot be processed.
SUBERROR Submit error, Event not found The Event needed by the Application has been deleted. It will need to be redefined.
SUBERROR Submit error, group not defined
The ESP Workload Manager Group definition for the Event has been deleted. It will need to be redefined.
SUBERROR Submit error, applfile not found
The APPLFILE in which the APPL resides could not be found.
SUBERROR Submit error, applfile I/O An I/O error occurred while reading the ATR (Application Tracking Record) from the APPLFILE.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 225
Status fields
You can display the following status fields on CSF:
Setting the User Status field
You can set the user status field when you use either of the following:
• HR command—holds a job with a reason.• SUS command—resets user status for a job.
For example, if you bypass a job you can use the user status field to notify others of the reason for this action. The user status field for a job looks like this:
JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY
ESP Workload Manager does not reset the User Status field.
SUBERROR Submit failed, Event error An error occurred processing the Event. Usually due to a syntax error in the ESP Procedure. An error message has been sent to the Event’s owner. This can also occur when the master ESP Workload Manager ends while trying to submit a job.
SUBERROR Submit error, invalid job name ESP Workload Manager encountered an invalid job name
SUBERROR Submit error, JCL missing The JCL for the job to be submitted was not found in the specified data set, or a data set was not specified for the job.
SUBERROR Submit error, member missing The PDS member in which a JOB’s JCL resides was not found.
SUBERROR Re-execution count exhausted The maximum re-execution count has been reached
SUBERROR Submit error, quit QUIT statement encountered
Pnode Status Description
Status Field Description
User status Displays information set by the user.
System status Displays the system state of a workload object. This is the system state that ESP Workload Manager continues to change during job processing. You cannot change the values in this field.
Status Displays the user status, if set. If the user status is set to null, it displays the system status.
Section–Defining a view
226 ESP-5.4-UG-05
To reset the User Status field to null:
• Issue the SUS command, and enter a period (.) in the field.
Defining a view
The process of defining a view involves replicating an existing view and customizing the new view to your requirements.
To define a view:
1. Select option C from the ESP Workload Manager Main Menu to access CSF.
2. Type V at the Command Line. ESP Workload Manager takes you to the View Definitions panel, which lists any existing views, as shown below.
3. Enter R to the left of a view name to copy an existing view under a new name. ESP Workload Manager takes you to the Replicate View panel.
4. Type the name, an applicable description, and the message you want displayed when there are no items matching the view criteria. The view you selected appears, showing all the jobs that fall within that view definition.
5. Customize the view as described in the next section.
Storing views
ESP Workload Manager stores your view definitions in the ESPCSFA member of your ISPF profile data set. This allows you to use the same view on different systems.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 227
Customizing a view
Once you select a view, you can customize the information presented. Some examples of types of views are:
• Application specific.
• Exception monitoring. For example, you can define a view called TROUBLE to display workload objects requiring intervention.
• Incomplete jobs.
• Overdue jobs.
Commands
You can enter the following commands on the COMMAND line to define the characteristics of a view:
The following sections describe each of these areas.
Filtering information
When you filter information, you are describing the criteria for displaying a job as part of a view. For example, you can filter by Application name to select only those jobs in a particular Application. This information defines the rows in your display.
To filter information:
• Type FI on the CSF Command Line.
This takes you to the Filter Specification panel where you can specify characteristics of the jobs ESP Workload Manager filters into the display. You can filter based on different conditions (for example failed jobs) and based on other criteria such as job name, Application name, and tag.
Command Characteristic
FI Filter information.PR Presentation information.PT Presentation titles.PL Presentation column length.SO Sort the information presented.CO Define color options based on job status.
You can use colors to distinguish workload states.
Section–Customizing a view
228 ESP-5.4-UG-05
Logic applied to multiple conditions
When you select two or more conditions, the resulting selection is controlled based on a logic dependent of:
• The position of the condition. for example, in the same column.• The kind of testing: positive or negative.
The following logic rules apply:
• When the conditions are in the same column:
• With positive testing (Y), ESP Workload Manager uses OR logic• With any negative testing (N), ESP Workload Manager uses AND logic
• When the condition are in different columns, ESP Workload Manager uses AND logic
Examples
To see all incomplete jobs:
• Type N in the Completed field.
To see all incomplete jobs in Application Payroll:
• Type N in the Completed field and PAYROLL in the Appl field.
ESP Consolidated Status: Filter Specification for View,REP COMMAND ===> Enter conditions in this section (N, blank or Y).
Failed ===> Manual ===> Intervention ===> Overdue ===> Links ===> On-request ===> Completed ===> Tasks ===> Requested ===> Res wait ===> External ===> Bypassed ===>
Enter filter criteria in this section, wildcards allowed.
Jobname ===> ===> ===> ===> ===> ===> ===> ===> P-Node ===> ===> ===> ===> Appl ===> ===> ===> ===> Subappl ===> ===> ===> ===> Account ===> ===> ===> ===> Tag ===> ===>
Active after ===> Scheduled before ===> Freeform filter ===> (blank, N or Y)
Column 3Column 2Column 1
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 229
To see all jobs that are incomplete AND not failed:
1. Type N in the Completed field.
2. Type N in the Failed field.
To see all jobs that are complete OR failed:
1. Type Y in the Completed field.
2. Type Y in the Failed field.
Note: Extensive help facilities are available with pop-up menus and hypertext links. Use your HELP key for additional information.
Freeform filtering
Freeform filtering is an extension to the CSF filtering capabilities that allows you a more versatile and customizable method of filtering your ESP Applications. If you cannot use the standard filter panel for your requirements, see “Freeform filtering” on page 247 for information on using this feature.
Presenting information
Once you have filtered the information you want, you can specify the attributes of the filtered jobs you want presented. For example, you can see the job number, Pnode (processing node), and status information for each job. This information defines the columns in your display.
Note: Option O.5 (Set CSF Options) allows you to set different options for CSF. This determines the types of entries displayed when you enter any Presentation command from CSF.
To present information:
1. Type PR on the CSF Command Line. The Presentation Fields panel appears.
2. On this panel, indicate the fields you want displayed by entering a number or letter beside each desired field. The numbers and letters also represent the order you want them to appear across the screen. You can alter the presentation order easily by using numeric and alphabetic characters.
Example
The following example positions the Appl Generation column between the Application and Completion Code columns.
Appl Generation 2AApplication 2Completion Code 3
Section–Customizing a view
230 ESP-5.4-UG-05
Note: ESP Workload Manager always lists the job name in the first column; you cannot change this.
To further define the presentation information, you can change the presentation column lengths and titles.
Presentation titles
The PT command takes you to the Presentation Fields panel. On this panel, you can define the titles that ESP Workload Manager presents for each of the fields listed. This is useful for long titles you want to abbreviate. For example, you can shorten the field title Account number. You can type an abbreviation such as ACCT in the area to the right of the field name Account number. Or you could change the TAG title to reflect how you are using tags in an Application.
Presentation column length
The PL command takes you to the Presentation Fields panel. On this panel ESP Workload Manager lists all the columns used in the CSF view. You can override the default display length of these columns by entering the number of characters you want in the display.
Sorting information
Sorting information defines the order in which ESP Workload Manager presents the rows of information.
To define your sorting requirements:
• Type SO on the CSF Command Line.
The Presentation Fields panel lets you identify the fields by which you want to sort your view, and the order in which you want ESP Workload Manager to sort them. You can select one or more fields to sort on by typing a one or two character string next to the field. The strings are sorted in normal collating sequence (for example, blank before letters before numbers) to determine the sort order of the displayed data.
Note: If a field contains multiple words (for example, STATUS field), the sort occurs only on the first word.
Sort sequence
A Sort sequence field allows you to specify an ascending or descending sort sequence for a field. Type A, or leave the field blank, for ascending order; Type D for descending order.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 231
The following logic rules apply:
• When the conditions are in the same column:
• With positive testing (Y), ESP Workload Manager uses OR logic• With any negative testing (N), ESP Workload Manager uses AND logic
• When the condition are in different columns, ESP Workload Manager uses AND logic
Color options
Color screens allow you to use different colors and highlighting options to indicate job status. You can choose different colored and highlighted options to represent different job status conditions, including:
• Submitted• Overdue• Task awaiting post• Executing• Failed
To select color options:
1. Type CO on the COMMAND line.
2. Complete the fields as required.
Updating a view
You can update a view at any time by selecting the different options for customization, such as FI, PR, and SO.
To update a view:
1. Enter U to the left of the view name you want to update.
2. Type the name, an applicable description, and the message you want displayed when there are no items matching your view criteria in the respective fields.
3. Press Enter. ESP Workload Manager returns you to the View Definitions panel.
Section–Deleting a view
232 ESP-5.4-UG-05
Deleting a view
You can delete an existing view at any time.
To delete an existing view:
1. Enter D to the left of the view name you want to delete.
2. Press Enter. ESP Workload Manager removes the view from the View Definitions panel.
Selecting views
There are two methods for selecting a view.
To delete a view, if you do not know the name of the view you want to select:
1. Type V on the COMMAND line of the Consolidated Status View pane. ESP Workload Manager presents you with a list of views.
2. From the list of views, type S beside the view you wish to select.
To delete a view if you know the name of the view you want to select:
• Type V viewname on the COMMAND line.
Commands
When ESP Workload Manager displays a view, it precedes each job name with an entry field. The codes below represent commands that are valid in CSF. To use one of these commands, type the letter code in the entry field preceding the job name you want to manipulate. ESP Workload Manager issues the appropriate command (for example, LISTAPPL, APPLJOB) in the background.
The next sections list the available commands in different categories.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 233
Working with Applications
The following table lists the available commands for working with Applications.
Working with subApplications
The following table lists the available commands for working with subApplications.
Working with jobs
The following table lists the available commands for working with jobs.
Command Description
AA Releases an Application held by ESP Workload Manager.
CA Completes all workload objects in an Application.
Note: If the Application is not held or waiting, the Application is now complete. Otherwise, the Application is still active.
HA Places Application into ESP Workload Manager hold status.
LA Lists Application.
LAD Dumps Application data.
UWA Removes Application from wait status.
Command Description
AS Releases a subApplication held by ESP Workload Manager.
BYS Bypasses a subApplication.
CS Completes an entire subApplication.
HS Places subApplication into ESP Workload Manager hold status.
LS Lists subApplication.
RDS Readies a subApplication.
RQS Requests a subApplication.
UBS Cancels the bypass of a subApplication.
URS Cancel the requests of a subApplication.
UWS Removes subApplication from wait status.
Command Description
A Releases a job.
$A Issues a JES release command on a z/OS job.
BC Browses COPYJCL.
BJ Browses the last executed JCL.
BY Bypasses a job.
C Completes a job.
$C Cancels a z/OS job in JES.
Section–Commands
234 ESP-5.4-UG-05
$CD Cancels a z/OS job with a dump in JES.
$CP Cancels and purges a z/OS job in JES.
$D Displays the JES status of a job.
DD Drops all predecessor dependencies.
DIN Displays an info record.
DR Drops all resource dependencies.
EC Edits COPYJCL.
EJ Edits the last executed JCL.
H Places a job into ESP hold status.
$H Issues a JES HOLD command on a z/OS job.
HR Places a job into ESP hold status with a reason.
IJ Inserts a job.
IJA Inserts a job after a selected job.
IJB Inserts a job before a selected job.
IW Inserts additional workload definitions into an active Application.
L Displays all dependencies.
L, then D Drops individual dependencies.
LI Displays index entries.
LJ Displays step-level statistics.
LJE Lists detailed information about the specified job.
LR Displays the job resources.
ME Modifies enqueues.
MR Modifies resources.
P Issues a system STOP command on an executing z/OS job, if it is programmed to do so.
QS Quiesces a z/OS job executing on a goal mode system. Requires ESP Workload Manager High Performance Option (HPO).
R Resubmits or restarts a job.
RD Readies a job, removing all predecessors, and submits time dependencies.
RM Reruns multiple jobs.
RP Replies to an AS/400 message.
RQ Requests a job.
RR Views the ESP Encore panels.
Note: Use RX if you want to exclude specifics steps from the range of steps you want to rerun.
RS Resumes the original service class of a z/OS job executing on a goal mode system. Requires ESP Workload Manager High Performance Option (HPO).
Command Description
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 235
Working with other ESP Workload Manager definitions
The following table lists the available commands for working with other ESP Workload Manager definitions.
Inserting a job
Using CSF, you can insert different job types into an active Application. The inserted job runs immediately unless you define a predecessor or insert the job on hold.
You can use two options to insert a job in CSF: IW or IJ.
RT Resets one or more time dependencies.
RX Views the ESP Encore panels
SUS Resets the user status field for a job.
UB Un-bypasses a bypassed job.
UIN Updates an info record.
UR Un-requests a requested job.
UW Un-waits a job from job-ancestor wait (JANCWAIT).
W Selects distributed job options.
WC Cancels a PeopleSoft job.
WSF Retrieve a distributed job spool file.
XP Manually expedites a job with an associated expedite policy, waiting for execution or executing. Requires ESP Workload Manager High Performance Option (HPO).
Command Description
Command Description
BD Browses job documentation.
BE Browses Event.
BP Browses ESP Procedure.
ED Edits job documentation.
EE Edits Event.
EP Edits ESP Procedure.
Section–Inserting a job
236 ESP-5.4-UG-05
IW option
Use IW for inserting:
• Jobs requiring different ESP Encore options• Jobs requiring resources• Distributed jobs with Agent-related statements• Multiple workload objects
This option takes you to the ISPF edit mode where you type the job definitions in the same free-format text used to define workload in an ESP Procedure.
Note: You must specify AFTER and RELEASE statements to define predecessor or successor relationship with other jobs in the Application. If you do not specify AFTER and RELEASE statements, the inserted jobs run immediately.
Example
To add job NEWJOB to an Application with a predecessor of job PAYD006A and a successor of job PAYD008A:
1. Type IW beside any job in the Application; you are taken to the ISPF edit mode.
2. Enter the following:
N_JOB NEWJOB AGENT HPBOX#11 SCRIPTNAME W:\PROD\SCRIPTS\NEWJOB.BAT AFTER PAYD006A RELEASE PAYD008AENDJOB
3. Exit the edit panel (PF3). ESP Workload Manager simulates the job you have inserted.
4. Exit the panel (PF3). A confirmation screen appears. You can proceed with the insertion, edit it, or cancel it. Type 1 to proceed and press Enter.
Your job, NEWJOB, should now appear as part of your CSF display.
IJ option
Use IJ for single jobs with basic requirements. This option present an ISPF panel where the user fills the appropriate fields
Example
To add job NEWJOB to an Application with a predecessor of job PAYD006A and a successor of job PAYD008A:
1. Type IJ beside any job in the Application.
2. Type NEWJOB as the object name on the Insert an Object panel.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 237
3. Type Y for predecessors, Y for successors, and press Enter.
4. Enter PAYD006A as the predecessor job name, and press Enter.
5. Enter PAYD008A as the successor job name, and press Enter.
Your job, NEWJOB, should now appear as part of your CSF display.
Resubmitting a job
Using CSF, you can resubmit a job that has terminated abnormally.
The following rules apply when you resubmit a job from the CSF panel shown below:
• If an override member name is specified (in the Member field), but no override JCL library name is specified (in the Dsname field), then the specified member name is used together with the original JCL library.
• If the JCL library name is specified but the member name is blank, then the specified JCL library is used with the original member name.
• If both fields are blank, the original library name and original member name are used.
• If both fields are filled in, then the specified library name and specified member name are used.
• On a resubmit, the original JCL library is forced into use, even if the same member has been placed in TEMPLIB. However, if an override of the data set is entered on the resubmit panel, this override is explicitly used.
Note: If the job is an INSERTED job, and a JCL Library is supplied on the resubmit, the supplied JCL library will be used and continue to be used on future resubmits. If an asterisk is placed in the JCL library name field, the previously supplied JCL library name will no longer be used for the current and future resubmits.
Section–Rerunning multiple jobs
238 ESP-5.4-UG-05
Note: Once an override library name has been specified on this panel, the Dsname field displays the latest override library name used for the remainder of the CSF session. Once you exit from CSF, this default value is lost.
Rerunning multiple jobs
You can rerun multiple jobs using the RERUNM (RM) command. The command resets specified jobs to the state before they ran. Application Manager schedules a rerun for them as their dependencies are satisfied. By default, the command requests a rerun of the root job and all of its successors. In the resulting CSF screen, you can modify the list of jobs run. You can also request an ESP Encore restart, and enter USER variables and ESP Encore commands.
To rerun multiple jobs from CSF:
1. In CSF, type RM next to the root job of the group of jobs you want to rerun.
2. Press Enter. The Rerun jobs in application screen appears. The root job name has a plus sign (+) appended to it, indicating that all successors will be included. From the screen, you can specify multiple root jobs, request ESP Encore restart, and enter USER variables and ESP Encore commands.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 239
3. Press Enter to update the list of selected jobs.
4. Enter SUB to submit your request.
Removing job dependencies
You can use CSF to remove different dependencies from a job in an Application.
Example
You can:
• Use the RT command to remove time dependencies• Use the DD command to drop all predecessor dependencies• Use the L and then D command to drop individual predecessor dependencies, like
this:
ESP Rerun jobs in application JEFF.17 Command ===>
Review and modify the settings as needed. Press ENTER to see the updated list of selected jobs. When ready, enter SUB to submit the request, CAN or END to abort.
Root jobs ===> A+
Job list data set ==> USER1 ===> USER2 ===> USER3 ===> USER4 ===> Case-sensitive ===> ( Y to preserve the case of USER variables) Encore restart ===> ( Y to select) Encore statements: ===> ( Y to go to the statements panel)
5 jobs will be selected for rerun: A, B, C, D, E
Section–Resetting a time dependency
240 ESP-5.4-UG-05
You can enter a D in front of any predecessor that is not yet completed, to drop a dependency.
JOB PAYD008A
PREDECESSORSD PAY006A NEWJOB
SUCCESSORS PAYR009A
• Use the RD command to ready a job—remove all dependencies except resources
• Use the DR command to remove all resource dependencies
Resetting a time dependency
A job in an Application can have different types of time dependencies. Using CSF, you can reset any of these dependencies.
To change a time dependency for a job:
• Type RT beside the job. The Reset Object Times panel appears.
The following table associates each field on the Reset Object Times panel with the corresponding Application statement.
Example
Suppose a job has an early submission time of 5 pm.
Field ESP Procedure Statement
Earliest submit time DELAYSUB or EARLYSUB
Late submit time LATESUB
Overdue time for job start DUEOUT INPUT
Overdue time for job end DUEOUT EXEC
Abandon execution at ABANDON SUBMISSION
Abandon dependencies at ABANDON DEPENDENCIES
Abandon resources at ABANDON RESOURCES
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 241
To remove this time dependency:
• Type RT beside the job and reset the early submit time with one of the following actions:• Type NOW in the earliest submit time field, and press ENTER• Type RESET in the earliest submit time field, and press ENTER• Blank out the data in the earliest submit time field, and press ENTER
Time at which an ESP Workload Manager object becomes overdue
The time at which an object becomes overdue for submission, start of execution, and end of execution can be displayed on CSF. They are also stored on the ESP Workload Manager history file for inclusion in history reports.
Overdue display in CSF
The following table shows the selection fields in the presentation screen (CSF PR command) and the sort screen (CSF SO command) and the resulting heading in the main CSF screen. You cannot use them as selection criteria in Freeform filters.
The values shown in CSF are in the same format as the Scheduled field, for example, “08.51 TODAY” or “16.30 MON”.
At the time an object becomes overdue for submission, start, or end, the object is marked as overdue, and the value of the appropriate overdue field is set to this time.
If an object's due time for submission, start, or end, is changed (for example, by means of a CSF RT line command), the new time value is compared to the current time. For the due time that was changed:
• If the object is currently marked as overdue and the new due time is in the future, the overdue status is revoked and the corresponding “overdue at” time is cleared.
• If the new due time is in the past, the object is marked as overdue, and the corresponding “overdue at” time is set to this new time.
Overdue for... Field description(Presentation or Sort screen)
CSF screen heading
Submission Became O/D Sub O/D Sub at
Start of execution Became O/D Strt O/D Strt at
End of execution Became O/D End O/D End at
Section–Bypassing and completing jobs
242 ESP-5.4-UG-05
Sample CSF display of an overdue job
ESP4 Consolidated Status: View 1 ------------ Row 1 of 8, Col 1COMMAND ===> SCR ===> CSR
Job Name Scheduled PNode CCode O/D Sub at O/D Strt at O/D End at ___ WAIT3 16.30 MON COMPLETE 0___ WAIT3#5 16.30 MON COMPLETE 0___ WAIT3#5S 16.30 MON COMPLETE 0___ WAIT5 16.30 MON COMPLETE 0___ WAIT5 08.51 TODAY COMPLETE 0 08.52 TODAY 08.53 TODAY 08.56 TODAY___ WAIT5 09.00 TODAY COMPLETE 0 09.01 TODAY 09.02 TODAY 09.05 TODAY___ WAIT5 10.17 TODAY COMPLETE 0 10.19 TODAY___ WAIT5 10.28 TODAY EXEC - 10.30 TODAY
Sample LCSF output of an overdue job
Note: For this sample, the overdue job information is shown in bold.
20040513 103802+0400 . . /MAIN/RFE1214A.7/WAIT5 STATE COMPLETE Conditions(COMPLETE) Status(COMPLETED AT 08.59 13 MAY) SystemStatus(COMPLETED AT 08.59 13 MAY)Jobno(19974) Account(?) ASeq(0005) Scheduled(08.51.00 THU 13 MAY 2004) UpdatedOn(08.59.03 THU 13 MAY 2004) ReaderTime(200405130854) StartTime(08.54.02 THU 13MAY 2004) EndTime(08.59.05 THU 13 MAY 2004) Cmpc(CC 0) OrigJno(19974) ExecJno(19974) Jes(2) Class(A) Priority(7) ASID(0022) SID(SYSA) SrvClass(JES) Sysname(SYSA) Sysplex(SYSAPLEX) OrigNode(CYBJES) ExecNode(CYBJES) AvgRT(5) OvdSubmitAt(08.52.02 THU 13 MAY 2004) OvdStartAt(08.53.02 THU 13 MAY 2004) OvdEndAt(08.56.02THU 13 MAY 2004)
Overdue history reporting
You can use the OVDSUBAT, OVDBEGAT, and OVENDAT fields to report overdue time history. For details see “History reporting fields” on page 277.
Bypassing and completing jobs
Using CSF, you can bypass and complete jobs.
Bypassing a job
You can bypass a job up to the time it becomes ready for submission by typing BY next to it. ESP Workload Manager updates the status field to BYPREQ indicating that a bypass has been requested. When the job’s predecessors are complete, the job is bypassed, and the successor jobs released. You can unbypass a job by typing UB next to the job anytime before the job actually becomes bypassed.
Completing a job
When you complete a job, you are telling ESP Workload Manager to consider the job complete. Successors are immediately released, including those in other Applications. You can complete a job by typing C next to the job, at any time.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 243
You cannot reverse the completion of a job. If you mistakenly complete a job, you can insert another occurrence of the job (qualified for uniqueness) with the required dependencies, but successor jobs can have already been released.
Adding job dependencies
Using CSF, you can add different dependencies to a job in an Application.
Example
For example, you can:
• Use the RT command to add time dependencies• Insert a task as a predecessor or successor• Insert a link with predecessor A and successor B to add a relationship between jobs
A and B
Adding a job with a time dependency
To add a job with a delayed submission time:
1. Insert the job on hold (IJ command, job on HOLD? ==> Y).
2. Reset the submission time for the job (RT command, earliest submit time ==> time).
3. Release the job from hold (A command).
Adding a job relationship in an Application
To add a relationship between two unrelated jobs in an Application:
1. Type the IJ command beside any job in the Application.
2. Enter the name of the link in the job name field.
3. Type A in the predecessor field.
4. Type B in the successor field.
5. Specify the job type as L (link).
When job A completes successfully, ESP Workload Manager completes the link and submits job B.
Section–Adding a LINK process
244 ESP-5.4-UG-05
Example
For example, you can add a link to an Application to cause job B to wait for job A to complete successfully. Visually, the dependencies look like this:
Adding a LINK process
Note: If the Application contains an APPLEND workload object, the hold count of the APPLEND workload object is incremented when a LINK process is inserted and becomes a predecessor to the APPLEND workload object. However, the HC data in the scoreboard is not immediately updated.
To add a link that processes commands:
1. Edit the Application definition to define the link and specify the commands you want processed. For example:
JOB EXTRA LINK PROCESS SEND 'THIS IS AN INSERTED LINK PROCESS' U(*)ENDJOB
2. Insert a link with the same name into the Application—specify job name, job type, and dependencies.
When the link becomes ready, ESP Workload Manager processes the commands.
Setting and resetting the user status field
To set the user status field:
Use either of the following:
• HR command to hold a job with a reason• SUS command
A B
LINKME
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 245
Example
For example, if you bypass a job, you can use the user status field to notify others of the reason for this action. The user status field for a job looks like this:
JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY
ESP Workload Manager does not reset the user status field. To reset the user status field to null, issue the SUS command and enter a period (.) in the field.
Modifying a Job Resources or Enqueues
You can use the LR command to display the resources and enqueues associated with a job. You can also use the MR and ME commands to modify the resources and enqueues associated with a job.
LR command
The LR command displays the resources and enqueues associated with a job.
For each resource, the following are displayed:
• The resource name
• The resource quantity
• The resource availability indicator:
• ? means that the resource is not defined.• Y means that the resource is available; in the case of local resource Y is only
displayed if the resource has gravity or if the requested quantity of the resource is available on a CPU of the current node.
• N means that the resource is not available on any CPU.• X means that the requested quantity of the resource is available on a CPU of a
node other than the current node and that the resource does not have gravity.
For each enqueue, the following are displayed:
• The enqueue name• Whether the enqueue is shared or exclusive
You can use two subcommands with the LR command for resources:
• L displays more information about a specific resource. You can also press Enter.• X displays more information about all resources
Section–Modifying a Job Resources or Enqueues
246 ESP-5.4-UG-05
ME command
The ME command allows you to change one or more enqueues and to add new enqueues. The ME command is equivalent to the JOBENQ command and provides the same operands.
For each enqueue, the following are displayed and updated automatically if you make changes:
• The enqueue name• Whether the enqueue is shared or exclusive
MR command
Using the MR command
The MR command allows you to change the quantity of a resource and to add new resources for a job. The MR command is equivalent to the JOBRES command.
For each resource, the following are displayed and updated automatically if you make changes:
• The resource name
• The resource quantity
• The resource availability indicator:
• ? means that the resource is not defined.• Y means that the resource is available; in the case of local resource Y is only
displayed if the resource has gravity or if the requested quantity of the resource is available on a CPU of the current node.
• N means that the resource is not available on any CPU.• X means that the requested quantity of the resource is available on a CPU of a
node other than the current node and that the resource does not have gravity.
You can use two subcommands with the MR command:
• L displays more information about a specific resource.• X displays more information about all resources
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 247
Using other commands
You can also enter the following commands on the COMMAND line of the Consolidated Status View panel:
Another way of processing ESP Workload Manager commands is to type ESP followed by the command you want processed. The following example issues a TRIGGER command from the command line.
ESP TRIGGER PROD.MORE_WORK ADD
Additional information
For more information on using these modes, see “Getting Started” on page 31.
Extensions to CSF
The Consolidated Status Facility can have extensions written in REXX. Your installation can add its own commands and enhance or replace the standard commands.
Example
For example, your installation can write commands to:
• Trigger an Event• Edit JCL prior to job submission• Provide confirmation panels• Force user status information• Access SDSF
Check with your administrator to see if any customized commands are available to you.
Freeform filtering
Freeform filtering is an extension to the CSF filtering that allows you a more versatile and customizable method of filtering your ESP Applications. You have the option to
Command Invokes ESP Workload Manager in ...
ESP Line mode.
ESPPM Page mode.
Section–Freeform filtering
248 ESP-5.4-UG-05
filter your Applications using the standard filter panel or to use the Freeform filter for scenarios that cannot be handled using the standard panel.
Example
For example, you can filter based on the following criteria:
• Jobs that have started and ended between specific times• Jobs on a critical path• Completion codes for jobs within a subApplication• Jobs within an Application that have a restart step
Entering a freeform filter
To enter a freeform filter:
1. Type FI on the CSF command line. The Filter Specification panel appears.
2. Type Y in the Freeform filter ===> field. This places you in ISPF Edit, where you can enter a Freeform filter, as shown below.
(COMPLETE OR INCOMPLETE)
Filter criteria syntax
term [[{AND|OR} term] ...]
Note: The AND operator takes precedence over the OR operator. You can nest expressions within parentheses to force precedence or to make your filter easier to understand.
Term syntax
(keyword[(v1[,v2])] reloperator value)|condition
Operand Description
term See “Term syntax” on page 248.
AND Connects two terms when both terms must be true.
OR Connects two terms when at least one term must be true.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 249
Examples of substring notation
For example, assume that JOBNAME contains the string PRODJOB. The following table demonstrates the outcome that results when you specify certain substring notations:
Operand Description
keyword Identifies the kind of workload objects on which you want to filter, such as Applications or workload object names. See “Keywords:” on page 250 for the list of valid keywords.
v1 Refers to the starting position if you want to use portions of a value, rather than its full contents. (Substring notation.)
Character positions start at one.
If v1 is negative, the starting position is relative to the last non-blank character of the variable. For example, -1 refers to the last character.
v2 Refers to the number of characters if you want to use portions of a value, rather than its full contents. (Substring notation.)• If v2 is omitted, it defaults to the remaining length of the variable.• If v2 is positive, it specifies the number of characters required.• If v2 is negative, it represents the remaining length less v2.
reloperator Specifies the operation, such as EQ for equal to. See “Relational operators” on page 253 for the list of relational operators.
value Specifies what you want Application name to be equal to, such as PAYROLL.
condition Specifies the condition. For example, if you want to see all Applications that are incomplete, the condition INCOMPLETE. See “Conditions” on page 254 for the list of available conditions.
Specification Result
JOBNAME PRODJOB
JOBNAME(1,4) PROD
JOBNAME(5) JOB
JOBNAME(5,1) J
JOBNAME(-1,1) B
JOBNAME(1,7) PRODJOB
JOBNAME(1,-3) PROD
Section–Freeform filtering
250 ESP-5.4-UG-05
Examples of freeform filter
Keywords:
Enter the following filter To see...
CRITICAL_PATH Workload objects on the critical-path.ON_REQUEST AND REQUESTED On-request workload objects that have
been requested.APPL EQ 'PAYROLL' AND RESTART_STEP_PRESENT
Workload objects in the PAYROLL Application that have a restart step.
JOBNAME(1,1) EQ 'P' AND JSBYTE EQ 'F'
Failed workload objects that start with P.
CMPC EQ 'S222' AND SUBAPPL EQ 'PAYJOBS'
Workload objects with a completion code of S222 in the PAYJOBS subApplication.
(JOBNAME(1,3) EQ 'PAY' OR JOBNAME(1,3) EQ 'ACC')AND APPL EQ 'FINANCE'
Workload Objects that start with PAY or ACC and belong to an Application called FINANCE.
JOBNAME(1,4) EQ 'TEST' AND APPL EQ 'TESTAPPL' AND INCOMPLETE
Workload Objects in Application TESTAPPL that start with TEST and are not complete.
APPL EQ 'CYBER' AND OVERDUE_START AND REQUEST
Workload Objects in Application CYBER whose execution start time is overdue and that are requestable.
JOBNAME(1,3) EQ 'CYB' AND STIME> TIME(11AM TODAY)
Workload Objects whose names start with CYB that started later than 11 am today.
WOBTYPE EQ 'HP' AND APPL EQ 'BILLING'
All HP workload objects in the BILLING Application.
JOBNAME(1,1) EQ 'X' AND APPL EQ 'MYAPPL' AND NOT_REQUESTED
Workload Objects that start with X in Application MYAPPL that have not been requested.
(JOBNAME EQ 'TESTJOB' OR JOBNAME(1,1) EQ 'A' OR JOBNAME(1,2) EQ 'BC') AND (APPL EQ 'MYAPPL' OR APPL (1,2) EQ 'PA') AND OVERDUE_START
Workload Objects called TESTJOB or whose names start with the characters A or BC and are contained within Application MYAPPL or any Application whose name starts with PA and whose execution start time is overdue.
EVENT EQ 'CYBER MYJOB' Workload Objects in Applications that have been generated by the Event CYBER.MYJOB.
Keyword Description
ACCOUNT Account number
AGENT Agent name
APPL Application name
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 251
APPLFILE Application file
APPLGEN Application generation
APPLSEQ Application definition sequence
APSLOT Application file slot number
ASFLAG Application status flag
ASID Execution address space identifier of the job
AUTH Authorization string
AVGRUNTIME Average execution time
CLASS Job class
CMPC Completion code
DMANAGER Distributed manager name
ETIME Job end time
EVENT Event name. The Event name consists of a prefix and a descriptive name. You must includes spaces so the prefix is eight characters long and the descriptive name starts in the ninth character position. The descriptive name can be 16 characters maximum. Specifying EVENT displays all jobs in Applications that have been generated by the Event.
EXECJNO Execution job number. It may be different from the submission job number if the job executes on a different JES node from the node where the job was submitted.
EXECNODE Execution JES node of the job
HC Hold count
HWRM High water reel mounts
HWCM High water cart mounts
JAFLAG Job attribute flag
JOBNAME Job name
JOBNO Job number
JSBYTE Job status byte as followValue Description
C Completed.
D Dependency.
E Executing.
F Failed.
I Input.
P Post-process.
R Resources.
JSFLAG Job status flag
LONGNAME Long name of the job
Keyword Description
Section–Freeform filtering
252 ESP-5.4-UG-05
MAXRUNTIME Maximum allowable execution time
MINRUNTIME Minimum allowable execution time
NETID DJC/JES3 network ID
NSCM Non-specific cart mounts
NSRM Non-specific reel mounts
ORIGJNO Submission job number. It may be different from the execution job number if the job executes on a different JES node from the node where the job was submitted.
ORIGNODE JES node where the job was submitted.
PGN Performance group number of the job if the execution system is in WLM compatibility mode
PNODE Processing node
PRIORITY Job priority
QUAL Qualifier
RDRTIME Time the job was submitted to a JES reader
SADFLAG SAD flags
SCBCYCLE Scoreboard cycle
SCBENTRY Scoreboard entry number
SCBTOKEN Scoreboard token
SCHED Scheduled time
SMFID Execution SMF identifier of the job
SRVCLASS Service class of the job if the execution system is in WLM goal mode
STATUS System status
STIME Job start time
SUBAPPL SubApplication name
SYSNAME Execution system name of the job
SYSPLEX Execution sysplex name of the job
TAG Tag
TRSLOT Trakfile slot number
USTATUS User status
WOBTYPE 2-character workload object type:Value Description
AE ApplEnd
AM AGENT_MONITOR
AX Aix_Job
A4 AS400_Job
CM CPU_Mon
DM DB_Job
Keyword Description
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 253
Note: For any of the time fields, (for example, ETIME, SCHED, and STIME), you need to use the TIME function in a comparison. For example, STIME > TIME(11AM TODAY). You can compare against any time in a format that ESP Workload Manager recognizes.
Relational operators
Relational operators include the following standard operators:
DT DSTRIG
EX EXTMON
FM File_Trigger
FT FTP_JOB
HM DISK_Mon
HP HPUX_Job
IM IP_Mon
LJ Linux_Job
LM EVENTLOG_Mon
NC NCR_Job
NT NT_Job
OV OpenVMS_Job
PM PROCESS_Mon
PS PS_Job
SJ Sun_Job
SM SERVICE_Mon
SP SAP_Job
SQ Sequent_Job
TA Tandem_Job
TM TEXT_Mon
UJ Unix_Job
Keyword Description
>= GE greater than or equal
<= LE less than or equal
> GT greater than
< LT less than
= EQ equal
¬= NE not equal to
Section–Freeform filtering
254 ESP-5.4-UG-05
Conditions
Condition Description
ALL All workload objects.
APPL_COMPLETE Application execution is complete.
BYPASSED Workload object execution has been bypassed.
COMPLETE Workload object execution is complete.
CRITICAL_PATH Workload object is on a critical path.
EXTERNAL Workload object is external to an Application.
INCOMPLETE Workload object execution is not complete.
INTERVENTION_REQUIRED Workload object execution requires manual intervention.
INTVRQ Workload object execution requires manual intervention.
LINK Workload object is a LINK.
MANUAL_TASK Workload object is a manual task.
NOT_APPL_COMPLETE Application execution is not complete.
NOT_BYPASSED Workload object execution has not been bypassed.
NOT_CRITICAL_PATH Workload object is not on a critical path.
NOT_EXTERNAL Workload object is not an external.
NOT_INTERVENTION_REQUIRED Workload object execution does not require manual intervention.
NOT_INTVRQ Workload object execution does not require manual intervention.
NOT_LINK Workload object is not a LINK.
NOT_ON_REQUEST Workload object is not defined as REQUEST.
NOT_OVERDUE_END Workload object execution end time has not been exceeded.
NOT_OVERDUE_START Workload object execution start time has not been exceeded.
NOT_REQUESTED Workload object has not been specifically requested.
NOT_RESTART_STEP_PRESENT Workload object does not have a restart step.
NOT_TASK Workload object is not a TASK.
ON_REQUEST Workload object is defined as REQUEST.
Chapter 7–Consolidated Status Facility (CSF)
ESP-5.4-UG-05 255
Note: Common conditions are available on the Filter Specifications screen and may not require a freeform filter.
OVERDUE_END Workload object execution end time has been exceeded.
OVERDUE_START Workload object execution start time has been exceeded.
REQUESTED Workload object has been specifically requested.
RESTART_STEP_PRESENT Workload object has a restart step.
TASK Workload object is a TASK.
Condition Description
Section–Freeform filtering
256 ESP-5.4-UG-05
ESP-5.4-UG-05 257
Job Documentation
The ESP Workload Manager job-documentation facility lets you create a complete and centralized definition of each one of your jobs. You can document a job’s entire requirements, including its predecessors and successors, its schedule frequency, all the resources it requires, and so on. Users and operators can retrieve this information easily using the JOBINFO command or through the Consolidated Status Facility.
Job documentation can also be used for informational purposes.
This chapter contains the following topics:
• Contents of job documentation• Control information• User description• Creating job documentation• Using the jobs option• Updating job documentation• Using job documentation• Using the control information• Referencing job-documentation members• Overriding job documentation• Using job documentation for qualified jobs• Using job documentation for links and tasks• Retrieving information• Converting existing job documentation• Other uses of job documentation
Section–Contents of job documentation
258 ESP-5.4-UG-05
Contents of job documentation
A job-documentation entry is a member of a partitioned data set (PDS). Each entry consists of the following information in two parts, either of which is optional:
Comment
Either section can include comments within /* */ pairs.
Control information
The control information comes first in your job-documentation entry and follows a very specific format, as shown below:
job name: JOBDOC
Example
For example, to specify the start of job documentation for the job PAYJOB1, enter the job name followed by a colon, a space, and the JOBDOC keyword like this:
PAYJOB1: JOBDOC
Using CLANG and REXX
Control information uses the same job-statement information you use in an ESP Procedure. You can also use CLANG and REXX within job documentation to handle conditional or complex requirements.
Job documentation entry Explanation
Control information Information that ESP Workload Manager will use directly when processing a job, such as the JCL library, job dependencies, and schedule frequency.
User description Other information you want to store about a job. This can include ABEND codes, messages, restart instructions, job severity, and so on.
Chapter 8–Job Documentation
ESP-5.4-UG-05 259
Example control information
Control information is specified as shown below:
PAYJOB: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP,GT,4)RUN WORKDAYSIF MONDAY('MONDAY') THEN DELAYSUB 7PMELSE DELAYSUB 6PM
Storing requirements
You can store all requirements for a job in a job-documentation library. Alternatively, you can also store some requirements in ESP Procedures and others in job documentation members. For example, you can use job documentation to store only the resource requirements for a job and use ESP Procedures to store scheduled frequency, job relationships, and time dependencies.
User description
The user-description section of your job documentation must begin with the keyword USERDESC as a heading. After that, the rest of the data can be formatted as you choose. You can divide the user description section into paragraphs and identify each paragraph with a label. You can then retrieve selected information by label name. ESP Workload Manager supplies the following standard labels:
ESP Workload Manager Label
Use this Label to…
Function Describe what the job does.
Programmer Identify the programmer of the job.
Abends Identify ABEND codes and recovery activity. A number sign (#) can precede each ABEND code. This lets you request display information about a specific ABEND code when retrieving information with the JOBINFO command.
Messages Identify message codes and recovery activity. A number sign (#) can precede each message ID code. This lets you request display information about a specific message ID when retrieving information with the JOBINFO command.
Section–Creating job documentation
260 ESP-5.4-UG-05
Customized labels
You can use any of your own labels as long you observe the following guidelines:
• A label consists of a word, 1 to 16 characters long, followed by a colon and at least one blank.
• A label must be the first entry on a line.• A label can precede any type of information, such as report distribution
information, severity codes, and escalation Procedures.• Each paragraph ends with the next label or the end of the PDS member.• You can specify as many labels as you wish.
Example
In the example below, the USERDESC keyword identifies this as the user-description area of job documentation. Each of the five user description paragraphs begins with a label (for example, FUNCTION, PROGRAMMER, ABENDS, MESSAGES, SEVERITY) followed by a colon (:).
USERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 – warning#Z001 - user not authorizedSEVERITY: 3
Creating job documentation
Create one entry for each job you want to document. Use a member name equal to the job name; otherwise, you will need to override this in an ESP Procedure. To create job documentation, use either ISPF edit or the jobs option of the ESP Workload Manager Main Menu.
Chapter 8–Job Documentation
ESP-5.4-UG-05 261
Using the jobs option
The jobs option (option J on the Main Menu) provides panels for creating job documentation members. These panels do not provide fields for all possible data, but they can assist you in specifying some of your requirements. You can then add to these requirements using ISPF edit.
To create a job documentation member for a job:
1. Select option J.
Note: The first time you select this panel, you must specify the name of the pre-allocated PDS file to store job documentation. This PDS then becomes your default.
2. Complete the job name and other control information on the Job Specifications screen, as shown below.
3. Enter 1 on the command line to access the Job User Description panel.
4. Complete any user description information, as shown below.
Section–Updating job documentation
262 ESP-5.4-UG-05
5. If you have DJC or JES3 installed, you can enter 2 on the command line to define DJC/JES3 specifications. See the ESP Workload Manager Advanced User’s Guide for more information.
6. Press PF3 twice to return to the Main Menu.
Result
You have now created and stored job documentation. ESP Workload Manager stores the information in a member of the job documentation PDS with the same name as the job name. The information is stored as shown below.
PAYJOB1: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP1 GT 4)USERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 - warning#Z001 - user not authorized
Points to note about the example shown
In this example, notice the following:
• The first line identifies the job name using a label and specifies JOBDOC.• The first descriptive section contains control information.• The user description section is headed by the keyword USERDESC. It is defined
in free format, using indentations to improve readability only.
Updating job documentation
You can return to the PDS member where your job documentation entry resides and update the information using either ISPF edit or the ED command from the Consolidated Status Facility.
Chapter 8–Job Documentation
ESP-5.4-UG-05 263
Note: Do not use the Job Specifications panel (Option J) to update existing job documentation. This option is only for initially setting up your documentation. When you try to use this panel to update an existing entry, you will receive an error message indicating the member already exists.
Updating the previous example
For example, you could update the previous example to:
• Insert IF-THEN-ELSE statements to allow for different delayed submission times• Insert a RUN statement to identify the job’s frequency• Add a user field to identify the job’s severity
Resulting job documentation
The job documentation now looks like this:
PAYJOB1: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP1 GT 4)RUN WORKDAYSIF TODAY('MONDAY') THEN DELAYSUB 7PM ELSE DELAYSUB 6PMUSERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 - warning#Z001 - user not authorizedSEVERITY: 3
Using job documentation
You can use job documentation in the following ways:
• To control processing using the control information directly• To retrieve information
Section–Using the control information
264 ESP-5.4-UG-05
Using the control information
To use the control information directly, you must use the DOCLIB statement in an ESP Procedure. This statement identifies the name of your job documentation library.
ESP Procedure
The ESP Procedure below shows a DOCLIB statement pointing to the library CYBER.JOBS.DOC that contains documentation on jobs specified in this Procedure.
APPL PAYJOBSJCLLIB 'CYB.JCL.CNTL'DOCLIB 'CYBER.JOBS.DOC'JOB PAYJOB1ENDJOBJOB PAYJOB2ENDJOBJOB PAYJOB3ENDJOB
ESP Workload Manager then uses the job-documentation information to establish dependencies and any other requirements. To invoke this Procedure, use an INVOKE command in an Event.
Relationship with Event and Procedure
The following diagram shows the relationship between an Event, an ESP Procedure, and a job documentation library. When ESP Workload Manager executes the Event, the INVOKE command invokes the ESP Procedure. The DOCLIB statement in the ESP Procedure identifies the name of the job documentation library. ESP Workload Manager retrieves the job documentation (if it exists) for each job identified by a JOB statement. This includes jobs submitted as part of the ESP Procedure, links, tasks, qualified jobs, external jobs, and manual jobs.
A: JOBDOCRUN DAILYRELEASE B
Job DocumentationLibrary
DOCLIB . . .JOB AINVOKE . . .
ESP ProcedureEvent
Chapter 8–Job Documentation
ESP-5.4-UG-05 265
Referencing job-documentation members
DOCMEM operand
ESP Workload Manager retrieves job documentation by job name. If you want to reference a job-documentation member with a name other than the job name, use the DOCMEM operand when you identify the job in an ESP Procedure.
In this example, job A uses a job documentation member called SPECIAL.
JOB A DOCMEM(SPECIAL)
Overriding job documentation
Job information can be specified in different places. These include ESP Procedures, job documentation, and tracking models. As a result, it is possible to have conflicting information specified for a job. Therefore, you must ensure ESP Workload Manager knows which information to use.
Rules
ESP Workload Manager uses the following rules:
Example
For example, if you specify a HISTFILE as below, it overrides the HISTFILE specified in a tracking model for the job.
APPL PAYJOBSDOCLIB 'CYBER.JOBS.DOC'JCLLIB 'CYBER.JOBS.JCL'JOB PAYJOB1 HISTFILE HIST2 RUN DAILYENDJOB
Type of information …overrides corresponding
ESP Procedure information… … job documentation information.
Job documentation information… …tracking model information.
Section–Using job documentation for qualified jobs
266 ESP-5.4-UG-05
Temporary override
You can temporarily override the control information specified in job documentation from within an ESP Procedure by specifying the new control information you want to use. In this example, the RELEASE statement for PAYJOB1 overrides any RELEASE statement specified in the job documentation for the job.
DOCLIB 'CYBER.JOBS.DOC'APPL PAYJOBSJOB PAYJOB1 RELEASE NEXTJOBENDJOB
Using job documentation for qualified jobs
Job qualifier
ESP Workload Manager uses the eight-character job name to access job documentation. If you want to use job documentation for jobs defined with a job qualifier, you can do one of the following:
• Use the DOCMEM operand when you define the job in the ESP Procedure, and specify the name of the member used for the job’s documentation.
• Use IF-THEN-ELSE logic in the job-documentation member to check the qualifier of a job and process different statements. Use the ESPAPQUAL symbolic variable for jobs in an Application. Use the ESPJQUAL variable for jobs in a DJC/JES3 network.
Each approach is illustrated below.
DOCMEM method
This method shows you how you use different job documentation members for different qualified versions of a job. Job A.RUN1 references member A1; job A.RUN2 references member A2.
JOB A.RUN1 DOCMEM(A1)JOB A.RUN2 DOCMEM(A2)
IF-THEN-ELSE method
This method uses a common job-documentation member for job A. ESP Workload Manager processes different statements based on the job qualifier.
If the qualifier is RUN1, the job runs daily and releases job Y.
If the qualifier is RUN2, the job runs on workdays and releases job Z.
Chapter 8–Job Documentation
ESP-5.4-UG-05 267
Visually, the dependencies look like this:
Job-documentation member
The job-documentation member looks like this:
A: JOBDOCIF ESPAPQUAL='RUN1' THEN DO RUN DAILY RELEASE YENDDOIF ESPAPQUAL='RUN2' THEN DO RUN WORKDAYS RELEASE ZENDDO
Using job documentation for links and tasks
You can use job documentation for links and tasks that you have identified in an ESP Application.
A.RUN1
Y
A.RUN2
Z
Section–Using job documentation for links and tasks
268 ESP-5.4-UG-05
Example: Documenting links and tasks
In this example, the Application consists of a job, a task, and a link. The Application identifies their names, and the job documentation library contains the processing requirements, as shown below:
Example: Documenting a job and a link
This example uses job documentation to store resource requirements. In this Application, there are two jobs: MEMOBACK and MEMOBACK.MSG. The specifications are that:
• The first job requires one unit of a resource called DB2TAB.• The second job is a link that sends a message when job MEMOBACK completes
successfully.
IF statement
ESP Workload Manager uses the same job-documentation member for each job because it does not check the qualifier when accessing job documentation. To prevent the link from using the resource, the job-documentation member for MEMOBACK uses an IF statement to assign a resource requirement to the unqualified job only.
DOCLIB 'CYBER.JOBS.DOCJCLLIB 'CYBER.JOBS.DOCAPPL ABCJOB AJOB CHECK TASKJOB ENDAPPL LINK PROCESSENDJOB
A: JOBDOCRUN DAILYRELEASE CHECK
CHECK: JOBDOCRUN DAILYSEND 'CHECK REPORT FOR JOB A'
ENDAPPL: JOBDOCRUN DAILYRELEASE CHECK
ESP ProcedureJob Documentation Member
Chapter 8–Job Documentation
ESP-5.4-UG-05 269
The ESP Procedure and job documentation member look like this:
Retrieving information
You can retrieve job-documentation information using the Consolidated Status Facility (CSF) or the JOBINFO (JI) command from the operator console, the ESP Workload Manager command processor, or ISPF interface (Line mode or Page mode). You can display all information for a job or display selected information as identified by fields and labels.
Using CSF
You can access job documentation information directly from CSF with the following commands.
ESP Workload Manager retrieves the information from the data set identified by the DOCLIB statement in an ESP Procedure. Using this method, ESP Workload Manager retrieves all information on the job. You cannot select individual fields.
Using TSO
If a job is submitted by an ESP Procedure, ESP Workload Manager searches the job-documentation library identified by the DOCLIB statement. If a job-documentation library was not identified in the ESP Procedure, or the job was not scheduled from an ESP Procedure, the JOBINFO command looks for the file name JOBDOC. If the file is allocated, it is opened and searched for a member corresponding to the job name. The JOBDOC file can consist of a concatenation of several partitioned data sets.
DOCLIB 'CYBER.JOBS.DOC'JCLLIB 'CYBER.JOBS.JCL'APPL MEMOJOB MEMOBACK RUN WORKDAYS RELEASE MEMOBACK.MSGJOB MEMOBACK.MSG LINK PROCESS RUN WORKDAYS SE 'MEMOBACK IS DONE' U(*)ENDJOB
MEMOBACK: JOBDOCIF ESPAPQUAL=' ' THEN + RESOURCE (1,DB2TAB)
Job DocumentationMember
ESP Procedure
Command Explanation
BD Browses job documentation
ED Edits job documentation
Section–Retrieving information
270 ESP-5.4-UG-05
To use the JOBINFO command in TSO you must pre-allocate a file to your TSO session, either in LOGON Procedure or LOGON CLIST. You can dynamically allocate this file during a session by issuing the following TSO command:
ALLOC FI(JOBDOC) DA('data set name') SHR
Using an operator console
The console version of the JOBINFO command requires the JOBDOC file in the ESP Workload Manager started task Procedure. You can issue the following commands from an operator console, or from Page mode, respectively:
F ESP,JOBINFO jobname or OPER JOBINFO jobname
Examples: Retrieving job-documentation information
Some examples of retrieving job-documentation are shown below.
• To display all information about PAYJOB1, type:
JOBINFO PAYJOB1
• To display ABEND information for PAYJOB1 as well as the contents of the user defined field SEVERITY, type:
JI PAYJOB ABENDS FIELD(SEVERITY)
• To display PAYJOB1’s successor (RELEASE) and JCL data set (DATASET) information, type:
JI PAYJOB1 RELEASE DATASET
Retrieving job-documentation information
The following table summarizes where and how you can retrieve job-documentation information:
Origin Command Retrieved from
Consolidated Status Facility BD or ED Library specified in the ESP Procedure.
Page mode or line mode JOBINFO DOCLIB in ESP Procedure or JOBDOC DD allocated to your TSO session.
Page mode or line mode OPER JOBINFO JOBDOC DD allocated to the ESP Workload Manager started task.
Operator console F ESP,JOBINFO JOBDOC DD allocated to the ESP Workload Manager started task.
Chapter 8–Job Documentation
ESP-5.4-UG-05 271
Converting existing job documentation
Methods for converting documentation
You can already use some form of job documentation and want to convert it to ESP Workload Manager. There are two methods for converting documentation. The method you use depends on how you want to use your existing job documentation.
• If you want to use ESP Workload Manager to retrieve your existing job documentation in its present format, you can insert a USERDESC label in each job-documentation member.
• If you want ESP Workload Manager to modify the data to allow retrieval of information by label name, you can use the GENDOC command.
To retrieve your existing job documentation through ESP Workload Manager:
1. Update each member to include the USERDESC heading at the beginning of the information. An example is shown below:
Before:
THIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH.FREQUENCY: LAST WORKDAY OF THE MONTH
After:
USERDESCTHIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH.FREQUENCY: LAST WORKDAY OF THE MONTH
2. Allocate the job documentation files, with the DD name of JOBDOC, to your TSO session or to the ESP Workload Manager started task. You can then use the JOBINFO command to extract information.
To convert an existing PDS job documentation library into an ESP Workload Manager documentation library:
• Use the GENDOC command in Line mode, Page mode, or in batch.
The GENDOC command identifies the input data set, the members to be copied, and the output data set. You can also identify changes you want to make when the old documentation converts.
Section–Converting existing job documentation
272 ESP-5.4-UG-05
Commands
You can use the following commands:
New data set
For each selected member of the input data set, ESP Workload Manager generates a corresponding member in the output data set. ESP Workload Manager automatically adds the following two lines to each member of the new data set:
jobname: JOBDOCUSERDESC
GENDOC can insert appropriate paragraph labels in the converted user-description section to allow retrieval of information by label.
Example: Using GENDOC to convert job doc.
Below is a set of sample conversion instructions for ESP Workload Manager:
GENDOC JOBDOC.DATA ESP.JOBDOC.DATA LEV(A-,B-) SNUMREMOVE '**'LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINELABEL 'RESTART PROCEDURES' 'RESTART:' BEFORE GO
The above example tells ESP Workload Manager to:
• Copy all members beginning with A and B from the data set JOBDOC.DATA to the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right-hand eight columns of each source member record.
• Not copy any lines containing **.
• Replace any lines starting with SYSOUT REVIEW with the character string SYSOUT_REVIEW.
• Overlay the semicolon on any line beginning with STEP. The semicolon is positioned after the third character following the string STEP.
• Place the label RESTART: on its own line before any line starting with the string RESTART PROCEDURES.
• Proceed with the copy process.
Command Explanation
REMOVE Identifies lines that are not to be copied to the output data set.
LABEL Alters or replaces lines in the output data set, or inserts lines at different locations.
GO Indicates that all specifications are complete and that the copy process should proceed
Chapter 8–Job Documentation
ESP-5.4-UG-05 273
Message at the end of the conversion
ESP Workload Manager issues the following message at the end of the conversion to indicate the number of members in the input and output data sets.
ESP000 nnn MEMBERS IN SOURCE DATASET, mmm MEMBERS PROCESSED
Other uses of job documentation
You can use ESP Workload Manager job-documentation facility for more than just jobs. You can also create documentation libraries for documenting such items as:
• Startup and shutdown Procedures• Telephone numbers• Trouble-shooting Procedures
Remember to allocate the JOBDOC file and use proper labels.
Example: Storing phone numbers
This example shows you how to use a job-documentation member to list phone numbers for software support. A label identifies the name of each product so that you can retrieve the information easily.
USERDESC/* LISTS PHONE NUMBERS FOR SOFTWARE SUPPORT */ESP: REGULAR (905) 479-4611 AFTER HOURS (416) 287-5021CICS:(905) 123-4567...
If you call the above member SUPPORT, you can retrieve support phone numbers for ESP Workload Manager by typing the following:
JI SUPPORT FIELD(ESP)ESP:REGULAR (905) 479-4611AFTER_HOURS (416) 287-5021
OutputInput
Section–Other uses of job documentation
274 ESP-5.4-UG-05
ESP-5.4-UG-05 275
Creating Reports
You can get information about your jobs in several ways. You can generate a report, flowchart a jobstream, view CSF, or use tracking commands to give you the job information you require.
This chapter contains the following topics:
• History reporting• Structuring the report• Reporting fields• Field formats• Invoking the report function• Specifying input criteria• Specifying output criteria• Ending the report definition• ESP Workload Manager history reporting fields• Accumulating reporting fields• Reporting on scheduled activity• Generating data• Extracting data• Generating scheduled versus actual report• Generating projected versus actual data• Extracting tape information• Using job mapping• Job-mapping data set
Section–History reporting
276 ESP-5.4-UG-05
• Generating data for the report• Producing a job-activity report• Producing a job-descendent report• Putting it all together• ESP Workload Manager FLOWDOC• Flowcharting• Generating flowcharts using MS Project• Generating flow charts with ESP Workload Manager and Timeline
Reporting in batch
When reporting in batch, a hyphen at the end of a line indicates a continuation. If you are using a hyphen as a mask, follow it with a semi-colon (for example, PAY-;).
History reporting
ESP Workload Manager has a powerful and versatile reporting facility that you can use at any time to generate details about the progress of jobs. Information in the job history files, defined by the administrator or installer, provide the basis for the reports. You can generate reports online or in batch
Note: You can report only on jobs, started tasks, and TSO users that the ESP Workload Manager administrator requests ESP Workload Manager to track.
Additional information
For more information on how to specify which of these ESP Workload Manager will track, see the ESP Workload Manager Installation and Configuration Guide.
Structuring the report
You can structure a report definition in several sections, some of which are optional. Start each section of a report definition by a command, and then code each section in free format and in any sequence.
Chapter 9–Creating Reports
ESP-5.4-UG-05 277
Sections of a report
The sections that make up a report are:
• Input source selection• Selection criteria• Display format• Sort options• Titles and footings• Section break definitions• Subtotals
Content of the report
For most reports, you usually specify input source selection, selection criteria, and display format. You can make reports as detailed as you want, describing such aspects as:
• Job name• Completion date• Application name• CPU time• Number of print lines
Reporting fields
You can select, sort, and display as many as 70 fields using the CRITERIA, SORT, and DISPLAY commands. With these commands, you can create a report containing as much detail as you want.
History reporting fields
You can find the list of ESP Workload Manager history reporting fields and their definitions in “ESP Workload Manager history reporting fields” on page 289.
Section–Field formats
278 ESP-5.4-UG-05
Field formats
Field categories
Using ESP Workload Manager, you can display or base selection criteria on the following field categories:
• Character• Numeral• Time• Elapsed time• CPU times• Dates.
Character fields
These include JOBNAME, ACCOUNT, CLASSID, and PGMR. These fields are always left justified. In the CRITERIA section, you can select character fields by specifying the full field value or part of it. If you specify a part of the field, you must include wildcard characters asterisk or hyphen (see “About this guide” on page 1.)
Example
The following example selects any jobs that begin with ZA and have a B in the fourth character position of the name. In this example, ESP Workload Manager would also select any occurrences of the job ABC.
CRITERIA JOBNAME EQ ZA*B OR JOBNAME EQ ABC
Numeric fields
These fields include APPLGEN, EXCP, EXEC#, JOBNO, RC, RRJOBNO, STEPS, SUBJOBNO, TRANSACT, and TRANSRES. ESP Workload Manager displays them right justified with leading zeros translated into blanks. You can increase the default length for these fields by specifying whatever length you want on the DISPLAY statement or by defining a longer title.
Example
The following example displays DASD EXCP counts to nine digits because the title length (DISK-EXCP) is nine characters. The title for the tape EXCP counts is TAPE I/O but ESP Workload Manager displays the counts to a length of nine, as specified. Blanks on the left fill the field. ESP Workload Manager justifies title and numeric fields on the right.
DISPLAY DEXCP 'DISK_EXCP' TEXCP 9 'TAPE I/O'
Chapter 9–Creating Reports
ESP-5.4-UG-05 279
Comparisons
You can also make comparisons against numeric fields in the CRITERIA section. ESP Workload Manager supports the following comparison operators: AND and OR.
Example
This example selects all jobs that perform I/O to tape, but use less than 1000 tape EXCPs.
CRITERIA TEXCP>0 AND TEXCP<1000
Time fields
Time appears in the 24-hour clock format. The default is hh.mm.ss, but you can omit the seconds by specifying a display size of five. The RDRON, EXECST, ENDT, and COMPT fields fall into this category. You can use any date and time format valid on a SCHEDULE command when you want to select these fields.
Example
The following example selects all jobs submitted since March 3rd, 2001.
CRITERIA RDRON GT MARCH 3RD 2001
Elapsed time fields
OVDSTART, INPUT, TOTALQT, and OVDCOMPT are examples of elapsed times. ESP Workload Manager displays them in the following forms:
You can select elapsed times by requesting them in the same formats as those that appear above.
ESP Workload Manager Form
Explanation
ss Seconds, where ss is the number of seconds when the elapsed time is less than 1 minute.
mmMss Minutes and seconds, when the elapsed time is less than 1 hour. For example: 10M53 (10 minutes and 53 seconds).
hhHmm Hours and minutes, when the elapsed time is less than 99 hours. For example: 16H14 (16 hours and 14 minutes).
hhhHm Hours and first digit of minutes, when the elapsed time is greater than 99 hours but less than 999 hours.
hhhH Hours, when the elapsed time is more than 999 hours.
Section–Field formats
280 ESP-5.4-UG-05
Example
The following example selects jobs that were in execution for one or more minutes, yet completed execution within five hours.
CRITERIA EXECQT GE 1M00 AND EXECQT LT 5H00
CPU time fields
This includes CPUTIME, SRBTIME, and TCBTIME. They appear in the form mm:ss.th, where mm is the number of minutes, ss is the number of seconds, and th are the tenths of a second.
Example
The following example selects all jobs that consumed between 10 seconds and 5 minutes of CPU time.
CRITERIA CPUTIME>10 AND CPUTIME<5:00
Date fields
These fields include RDRONDATE, EXECSDATE, ENDDATE, PURGDATE, SCHEDDATE, and COMPDATE. By default, they appear in the form xxxddmmmyy, where:
You can change the way date fields are displayed in a report using the DATEFORM command within the report. See “Specifying output criteria” on page 284.
You can use any date and time format valid on a SCHEDULE command when you want to select these fields as input criteria to your report.
Example
The following example selects all jobs that were submitted since 9 am on
March 29th, 2000.
CRITERIA RDRONDATE GT 9AM MARCH 29TH 2000
The date fields also allow for some sorting by storing time information. When you request sorting by a date field, ESP Workload Manager sorts by date and time. If you specify the following, ESP Workload Manager reports only on those jobs with a reader-on time and date of midnight, August 23, 2000.
CRITERIA RDRONDATE EQ AUGUST 23RD 2000
Field Symbol Explanation
xxx first three characters of the day of the week.
dd day of month number.
mmm first three characters of the month name.
yy last two digits of the year.
Chapter 9–Creating Reports
ESP-5.4-UG-05 281
Invoking the report function
To invoke the reporting function:
Use any of the following methods:
• Type the REPORT command from Page mode or Line mode.• Execute PGM=ESP in batch and specify the REPORT command.• Use the LOAD command to load a report definition from a data set.• Use the REPORT command of the ESP Workload Manager command processor.
When you enter the REPORT command, you are in report mode and can now structure your report.
Specifying input criteria
The input for a report consists of:
• A history file• A time range• Selection criteria
This section describes each of these areas.
To identify the history file:
• Use the HISTFILE command to specify the history files you want to use as the input source.
If you omit the history file you want to use, ESP Workload Manager scans all the history files you can access. Your ESP Workload Manager Administrator determines history-file access.
The following specifies a history file called HIST1:
HISTFILE HIST1
To use a history file other than current:
• Use the INPUT command to request that ESP Workload Manager read in other records from a data set other than an active history file.
You can use any VSAM KSDS, ESDS, or non-VSAM sequential data set as input. The data records must have the exact format of the ESP Workload Manager history file records. You will find this option most useful with files you create using the COPY statement.
Section–Specifying input criteria
282 ESP-5.4-UG-05
If the ESP Workload Manager subsystem is not functioning when the system generates a report, use the INPUT statement rather than the HISTFILE statement. The sub-system does not have to be active to use the INPUT statement.
To specify the time range:
• Use the FROM and TO commands to specify a time range for the history-file search.
In this way, you can limit your search based on the job submission time in the history file. If you do not specify an end time, ESP Workload Manager uses the current time. You can use any valid schedule command that resolves to a date and time, for example:
FROM 10AM TODAYFROM 8AM YESTERDAY TO 8AM TODAYFROM 9AM TODAY LESS 1 WEEK TO 9AM YESTERDAY
To specify the selection criteria:
• Use the CRITERIA command to specify selection criteria.
The syntax is:
CRITERIA field operator value
To view all the values possible for field, see “ESP Workload Manager history reporting fields” on page 289.
You can specify several field, operator, and value groups. To be selected, all criteria elements must be matched. Use the OR connective to provide alternatives. If you do not specify a CRITERIA command, ESP Workload Manager reports on all records that meet the time-range criteria.
You can use the following operators in either their symbol or letter form in a CRITERIA command. You cannot use the equal sign (=).
If you want to compare a field to a null string, use a blank enclosed in single quotes, as in ' '.
Note: You can specify several criteria sections in a single report, using multiple CRITERIA commands; ESP Workload Manager selects a job if it satisfies any criteria section.
Symbol Form Letter Form Explanation
>= GE Greater than or equal.
<= LE Less than or equal.
< LT Less than.
> GT Greater than.
¬= NE Not equal to.
EQ Equal.
Chapter 9–Creating Reports
ESP-5.4-UG-05 283
Example 1
The following example selects only those jobs that belong to the PAYROLL Application:
CRITERIA APPLSYS EQ PAYROLL
Example 2
The following example selects only those jobs that have been restarted:
CRITERIA RRJOBNO NE 0
Example 3
The following example selects a job if it belongs to the PAYROLL Application and the job name starts with P.
CRITERIA APPLSYS EQ PAYROLL JOBNAME EQ P-
Example 4
The following example selects a job if it belongs to the PAYROLL Application or the job name starts with P.
CRITERIA APPLSYS EQ PAYROLLCRITERIA JOBNAME EQ P-
Or you could use OR to separate the requirements:
CRITERIA APPLSYS EQ PAYROLL OR JOBNAME EQ P-
Example 5
The following example selects all jobs that ended between 8 am and 4 pm on May 17, 2001:
CRITERIA ENDDATE GE 8:00 MAY17,2001 -ENDDATE LE 16:00 MAY17,2001
Example 6
The following example selects all jobs that were submitted by ESP Workload Manager outside of an ESP Application:
CRITERIA ESPSUB EQ YES AND APPLSYS NE ' '
Section–Specifying output criteria
284 ESP-5.4-UG-05
Example 7
The following example selects only those jobs for reporting that either:
• Have names beginning with ABC
• Have two character names that begin with A
• Perform tape I/O
• Have no more than 10000 EXCPs to DASD devices
CRITERIA TEXCP GT 0 OR DEXCP LT 10000CRITERIA JOBNAME EQ ABC- OR JOBNAME EQ A*
Example 8
The next example selects only those jobs that:
• Have more than 10000 EXCPs
• Or have more than 1 minute of CPU time
The commands look like this:
CRITERIA EXCP GT 10000CRITERIA CPUTIME GT 1:00
Specifying output criteria
To specify an output data set:
• Use the COPY command if you want to specify an output data set or file to receive all or subsets of the job history records read in from the input source.
ESP Workload Manager writes to any format sequential data set. If a data set is new and you have not yet specified a record format for it, ESP Workload Manager uses the following default: LRECL=4096, RECFM=VBS, BLKSIZE=6144.
To separate data into different files:
• Use the COPY option when you want to separate data in a history file into one or more files.
The example below sends records to tape after they are 12 weeks old:
REPORTHISTFILE HIST1CRITERIA RDRON GT TODAY LESS 12 WEEKSCOPY SELECT FILE(DISK1)COPY REJECT FILE(TAPE1)
Chapter 9–Creating Reports
ESP-5.4-UG-05 285
To specify the date format:
• Change the default using the DATEFORM command.
History reporting displays date fields in DDMMMYY format by default.
The options are as follows:
Note: This setting only affects the date format you use to display fields in a history report; it does not affect the date format you use on a CRITERIA command, and it does not affect the date format used in schedule criteria.
Example: DATEFORM
In the following example, the date format is set to YMD. Any date fields, such as EXECSDATE (start date), displayed in the report will be in YYYYMMMDD format.
DATEFORM YMD
To specify fields to display:
Use the DISPLAY command to specify the fields you want to display. Then you have the option to define titles.
Entering field names
Once you start the DISPLAY section, you can enter several field names one after the other. Separate each by a blank or a comma, along with optional lengths and titles. ESP Workload Manager places the fields you specify on the report detail line in the order you specified them. To view all the values possible for field, see “ESP Workload Manager history reporting fields” on page 289.
DATEFORM Results Example
DMY This is the default.
Day DDMMMYY MON14MAY01
JULIAN Day DDDYY MON13401
YM Day YYYYMMM MON200105
YMD Day YYYYMMMDD MON20010514
MDY Day MMMDDYY MON051401
Section–Specifying output criteria
286 ESP-5.4-UG-05
Example
In the following example, ESP Workload Manager:
• Displays both job name and the reader-on time and date, along with their default titles
• Restricts the reader-on date to five characters
• Displays the tape and disk EXCP count to five and six digits respectively
• Includes special title segments for the last two fields
DISPLAY JOBNAME, RDRON, RDRONDATE 5, TEXCP 'TAPE' -'EXCPS' DEXCP 6 'DISK' 'EXCPS'
To specify the sort criteria:
• Use the SORT option to specify the fields you want to sort and whether you want the sort sequence to be ascending or descending.
The default is ascending. The following example sorts data by decreasing use of CPU time. ESP Workload Manager displays the data in sequence of ascending DASD EXCP counts.
SORT CPUTIME D DEXCP
To specify other formats:
• Use the BREAK command to define the points in the report where you want to:• Force a new page• Print any number of blank lines• Produce a subtotal
You can specify several break elements in a break section. ESP Workload Manager subtotals only meaningful fields such as CPUTIME and DEXCP, but not JOBNO. The subtotal detail line has the same format as the normal detail line, except that it always has the word subtotal starting in column one. The next column displays the number of items ESP Workload Manager sub-totaled. The preceding information occupies the first 14 character positions on the line. When you create a detail line, do not place any fields you want ESP Workload Manager to subtotal in the first two columns.
Chapter 9–Creating Reports
ESP-5.4-UG-05 287
Example: Specifying a format
In the following example:
• When the first three characters of the first account number change, ESP Workload Manager prints a subtotal and starts a new page.
• When the first two characters of the job name change, ESP Workload Manager leaves one blank line.
DISPLAY JOBNAME JOBNO ACCOUNT RDRON DEXCP TEXCPSORT ACCOUNT JOBNAMEBREAK ACCOUNT 3 EJECT SUBTOTALBREAK JOBNAME 2 SPACE 1
Ending the report definition
To end the report definition:
• Use the ENDR command to mark the end of a report definition and initiate the report generation.
Example: Reporting on an Application
This example reports on all jobs in an ESP Application called PAYROLL that have changed status since 8 am today. The SETWIDTH command sets the width of the report to 80 characters.
REPORT SETWIDTH 80 FROM 8:00AM TODAY CRITERIA APPLSYS EQ PAYROLL DISPLAY JOBNAME CMPC EXECST EXECSDATE ENDT ENDDATE CPUTIMEENDR
Sample output from the above commands is shown below.
JOBNAME JOBNO COMP CODE
EXEC START
START DATE
EXEC END END DATE
CPU TIME
PAYD001A 2221 0 11.56 MON 14MAY01 12.02 MON 14MAY01 0:01
PAYD002A 2227 0 12.02 MON 14MAY01 12.02 MON 14MAY01 0:00
PAYD003A 2226 0 12.02 MON 14MAY01 12.02 MON 14MAY01 0:00
PAYD004A 2229 0 12.02 MON 14MAY01 12.07 MON 14MAY01 0:04
PAYD100A 2232 0 12.07 MON 14MAY01 12.07 MON 14MAY01 0:00
PAYD006A 2233 0 12.08 MON 14MAY01 12.08 MON 14MAY01 0:00
PAYD008A 2234 SOC1 12.08 MON 14MAY01 12.08 MON 14MAY01 0:00
PAYD008A 2270 SOC1 12.57 MON 14MAY01 12.57 MON 14MAY01 0:00
PAYD008A 2271 0 12.58 MON 14MAY01 12.58 MON 14MAY01 0:00
PAYD009A 2272 0 12.58 MON 14MAY01 12.58 MON 14MAY01 0:00
PAYD010A 2273 SOC1 12.59 MON 14MAY01 12.59 MON 14MAY01 0:00
Section–Ending the report definition
288 ESP-5.4-UG-05
Example: Reporting in batch
In the example below, the first four lines represent JCL statements, and the remaining lines define a report. The report includes information on jobs whose first account number begins with PAY that ESP Workload Manager has tracked from 6 pm yesterday until 8 am today.
//REPORT JOB ...//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=X//SYSIN DD *REPORTHISTFILE HIST1FROM 6PM YESTERDAY TO 8AM TODAYCRITERIA ACCOUNT EQ PAY-;DISPLAY JOBNAME, JOBNO, ACCOUNT, DEXCP, TEXCPSORT ACCOUNT BREAK ACCOUNT 4 EJECT SUBTOTALENDR
Note: When the reporting job is executed in batch, a hyphen at the end of a line indicates a continuation. If you are using a hyphen as a mask, follow it with a semi-colon (for example PAY-;).
PAYD010A 2275 0 12.59 MON 14MAY01 12.59 MON 14MAY01 0:00
PAYD011A 2276 0 12.59 MON 14MAY01 13.04 MON 14MAY01 0:01
SUBTOTAL (13) 0:06
TOTAL (13) 0:06
JOBNAME JOBNO COMP CODE
EXEC START
START DATE
EXEC END END DATE
CPU TIME
Chapter 9–Creating Reports
ESP-5.4-UG-05 289
Example: Writing report output to a data set
The following example writes a history report to a new data set. The report includes information on jobs with names beginning with CYB that ESP Workload Manager has tracked since 4 pm on the current day.
//HISTRPT JOB (CYB1000),'HIST.REPORT',CLASS=A,MSGCLASS=O,//NOTIFY=CYB01//STEP1 EXEC PGM=ESP,REGION=4000K,PARM='SUBSYS(ES51)'//STEPLIB DD DSN=CYB8.SCP5100.SSCPLINK,DISP=SHR//SYSPRINT DD DSN=CYB2.NF.HISRPT,DISP=(NEW,CATLG,DELETE),// DCB=(RECFM=FB,LRECL=133,BLKSIZE=13300),// UNIT=SYSDA,SPACE=(CYL,(1,1),RLSE),VOL=SER=WORK01//SYSIN DD *REPORTHISTFILE HIST1CRITERIA JOBNAME EQ CYB-;FROM 4PM TODAYDISPLAY JOBNAME JOBNO CMPC MXCMPC EXECST EXECQT CPUTIMESORT JOBNAME DBREAK JOBNAME 4 EJECT SUBTOTALENDR
ESP Workload Manager history reporting fields
The following are history reporting fields.
Field Explanation
ACCOUNT Specifies the job first account operand, can also be specified as ACCOUNT1.
ACCOUNT2 Specifies the job second account operand.
ACCOUNT3 Specifies the job third account operand.
ACCOUNT4 Specifies the job fourth account operand
AGENT Specifies the Agent name as stated in the AGENT statement.
ALLOCQT Specifies the allocation queue time. This is the total time the job spends in the allocation process (for example waiting for tape mount).
APPLGEN Specifies the Application generation number (absolute).
APPLSYS Specifies the Application name for jobs defined to an Application; can also be specified as APPL.
APPLTAG Specifies the tag associated with a job in an Application.
ASID Specifies the address-space identifier of an executing z/OS job.
AUTHSTR Indicates job authority string that you can use to verify ownership of the job.
AVGRUNT Specifies the job average execution time.
Section–ESP Workload Manager history reporting fields
290 ESP-5.4-UG-05
CCFAIL Indicates whether or not the job failed because of condition codes. The field has a value of YES if the job failed because of a condition code, and the value is NO otherwise.
CLASSID Specifies the ESP Workload Manager class to which you defined the Event.
CMPC Specifies the job completion code, including return code, user abend code, or system abend code. For more information on the different completion codes, go to the last page of the History Reporting Field topic.
COMPDATE Specifies the job completion date: it is the date on which the job completed its last post-processing phase. If the job has no post-processing phases, the completion date is the same as the purge date. (See note at the end of the table.)
COMPT Specifies the job completion time: it is the time at which the job completed its last post-processing phase. If the job has no post-processing phases, it is the same as the purge time. (See note at the end of the table.) COMPT is set equal to the ENDT field for distributed workload.
CPUTIME Specifies the total CPU time, including both SRBTIME and TCBTIME.
DEXCP Specifies the total EXCP count to DASD devices.
ENDDATE Specifies the date at the end of execution.
ENDT Specifies the time at the end of execution.
ESPSUB Indicates whether or not the job was submitted by ESP Workload Manager. It has a value of YES if the job was submitted by ESP Workload Manager (either through an Event or as part of an Application); otherwise, it has a value of NO.
EXCP Specifies the total EXCP count for the job during the execution phase.
EXEC# Specifies the number of times the job has executed as part of a particular generation of an Application.
EXECNODE Specifies the JES node name where a z/OS job is executing or waiting for execution (for example, LOCAPPL operand).
EXECQT Specifies the elapsed time for the job during the execution.
EXECSDATE Specifies the date at the start of the execution.
EXECST Specifies the execution start time. For example, 08:26.
EXECSYS Specifies the system where the job executed. This is not set until the job is purged regardless of your tracking options.
EXEJOBNO Specifies the JES job number where the job executed. This value is different from the SUBJOBNO value when the job executes on a node different from the node it was submitted to.
Field Explanation
Chapter 9–Creating Reports
ESP-5.4-UG-05 291
GROUP Specifies the prefix of the Event associated with the job, if ESP Workload Manager submitted it.
INFOREC Specifies the Info/System record number.
INPUTQT Specifies the length of time the job was in the input queue.
INSYS Specifies the system the job was submitted on. This is not set until the job is purged regardless of your tracking options.
JOBCLASS Specifies the JES execution class.
JOBNAME Specifies the name of the job.
JOBNO Specifies the job number. This value is the submit job number before and after the job executes and the execution job number during the time the job executes.
JOBQUAL Specifies the ESP Workload Manager job qualifier.
LINES Specifies the number of print lines.
LONGNAME Specifies the long name of a job.
MAXRUNT Specifies the job longest expected execution time.
MINRUNT Specifies the job shortest expected execution time.
MSGFAIL Indicates whether or not the job failed because of an ESP Workload Manager SYSMSGS command. The field has a value of YES if the job terminated because of the ESP Workload Manager SYSMSGS facility, and the value is NO otherwise.
MXCMPC Specifies the maximum completion code for the job.
MXRC Specifies the highest return code from any step in the job. This is a numeric field. For more information, see “Numeric fields” on page 296.
NCI Specifies the number of card images submitted to the internal reader.
NETID Specifies the network identifier for a job belonging to a DJC/JES3 job network.
NSTM Specifies the number of nonspecific tape mounts (scratch tapes) for the job.
ORIGNODE Specifies the job original or submission JES node.
OUTSYS Specifies the system the job was purged on. This is not set until the job is purged regardless of your tracking options.
OVDBEGAT Specifies the time at which the job last became overdue for start.
OVDCOMP Specifies the amount by which the job was overdue at the time of completion. The criteria for being late are defined by the DUEOUT OUTPUT statement in an ESP Procedure or in a job tracking model.
OVDEND Specifies the amount of time by which the job was late in ending execution. The criteria for being late are defined by the DUEOUT EXEC statement in an ESP Procedure or in a job tracking model.
Field Explanation
Section–ESP Workload Manager history reporting fields
292 ESP-5.4-UG-05
OVDENDAT Specifies the time at which the job last became late in ending execution.
OVDSTART Specifies the amount of time by which the job was late in starting execution. The criteria for being late are defined by the DUEOUT INPUT statement in an ESP Procedure or in a job tracking model.
OVDSUBAT Specifies the time at which the job last became overdue for submission.
PGMR Specifies the contents of the programmer name field for the job.
PGN Specifies the performance group number of an executing z/OS job. This applies only to jobs running in a compatibility mode system.
POSTQT Specifies the elapsed time spent in post-output processing phases.
PRINTQT Specifies the length of time the job remained in the print queue.
PRIORITY Specifies the job JES execution priority. It has a value between 0 and 15.
PURGDATE Specifies the date of job purge.
PURGT Specifies the purge time. PURGT is set equal to the ENDT field for distributed workload.
RC Specifies the return code from the last step executed in the job. This is a numeric field. For more information, see “Numeric fields” on page 296.
RDRON Specifies the time at which ESP Workload Manager read the job into the system. RDRON is set equal to the EXECST field for distributed workload.
RDRONDATE Specifies the date at job submit time. This field also includes the time for sorting purposes but not for display purposes.
RRJOB Specifies the name of job being rerun or null.
RRJOBNO Specifies the job number of the most recent execution of a resubmitted job. This field only has a value for a job that is being rerun by ESP Workload Manager (for example, a job that has been resubmitted via an explicit AJ command or the R line command in CSF). If the job is not a rerun, this field is set to zero.
RTYPE Specifies the run type as follows:Value Explanation
P A primary run—set for a normally scheduled execution or by a TRIGGER REPLACE command.
T An extra run—set by a TRIGGER ADD command.
D An execution caused by data-set activity.
R A rerun.
SCHEDDATE Specifies the scheduled date.
SCHEDT Specifies the scheduled time.
Field Explanation
Chapter 9–Creating Reports
ESP-5.4-UG-05 293
SID Specifies the SMF identifier of system that z/OS job is executing on.
SPTM Specifies the number of specific (for example, non-scratch) tape mounts for the job.
SRBTIME Specifies the CPU time consumed while in SRB mode.
SRVCLASS Specifies the service class of an executing z/OS job. This applies only to jobs running in a goal mode system.
STATUS Specifies the job status. There are four possible values:Value Explanation
INPUT Defines submitted jobs not yet started.
STARTED Defines jobs currently in execution.
COMPLETE Defines jobs that completed all phases of processing.
ENDED Defines jobs that completed execution but did not finish all phases of processing.
STEPS Specifies the number of job steps.
SUB# Specifies the submission number for a job in an Application.
SUBAPPL Specifies the subApplication identifier.
SUBJOBNO Specifies the JES job number where job was submitted. This is useful when a job is submitted on one system and routed to another system where a different JES job number is assigned.
SUNITS Specifies the job service units, as defined by the SRM.
SYSABD Specifies the system abend code or null.
SYSNAME Specifies the name of the system in the sysplex that z/OS job is executing on.
SYSPLEX Specifies the name of the sysplex that z/OS job is executing on.
TAPEM Specifies the number of tape mounts for the job.
TAPEW Specifies the maximum number of tape drives allocated to a job at one time. Note that SPTM and NSTM may not add up to TAPEW. SPTM and NSTM represent numbers of tape mounts. TAPEW counts the number of different tape drives that were used at one time. For example, if a job-step calls for three specific tapes, one at a time, on the same drive, then TAPEW will be one, but SPTM will be three.
TCBTIME Specifies the CPU time consumed while in TCB mode.
TEXCP Specifies the total EXCP count to tape drives.
TMODEL Specifies the name of the ESP Workload Manager tracking model that was used to track the job.
TOTALQT Specifies the total elapsed time for the job.
Field Explanation
Section–ESP Workload Manager history reporting fields
294 ESP-5.4-UG-05
TRANSACT Specifies the total time for which a transaction is active. In the case of a batch job, this is approximately equal to the total execution times for the programs contained in the job. It is measured in units of 1024 microseconds.
TRANSRES Specifies the total time during which a transaction was resident in real memory. This is often identical to the transaction active time (TRANSACT), but can differ since it does not include any time during which the task was swapped out of real memory. It is measured in units of approximately one millisecond, or more precisely, units of 1024 microseconds.
TRUSER Specifies the user ID that triggered the Event. It resolves to the user ID that manually triggered an Event, and is blank otherwise.
UABEND Specifies the user abend code or null.
WDFAIL Indicates whether or not there was a WTO-detected JCL error. The field has a value of YES if the job terminated prior to starting execution, and the value NO otherwise. These errors are caused by such activities as an early (pre-execution) JCL error, certain security-system verification errors, and a cancellation of a job while it is on the JES input queue.
Field Explanation
Chapter 9–Creating Reports
ESP-5.4-UG-05 295
ESP Workload Manager may not track jobs through to the output stage at your installation. For such jobs:
• The times specified in the COMPDATE and COMPT fields refer to when the jobs complete successfully.
• The LINES, POSTQT, PRINTQT, PURGDATE, and PURGT fields are not applicable.
WOBTYPE Specifies the short name of workload object types:.Value Description
AE ApplEnd
AM AGENT_MONITOR
AX Aix_Job
A4 AS400_Job
CM CPU_Mon
DM DB_Job
DT DSTRIG
EX EXTMON
FM File_Trigger
FT FTP_JOB
HM DISK_Mon
HP HPUX_Job
IM IP_Mon
LJ Linux_Job
LM EVENTLOG_Mon
NC NCR_Job
NT NT_Job
OV OpenVMS_Job
PM PROCESS_Mon
PS PS_Job
SJ Sun_Job
SM SERVICE_Mon
SP SAP_Job
SQ Sequent_Job
TA Tandem_Job
TM TEXT_Mon
UJ UNIX_Job
Field Explanation
Section–ESP Workload Manager history reporting fields
296 ESP-5.4-UG-05
Numeric fields
The RC and MXRC fields contain strictly numeric values. For cases where a completion code is non-numeric (for example JCL errors, system or user abends, CCFAIL), special values are inserted in these fields as an indication of the actual completion status.
The following table lists the completion codes:
Field length change
All fields that represent Time previously displayed minutes and hours. As of ESP Workload Manager 5.1, these displays now include seconds. This causes an increase in the field length for coding purposes. Knowing this is important if you produce a history report and use another program (for example SAS) to pull data out of the report.
Type of Error Value
System ABEND Abend code + 10000 (abend code converted to decimal first)
User ABEND Abend code + 20000
SYSERROR 30000 (actual completion status unavailable)
CCFAIL 30001 (terminated by CCFAIL or CCCHK logic)
JCLERROR 30002
RUNNING 32767 (job still executing)
Chapter 9–Creating Reports
ESP-5.4-UG-05 297
Example: History report showing overdue jobsREPORTINPUT DATASET('CYB1.TONYT540.HISTFILE')CRITERIA JOBNAME EQ WAIT5 OR JOBNAME EQ CALCFROM MAY 1 2004DISPLAY JOBNAME,JOBNO,APPLSYS,OVDSUBAT,OVDBEGAT,OVDENDAT,OVDENDSORT EXECSDATE EXECST JOBNAMEENDRCYBERMATION ESP VER 5.4.0 BATCH INTERFACE 10.06.25 THURSDAY MAY 13TH,
JOBNAME JOB APPLSYS OVERDUE OVERDUE OVERDUE OVERDUE NO SUBMIT SINCE START SINCE END SINCE END FORWAIT5 52329 - - - -WAIT5 52701 TESTSAD - - - -WAIT5 57042 TESTSAD - - - -WAIT5 57780 RFE1214A 5MAY04 13.00 5MAY04 13.01 5MAY04 13.04 3M02WAIT5 57998 RFE1214 - - 5MAY04 14.56 3M01WAIT5 58016 RFE1214 - - 5MAY04 15.06 1M13WAIT5 58178 TESTSAD - - - -WAIT5 60836 RFE1214 - - 6MAY04 10.39 3M01WAIT5 60846 RFE1214A 6MAY04 10.38 6MAY04 10.39 6MAY04 10.42 3M03WAIT5 60894 RFE1214 - - 6MAY04 11.01 3M01WAIT5 60961 RFE1214 - - 6MAY04 11.10 3M01WAIT5 60997 TSTRFES - - 6MAY04 11.19 1M02WAIT5 61218 RFE1214 - - 6MAY04 12.40 3M02WAIT5 61231 RFE1214A 6MAY04 12.48 6MAY04 12.49 6MAY04 12.52 3M01WAIT5 61270 - - - -WAIT5 61291 - - - -WAIT5 61404 - - - -WAIT5 61683 TESTSAD - - - -WAIT5 63421 TESTSAD - - - -WAIT5 11567 TESTSAD - - - -WAIT5 19967 TESTSAD - - - -WAIT5 19974 RFE1214A 13MAY04 08.52 13MAY04 08.53 13MAY04 08.56 3M00WAIT5 20007 RFE1214A 13MAY04 09.01 13MAY04 09.02 13MAY04 09.05 3M01
Accumulating reporting fields
Totals are produced for the following reporting fields:
• ALLOCQT • NSTM • STEPS
• CPUTIME • OVDCOMP • SUNITS
• DEXCP • OVDEND • TAPEM
• EXCP • OVDSTART • TCBTIME
• EXECQT • POSTQT • TEXCP
• INPUTQT • PRINTQT • TOTALQT
• LINES • SPTM • TRANSACT
• NCI • SRBTIME • TRANSRES
Section–Reporting on scheduled activity
298 ESP-5.4-UG-05
Reporting on scheduled activity
The scheduled-activity facility reports on the scheduled workload for a time period in the future. You can generate online and hardcopy reports about scheduled jobs, links, tasks, and manual jobs. The reports provide a variety of job statistics that indicate processing requirements. The data the report generates uses average execution results from tracked jobs to provide a true picture of what you can expect during the next scheduled occurrence of the jobs.
Note: This facility reports on job workload that is not yet active. Jobs in an active Application are excluded, for example.
To set up schedule forecasting:
1. Allocate a sequential data set to store scheduled activity data. See the SADGEN command in the ESP Workload Manager Reference Guide.
2. Generate data on scheduled jobs.
3. Extract data to create a report.
4. Update data to obtain a scheduled versus actual report. (This is an optional Procedure.)
Generating data
To generate data that you can use for scheduled-activity reporting, ESP Workload Manager must simulate all the Events and ESP Procedures it would execute in a specified period. ESP Workload Manager does this by executing the ESP Workload Manager subsystem started task Procedure in batch with a special parameter (PARM='SAR' or PARM='SAD'). The output generated by this simulation forms a scheduled activity data set.
You can also create multiple schedule-activity data sets. You can generate separate data sets on scheduled activity for the next day or for the next week, or you want different activity data sets for different production groups.
Note: ESP Workload Manager does not reflect an Event in the scheduled activity data set unless it contains either a SCHEDULE or EXPECT command.
SADGEN command
When creating a job to generate a scheduled-activity data set, you can limit the simulation to specific Event data sets, prefixes, and classes using the different operands of the SADGEN command.
Chapter 9–Creating Reports
ESP-5.4-UG-05 299
You can also use the ESPSADG symbolic variable in an ESP Procedure to affect the simulation. This variable is set equal to 1 during SADGEN processing; otherwise, it is set to zero. For example, the following statement at the beginning of an ESP Procedure causes ESP Workload Manager not to simulate the Procedure during SADGEN processing:
IF ESPSADG=1 THEN QUIT
When ESP Workload Manager creates a scheduled activity data set, it contains a record for each job you want to submit, within the time range you have specified on a schedule command. If you specify neither the FROM nor TO time range, ESP Workload Manager provides the following default:
'NOW' TO '6AM TOMORROW'
You can use the EXTERNALS operand to add an extra entry on the SADGEN data set for each external job found within the specified scheduling criteria.
Example
The example below is a batch job, SADGEN, that generates a scheduled activity data set called CYBER.SAD. The name of the started task Procedure for ESP Workload Manager is ESP.
//SADGEN JOB...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD *//SYSIN DD *SADGEN DATASET('CYBER.SAD') -FROM('8AM TODAY')TO('8AM TOMORROW')
Extracting data
After ESP Workload Manager generates the data, you can extract data to produce a standard-format scheduled-activity report. You can create the report either in batch or online using the LSAR command, or using option S on the Main Menu.
Section–Extracting data
300 ESP-5.4-UG-05
LSAR command
The LSAR command generates a standard scheduled activity report that includes the following data:
• Job name. A character following the job name identifies a specific job type:• T = Task• M = Manual• R = Request• L = Link• E = External• blank = other job type
• Scheduled submit date and time. These reflect the Event schedule time unless you use the modeling feature to provide estimated submit times.
• Number of samples used for average.
• Average values for previous job executions:
• Elapsed execution time• CPU time• Number of print lines• Number of specific and non-specific (scratch) tape mounts• Number of tape drives required• DJC network and/or Application• Fully qualified Event identifier
• Total values for previous job executions:
• Number of jobs• Number of jobs without statistics• Initiator time• CPU time• Number of print lines• Number of specific tape mounts• Number of non-specific (scratch) tape mounts
Note: If you do not use the FROM keyword, the starting time for this report defaults to now.
Example: Displaying scheduled activity data
The following example requests a report on activity scheduled in an 8 hour period starting at 5 am using the data set CYBER.SAR. ESP Workload Manager presents the data in scheduled time sequence.
LSAR DSN('CYBER.SAR') FROM('5AM TODAY')-TO('1PM TODAY') TIMESEQ
Chapter 9–Creating Reports
ESP-5.4-UG-05 301
Generating scheduled versus actual report
You can update a scheduled activity data set with current job status, creating a scheduled versus actual report. ESP Workload Manager calculates the completion status of a schedule, so that you can see how much work has been completed and how much remains.
If you use CSF to monitor the workload, you receive more up-to-date information because ESP Workload Manager automatically updates the CSF. However, to generate a hardcopy report on the current status from CSF, you can code your own extensions. For more information on CSF, see “Consolidated Status Facility (CSF)” on page 221.
SADUPD command
You perform the schedule update in a similar way to the schedule activity generation. Instead of the SADGEN command, use the SADUPD command. ESP Workload Manager can run a job at frequent intervals during a day to update the scheduled activity data base. The job executes in a fraction of the time of the original schedule generation.
After ESP Workload Manager has run the scheduled update, use the STATUS operand on the LSAR command, or specified on the Option S panel, to request a status display instead of the regular schedule display. This provides the status of all jobs in the schedule, as well as the time and percent of the schedule still remaining. ESP Workload Manager displays actual start and end times, completion codes, and rerun indicators.
Example 1: Creating a scheduled activity data set
This example uses JCL to create the scheduled activity data set:
//SADGEN JOB CYB1000,CLASS=A//S1 EXEC ESP,PARM='SAR'//SYSIN DD *SADGEN DATASET('CYBER.ESP.SAD') -FROM('5AM TODAY')TO('5AM TOMORROW')
Example 2: Updating a scheduled activity data set
This example shows the JCL which can be used to provide an update on this scheduled activity:
//SADUPD JOB CYB1000,CLASS=A//S1 EXEC ESP,PARM='SAR'//SYSIN DD *SADUPD DATASET('CYBER.ESP.SAD')
Section–Generating projected versus actual data
302 ESP-5.4-UG-05
Generating projected versus actual data
The scheduled activity update feature provides you with actual start and end times for jobs. ESP Workload Manager modeling feature can project these times in advance. As a result, ESP Workload Manager can generate a Projected versus Actual report that shows each job’s projected and actual start and end times. For detailed information on modeling, see the ESP Workload Manager Advanced User’s Guide.
To generate a projected versus actual report:
1. Before ESP Workload Manager starts the workload you are interested in, generate a scheduled activity data set using the SADGEN command in a batch job.
2. When the SADGEN completes, run a model in batch. The model processor updates each job’s projected start and end times in the SADGEN data set. Ensure that the model processing covers the appropriate period.
3. After all jobs in the SADGEN data set are complete, update the scheduled activity data set using the SADUPD command in a batch job.
4. Use the LSAR command with the PROJECTED operand to generate a Projected versus Actual report.
LSAR DSN('CYBER.SADFILE') PROJECTED
Extracting tape information
You can request the ESP Workload Manager extract tape volume serial information during a scheduled-activity data-set generation run. ESP Workload Manager references the tape management catalog when it generates the scheduled activity data set.
ESP Workload Manager can then generate a data set using this extracted information and feed the data set into the TMS or CA1 tape pull program.
Chapter 9–Creating Reports
ESP-5.4-UG-05 303
To extract tape information:
1. Use the INPUTDS statement in the job documentation data set or ESP Procedure identifying the tape data sets associated with each job. For example:
JCLLIB PROD.JCLAPPL PAYROLLJOB JOB1 RELEASE JOB2ENDJOBJOB JOB2 INPUTDS PROD.GDG(-1)ENDJOBSELECT (JOB1,JOB2)
2. Generate a scheduled activity using the SADGEN command in a batch job.
3. Use the LSAR command specifying TAPEPULL(dsname), where dsname is the pre-allocated PDS to store tape data set information. An example is shown below:
LSAR DSN('CYBER.ESP.SAD') TAPEPULL('PROD.TAPE.PULL')
4. ESP Workload Manager creates a member for each job. You should re-initialize the TAPEPULL data set before you generate the scheduled activity data set.
5. Use this PDS as input to the TMS or CA1 tape pull program.
Using job mapping
Job mapping is a reporting facility you use produce detailed job information. You can generate the following reports:
Unlike the scheduled-activity report, which is based on time, the job mapping feature generates data based on Event names. These Events can be scheduled or can require data set or manual triggers. There is no need for these Events to have executed because history data is not required for the jobs. If history data is available, this historical information is incorporated into the reports.
Type of Report Content of Report
Job activity This report contains detailed information on jobs including job name, Application name, job type, Event name, ESP Procedure name, JCL library, execution time, CPU time, and predecessor and successor jobs.
Job descendent This report shows a job and its successors.
Section–Using job mapping
304 ESP-5.4-UG-05
To set up job mapping:
1. Allocate a sequential data set to store the job mapping data. See below.
2. Generate data for the report using the MAPGEN command. See “Generating data for the report” on page 304.
3. Use the JOBMAP command to display a job activity report or use the JOBTREE command to display a job descendent report. See “Producing a job-activity report” on page 305.
Job-mapping data set
Allocate a sequential data set to store the data. This is referred to as the job-mapping data set.
Generating data for the report
Before performing this step, you must allocate a sequential data set to store the data. See “Job-mapping data set” on page 304.
Use the MAPGEN command to generate data for the job-mapping data set that can be used by the JOBMAP and JOBTREE commands to produce reports. To use the MAPGEN command, use a batch job that executes the ESP Workload Manager started task with the special parameter, PARM='SAR' or PARM='SAD'.
The MAPGEN command takes the information for an Event, or set of Events, and stores it in your job mapping data set. To use this command, specify the name of your job mapping data set and an Event descriptive name (for example, without the prefix), which can include wildcards.
Note: You must use the MAPGEN command in batch.
Example 1
In the following example, ESP Workload Manager generates data for all Events and stores the output in the ESP.MAPGEN data set. The name of the started task for ESP Workload Manager is ESP.
//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(-)
Explanation Attributes for 3390 DASD Otherwise use
Organization PS PS
Record format VBS VBS
Record length 32756 32756
Block size 27998 16384
Chapter 9–Creating Reports
ESP-5.4-UG-05 305
Example 2
In the following example, the MAPGEN command causes ESP Workload Manager to generate data for all Events with descriptive names that start with PAY and store the output in the ESP.MAPGEN data set.
//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(PAY-)
Producing a job-activity report
Before performing this step, you must generate data for the report. See “Generating data for the report” on page 304.
JOBMAP command
Use the JOBMAP command to produce a job-activity report. This report contains detailed job information. For each job, regardless of its frequency, the job-activity report lists the following information:
• Job name (An M or a T can follow the job name, indicating that the job is a manual job or a task)
• Application name• Job type (for example, job, request, manual, external)• Scheduled frequency• Job qualifier• Event name• Calendar names• JCL data set and member name• Indication if the JCL data set is a JCLLIB or TEMPLIB• Scope for external and manual jobs• Job class• Programmer name• Tape drive and mounts (both cartridge and reel)• Elapsed execution time• CPU time• Hold count• List of predecessor jobs• List of successor jobs• List of resources• ESP Procedure data set and member names• Tag
To use the JOBMAP command:
• Specify the name of your job-mapping data set.
Section–Using job mapping
306 ESP-5.4-UG-05
Because this command uses the job-mapping data set as input, you can report only on jobs contained in that data set. You can use the JOBMAP command in batch, by executing PGM=ESP with the correct SUBSYS parameter, or in Page mode.
Example - Using JOBMAP in batch
The following example creates a job-activity report for all jobs. The subsystem name for ESP Workload Manager in this example is ESPM.
//MYJOB JOB ...//S1 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD *JOBMAP DSN('ESP.MAPGEN')
Example: Using JOBMAP in Page mode
The following example creates a job-activity report, for all jobs, in Page mode.
JOBMAP DSN('ESP.MAPGEN')
Chapter 9–Creating Reports
ESP-5.4-UG-05 307
Reviewing the output
For each job, ESP Workload Manager produces output similar to the following:
Customizing your job-activity report
Because of the amount of data generated for each job, you can limit the report to a specific Application, produce an index, or suppress certain fields in your report.
Generating a report for a specific Application
You can use the APPL operand to restrict the data to a specific Application. The following example lists a job activity report for all jobs in the PAYROLL Application.
JOBMAP DSN('ESP.MAPGEN') APPL(PAYROLL)
Generating an index
You can use the JOBINDEX, APPLINDEX, and RESINDEX operands to produce an index by job name, Application name, or resource name, respectively.
The following example creates a job activity report with an index by job name and an index by Application name.
JOBMAP DSN('ESP.MAPGEN') JOBINDEX APPLINDEX
JOB NAME APPL NAME TYPE SCHEDULING
PAYJOB01 PAYROLL JOB SCHEDULED: DAILY
QUALIFIER:
EVENT: CYBER.PAYJOB01 SYSTEM
CALENDAR (S):
JCL: MY.JCLLIB (PAYJOB01)
SCOPE:
CLASS: A
PROGRAMMER: J. DOE
TAPES: REEL DRIVES: 0
REEL MOUNTS: 0
CART DRIVES: 0
CART MOUNTS: 0
ELAPSED: 0H 0M 0S
CPU: 0H 0M 0S
HOLD COUNT: 0
AFTER: –NONE–
BEFORE: PAYJOB02
PAYJOB03
RESOURCES: –NONE–
PROC: MY.ESPPROC (PAYJOB01)
TAG:
Section–Using job mapping
308 ESP-5.4-UG-05
The following is a sample index of jobs that will appear at the end of your job-activity report:
JOB INDEX
JOB NAME APPL NAME PAGE-------- --------- ----PAYJOB01 PAYROLL 1PAYJOB02 PAYROLL 2PAYJOB03 PAYROLL 2END OF LIST
The following is a sample index of Applications that will appear at the end of your job-activity report:
APPLICATION INDEX PAGEAPPL NAME JOB NAME PAGE--------- -------- ----PAYROLL PAYJOB01 1 PAYJOB02 2 PAYJOB03 2END OF LIST
Suppressing fields
To suppress certain fields:
• Use the NODISPLAY operand.
You can suppress the following fields:
Field Description
CALENDAR Calendar names.
CLASS Job class.
CPU CPU time.
ELAPSED Elapsed execution time.
EVENT Event name.
HOLDCOUNT Hold count.
JCLDS JCL data set and member name.
PGMER Programmer name.
PRED List of predecessor jobs.
PROC ESP Procedure data set and member name.
RESOURCE List of resources.
SCOPE Scope (externals and manuals only).
SUCC List of successor jobs.
TAG Tag.
TAPES Tape drives and mounts (both cartridge and reel).
Chapter 9–Creating Reports
ESP-5.4-UG-05 309
The following example suppresses the display of CPU time, elapsed execution time, tape drives, and mounts.
JOBMAP DSN('ESP.MAPGEN') NODISPLAY(CPU,ELAPSED,TAPES)
Producing a job-descendent report
To produce a job-descendent report:
• Use the JOBTREE command.
This report lists a job and all successor, or descendent, jobs.
Because the JOBTREE command uses the job-mapping data set as input, you can report only on jobs contained in that data set. You can use the JOBTREE command in batch, by executing PGM=ESP with the correct SUBSYS operand, or in page mode.
To use the JOBTREE command:
Specify:
• The name of the job-mapping data set• The specific name of a job• Optionally, the name of an Application to which the job belongs
If you do not specify the name of an Application, ESP Workload Manager examines all Applications in the job-mapping data set for a match and uses the first one that it finds.
Example: Using JOBTREE in batch
In the following example, a job-descendent report is produced for job PAYJOBA. The subsystem name for ESP Workload Manager, in this example, is ESPM.
//MYJOB JOB...//S1 EXEC PGM=ESP, PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD*JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)
Example: Using JOBTREE in page mode
The following example creates a job-descendent report, for job PAYJOBA, in page mode.
JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)
Section–Producing a job-descendent report
310 ESP-5.4-UG-05
Example
In the following example, a job-descendent report is produced for job START.APPL in the PAYROLL Application.
JOBTREE DSN('ESP.MAPGEN') JOB(START.APPL) APPL(PAYROLL)
Reviewing the output
The report uses indentation to indicate successor relationships. A job that is indented farther than the job on the previous line indicates a successor relationship.
Consider the following flow of jobs:
A job descendent tree for PAYJOBA looks like the following. PAYJOBA releases PAYJOBB and PAYJOBC, PAYJOBB and PAYJOBC release PAYJOBD, and PAYJOBD releases PAYJOBE.
JOB DESCENDENT TREEPAYJOBA JOB PAYROLLPAYJOBB JOB PAYROLLPAYJOBD JOB PAYROLLPAYJOBE JOB PAYROLLPAYJOBC JOB PAYROLLPAYJOBD JOB PAYROLLPAYJOBE JOB PAYROLL
PAYJOBA
PAYJOBB PAYJOBC
PAYJOBD
PAYJOBE
Chapter 9–Creating Reports
ESP-5.4-UG-05 311
Putting it all together
Sample batch job
The following is a sample batch job to:
• Allocate a job-mapping data set (STEP1)
• Generate data for the job-mapping data set for all Events with descriptive names that start with P (STEP2)
• Generate a job-activity report, with an index by job name, for all jobs in the PAYROLL Application (STEP3)
• Generate a job-descendent report for START.APPL in the PAYROLL Application job name (STEP3)
//MYJOB JOB ...//STEP1 EXEC PGM=IEFBR14//ALLOC DD DSN=MY.MAPGEN,// DISP=(,CATLG),// UNIT=SYSDA,SPACE=(TRK,(40,20)),// DCB=(DSORG=PS,RECFM=VBS,LRECL=32756,BLKSIZE=16384)//STEP2 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=A//SYSIN DD *MAPGEN DATASET('MY.MAPGEN') EVENT(P-)//STEP3 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=A//SYSIN DD *JOBMAP DSN('MY.MAPGEN') APPL(PAYROLL) JOBINDEXJOBTREE DSN('MY.MAPGEN') JOB(START.APPL) APPL(PAYROLL)/*
Section–ESP Workload Manager FLOWDOC
312 ESP-5.4-UG-05
ESP Workload Manager FLOWDOC
ESP Workload Manager FLOWDOC generates reports detailing information about workload scheduled by ESP Workload Manager. The following outlines the information that is produced:
• Application/subApplication names
• Run dates
• Calendars referenced
• Job-level information:
• Whether the job is held or not• Tag field• Job type • Submission time (DELAYSUB/EARLYSUB if coded in the Application, else
Event submission time)• Job name• Hold count• Released jobs• Resource information• Scope information (look back/ahead times for manual or external jobs)• External job information (Application and job names)
Graphical representation
The entire process is represented as follows:
User InputUser Input ESPESP
CYBES091CYBES091
CYBES090CYBES090
SAD FileSAD File
FlowDocFlowDoc
VSAMVSAM
Chapter 9–Creating Reports
ESP-5.4-UG-05 313
ESP Workload Manager FLOWDOC components
ESP Workload Manager FLOWDOC consists of three components:
• ESP Workload Manager data generation• data base generation• Report generation
ESP Workload Manager data generation
An ESP Workload Manager SADGEN request is made to generate the ESP Workload Manager information. The following JCL provides an example of this job:
//STEP1 EXEC PGM=IEFBR14//SADGEN DD DSN=DAILY.SADGEN,DISP=(MOD,DELETE),// UNIT=SYSDA,SPACE=(TRK,0)//STEP2 EXEC PGM=IEFBR14//SADGEN DD DSN=DAILY.SADGEN,DISP=(,CATLG),// UNIT=SYSDA,SPACE=(CYL,(40,20)),// DCB=(DSORG=PS,RECFM=VB,LRECL=16380,BLKSIZE=16384)//STEP3 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *SADGEN DATASET('DAILY.SADGEN') - FROM ('TODAY') TO ('TODAY PLUS 30 DAYS') - EXTERNALS - EVENTSET(-) LEVEL(-) THRESH(0)/*
Data base generation
The data base generation step is used to create the VSAM data base. The following JCL would be used to execute this utility:
//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD * DELETE DAILY.FLOWDOC CLUSTER DEFINE CLUSTER(NAME(DAILY.FLOWDOC) - RECORDSIZE(64 32760) - KEYS(53 0) - INDEXED - SHR(3 3) - CYLINDERS(40 20) - VOLUMES(vol_ser))/*//STEP2 EXEC PGM=CYBES090//STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK//SYSPRINT DD SYSOUT=X//SYSUT1 DD DISP=SHR,DSN=DAILY.SADGEN//SYSUT2 DD DISP=SHR,DSN=DAILY.FLOWDOC
Section–ESP Workload Manager FLOWDOC
314 ESP-5.4-UG-05
Note: The space allocated for the VSAM data base should be approximately 25% greater than the space consumed by the SADGEN data set.
Report generation
ESP Workload Manager generates reports by Event or Application name along with a date range. Wild cards are permitted in the selection criteria. The following JCL would be used to generate a report:
//stepname EXEC PGM=CYBES091//STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK//SYSPRINT DD SYSOUT=*//SYSUT1 DD DISP=SHR,DSN=DAILY.FLOWDOC//SYSIN DD * FLOWDOC { PREFIX(event_prefix)EVENT(event_name)|APPL(appl_name)} { FROM('criteria') TO('criteria') | DATE('criteria') }/*
If selection by Events is desired, then you must specify PREFIX and NAME.
If selection by Applications is desired, specify the APPL operand. Applications and Events are mutually exclusive. The names specified can contain wildcards.
If a range of dates is desired, specify the FROM and TO. If only a single date is desired, then specify DATE. Single dates and date ranges are mutually exclusive.
Multiple FLOWDOC statements can be present in the input stream.
Report organization
The data is presented organized by subApplication with Application or Event. The jobs are shown in the order in which they will be executed.
If a job is referenced as a predecessor of a job in another Application as an EXTERNAL job, the referencing job name and Application name for that job is shown provided that the referencing job is part of an Application that is already on the data base.
Repeated executions of an Application or Event are grouped together to eliminate redundant reporting. These repeating Applications are shown by date. If there is any variation in the sequence of jobs executed, each variation will be shown separately. For example, if an Application has a series of jobs which run daily but some which only run on Monday, a thirty day report would display for example, 26 executions of the Application showing all of the non-Monday jobs and four executions of the Application showing all jobs.
Chapter 9–Creating Reports
ESP-5.4-UG-05 315
Report headings
The following shows the headings as they appear in the report, and what they mean:
Sample report generation jobs
The following are examples of report generation jobs that could be used to produce ESP Workload Manager FLOWDOC reports.
Heading Description
HOLD This field is set to Y if the ESP Workload Manager JOB definition statement specified the HELD operand.
TAG This field is the first eight bytes of the job tag.
TYPE This field can be one of:• TASK a task• MAN a manual• LINK a link• EXT an external job• JOB a normal job
SUB TIME This field is the expected submission time of the job. If it is blank, then the ESP Workload Manager SADGEN process has determined no specific time. This time reflects ESP Workload Manager statements, which affect submission time such as DELAYSUB.
JOB NAME This is the job name as defined in the ESP Procedure.
HC This is the number of outstanding predecessors. If a job has no predecessors, the hold count field has a value of zero.
RELEASES This lists all of the jobs (two per line) which are released by this job. If a job does not have any successors, then (NONE) will be placed in the release field.
RESOURCE This lists all of the resources (one per line) which are used by this job.
SCOPE These fields are only present for external jobs. They represent the first and second scope times in the format hh:mm where hh is the hours and mm is the minutes.
SUCCESSOR This lists all of the downstream jobs, one per line, showing the Application name and the referencing job name. A downstream job is a job that references this job as an external. It can release this job or it can require this job as a predecessor.
Section–ESP Workload Manager FLOWDOC
316 ESP-5.4-UG-05
Example 1
The following report-generation JCL could be used to produce a report detailing information about the PAYROLL Application starting today ending tomorrow:
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(PAYROLL) FROM('TODAY') TO('TOMORROW')
Example 2
The following report-generation JCL could be used to produce a report detailing information about an Application which is invoked by an Event called CYBER.PAYROLL on August 29th, 2000:
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC PREFIX(CYBER) NAME(PAYROLL) DATE('AUGUST 29, 2000')
Example 3
The following report-generation JCL could be used to produce a report detailing information about the BILLING Application from 4 pm today until 4 pm two days from today:
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(BILLING) FROM('4PM TODAY') TO('4PM TODAY PLUS 2 DAYS')
Chapter 9–Creating Reports
ESP-5.4-UG-05 317
Example 4
The following report-generation JCL could be used to produce a report detailing information about the CLAIMS Application from Monday to Friday. Jobs in the CLAIMS Application that have varying run frequencies will be displayed on their respective day, for example, jobs coded as RUN MONDAY will be displayed on Mondays run date.
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(CLAIMS) DATE('MONDAY')FLOWDOC APPL(CLAIMS) DATE('TUESDAY')FLOWDOC APPL(CLAIMS) DATE('WEDNESDAY')FLOWDOC APPL(CLAIMS) DATE('THURSDAY')FLOWDOC APPL(CLAIMS) DATE('FRIDAY')
Sample JCL and report
The following example shows the report-generation JCL and the report produced by that JCL.
Report generation JCL
The following report-generation JCL could be used to produce a report detailing information about the PAYROLL and ACCTPAY Applications from September 15, 2000 until September 16, 2000:
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(PAYROLL) FROM('TODAY') TO('TOMORROW')
Section–Flowcharting
318 ESP-5.4-UG-05
Sample ESP Workload Manager FLOWDOC report
The following FLOWDOC report results from the previous JCL:
Flowcharting
Schedulers and operators sometimes find it helpful to have a representation of the workload. Graphic flow charts make it easier to see job dependencies and to monitor the progression of work.
Creating flowcharts
You can create flow charts of workloads using the following PC-based graphics software:
• MS Project• TIMELINE
ESP Workload Manager produces an input file for the PC software. This input file is then used in creating the graphic flow chart of the workload. You have the option of
APPLICATION: PAYROLL
RUN DATES: FRI 15 SEP 2000
***SUCCESSOR***
HOLD TAG TYPE SUBTIME JOBNAME HC RELEASES RESOURCE SCOPE APPL JOBNAME
N LINK 22.00 START PAY1 CPUABS
N PAYROLL JOB 20.00 PAY1 1 PAY2, PAY3
PAY4, PAY5
N PAYROLL JOB 20.00 PAY2 1 PAY6 IMS
N PAYROLL JOB 20.00 PAY3 1 PAY6 IMS
N PAYROLL JOB 20.00 PAY4 1 PAY6
N PAYROLL JOB 20.00 PAY5 1 PAY6 ACCTPAY ACCT1
N PAYROLL JOB 20.00 PAY6 4 PAY7, PAY8
PAY9
N PAYROLL JOB 20.00 PAY7 1 PAY10
N PAYROLL JOB 20.00 PAY8 1 PAY10 ACCTPAY ACCT1
N PAYROLL JOB 20.00 PAY9 1 PAY10
N PAYROLL JOB 20.00 PAY10 3 END CPUABS
Chapter 9–Creating Reports
ESP-5.4-UG-05 319
viewing the ESP Workload Manager workloads on the PC, or sending the output to the PC printer or plotter when you want a paper copy.
Generation of flow charts consists of some operations on the mainframe, a PC file transfer, and some additional operations on a PC.
For a real-time, graphical view of the workload, see the ESP Workstation User’s Guide.
Generating flowcharts using MS Project
ESP Workload Manager GENPROJ feature exports data that describe an existing ESP Application in a format that can be used by PC-based project-management software, Microsoft Project.
Exported fields
The exported fields include:
• Job Name• SubApplication name• Start date and end date• Duration• Late start time and late end time• Percent complete• Tag
To test and use the GENPROJ feature:
1. Create a data set to receive the GENPROJ data. The recommended DCB attributes are RECFM=FB, LRECL=80, and BLKSIZE=3120. However, you can use any sequential or partitioned data set with VB or FB format and an LRECL of at least 72.
2. Create an active ESP Application or use an Application you can display using the LISTAPPL command. If you need to create a dummy test Application, you can insert a built-in delay prior to the first job by using an EARLYSUB command. This ensures that the Application does not complete prior to the GENPROJ data extract. For example:
APPL TESTAPPLJOB JOB1 EARLYSUB NOW PLUS 24 HOURS RUN DAILY RELEASE JOB2ENDJOB
3. Use the GENPROJ command to extract data from the Application. For example:
GENPROJ TESTAPPL.0 DATASET('SYS1.TESTAPPL.GENPROJ')
Section–Generating flowcharts using MS Project
320 ESP-5.4-UG-05
4. Download the data set (SYS1.TESTAPPL.GENPROJ) to a DOS file, like TESTAPPL.TXT, using your installation’s file transfer Procedure. You should specify the ASCII and CRLF file transfer options.
5. Execute the Cybermation-supplied utility CONVERT.EXE on your PC. You can copy this program from a diskette supplied by Cybermation. If your installation did not receive this diskette, please contact Cybermation Technical Support. At the DOS prompt, or in Windows: File Run, switch to the appropriate directory and enter: CONVERT <input file> <output file>.For example:
CONVERT TESTAPPL.TXT TESTAPPL.MPX
The extension .MPX identifies the file as an Microsoft Project file. If you enter CONVERT without operands the command syntax is displayed.
6. Start Microsoft Project on your PC. Within Microsoft Project, open the .MPX file, for example TESTAPPL.MPX. Once the project has been opened within Microsoft Project, it can be manipulated and viewed in the same way any other project. A PERT chart displays the Application horizontally with each job shown as a box within the chart. Bold boxes identify critical path jobs. Boxes with a diagonal slash indicate that this job is complete. You should save the Application as a project file, for example TESTAPPL.MPP. Subsequent GENPROJ data extracts can be used to update the project status of an Application.
Illustration of steps 1 to 5
These steps are illustrated below:
APPL on APPLFILE mydsn
mydsn.txt mydsn.mpx
mydsn.mpp
GENPROJ
Convert
download
MS Project
Chapter 9–Creating Reports
ESP-5.4-UG-05 321
Generating flow charts with ESP Workload Manager and Timeline
ESP Workload Manager GENFLOW feature exports data that describes a scheduled ESP Application in a format used by the PC-based project-management software, Timeline. ESP Workload Manager uses information from a Scheduled Activity data set and exports the following fields:
• Job name• Start time and end time
To test and use the GENFLOW feature:
1. Access ESP Workload Manager in Page mode. Issue the GENFLOW command, specifying two positional operands:
• The name of a scheduled activity-data set (SADGEN file). ESP Workload Manager uses this data set as input.
• The name of a file to which GENFLOW will write the data. If you do not specify the DCB attributes, GENFLOW sets them to: LRECL=80, BLKSIZE=3120.
2. Issue a FLOW command for each separate flowchart you require. The FLOW command identifies a flow chart by a name of up to seven characters. The FLOW command also identifies jobs and/or Applications to be included.
3. After the flow commands have been entered (you can specify as many as required), type GO. ESP Workload Manager reads the SADGEN file and writes the output to the target file.
GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER'FLOW PAYROLL APPL(PAYROLL)FLOW BACKUPS JOBS(BACK-)GO
4. Use a PC file transfer program to send the data to a PC.
5. On the PC, use a file editor to edit the file, as described below.
Each flow command generates two sections in the file. Each section is preceded by a file identifier in the form:
--ffffx.CSV where ffff is the flow ID, and x is T for TASK or D for dependencies.
Section–Generating flow charts with ESP Workload Manager and Timeline
322 ESP-5.4-UG-05
For the preceding example, you will see the following:
--PAYROLLT.CSV–100–nnn–900....–PAYROLLD.CSV–100-....–BACKUPST.CSV-100...-...–BACKUPDS.CSV-100..-...
Each FLOW generates a TASK section, named ffffT.CSV, and a dependency section, ffffD.CSV, where ffff is the ID on the FLOW statement.
Split the file into two files for each flow. The file names should:
• Be called ffffT.CSV and ffffD.CSV• Contain the corresponding contents of the main file, excluding the file
identifier (--ffffx.CSV) line.
6. You can now access Timeline.
7. Use the File, Import, Tables menu. Specify that you are using tasks and dependencies, and specify the names of the files you created.
Note: You will have to do one flow at a time.
8. Once the data has been analyzed, you can view the data in GANTT (spreadsheet format) or PERT (Flowchart format). To print the flowchart, use the GRAPHIC, PERT function.
Chapter 9–Creating Reports
ESP-5.4-UG-05 323
Illustration of steps 1 to 8
These steps are illustrated below:
SADGEN file mydsn
mydsn.txt
mydsn.mlp
GENFLOWFLOWGO
Split file
download
Timeline
chart1t.csv
chart1d.csv
Section–Generating flow charts with ESP Workload Manager and Timeline
324 ESP-5.4-UG-05
ESP-5.4-UG-05 325
Using Resources
You can ensure that jobs in an ESP Application are submitted only when all of their resource requirements are met. Because you do this without manual intervention, there are no unnecessary delays before a job starts. With ESP Workload Manager resource feature, you can automate resource management.
Note: Before you start to use ESP Workload Manager resource features, your Systems Programmer needs to define a resource data set called the RESFILE, and specify the CPUs and nodes in your environment. If you want ESP Workload Manager to make default resource assignments, the RESDFLT initialization statement must also be specified.
This chapter contains the following topics:
• What is a resource?• Types of resources• Scope of resources• Using real devices• Routing jobs to other systems• Managing jobs• Requesting resources• Default resources• Working with resources• Defining resources• Setting resources• Modifying Resources
Section–What is a resource?
326 ESP-5.4-UG-05
• WLM Workload Balancing• Agent Workload Balancing• Deleting resources• Displaying resource information• Step-level resource release• Resource absorption• Example: Controlling mutually exclusive jobs• Example: Controlling access to an online system• Example: Time periods for low priority jobs• Example: Using a resource for a self-completing task• Example: Controlling access to a data base• Example: Running jobs on a particular system• Example: Controlling mutually exclusive groups of jobs• Example: Planning for a system shutdown - Part 1• Example: Planning for a system shutdown - Part 2• Example: Schedule dependency
What is a resource?
A resource is any type of real or abstract object that affects a job’s ability to run successfully and can be quantified. Resources are classified by resource type and by scope.
Examples of resources
Some examples of resources are:
• Tape drives• Scratch tapes• Online systems• data bases• Time periods• The completion of a job
Types of resources
ESP Workload Manager resources are classified into three types:
• Renewable• Depletable• Threshold
Chapter 10–Using Resources
ESP-5.4-UG-05 327
Renewable resource
A renewable resource is a borrowed resource. When a job is submitted by ESP Workload Manager, the job removes the resource from the resource pool. However, the resource is not permanently used up. Instead, it is returned to the resource pool at the end of execution, whether successful or not. In other words, the job temporarily borrows the resource to allow it to execute successfully.
For example:
A renewable resource can be used to control concurrent access to a data base.
Depletable resource
A depletable resource is a consumed resource. When a job is submitted by ESP Workload Manager, the job removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. The job needs to consume the resource to execute successfully.
For example:
A depletable resource can be a scratch tape, which is removed from the pool when a job writes a permanent data set onto it.
Threshold resource
A threshold resource is a sizing resource. A job does not actually remove the resource from the pool of resources while it executes. You can think of a threshold resource as a variable height doorway into the system. If the resource quantity is set to two, any number of jobs requiring two or fewer units are submitted. However, any job requiring three or more units is too high to pass through the door and so is not submitted. ESP Workload Manager sizes the job against the current level of the threshold resource.
For example:
A threshold resource can be used to represent elapsed time and limit the size of jobs entering the system. You can prevent long-running jobs from being submitted just before scheduled downtime.
Section–Scope of resources
328 ESP-5.4-UG-05
Scope of resources
You can classify the scope of the resources you define according to the following resource levels:
Using real devices
A real resource represents an actual hardware device. It is normally used for tape drive. The limitation is that they can work correctly only in a single z/OS image. The ESP Workload Manager master is only aware of the status of devices on the image it is running on.
Device counts
ESP Workload Manager determines the available count by first looking at the system control blocks for the resources. Then ESP Workload Manager counts how many of the UCBs (unit control blocks) within that device group are currently online and not allocated. If ESP Workload Manager schedules a job that requires a tape device, it could be several seconds or minutes before the job actually allocates the UCB. ESP Workload Manager ensures that it does not over-allocate a resource when scheduling jobs that require it. ESP Workload Manager uses an effective available count that is the lower of the following values: real value and the available count maintained by ESP Workload Manager.
Example
If a job requires three units of a real resource, and ESP Workload Manager available count is three, ESP Workload Manager waits for the resource if there are only two devices actually online and unallocated.
Type of resource Explanation
Local resource Each processor maintains an individual counter for the resource.
Global resource The resource availability counter is shared among all processors within a node.
Enterprise resource The resource availability counter is shared among all nodes. This type has a true meaning only when one ESP Workload Manager system submits the work for all nodes.
Chapter 10–Using Resources
ESP-5.4-UG-05 329
Routing jobs to other systems
In a multiple CPU environment, a job can require a mix of resources that are not available on the ESP Workload Manager system submitting the job. However, these resources can be available on another processor, either on the current node or on a remote node. ESP Workload Manager tries to find all the resources a job requires on one system.
Routing JCL
ESP Workload Manager can automatically insert the appropriate JCL into a job to ensure the job is routed to the required node or processor. The JCL ESP Workload Manager uses to route jobs is specified as part of the NODE and CPU definitions in your ESP Workload Manager initialization parameters. These are normally a /* EXEC nodename card and a /*JOBPARM SYSAFF=xxxx card.
Example
If ESP Workload Manager builds an Application on SYSA but the resource a job needs is on SYSB, ESP Workload Manager routes the job to SYSB. If these systems are within the same JES node, ESP Workload Manager submits the job and inserts a /*JOBPARM SYSAFF=SYSB card to route the job to SYSB.
Gravity
ESP Workload Manager can cause a job to be routed to a remote node only if one of the resources required by the job has the GRAVITY attribute in its definition. ESP Workload Manager can cause a job to be routed to another CPU within the same node regardless of the GRAVITY setting.
Managing jobs
When the Application Manager readies a job for submission, it checks to see if the job has requested any resources. If so, the Application Manager passes the job to the Resource Manager component. The Resource Manager submits the job when the required resources become available. If all of a job’s resource requirements cannot be met, ESP Workload Manager does not submit the job.
Multiple resources
If a job requires multiple resources, or multiple units of a single resource, and all of these resources are not available when the job is readied for submission, ESP Workload Manager does not hold on to any resources. As soon as another job ends that is using a resource this job needs, or the resource status changes in any way—for
Section–Requesting resources
330 ESP-5.4-UG-05
example, by the RESDEF command being issued—the job is rechecked for submission.
Renewable resources
If a job is using a renewable resource, the resource is taken when the job is submitted and is freed up as soon as the job ends, whether it is successful or not. A failed job, by default, has the same resource requirements upon restart as at submission time.
Requesting resources
To identify the resources required by individual jobs or by an Application, you use the RESOURCE statement within an Application definition. This can be done at an Application level or at a job level. An individual job can request any number of different resources. You can use resources for jobs and tasks, but not for links.
Statements
When you specify resource requirements, there are two statements you can use:
• The RESOURCE statement• The PRIORITY statement
Using the RESOURCE statement
Use the RESOURCE statement to identify resource requirements. In parentheses, specify the number of units required, followed by the resource name. If you omit the number of units, ESP Workload Manager uses a default of 1.
For example, to specify one unit of a resource called CICS, use:
RESOURCE (1,CICS) or RESOURCE (CICS)
If you want to request more than one resource, string your resource specifications together. For example, if your requirements are one unit of the resource called CICS and two units of a resource called SCRATCH, specify:
RESOURCE (1,CICS,2,SCRATCH)
Placing the RESOURCE statement
When you use a RESOURCE statement within an Application to provide specific resource information for an individual job, you place the statement between the JOB ... ENDJOB pair. The RESOURCE statement then affects only that individual job. It also overrides any resources that occur before the JOB ... ENDJOB pair.
If the RESOURCE statement is specified outside the scope of a JOB ... ENDJOB pair, the RESOURCE statement applies to the jobs that follow until a new
Chapter 10–Using Resources
ESP-5.4-UG-05 331
RESOURCE statement, outside the scope of a JOB statement, occurs. Jobs inserted into an Application after it has been generated do not inherit any resource requirements.
Example: Requesting resources
In the following example, all jobs in the Application require one unit of the NITESHFT resource except job A that requires one unit of the CICS resource.
APPL ABCJCLLIB 'CYB.ESP.JCL'RESOURCE (1,NITESHFT)JOB A RESOURCE (1,CICS) RUN DAILYENDJOBJOB B RUN DAILYENDJOBJOB C RUN DAILYENDJOB
Adding resource requirements
Use the ADD operand on the RESOURCE statement to specify resources in addition to the resource requirements already specified for a job or the Application. You use it by specifying RESOURCE ADD, the number of units, and then the resource name.
Example
In the following example, job A needs one unit of the CICS resource in addition to one unit of the NITESHFT resource:
RESOURCE (1,NITESHFT)JOB A RESOURCE ADD(1,CICS)ENDJOB
Dropping resource requirements
The DROP operand on the RESOURCE statement specifies that one or more resource requirements are dropped for the jobs that follow, until a new RESOURCE statement occurs either within a JOB ... ENDJOB pair, or outside the scope of a JOB... ENDJOB pair. You use it by specifying RESOURCE DROP and then the resource name, like this:
RESOURCE DROP(T3420)RESOURCE DROP(CICS,T3420)
Section–Requesting resources
332 ESP-5.4-UG-05
To free a job from any resource dependency (except default resources) you specify:
RESOURCE DROP
Example
In the following example, job ABC requires one unit of the LOWPRIO resource and two units of the IMS resource. If the scheduled day is Friday, the LOWPRIO requirement is removed.
JOB ABC RUN DAILY RESOURCE (1,LOWPRIO,2,IMS) IF TODAY('FRIDAY') THEN RESOURCE DROP(LOWPRIO)ENDJOB
Dropping default resources
You cannot drop default resources using the DROP operand. Instead, you must request zero units of the default resource to indicate you do not want to use the default resource for a job or group of jobs.
Example
In the following example, job ABC does not have the ELAPSED default resource assigned to it and has a requirement for one unit of CICS.
JOB ABC RESOURCE (0,ELAPSED,1,CICS)ENDJOB
Using the PRIORITY statement
You can use the PRIORITY statement in a job definition to specify the relative priority of the job within an ESP Workload Manager group. The maximum value is 99. Zero is the lowest priority value and the default.
You can prioritize jobs within one group without delaying jobs in another group. ESP Workload Manager uses the priority when one or more jobs, within the same ESP Workload Manager group, are competing for the same resource. In this case, ESP Workload Manager queues the higher priority job ahead of the lower priority job. The queuing sequence of jobs in other groups is not affected. PRIORITY only applies to renewable and depletable resources.
ESP Workload Manager groups
The ESP Workload Manager group name is determined by the Event prefix. For example:
• CYBER.nnn identifies a job belonging to the group CYBER.• PROD.nnn identifies jobs in the PROD group.
Chapter 10–Using Resources
ESP-5.4-UG-05 333
For instance, a job that is assigned a priority in a group called CYBER is compared only to other jobs in the CYBER group and not to jobs in another group called PROD.
Example: Setting priority
The following example sets a priority of 99 for job BIGJOB. ESP Workload Manager queues this job ahead of other jobs from the same group when these jobs are waiting for the MSTRFILE resource.
JOB BIGJOB PRIORITY 99 RESOURCE (1,MSTRFILE)ENDJOB
Example: Setting priority
The following example sets a different priority for jobs B, C, and D. Each job requires one unit of a renewable resource called MSTRFILE. When job A completes, ESP Workload Manager queues the jobs in the order D, C, and B.
JOB A RUN DAILY RELEASE (B,C,D)ENDJOBJOB B RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 10ENDJOBJOB C RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 20ENDJOBJOB D RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 30ENDJOB
Default resources
ESP Workload Manager can determine some of the significant resource requirements that a job have by looking at the job’s run history. If required, ESP Workload Manager can then make default resource assignments automatically.
Section–Default resources
334 ESP-5.4-UG-05
Default assignments
The resources for which ESP Workload Manager can make default assignments are:
• Number of tape drives needed• Number of scratch tapes needed• Percentage CPU absorption• Total CPU time used• Total elapsed time used• Total print lines generated
Determining a default assignment
The information used to assign default resources is based on information contained in ESP Workload Manager Job Index file. ESP Workload Manager bases the default resource levels that it assigns on an average of the samples found in the job index. The number of samples depends on the index count specified when the job’s tracking model was defined. Only information from normal job completions, and not from abends, is used. The information is updated each time a new generation of an Application is created.
Default resources
To set up default resources:
1. Use the RESDFLT initialization statement in the ESP Workload Manager initialization parameters to identify the default resource you want to use.
2. Issue the RESDEF ADD command to define the default resource.
Example: Default scratch tape resource
The following ESP Workload Manager initialization statement causes ESP Workload Manager to use a default resource for scratch tapes. The name of the resource is SCRTAPES.
RESDFLT SCRATCH(SCRTAPES)
The following ESP Workload Manager command defines the SCRTAPES resource as a global, depletable resource, with a maximum quantity of 293.
RESDEF SCRTAPES ADD GLOBAL DEPLETABLE MAX(293)
ESP Workload Manager uses historical information to assign scratch-tape resource requirements to each job in an Application when it creates a generation of that Application.
Chapter 10–Using Resources
ESP-5.4-UG-05 335
Excluding default resources for an Application
Each Application ESP Workload Manager creates uses default resources you have set up. In an Application, you can code RESOURCE (0, resname) if you do not want ESP Workload Manager to assign default resources for a job or for an Application.
Working with resources
RESDEF command
You define, display, set, and delete resources using the RESDEF command. In a multiple CPU environment, you must issue the RESDEF command from a master ESP Workload Manager system. This is normally the same system on which your Applications are built.
Note: Your ESP Workload Manager administrator needs to grant you the necessary access for these functions.
The following sections describe how to define and work with resources. See the Examples sections later in this chapter for more examples of using resources.
Defining resources
Once you define a resource, the definition is stored in an ESP Workload Manager file, called the RESFILE. This information is saved across restarts of ESP Workload Manager unless ESP Workload Manager is restarted with the RESFORM option. Resource definitions are normally stored in the ESP Workload Manager initialization parameter data set or another data set that ESP Workload Manager reads at startup time.
To define a resource using the RESDEF command:
1. Name the resource, using up to 44 alphanumeric characters, the first of which must be alphabetic or national.
Note: The resource’s name must not end with a period or use two consecutive periods.
2. Use the ADD operand to indicate you are adding a resource.
3. Indicate the scope as local, global, or enterprise.
4. Indicate the type as renewable, depletable, or threshold.
5. Indicate if the resource corresponds to a real device, and specify the IBM generic or esoteric Unit Name for the device.
Section–Defining resources
336 ESP-5.4-UG-05
6. Indicate the CPU to which the resource applies, if it is a local resource and you have more than one CPU.
7. Specify the maximum and available quantities associated with the resource. For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. Maximum is the total quantity of the resource that exists; available is the current quantity.
Indicate whether or not the resource has gravity. This allows a job to be routed to another node if the resource is not available on the node on which the job was submitted.
Example: Defining a renewable resource
This example defines a resource called DATABASE. It is a global, renewable resource with maximum and available quantities of one.
RESDEF DATABASE ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)
Example: Defining a threshold resource
This example defines a resource called CICSUP. It is a local, threshold resource on SYSA with an availability count of one.
RESDEF CICSUP ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)
Example: Long resource name with no restrictions:
RESDEF RED_CARTRIDGE_WITHOUT_LABELS_OR_NUMBERS +ADD LOCAL DEPLETABLE AVAIL(50)
Defining a real resource
A real resource is one that is associated with an actual hardware device. This is normally a tape transport. ESP Workload Manager looks at the number of online, unallocated devices to satisfy a job’s real resource requirement.
To define a real resource:
• Use the DEVICE operand, on the RESDEF command, to specify a valid z/OS device name (for example, legal value for the UNIT=keyword in JCL).
The unit name can be a generic, such as 3480, or an installation-defined esoteric such as TAPE. Real resources should be defined as local and renewable. Use the MAX operand to identify the number of devices available to ESP Workload Manager submitted jobs.
Chapter 10–Using Resources
ESP-5.4-UG-05 337
RESREFR command
You can use the RESREFR command to refresh resource status. This can be required when you change the environment. For example, if a job is waiting for tape drive resources and you vary more tape drives online, ESP Workload Manager is not immediately aware of this. The RESREFR command causes ESP Workload Manager to look at the environment and refresh the status of real resources.
Example: Defining a real resource
This example defines a resource called T3480. It is a local, renewable, real resource that represents a device type of 3480. There is a maximum of 20 of these devices.
RESDEF T3480 ADD LOCAL RENEWABLE DEVICE(3480) MAX(20)
Setting resources
To change a resource:
• Use the SET operand on the RESDEF command to change the scope or the quantity of a resource.
You cannot change the type of a resource without deleting and redefining it.
For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. If you set the maximum, the available count changes. Setting the available count has no effect on the maximum count.
Example
This example sets the available quantity of the resource LOWPRIO to one.
RESDEF LOWPRIO SET AVAIL(1)
Setting quantities automatically
For some resources, you want ESP Workload Manager to set the quantity for you automatically. For example, you have a resource called CICSUP to represent that a started task called CICS is active. You can use ESP Workload Manager to automatically set the quantity of the resource to indicate the availability. See Job Monitoring and Alert Processing in the ESP Workload Manager Advanced User’s Guide for more information.
Section–Modifying Resources
338 ESP-5.4-UG-05
Modifying Resources
You can use the JOBRES command to add new resource requirements and change existing resource requirements for a job. This is done after the Application has been generated. Once the Application is generated, you can issue the JOBRES command at any time, including if the job is already waiting for resources (RESWAIT state).
You can also use the MR command in CSF.
WLM Workload Balancing
You can define real resources representing a number of CPU service units required by a job. They are used for WLM workload balancing within a sysplex. The use of those resources is based on the feedback from IBM WLM queries. CPU service unit resources are supported for systems in a sysplex running in goal mode. When ESP Resource manager determines that a number of CPU service unit resources requested by a job is available on more than one system in the sysplex, it uses the feedback from IBM WLM queries to route the job on the system with the most available service units. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.
Note: CPU service unit resources are available only if the ESP Workload Manager High Performance Option (HPO) is installed.
CPU service unit resources are controlled with the NODE command or initialization parameter and the RESDEF command. See the ESP Workload Manager Reference Guide for commands and the ESP Workload Manager Installation and Configuration Guide for initialization parameters. See the “ESP Workload Manager High Performance Option” in the ESP Workload Manager User’s Guide for information on how to use WLM workload balancing.
To use WLM workload balancing, you must:
• Code one or more NODE initialization parameters or commands. You must specify the SYSPLEX operand.
• Code CPU initialization parameters or commands for each CPU participating in the load balancing. You must use the SYSNAME value as the name.
• Define resources with the RESDEF command specifying the WLM operand.
• Specify the required resources in the ESP Procedures for the jobs you want to direct to the CPU with the most available service units using workload balancing.
Chapter 10–Using Resources
ESP-5.4-UG-05 339
Agent Workload Balancing
You can define real resources representing the percentage of CPU availability required by a job. This is used for workload balancing within a system with multiple ESP Agents. The workload balancing is based on the feedback from the Agents. When ESP Resource manager determines that the percentage of CPU availability requested by a job is available on more than one system, it uses the feedback from the Agents to route the job to the Agent platform with the highest percentage of availability. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.
Note: Agent workload balancing is available only if the ESP Workload Manager High Performance Option (HPO) is installed.
Agent workload balancing is controlled with the CPU and NODE commands or initialization parameters and the RESDEF command. See the ESP Workload Manager Reference Guide for commands and the ESP Workload Manager Installation and Configuration Guide for initialization parameters. See the “ESP Workload Manager High Performance Option” in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.
To use Agent workload balancing, you must:
• Code the NODE initialization parameter or command to define a common node to which all the Agent platform participating in load balancing belong.
• Code CPU commands or initialization parameters with the AGENT operand for each Agent platform participating in the load balancing.
• Define resources with the RESDEF command specifying the MONITOR(CPU) operand and a non-zero POLL operand.
• Specify the needed resources in the ESP Procedures of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.
• Code the ROUTING operand in the AGENT statement of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.
Deleting resources
To delete a resource:
• Use the DELETE operand on the RESDEF command.
Section–Displaying resource information
340 ESP-5.4-UG-05
This example deletes the resource LOWPRIO.
RESDEF LOWPRIO DELETE
Note: You cannot delete a resource while any job is using the resource.
Displaying resource information
To display information about a resource:
• Use the Consolidated Status Facility and ESP Workload Manager commands.
To display the resources associated with that job and determine what jobs have resources allocated:
• Use the LR command for a job using CSF.
If a job is awaiting resources, the status field in CSF states waiting for resources, and the PNODE field in CSF states RESWAIT.
In the following example, the LOCKOUT resource is displayed to determine what jobs are using the resource and what jobs are waiting for the resource.
Resource LOCKOUT List Own WaitResource LOCKOUT Global Renewable 1 needed by PAYJOBD, Appl PAYROLL.396TORONTO * Max=1 Avail=0 1 used by BILLJOBA, Appl BILLING.293
You can drop resource dependencies using the DR command.
To display one or more resources:
• Use the LIST operand on the RESDEF command.
The display shows the name of the resource, the type of resource, and the quantities associated with the resource. You can also display the jobs using the resource and the jobs needing the resource.
This example displays the CICSUP resource. It is a local, threshold resource with an available count of one on CPU1 and an available count of zero on CPU2.
RESDEF CICSUP LISTResource CICSUP Local ThresholdNODE1 CPU1 Avail=1NODE1 CPU2 Avail=0
The following command is used to display all resources.
RESDEF – LIST
Chapter 10–Using Resources
ESP-5.4-UG-05 341
To display resource requirements for jobs not yet submitted in an active Application:
• Use the LISTAPPL (LAP) command.
Sample output looks like this:
LAP TURNOVER.14 ALLAPPL TURNOVER GEN 14 CREATED AT 13.43 ON TUESDAY MAY 15TH, 2001 BY EVENT CYBER.TURNOVER A J1169, STARTED, STEP 1 B, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1 C, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1, 1 LOWPRIO D, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1, 1 LOWPRIO
Step-level resource release
Step-level resource release allows you to return resources to the resource pool at job step-end. Previously, resources would remain allocated to a job for the duration of the job.
Step-level resource release is achieved by the use of a new STEPEND statement. STEPEND is coded within the scope of the job statement. You can release part or all of the resources to the resource pool. You can have more than one STEPEND statement in one job.
Step-level resource release is available for renewable resources only.
Syntax
The following is the syntax of the STEPEND statement:
STEPEND STEPNAME(stepname) PROCSTEP(procstep) –RELRES(n1,resname1,n2,resname2,…)
Operand Description
stepname Indicates the name of the job step.procstep Indicates the name of the proc step.n,resname Indicates the quantity and name of the resource to be released.
Section–Resource absorption
342 ESP-5.4-UG-05
Examples – Stepend statement
The following example shows releasing one unit of a resource after STEP1, PROCA finishes:
APPL ONEJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (6,T3480) STEPEND STEPNAME(STEP1) PROCSTEP(PROCA) - RELRES(1,T3480)ENDJOB
The following example shows releasing two more units of the same resource later in the same job:
APPL ONE JCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (5,T3480) STEPEND STEPNAME(STEP3) PROCSTEP(PROCB) - RELRES(2,T3480)ENDJOB
Ensure the step names and procedure steps you specify match your JCL exactly. You can release resources by specifying just a procedure step and not a step name, if that is how your JCL is tailored.
Note: Step-level Resource Release only works if USERMOD 11 is off. When USERMOD 11 is on, the Application Manager does not get step-end notification.
Resource absorption
In ESP Workload Manager Version 5 Release 1, jobs that required a large resource count would encounter processing delays as jobs with low resource requirements would get the resource, thus keeping the overall available resource count low.
In ESP Workload Manager Version 5 Release 3, Resource Absorption reserves the resources that are available at the time the job is next in the queue and holds them while waiting to accumulate the remainder of resources required for that job. Jobs with smaller resource requirements cannot use the reserved resource.
The ABSORB statement will only ABSORB resources if the request is for less than or equal to the maximum resource defined. An ABSORB statement is coded within the scope of the job, above the RESOURCE statement, where Absorption is to occur. ABSORB can also be used at the Application level.
Chapter 10–Using Resources
ESP-5.4-UG-05 343
A job with a higher priority and the same resource requirements will take the resources and run before the lower priority job with the ABSORB statement.
Once the higher priority job completes, or has the resources it needs, the process of gathering resources starts again.
Example: ABSORB statement
The following example shows coding an ABSORB statement within the scope of the job:
APPL ABSRESJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBX RUN DAILY ABSORB RESOURCE (4,T3480)ENDJOB
When JOBX is first in the queue, the Resource Manager begins the process of reserving the required resources, four units of T3480. Jobs that follow JOBX in the queue that require less than or equal to the same resource, and are the same job priority, will not be submitted before JOBX.
Types of resources
Absorption is available for the following types of resources:
• Renewable• Depletable
Section–Resource absorption
344 ESP-5.4-UG-05
Example 1: Application with absorption
The following example shows an Application with an Absorb statement:
APPL ABSRESJCLLIB 'CYBER.JCLLIB.CNTL'JOB A RESOURCE (1,T3480)ENDJOBJOB B RESOURCE (1,T3480)ENDJOBJOB C RESOURCE (1,T3480)ENDJOBJOB D ABSORB RESOURCE (3,T3480)ENDJOBJOB E RESOURCE (1,T3480)ENDJOBJOB F RESOURCE (1,T3480)ENDJOBSELECT (A,B,C,D,E,F)
Example 2: Application with absorption
The following example shows the CSF display of Application ABSRES:
Jobname APPL GEN Pnode StatusA ABSRES 10 EXEC EXECUTING STEP2B ABSRES 10 EXEC EXECUTING STEP1C ABSRES 10 EXEC EXECUTING STEP1D ABSRES 10 RESWAIT Waiting for ResourcesE ABSRES 10 RESWAIT Waiting for ResourcesF ABSRES 10 RESWAIT Waiting for Resources
The following example shows the current resource allocations:
Resource ABSRES List Own WaitResource ABSRES Global Renewable 3 needed by D, Appl ABSRES.11 1 needed by E, Appl ABSRES.11 1 needed by F, Appl ABSRES.11TOR1 * Max=3 Avail=-3 1 used by A, Appl ABSRES.11 1 used by B, Appl ABSRES.11 1 used by C, Appl ABSRES.11 3 absorbed by D, Appl ABSRES.11
Chapter 10–Using Resources
ESP-5.4-UG-05 345
Example: Controlling mutually exclusive jobs
In this example, a renewable resource controls the execution of two jobs so they do not execute at the same time.
You can also use another method to control mutually exclusive jobs. See “Using Implicit Resources” on page 166.
The criteria for this example are:
• Job A and job B cannot execute at the same time.• Each job requires one unit of a resource called DB2TAB1.
To set-up mutually exclusive jobs:
1. Define a global, renewable resource with maximum and available quantities of one.
RESDEF DB2TAB1 ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)
2. Specify, in the Application in which each job is defined, a requirement of one unit of the resource. For example:
JOB A RESOURCE (1,DB2TAB1)ENDJOB
JOB B RESOURCE (1,DB2TAB1)ENDJOB
Result
At any time, either one unit of the resource is available, or no units of the resource are available. If, for example, job A is executing, the available count of the resource is zero, and ESP Workload Manager prevents job B from executing. ESP Workload Manager returns the resource to the system upon completion (successful or not) of job A.
Extending this example
You can extend this example to any number of jobs.
Resource DB2TAB1
Job A Job BWaiting for Resource
Section–Example: Controlling access to an online system
346 ESP-5.4-UG-05
If you need to control mutually exclusive groups of jobs, see “Example: Controlling mutually exclusive groups of jobs” on page 350.
Example: Controlling access to an online system
This example uses a renewable resource to control the maximum number of concurrent job executions.
The criteria for this example are:
• Access to an IMS region is limited to a small number of jobs at any one time.• Job A and either job B or job C can execute at the same time.• Jobs B and C cannot execute at the same time.
Visually, the requirements look like this:
To control access to an Online System:
1. Define a local, renewable resource with maximum and available quantities of three. The name of the resource is IMS.
RESDEF IMS ADD LOCAL RENEWABLE MAX(3) AVAIL(3)
2. In an Application, specify the number of units each job requires. For example:
Result
ESP Workload Manager processes the jobs as follows:
• Job A can run concurrently with either job B or job C.• Jobs B and C cannot execute at the same time because they require a total count of
four units of the IMS resource.
Job RESOURCE Statement
A RESOURCE (1,IMS)
B RESOURCE (2,IMS)
C RESOURCE (2,IMS)
IMS 31,IMS
2,IMS
2,IMS
A
B
C
Chapter 10–Using Resources
ESP-5.4-UG-05 347
Example: Time periods for low priority jobs
This example uses a threshold resource to control when low priority jobs run.
The criteria for this example are:
• Low priority jobs can execute between 9 am and 4 pm on workdays.• At other times, ESP Workload Manager puts low priority jobs into a waiting for
resources status.
To set time periods for low priority jobs:
1. Define a threshold resource with an available quantity of one. The name of the resource is LOWPRIO.
RESDEF LOWPRIO ADD GLOBAL THRESHOLD AVAIL(1)
2. For each low priority job, identify a resource requirement of one unit of the resource, like this:
JOB ABC RESOURCE (1,LOWPRIO) RUN DAILYENDJOB
3. Set up two Events: one to set the quantity of the resource to zero and the other to set the quantity of the resource to one. The Events look like this:
EVENT ID(OPER.SET_LOWPRIO_ON) SCHEDULE 9AM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(1)'ENDDEF
EVENT ID(OPER.SET_LOWPRIO_OFF) SCHEDULE 4PM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(0)'ENDDEF
Section–Example: Using a resource for a self-completing task
348 ESP-5.4-UG-05
Result
ESP Workload Manager turns the LOWPRIO resource on and off automatically. Any job requiring one unit of the LOWPRIO resource can only execute between 9 am and 4 pm on workdays.
In a multiple CPU environment, you can have different time periods to run low priority jobs on different systems. You can define different local resources and set them independently.
Example: Using a resource for a self-completing task
A link cannot have a resource requirement because a link is marked complete as soon as it becomes ready. Instead, you can use a self-completing task that requires a resource.
Self-completing task
This example uses a task called WAIT4.LOWPRIO that requires one unit of a resource called LOWPRIO.
JOB WAIT4.LOWPRIO TASK PROCESS RUN ANY RELEASE NEXTJOB RESOURCE (1,LOWPRIO) ESP AJ WAIT4.LOWPRIO COMPLETE APPL(WAIT4.%ESPAPGEN)ENDJOB
Result
When the LOWPRIO resource becomes available, ESP Workload Manager readies the task and issues an ESP AJ command to complete itself. This command uses an ESP Workload Manager symbolic variable (%ESPAPGEN) for the Application generation number to ensure the task is marked complete in the correct generation.
RESDEF LOWPRIO SET AVAIL(1)
RESDEF LOWPRIO SET AVAIL(0)
Allow low priority
Disallow low priority
9 a.m. to 4 p.m.
4 p.m. to 9 a.m.
Chapter 10–Using Resources
ESP-5.4-UG-05 349
Example: Controlling access to a data base
In this example, a renewable resource controls access to a data base.
The criteria for this example are:
• Any job that updates the data base requires exclusive use of the data base. In this example, jobs A and Z update the data base.
• Any number of jobs that read the data base can execute at the same time. In this example, jobs B and C read the data base.
To control access to a data base:
1. Define a global, renewable resource with maximum and available counts of 999. The name of the resource is DBASE1.
RESDEF DBASE1 ADD GLOBAL RENEWABLE MAX(999) AVAIL(999)
2. In the Applications for each job, specify the number of units required. A job that updates the data base requires 999 units; a job that reads the data base requires one unit. For example:
Result
ESP Workload Manager processes the jobs as follows:
• Neither job A or job Z can run concurrently with any of the other jobs, because each requires the maximum count for the resource.
• Jobs B and C can run together because they require a total count of two units of the DBASE1 resource.
Example: Running jobs on a particular system
This example uses threshold resources to control on which system a job runs.In a master-proxy environment, you may need jobs to run on a particular system. Instead of hard coding this requirement in JCL, ESP Workload Manager can add, at submit time, the JCL required to route a job to a system.
Job RESOURCE Statement
A RESOURCE (999,DBASE1)
B RESOURCE (1,DBASE1)
C RESOURCE (1,DBASE1)
Z RESOURCE (999,DBASE1)
Section–Example: Controlling mutually exclusive groups of jobs
350 ESP-5.4-UG-05
CPU definitions
Prior to using the resource feature, CPU definitions are added to the ESP Workload Manager initialization parameters that assign names to your master and proxy ESP Workload Manager systems and identify routing JCL for routing jobs to each system. These definitions must be in place for proper routing.
For example, the following are two CPU definitions that specify routing JCL:
CPU SYSA ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSA')-CURRENTCPU SYSB ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSB')
Defining the resources
You can represent each system by a local, threshold resource. The name of the CPU must be the same as that identified in your ESP Workload Manager initialization parameters. For example, the following defines two local, threshold resources called SYSA and SYSB, each with an available count of one.
RESDEF SYSA ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)RESDEF SYSB ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(1)
Requesting the resource
To specify a job must run on SYSB, request one unit of the SYSB resource. For example:
JOB XYZ RESOURCE (1,SYSB) RUN DAILYENDJOB
A job can request other resources, which can be either local or global. ESP Workload Manager tries to find all the resources a job needs on one system.
Result
When the SYSB resource is available, ESP Workload Manager submits the job and adds a system affinity card for SYSB. For example, ESP Workload Manager adds the following card:
/*JOBPARM SYSAFF=SYSB
Example: Controlling mutually exclusive groups of jobs
In this example, ESP Workload Manager controls resources such that one group of jobs does not execute while another group is running. The technique illustrated here can be used whether or not both groups of jobs are in the same Application.
Chapter 10–Using Resources
ESP-5.4-UG-05 351
Criteria for this example
The criteria for this example are:
• One group of jobs consists of jobs B and D.• The other group of jobs consists of jobs C and E.• All jobs in one group must complete successfully before processing any jobs in the
other group.
To control a mutually exclusive group of jobs:
1. Define a global, depletable resource with a maximum quantity of one.
RESDEF MUTUAL ADD GLOBAL DEPLETABLE MAX(1)
2. Use a different task as a predecessor to each group of jobs. Each task requires one unit of the depletable resource and completes itself when the resource requirement is met.
3. Use a link at the end of each group of jobs to reset the available count of the depletable resource to one.
Visual perspective
Visually, the dependencies look like this:
B
START.2(task)
(job)
A(job)
START.1(task)
C(job)
D(job)
E(job)
RESET.2(link)
RESET.1(link)
Section–Example: Controlling mutually exclusive groups of jobs
352 ESP-5.4-UG-05
Sample Application
JCLLIB 'SYS1.JCL'APPL MUTUALJOB A RUN DAILY RELEASE (START.1,START.2)ENDJOBJOB START.1 TASK PROCESS RUN DAILY RELEASE B RESOURCE (1,MUTUAL) ESP AJ START.1 COMPLETE APPL(MUTUAL.%ESPAPGEN)ENDJOBJOB B RUN DAILY RELEASE DENDJOBJOB D RUN DAILY RELEASE RESET.1ENDJOBJOB RESET.1 LINK PROCESS RUN DAILY ESP RESDEF MUTUAL SET MAX(1) ENDJOBJOB START.2 TASK PROCESS RUN DAILY RELEASE C RESOURCE (1,MUTUAL) ESP AJ START.2 COMPLETE APPL(MUTUAL.%ESPAPGEN)ENDJOBJOB C RUN DAILY RELEASE EENDJOBJOB E RUN DAILY RELEASE RESET.2ENDJOBJOB RESET.2 LINK PROCESS RUN DAILY ESP RESDEF MUTUAL SET MAX(1)ENDJOB
Chapter 10–Using Resources
ESP-5.4-UG-05 353
Result
ESP Workload Manager produces the following results:
• When job A ends successfully, ESP Workload Manager completes one of the tasks and starts processing one group of jobs.
• The predecessor task for the other group of jobs requires the MUTUAL resource, which is not available.
• When the first group of jobs is done, a link sets the available quantity of the MUTUAL resource to one. This allows the other group of jobs to process.
Example: Planning for a system shutdown - Part 1
You can use the ELAPSED default resource to prevent long-running jobs from starting prior to a system shutdown. ESP Workload Manager uses historical information to assign elapsed-time resource requirements to each job in an Application when it creates a generation of that Application.
To set up this example:
1. Define the ESP Workload Manager resource representing elapsed time. The name of the resource in this example is RUN_TIME.
2. Turn on the default resource called ELAPSED.
3. Optionally, set up a countdown Procedure that you can use prior to a system shutdown.
Defining the resource representing elapsed time
The following ESP Workload Manager command defines the RUN_TIME resource as a local, threshold resource, with an available quantity of 9999. If you are running a master-proxy environment, you should define a local resource for each CPU and use the same name for the resource.
RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(9999)
Turning on the ELAPSED resource
The following ESP Workload Manager initialization statement causes ESP Workload Manager to use a default resource for elapsed time.
RESDFLT ELAPSED(RUN_TIME)
When ESP Workload Manager creates an Application, each job is assigned a RUN_TIME requirement, unless you have specified RESOURCE (0,RUN_TIME) in your Application.
Section–Example: Planning for a system shutdown - Part 2
354 ESP-5.4-UG-05
Setting up a countdown Procedure
The following example uses an Event called OPER.SHUTDOWN that invokes an ESP Procedure. When you trigger this Event, specify the number of minutes until shutdown in the USER1 field.
Actions carried out by the ESP Procedure
The ESP Procedure:
• Assigns the USER1 variable to a variable called TIME.• Sends a message to CN(01) informing them of the number of minutes until
shutdown.• Sets the available quantity of an ESP Workload Manager threshold resource called
RUN_TIME to the number of minutes until shutdown.• Decrements the TIME variable by one.• If the amount of time now left until shutdown is greater than or equal to zero,
ESP Workload Manager re-triggers the Event in one minute (the amount of time left is passed as the USER1 variable).
• The process repeats until the amount of time left is less than zero.
/*/* PASS NUMBER OF MINUTES TO SHUTDOWN USING USER1/* PARAMETER WHEN TRIGGERING EVENT/*/*SEND MESSAGE, DECREMENT TIME AND RE-TRIGGER EVENT IN /*1 MINUTE IF TIME >=0/*INTEGER TIMETIME=USER1SEND 'SYSTEM COMING DOWN IN %TIME MINUTES' CN(01)RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)TIME=TIME-1IF TIME>=0 THEN ESP TRIGGER OPER.SHUTDOWN + USER1('%TIME') AT('REALNOW PLUS 1 MINUTE')
Example: Planning for a system shutdown - Part 2
In a master-proxy environment, a default resource representing elapsed time (for example RUN_TIME) can be used to prevent jobs from being submitted if there is not enough elapsed time available. If the RUN_TIME resource is defined as a local resource for each CPU, then each CPU can have its own counter. ESP Workload Manager only submits a job to JES if there is enough of the RUN_TIME resource available on any CPU. Even though JES controls where the job executes, ESP Workload Manager can automatically insert a system affinity card to control routing.
Chapter 10–Using Resources
ESP-5.4-UG-05 355
Resource check
When a job’s predecessor and time requirements have been met, ESP Workload Manager checks to see if the required resources are available. For example, ESP Workload Manager checks to see if enough of the RUN_TIME resource is available for job XYZ on each of the CPUs. If no ORDER has been specified on the CPU definitions in the ESP Workload Manager initialization parameters for the master, ESP Workload Manager checks each CPU in the order in which each is defined.
Suppose ESP Workload Manager does not find enough of the resource on SYSA but does find enough of the resource available on SYSB; ESP Workload Manager submits the job and adds a system affinity card to route the job to SYSB. If no JCL has been specified for the ROUTEJCL operand in the CPU initialization parameter, ESP Workload Manager submits the job and JES determines where the job runs.
Multiple resource requirements
If a job needs the RUN_TIME resource and must execute on a particular system, on SYSA for example, you have two resource requirements. You should add a resource requirement of one unit of SYSA in your Applications. This is a local, threshold resource with quantity of one. ESP Workload Manager will not submit a job until enough of the RUN_TIME resource is available and the SYSA resource is available; each of these local resources needs to be available on the same system.
Defining the system resources
Define a local resource that represents the CPU. For example, the following defines two local, threshold resources called SYSA and SYSB, each with an available count of one.
RESDEF SYSA ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)RESDEF SYSB ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(1)
To specify a job must run on SYSA, request one unit of the SYSA resource. For example:
JOB XYZ RESOURCE (1,SYSA)ENDJOB
Defining the default resources
The following example defines two local RUN_TIME resources, one for SYSA and one for SYSB.
RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(99999999)RESDEF RUN_TIME ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(99999999)
Section–Example: Schedule dependency
356 ESP-5.4-UG-05
Setting the resources
You can set the available count of your RUN_TIME resources using the Procedure explained in Part 1 of this example. Use the CPU operand on the RESDEF command to specify the system on which you are setting the resource. For example:
RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)
The system resources, SYSA and SYSB, are always available. You can turn them off when the system ends and turn them on when the system starts using ESP Workload Manager or some other form of automation.
Result
When enough of the RUN_TIME resource is available and the system resource (for example, SYSA or SYSB) is available, ESP Workload Manager submits the job and adds a system affinity card for the appropriate system.
Example: Schedule dependency
This example uses a threshold resource to represent the completion of a job. For example, you can have a job that is dependent on an on-request job with an unpredictable frequency.
In this example, PAYJOB2 requires that the previous run of PAYJOB1 has completed successfully.
To set schedule dependency:
1. Define a threshold resource with an available quantity of zero. In this example, the name of the resource is the same as the name of the predecessor job, PAYJOB1.
RESDEF PAYJOB1 ADD GLOBAL THRESHOLD AVAIL(0)
2. For the successor job, define the first job as a resource requirement.
JOB PAYJOB2 RESOURCE (1,PAYJOB1)ENDJOB
Chapter 10–Using Resources
ESP-5.4-UG-05 357
3. Use a link in each Application to set the quantity of the resource.
When PAYJOB1 completes successfully, use a link to set the available quantity of the PAYJOB1 resource to one.
JOB END.PAYJOB1 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(1)ENDJOB
When PAYJOB2 completes successfully, use a link to set the available quantity of the PAYJOB1 resource to zero. This prevents PAYJOB2 from running without its dependency the next time it is scheduled.
JOB END.PAYJOB2 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(0)ENDJOB
Visually, the dependencies look like this:
Result
ESP Workload Manager produces the following results:
• When PAYJOB1 ends successfully, ESP Workload Manager processes a link called END.PAYJOB1. The link sets the available count of the PAYJOB1 resource to one.
• ESP Workload Manager does not submit PAYJOB2 until the PAYJOB1 resource is available.
• When PAYJOB2 completes successfully, ESP Workload Manager processes a link called END.PAYJOB2. The link sets the available count of the PAYJOB1 resource to zero.
END.PAYJOB1(link)
PAYJOB1(job)
PAYJOB2(job)
END.PAYJOB2(link)
Section–Example: Schedule dependency
358 ESP-5.4-UG-05
ESP-5.4-UG-05 359
Optimizing ESP Applications to UseDistributed Manager
When your ESP Workload Manager network contains one or more Distributed Managers, you can create ESP Applications that run workload on one or more ESP Agents controlled by a Distributed Manager. You should consider certain guidelines when defining Applications that run workload managed by a Distributed Manager.
You can tailor the structure of the ESP Applications that require management by a Distributed Manager to make the most efficient use of the Distributed Manager's ability to manage previously scheduled workload when the mainframe is unavailable.
This chapter describes the guidelines to follow when defining distributed Applications and those ESP Workload Manager features that are not currently supported by the Distributed Manager.
If this is a new installation of ESP Workload Manager that does or will include one or more Distributed Managers, read this chapter before you begin coding ESP Applications.
Section–Planning Applications to optimize Distributed Manager
360 ESP-5.4-UG-05
This chapter contains the following topics
• Planning Applications to optimize Distributed Manager• Establishing ownership of a workload object• Creating distributed Applications• Defining ownership of an Application• Changing ownership of an Application• Changing ownership of an Application dynamically
Planning Applications to optimize Distributed Manager
Before you define a new distributed ESP Application or update an existing distributed Application, you should consider the features and limitations of the Distributed Manager. Creating Applications that optimize the abilities of the Distributed Manager ensure the completion of the Application when the mainframe is unavailable.
To plan optimal Applications:
1. Plan the proposed workflow for this Application.
2. Will this Application be required to run and complete when the mainframe is unavailable?
• Yes. The Distributed Manager must be specified as the owner on the APPL statement.
• No. The owning Manager can default to the central ESP Workload Manager.
3. Review the workflow to identify the following:
• The owning Manager of each workload object. See “Establishing ownership of a workload object” on page 364.
• The number of times the owning Manager changes from a Distributed Manager to the central ESP Workload Manager or vice versa.
See “Example 2: Non-recommended structure” on page 362.
4. Group the workload objects wherever possible, to minimize the number of changes in owning Manager:
• Group z/OS workload at the beginning or end of an Application.• If network integrity is a problem, group workload objects that run on Agents
controlled by one Distributed Manager together, reducing the communication required between Distributed Managers.
See “Example 1: Recommended structure” on page 361.
Chapter 11–Optimizing ESP Applications to Use Distributed Manager
ESP-5.4-UG-05 361
5. Review the list of ESP Workload Manager functions not supported by the current release of DM. Eliminate the use of the following functions in any ESP Application that runs workload managed by a Distributed Manager:
• Resolution of runtime symbolic variables.• Resolution of runtime CLANG or REXX statements.• Workload objects containing EXTERNAL or MANUAL operands.• ESP Workload Manager alerts.
For more detailed information, see “Unsupported functions” on page 364.
6. Create a set of rules for defining distributed Applications at your site.
Features and limitations
The primary purpose of a Distributed Manager is to track scheduled workload that is running on ESP Agents. As status is returned from an Agent, the Distributed Manager passes the status to the central ESP Workload Manager or any other Distributed Managers. If the mainframe is down or communication to the mainframe is unavailable, the Distributed Manager continues to track workload, releasing workload objects under its control as their dependencies are met. When the mainframe becomes available again, the Distributed Manager sends all status updates to the ESP Workload Manager.
The Distributed Manager can release workload under its control, or it can send status to another Distributed Manager. It cannot determine that a workload object has completed if information from the owning Manager (such as the central ESP Workload Manager) is unavailable. See the following examples that graphically describe the optimal way to design the interrelationships within an ESP Application.
Example 1: Recommended structure
The following example shows an ESP Application that runs z/OS, UNIX, and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Note that the workload is grouped to limit the number of owning Manager changes and the number of interdependencies between Managers.
In this example, the dependency on the availability of the mainframe is limited to the beginning of the Application: ESP Workload Manager schedules the Application and manages the first two workload objects. After they complete, if the connection to the mainframe is lost, or the mainframe is taken down for maintenance, the workload
Section–Planning Applications to optimize Distributed Manager
362 ESP-5.4-UG-05
continues to run because it does not rely on intervention from the mainframe. Ideally, remove all dependencies on the mainframe entirely, or limit them to the beginning or end of the Application.
Example 2: Non-recommended structure
The following example shows an ESP Application that runs z/OS, UNIX, and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Distributed Manager 1 controls the UNIX workload, and Distributed Manager 2 controls the Windows NT workload. Note that the workload objects have many interplatform dependencies, and the owning Manager changes six times within the Application. In this example, if the mainframe becomes unavailable after JOB A completes, workload cannot continue to run after UNIX_JOB F and NT_JOB S complete.
In the following example, each Distributed Manager has a dependency on the availability of the mainframe throughout the entire Application. If the mainframe or communication to it becomes unavailable at any point during the execution of the Application, the work cannot continue to run. A workload object can complete, but
JOB A
JOB B
NT_JOB S
NT_JOB T
NT_JOB V
Distributed Manager 1 Distributed Manager 2
Central ESP Workload Manager
UNIX_JOB F
UNIX_JOB G
UNIX_JOB H
Change
Change
Chapter 11–Optimizing ESP Applications to Use Distributed Manager
ESP-5.4-UG-05 363
the next workload object will not be released until the mainframe becomes available again. This Application structure defeats the purpose of the Distributed Manager.
UNIX_JOB F
JOB A
UNIX_JOB G
JOB B
NT_JOB S
NT_JOB S
NT_JOB S
JOB C
Central ESP Manager
Distributed Manager 1 Distributed Manager 2
Central ESP Manager
Change
Change
Change
ChangeChange
ChangeChange
Section–Establishing ownership of a workload object
364 ESP-5.4-UG-05
Unsupported functions
Some ESP Workload Manager functions are not yet supported by ESP Distributed Managers. While your workload objects will not cause errors in the Distributed Manager if they contain statements the Distributed Manager does not recognize, your workload can not perform as expected. The following ESP Workload Manager functions are not supported by Distributed Managers:
• Resolution of runtime symbolic variables• Resolution of runtime CLANG or REXX statements• Workload objects containing EXTERNAL or MANUAL operands• ESP Workload Manager alerts
Support of these functions varies depending on the owning Manager of the Application or workload object. See the following table to determine when a function is unavailable:
Establishing ownership of a workload object
The owning Manager of a workload object controls the following:
• When the workload object is submitted• Status updates regarding the workload object• Reporting to other Managers about the status of the workload object
State of central ESP Workload Manager
Functions Unavailable if Owned by ESP Workload Manager
Functions Unavailable if Owned by a Distributed Manager
ESP Workload Manager available
• Runtime symbolic variables
• Runtime scripting of CLANG and REXX
• EXTERNAL• MANUAL• Alerts
ESP Workload Manager unavailable
• Runtime symbolic variables• Runtime scripting of
CLANG and REXX• EXTERNAL• MANUAL• Alerts
• Runtime symbolic variables
• Runtime scripting of CLANG and REXX
• EXTERNAL• MANUAL • Alerts
Chapter 11–Optimizing ESP Applications to Use Distributed Manager
ESP-5.4-UG-05 365
Owner of an Application
The owning Manager of an Application is defined on the APPL statement or in the workload definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager. The owner specified at the Application level also applies to all links and tasks within the Application, unless the owner is specified in the link or task definition.
The owning Manager determines the status of the Application and is the only Manager that can complete the Application. Therefore, if you are running a distributed Application that must be able to complete when the mainframe is unavailable, a Distributed Manager must be the owner.
Owner of a link or task
The owner of a link or task is defined either at the Application level, with the OWNER operand on the APPL statement, or in the link or task definition with the OWNER operand. Specifying the OWNER operand in the link or task definition overrides any specified at the Application level.
Specifying a Distributed Manager as the owning Manager of a link or task allows you to define the link or task as distributed workload. The Distributed Manager determines if the conditions of the link or task are met.
Owner of a z/OS job
The owner of a z/OS job is always the central ESP Workload Manager.
Owner of a distributed workload object
The owner of a distributed workload object is not determined by an OWNER operand—it is determined by the network topology defined in the AGENTDEF file. A Manager—either a Distributed Manager or the central ESP Workload Manager—owns each Agent. The Manager that owns the Agent running the workload object owns the distributed workload object.
Creating distributed Applications
You can optimize your ESP Applications for use with a Distributed Manager by keeping some simple rules in mind when designing the Application. Also, consider if the Application will run most efficiently under the ownership of a Distributed Manager or the central ESP Workload Manager.
Section–Defining ownership of an Application
366 ESP-5.4-UG-05
To create an ESP Application that optimizes the Distributed Manager's capabilities:
1. Specify a Distributed Manager as the owner if this Application must be able to complete when ESP Workload Manager is unavailable. Specify an OWNER operand on the APPL statement or specify an owner in the Owner field in ESP Workstation.
2. Structure the Application to minimize embedded dependencies on z/OS workload. If dependencies on z/OS workload are required within the Application, try to place them at the beginning or end of the Application.
3. Ensure you do not include external or manual jobs within the Application.
4. Ensure any symbolic variables can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime symbolic variables.
5. Ensure any CLANG or REXX used within the Application can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime-scripting requirements.
6. Ensure you do not use ESP Workload Manager alerts in the Application.
7. Group workload by Distributed Manager where possible.
Defining ownership of an Application
The owning Manager of an Application is the only Manager that can start or complete an Application, change the status of an Application, or send notifications to the other Managers regarding the status of an Application. The owner of an Application is also the owner of all links and tasks within the Application, unless the owner is specified within the link or task definition.
The owning Manager of an Application is defined on the APPL statement or in the Application definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager.
If you are running a distributed Application that must be able to complete when the mainframe is unavailable, specify a Distributed Manager as the owner.
Chapter 11–Optimizing ESP Applications to Use Distributed Manager
ESP-5.4-UG-05 367
To define the owner of an Application:
1. Create a new Application or edit an existing Application.
2. Proceed to step 4 if you are using ESP Workstation. Otherwise continue.
Proceed to step 3 if you want to specify an owner that changes based on a schedule. Otherwise continue.
Specify an OWNER operand on the APPL statement. Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character, as follows:
APPL PAYROLL OWNER(DMTOR)
Proceed to step 5.
3. Specify an OWNER operand on the APPL statement. Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character. Define the circumstances under which you want ownership of the Application determined. Specify the exceptions first. Specify the normal business-as-usual circumstances next. The following example defines a Distributed Manager as the owner of the Application on weekends:
IF TODAY('WEEKEND') THEN - APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL
Proceed to step 5.
4. Bring up Workload Definition Defaults in the Workload Editor.
Find the Owner field on the Application tab.
Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character.
5. Simulate the Event that runs this Application for each circumstance. Ensure the results are as expected.
6. Save the Application.
7. Upload the Procedure to the mainframe if you are using ESP Workstation.
Changing ownership of an Application
Depending on how ownership is specified in your Application, there can be times when you want to change the ownership, such as when you expect the mainframe to be shut down for maintenance.
You need to change the ownership in the Application, and trigger the Event prior to shutting down ESP Workload Manager.
Section–Changing ownership of an Application dynamically
368 ESP-5.4-UG-05
To change the ownership of an Application:
1. Edit the Application.
2. Change the owner to the new name if an owner is currently defined for the Application. Otherwise, add an owner name in the Owner field on ESP Workstation, or add an OWNER statement as follows:
APPL PAYROLL OWNER(DMTOR)
3. Simulate the Event that runs this Application to ensure expected results.
4. Save the Application.
5. Upload the Procedure to the mainframe if you are using ESP Workstation.
When the Event is triggered, the new owner controls the status of the Application.
Changing ownership of an Application dynamically
Depending on how ownership is specified in your Application, there can be times when you want to change the ownership dynamically. For example, if the mainframe is shut down for maintenance on a certain schedule, you can use ESP Workload Manager to change the ownership of the Application to a Distributed Manager during those scheduled times. This is especially important if your Application must be able to complete (and perhaps run additional generations of the Application) even if the mainframe is unavailable.
Ensure the Event is triggered prior to shutting down ESP Workload Manager.
To change the ownership of the Application dynamically:
1. Create a new Application or edit an existing Application.
2. Define the circumstances under which you want ownership of the Application determined. Specify the exceptions first. Specify the normal business-as-usual circumstances next. For example:
IF TODAY('FRIDAY') THEN - APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL
3. Simulate the Event that runs this Application for each circumstance. Ensure the results are as expected.
4. Save the Application.
5. If you are using ESP Workstation, upload the Procedure to the mainframe.
ESP-5.4-UG-05 369
Using XCF with ESP Workload Manager
ESP Workload Manager Version 5 Release 4 can use the Cross-System Coupling Facility (XCF) component of z/OS.
This chapter contains the following topics:
• Commands• XCF Services• State awareness• Trace
Section–Commands
370 ESP-5.4-UG-05
Commands
All the ESP Workload Manager XCF commands can be issued via:
• ESP Workload Manager page mode, option G from the ESP Workload Manager main menu
• ESP Workload Manager line mode
• ESP Workstation
• MVS MODIFY command
The following display is the response from the XCF HELP command:
XCF Command Options
DELETE|DEL MEMBER|MEM|M memberDISPLAY|D ACTIVITY|ACTIVE|ACT|ADISPLAY|D GROUPS|GROUP|GR|GDISPLAY|D SERVICES|SERVICE|SERV|SDISPLAY|D SYSTEMS|SYSTEM|SYSDISPLAY|D TRACE|TRFORCE MEMBER|MEM|M memberHELP|H|?PURGE|PG CONNECTION|CON connectionPURGE|PG SERVICE|SERV|S serviceRESTART|RES|RS|SPIN|SP TRACE|TRSET|T INTERVAL|INT intervalSET|T MEMBER|MEM|M member MASTER|MSET|T SERVICE|SERV|S service SUSPEND|S(seconds)SET|T TERMOPT|TO LEAVE|L|QUIESCE|QSET|T TRACE|TR SYSOUT|S(class)START|S SERVICE|SERV|S serviceSTART|S TRACE|TRSTOP|P GROUP|GR|GSTOP|P MEMBER|MEM|M(member)STOP|P SERVICE|SERV|S serviceSTOP|P TRACE|TRVERIFY|VER MEMBER|MEM|M member
XCF Services
XCF Services are functions of ESP Workload Manager that use sysplex architecture. ESP Workload Manager currently registers these two XCF Services:
• Data-set triggering (dstrig)• Job tracking (tracking)
Chapter 12–Using XCF with ESP Workload Manager
ESP-5.4-UG-05 371
Enabling XCF Services
XCF Services are registered and started via the XCF START SERVICE xxxx command. This command must be coded in the initialization parameter data set. XCF Services must be coded in all the ESP Workload Manager subsystems in the XCF group.
When an XCF Service is coded and started on the ESP Workload Manager master, a listener is activated. When an XCF Service is started on the ESP Workload Manager proxies, it will connect to the ESP Workload Manager master’s listener for that Service.
Job tracking and data-set triggering
In ESP Workload Manager Version 5 Release 1, an ESP Workload Manager proxy subsystem writes job tracking and data-set-triggering records to a QUEUE file. The ESP Workload Manager master subsystem reads those records from the QUEUE file.
In ESP Workload Manager Version 5 Release 3, you have the option to use XCF for job tracking and data-set triggering. When XCF is used, the ESP Workload Manager proxy transmits job tracking and data-set-triggering records to the ESP Workload Manager master via XCF. You have a faster vehicle for communication, thus reducing contention on the QUEUE file.
If XCF Services are not enabled, ESP Workload Manager Version 5 Release 3 will continue to write job tracking and data-set-triggering records to the QUEUE file.
QUEUE file
The QUEUE file is still required in ESP Workload Manager Version 5 Release 3.
The QUEUE file has a record of abended job information (available via the DAB command) and information on jobs in the Input, Execute, and Output pnodes.
QUEUE file to XCF migration considerations
The ESP Workload Manager master will always check the QUEUE file for job tracking and data-set-triggering records written by ESP Workload Manager proxies. To migrate from the QUEUE file to an XCF connection, add the XCF START SERVICE xxxx commands in the ESP Workload Manager master and ESP Workload Manager proxy initialization parameter data set at the same time. If you are going to add the XCF START SERVICE xxxx commands separately, put them in the ESP Workload Manager master first.
If the ESP Workload Manager proxy has the XCF START SERVICE xxxx commands in the initialization parameters and the ESP Workload Manager master does not, job tracking and data set triggering records cannot be sent from the ESP Workload Manager proxy to the ESP Workload Manager master.
Section–XCF Services
372 ESP-5.4-UG-05
To start XCF Services:
Use the following is the syntax for the XCF START SERVICE commands in the initialization parameter data set:
XCF START SERVICE DSTRIGXCF START SERVICE TRACKING
Displaying XCF Services
The following is an example of a response to the XCF DISPLAY SERVICE command entered from the ESP Workload Manager master. This example includes XCF Services available with HAO and HPO:
Service Status Group Member SuspDSTRIG Active QS10 QS10M3 120ROUTING Active QS10 QS10M3 120SCOREBD Active QS10 QS10M3 120TRACKING Active QS10 QS10M3 120
This is an example of a response to the XCF DISPLAY SERVICE command entered from an ESP Workload Manager proxy. This example includes XCF Services available with HAO and HPO:
Service Status Group Member SuspDSTRIG Active QS10 QS10S 120ROUTING Active QS10 QS10S 100SCOREBD Active QS10 QS10S 120TRACKING Active QS10 QS10S 100
To display active XCF Service connections:
Enter the following command from an ESP Workload Manager master:
XCF DISPLAY ACTIVE
The following is an example of a response to the above command:
Group=P520, Member=P521Partner Service Status ConnectionListener DSTRIG ActiveListener TRACKING ActiveP522 DSTRIG Active 1,5P522 TRACKING Active 3,7
To stop an XCF Service:
• Enter the following command:
XCF STOP SERVICE DSTRIG
To restart an XCF Service on the fly after it has been stopped:
• Enter the following command:
XCF START SERVICE DSTRIG
Chapter 12–Using XCF with ESP Workload Manager
ESP-5.4-UG-05 373
Purging XCF Services
When you purge a Service on an ESP Workload Manager master, the Service is purged and restarted. ESP Workload Manager stops and starts the listener. You should only use purging in situations when XCF STOP SERVICE does not appear to be working.
Example of Purging a Service
The following is an example of purging an XCF Service:
XCF PURGE SERVICE DSTRIG
Result:
ESP4221I Listener and 1 connection purged, Service=DSTRIG, Group=P520, Member=P521
Example of a restarted Service
To display the active XCF connections from an ESP Workload Manager master, enter:
XCF DISPLAY ACTIVE
The following example shows the Service DSTRIG connected on a new listener compared to the previous DISPLAY ACTIVE illustration:
Group=P520, Member=P521Partner Service Status ConnectionListener TRACKING ActiveListener DSTRIG ActiveP522 TRACKING Active 3,7P522 DSTRIG Active 4,8
State awareness
In an XCF group, state awareness exists between all the ESP Workload Manager subsystems in the group. Each ESP Workload Manager is a unique member of a common group, but they all know each other’s operating status.
Each ESP Workload Manager subsystem knows which other ESPs are active, quiesced, or failed in the XCF group. Each ESP Workload Manager member also knows the XCF Services that are available on the ESP Workload Manager master.
Section–Trace
374 ESP-5.4-UG-05
To display the members in the XCF group and their respective states:
• Use the XCF DISPLAY GROUP command.
XCF DISPLAY GROUPGroup=QS10 Member=QS10M3 Interval=60 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Shadow ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Master ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy ActiveQS10 QS10S2 SYSC 0046 QS10S2 QS12 Proxy Active
To stop an ESP Workload Manager XCF member:
• Use the XCF STOP MEMBER command.
XCF STOP MEMBER member
To stop all the ESP Workload Manager XCF members in the XCF group simultaneously:
• Use the XCF STOP GROUP command.
XCF STOP GROUP
Trace
The XCF Trace facility is a debug tool. XCF Trace captures data and spools the output to a preset sysout class. Only use the tool when instructed by Cybermation technical support.
To activate and capture data using XCF Trace:
1. Define a sysout class by entering:
XCF SET TRACE SYSOUT(x)
2. Activate the trace by entering:
XCF START TRACE
3. When you have captured the data, turn the trace off and spool the current XCF trace file to output by entering:
XCF STOP TRACE
SPIN TRACE
The XCF SPIN TRACE command spools the current XCF trace file to output and starts a new XCF trace file. It can be used when the trace file is started upon initialization of the ESP Workload Manager subsystem and kept running for the duration of the subsystem session.
Chapter 12–Using XCF with ESP Workload Manager
ESP-5.4-UG-05 375
Usage notes
The XCF SET TRACE SYSOUT(x) and XCF START TRACE commands can be specified in the initialization parameter data set, but XCF STOP TRACE and XCF SPIN TRACE cannot. It is recommended to put XCF SET TRACE SYSOUT(x) in the initialization parameter data set because then only XCF START TRACE is required to start it.
Section–Trace
376 ESP-5.4-UG-05
ESP-5.4-UG-05 377
ESP Workload Manager High Performance Option
This chapter provides you with information on the ESP Workload Manager High Performance Option.
This chapter contains the following topics:
• Expedite• Resource Balancing• Workload Balancing• XCF Status Monitoring• XCF Routing Service• XCF Scoreboard Service
Section–Expedite
378 ESP-5.4-UG-05
Expedite
The Expedite feature in the ESP Workload Manager High Performance Option (HPO) provides a method of accelerating a job. With Expedite, you can define actions specifying how a job should be accelerated based on certain criteria.
If the command prefix of the first JES node is different from the command prefix on other JES nodes, you cannot use the EXPEDITE feature on them to:
• Change the class of a job• Change the priority of a job• Start a job immediately
Overview
Expedite Actions are defined in a policy. An Expedite Policy is associated with an ESP Application through the expedite statement. An Expedite Policy specifies how a job priority should be increased. The criteria are OVERDUE (the job start or end time is overdue) and CRITICAL_PATH (the job is on the critical path). OVERDUE and CRITICAL_PATH are EXPEDITE command operands.
Expedite Policies are defined in the initialization parameter data set or with the EXPEDITE command. The EXPEDITE command and expedite statement are documented on subsequent pages in this chapter and also in the ESP Workload Manager Reference Guide.
For information on the EXPEDITE initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.
The Expedite feature is documented in the following order in this chapter:
• Expedite actions• Examples of Expedite policy definitions• Expedite statement
Expedite actions
The methods of accelerating a job are known as Expedite actions.
The following Expedite actions are available for submitted jobs that are not yet executing. The objective of a job expedite is to initiate the job as soon as possible or to make it run as quickly as possible when it does start.
Option Action
1 Change the job JES execution class, specified by the EXPEDITE CLASS(class) operand.
2 Change (increase) the job priority on the JES execution queue, specified by the EXPEDITE PRIORITY(priority) operand.
3 Start the job immediately, specified by the EXPEDITE START operand.
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 379
The following Expedite actions are available for executing jobs. The objective of a job expedite is to increase the job dispatching priority.
The following Expedite action is available for a job that is not yet submitted.
Examples of Expedite policy definitions
The following command defines an Expedite policy, called POLICY_1. The Expedite policy specifies that a job in the ESP Application associated it is associated with, be expedited if its start or end time is overdue. If the job is expedited while it is waiting for execution, its execution queue priority will be set to 15. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.
EXPEDITE POLICY_1 ADD OVERDUE PRIORITY(15) SRVCLASS(JES_FAST)
If the following command is then issued after the previous one, a job in an ESP Application associated with Expedite policy POLICY_1 will be expedited if its start time or end time is overdue and it is on the critical path. If the job is expedited while it is waiting for execution, its job class will be set to F. It is started (initiated), provided F is an IBM WLM-managed job class queue. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.
EXPEDITE POLICY_1 ALTER CRITICAL_PATH NOPRIORITY + CLASS(F) START
The following command has the same effect as issuing the previous two in succession:
EXPEDITE POLICY_1 ADD OVERDUE CRITICAL_PATH +CLASS(F) START SRVCLASS(JES_FAST)
Expedite statement
The expedite statement associates an ESP Workload Manager Expedite policy with an ESP Application. When EXPEDITE is specified within the scope of a job in the Application, it designates the Expedite policy for that job only. When EXPEDITE is specified outside the scope of any job in the Application, it designates the default Expedite policy for that Application.
Option Action
1 Change the job service class, specified by the EXPEDITE SRVCLASS(srvclass) operand. This requires the system be in IBM WLM goal mode.
2 Change the job performance group, specified by the EXPEDITE PERFORM(pgn) operand. This requires the system be in IBM WLM compatibility mode.
Option Action
1 Change the ESP Workload Manager priority of a job waiting for ESP Workload Manager resources dynamically. This is specified by the ESP_PRIORITY operand.
Section–Expedite
380 ESP-5.4-UG-05
Host security check
A user’s authority to specify an EXPEDITE statement in the ESP Application is governed by a host security check on the Expedite policy’s name.
The user the Application is running on behalf of must have read access to the specified Expedite policy host security resource name; otherwise, the Expedite action is ignored.
The host security resource name for an Expedite policy is:
prefix.EXPEDITE.name
Example
If an Application is invoked under user ID DEPT001 and contains the following statement:
EXPEDITE FAST_BAT
A host security check is made to ensure that user DEPT001 has read access to host security resource ESP.EXPEDITE.FAST_BAT before the Application can go ahead.
Related information
For more information, see the host security resource name EXPEDITE in the ESP Workload Manager Security Guide.
Example of using the expedite statement
For this example, the following Expedite policy definitions exist:
EXPEDITE FAST ADD OVERDUE PRIORITY(15) SRVCLASS(FAST)EXPEDITE SUPER ADD OVERDUE START SRVCLASS(SUPER)
Operand Description
prefix Indicates the ESP Workload Manager resource name prefix specified in the PREFIX operand of the SAFCLASS statement in the initialization parameters. This is usually PREFIX(ESP).
name Indicates the Expedite policy name.
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 381
Example Application:
APPL DAILYRUNJCLLIB 'DEPT01.JCLLIB'EXPEDITE FAST
JOB JOB001 DUEOUT EXEC REAL PLUS 10 MINUTES RELEASE JOB002 RUN DAILYENDJOBJOB JOB002 EXPEDITE OFF RELEASE JOB003 RUN DAILYENDJOBJOB JOB003 EXPEDITE SUPER RUN DAILYENDJOBJOB JOB004 EXPEDITE OFF RUN DAILYENDJOB
How it works:
• Job JOB001 is associated with Expedite policy FAST and is expedited if it has not completed successfully 10 minutes after the trigger time of the corresponding Event.
• Job JOB002 is not associated with any Expedite policy and therefore cannot be expedited.
• Job JOB003 is associated with Expedite policy SUPER but can only be expedited manually (for example, by the XP CSF line command), as it has no due-out specification and Expedite policy SUPER does not specify CRITICAL_PATH as a criterion.
• Job JOB004 is not associated with any Expedite policy and therefore cannot be expedited.
Note: The above example is intended primarily to illustrate the capabilities of the expedite statement. Typically, most Applications will have a single, global-scope EXPEDITE statement to govern all jobs in the Application.
Section–Resource Balancing
382 ESP-5.4-UG-05
Resource Balancing
Resource balancing is an enhancement that enables ESP Workload Manager to monitor all the ESP Workload Manager resources in the ESP resource topology for availability and utilization.
When the ESP Workload Manager High Performance Option is not installed, if the first CPU in the ESP resource topology has a resource definition count of AVAIL=x, and x matches workload in the queue, ESP Workload Manager still sends workload to the first processor, regardless of whether or not the CPU was operating at ESP Workload Manager resource capacity.
When the ESP Workload Manager High Performance Option is installed, ESP Workload Manager checks all the CPUs and determines which machine has more available resources. ESP Workload Manager then selects the least loaded CPU and distributes the workload accordingly. ESP Workload Manager balances the workload across the ESP resource topology.
Usage note
There is no coding required to enable resource balancing. With the ESP Workload Manager High Performance Option installed, it is an automatic behavioral change
Workload Balancing
ESP Workload Manager uses workload balancing to select the where to run workload. For z/OS systems, ESP Workload manager uses WLM workload balancing, which is based on information from IBM WLM. For workload associated with ESP Agents, ESP Workload manager uses Agent workload balancing, which is based on polling the Agent platforms.
WLM workload balancing
To use WLM workload balancing, you must:
• Code one or more NODE initialization parameters or commands. You must specify the SYSPLEX operand.
• Code CPU initialization parameters or commands for each CPU participating in the load balancing. You must use the SYSNAME value as the name.
• Define resources with the RESDEF command specifying the WLM operand.
• Specify the required resources in the ESP Procedures for the jobs you want to direct to the CPU with the most available service units using workload balancing.
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 383
Use of CPU service unit resources
You can define real resources representing a number of CPU service units required by a job. They are used for WLM workload balancing within a sysplex. The use of those resources is based on the feedback from IBM WLM queries. CPU service unit resources are supported for systems in a sysplex running in goal mode. When ESP Resource manager determines that a number of CPU service unit resources requested by a job is available on more than one system in the sysplex, it uses the feedback from IBM WLM queries to route the job on the system with the most available service units. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.
Coding RESDEF with WLM operand
You must define a WLM resource as LOCAL RENEWABLE. In a multi JES node sysplex environment, you must also specify GRAVITY in the resource definition.
To determine the MAX count, see the “CPU capacity table” in the MVS planning: Workload Management IBM manual. Choose a number of service units per second for your CPU model and multiply it by either 60, 180, or 600 for SUM60, SUM180, or SUM600 respectively. You can use the result or any higher number. If your installation has CPUs of different models, use the RESDEF SET command to adjust the counts on individual CPUs.
You can determine the quantity of the WLM resource required by jobs using either the CPU service units or the CPU time shares (percentage) of jobs in the entire workload. You can calculate these numbers based on ESP Workload Manager history reports with the SUNITS field selected. You can also use other performance and reporting tools. It is important that you understand that the resource represents the rate at which service units are consumed (over the last 60, 180, or 600 seconds), and not the total amount used by a job. Reports usually show the total amount.
ESP Workload Manager routes a job to one of the available systems based on the WLM resources requested by a job and other requested resources.
IBM WLM feedback is a measurement of recent but past activity; therefore, it is not a precise prediction of a CPU load by the time ESP Workload Manager submits a job. The real value of a WLM resource is the number of unused service units. This number can be different from the number of service units available for a job if that job service class is higher than the service class of the currently executing workload.
The workload is balanced between all the CPUs that belongs to the same NODE in the resource topology. The node is defined with the NODE initialization parameter or command (it must include the SYSPLEX operand).
Section–Workload Balancing
384 ESP-5.4-UG-05
Scenario using WLM workload balancing
Assumptions:
• 2 CPUs in node Toronto• 3 CPUs in node Chicago
Setting the topology:
NODE TORONTO ADD SYSPLEXNODE CHICAGO ADD SYSPLEXCPU T1 ADD NODE(TORONTO) CURRENTCPU T2 ADD NODE(TORONTO)CPU C1 ADD NODE(CHICAGO)CPU C2 ADD NODE(CHICAGO)CPU C3 ADD NODE(CHICAGO)
Setting the resources
RESDEF MAINRES ADD LOCAL RENEWABLE GRAVITY + MAX(100) WLM(SUM180)
ESP Workload Manager will receive the number of unused CPU service units over three minutes from IBM WLM. The number of unused CPU service units is obtained before a job using the resource is submitted.
Specifying a job:
JOB mytojob RUN DAILY RESOURCE(1,MAINRES)ENDJOB
The job runs on the CPU where maximum service units is available. The number 1 in RESOURCE(1,MAINRES) should be replaced by the number of service units used by the job. You can obtain this number with the LJE command and in the history report.
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 385
Agent workload balancing
To use Agent workload balancing, you must:
• Code the NODE initialization parameter or command to define a common node to which all the Agent platform participating in load balancing belong.
• Code CPU commands or initialization parameters with the AGENT operand for each Agent platform participating in the load balancing.
• Define resources with the RESDEF command specifying the MONITOR(CPU) operand and a non-zero POLL operand.
• Specify the needed resources in the ESP Procedures of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.
• Code the ROUTING operand in the AGENT statement of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.
Resource representing the percentage of CPU availability
You can define real resources representing the percentage of CPU availability required by a job. This is used for workload balancing within a system with multiple ESP Agents. The workload balancing is based on the feedback from the Agents. When ESP Resource manager determines that the percentage of CPU availability requested by a job is available on more than one system, it uses the feedback from the Agents to route the job to the Agent platform with the highest percentage of availability. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.
Coding RESDEF with MONITOR(CPU) operand
You must define a MONITOR(CPU) resource as LOCAL RENEWABLE GRAVITY.
The system asks all Agents to provide the percentage of availability on the platforms they control. This is done at the frequency specified by the POLL operand for platforms where the corresponding CPU initialization parameter includes an AGENT operand. You can limit the scope of the resource you define by using the NODE and CPU operands.
ESP Workload Manager routes a job to one of the available systems based on the MONITOR(CPU) resources requested by a job and other requested resources.
The workload is balanced between all the Agent platform in the same NODE. The node is defined with the NODE initialization parameter or command.
Section–Workload Balancing
386 ESP-5.4-UG-05
Scenario using Agent workload balancing
Assumptions:
• 3 Windows NT CPUs associated with Agents called AGwin1, AGwin2, and AGwin3
• 4 UNIX CPUs associated with Agents called AGunix1, AGunix2, AGunix3, and AGunix4
Setting the topology:
NODE WIN ADDNODE UNIX ADDCPU WIN1 ADD NODE(WIN)AGENT(AGwin1)CPU WIN2 ADD NODE(WIN)AGENT(AGwin2)CPU WIN3 ADD NODE(WIN)AGENT(AGwin3)CPU UNIX1 ADD NODE(UNIX)AGENT(AGunix1)CPU UNIX2 ADD NODE(UNIX)AGENT(AGunix2)CPU UNIX3 ADD NODE(UNIX)AGENT(AGunix3)CPU UNIX4 ADD NODE(UNIX)AGENT(AGunix4)
All the CPUs that have the same NODE operand in the CPU initialization parameter are linked.
Setting the resources:
RESDEF RESWIN ADD NODE(WIN) LOCAL RENEWABLE GRAVITY MAX(100)+ MONITOR(CPU) POLL(5 MINUTES)RESDEF RESUNIX ADD NODE(UNIX) LOCAL RENEWABLE GRAVITY MAX(100)+ MONITOR(CPU) POLL(5 MINUTES)
ESP Workload Manager will receive the status of every CPU in both nodes every five minutes.
Specifying an NT job:
NT_JOB myntjob RUN DAILY RESOURCE(1,RESWIN) AGENT AGwin1 ROUTING CMDNAME C:\myjob.exeENDJOB
The ROUTING operand specifies that the job may run on any CPU in the same node as the CPU associated with Agent AGwin1.
Note: The value of 1 in the RESOURCE statement should be changed to a realistic value representing the actual load of the job on CPUs. If you do not adjust this value, the lag time due to the frequency of the polling may affect the CPU selection.
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 387
Specifying a UNIX job:
UNIX_JOB myunjob RUN DAILY RESOURCE(1,RESUNIX) AGENT AGunix1 ROUTING SCRIPTNAME /SW/myjobENDJOB
The ROUTING operand specifies that the job may run on any CPU in the same node as the CPU associated with Agent AGwin1.
Note: The value of 1 in the RESOURCE statement should be changed to a realistic value representing the actual load of the job on CPUs. If you do not adjust this value, the lag time due to the frequency of the polling may affect the CPU selection.
XCF Status Monitoring
Note: XCF status monitoring is also available with the ESP Workload Manager High Availability Option (HAO).
XCF status monitoring is a feature that monitors ESP Workload Manager XCF members’ activity for any possible problems. An ESP Workload Manager XCF member requests XCF status monitoring when it joins the XCF group.
When XCF status monitoring is enabled, ESP Workload Manager notifies XCF of an interval period. The interval period is specified in seconds. ESP Workload Manager then updates its status with XCF according to the specified interval.
XCF status monitoring is enabled by coding the INTERVAL operand on the SYSPLEX initialization parameter.
How XCF status monitoring works
If an ESP Workload Manager subsystem has not updated its XCF status monitoring field for at least two intervals, XCF warns the other members in the XCF group of a possible problem with that ESP Workload Manager as there can be either a loop or hang in the ESP Workload Manager main task.
Message ESP4316I is issued:
ESP4316I XCF status update missing, possible main task loop or hang
Note: This message may not necessarily indicate a problem with the ESP Workload Manager. For example, the system that ESP Workload Manager is running under can be heavily loaded and z/OS is not dispatching ESP Workload Manager.
Section–XCF Routing Service
388 ESP-5.4-UG-05
Second warning message
When XCF does not receive a positive response from the failing ESP Workload Manager subsystem, XCF broadcasts to all the other ESP Workload Manager XCF members in the XCF group that a status update missing condition exists for that member.
Message ESP4331W is issued:
ESP4331W XCF status update missing
XCF member failure
If the failing ESP Workload Manager subsystem terminates, message ESP4317I is issued:
ESP4317I XCF member state change
Normal operating status resumed
If the failing ESP Workload Manager subsystem resumes its normal operating status, message ESP4318I is issued:
ESP4318I XCF status update resumed
For the full explanation of the ESP Workload Manager messages indicated above, see the ESP Workload Manager Messages manual.
XCF Routing Service
Note: XCF routing service is also available with the ESP Workload Manager High Availability Option (HAO).
XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services also apply to the XCF ROUTING and SCOREBD Services.
Note: Cybermation recommends that the default routing be changed from LOCAL to MASTER during installation. You can display your current routing status by using the ROUTING STATUS command.
Overview
The ROUTING Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and Workstation servers) connected to the ESP Workload Manager proxy the ability to route subsystem requests, usually ESP Workload Manager commands, to the ESP Workload Manager master. The ESP Workload Manager master processes the subsystem requests and routes command responses back
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 389
to the ESP Workload Manager client through the ESP Workload Manager proxy. In this scenario, the ROUTING MASTER command must be specified.
Description
Without ESP Workload Manager High Availability Optionor High Performance Option
Typically installations run an ESP Workload Manager proxy on each system in the sysplex and the ESP Workload Manager master runs on one of the systems. To issue subsystem requests to the ESP Workload Manager master, an ESP Workload Manager client must connect directly to the ESP Workload Manager master. Therefore, the TSO/ISPF user and/or Workstation Server must be on the same system as the ESP Workload Manager master.
With ESP Workload Manager High Availability Optionor High Performance Option
By connecting an ESP Workload Manager client to the ESP Workload Manager proxy rather than to the ESP Workload Manager master, the client (TSO/ISPF users or Workstation Servers) can run on any system in the sysplex and issue subsystem requests to the ESP Workload Manager master through the XCF ROUTING Service.
Benefit
It does not matter which system in the sysplex the ESP Workload Manager master is running on. The ESP Workload Manager proxy always knows, through its XCF group member State Awareness capabilities, where the ESP Workload Manager master is and how to access it.
Enabling XCF ROUTING
XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if that data set is different than the ESP Workload Manager master. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.
The following is an example enabling XCF ROUTING:
XCF START SERVICE ROUTING
The ROUTING command
The ROUTING command is an ESP Workload Manager command that can be issued in ESP Workload Manager page mode or in a line mode interface. It can be issued by both TSO/ISPF users and ESP Workstation users.
Section–XCF Scoreboard Service
390 ESP-5.4-UG-05
Purpose of the ROUTING command
The ROUTING command is used to instruct the connected ESP Workload Manager subsystem to either process subsystem requests itself, or to route subsystem requests to the ESP Workload Manager master.
How it works
When an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to the ESP Workload Manager master, the ROUTING command is not useful, as the LOCAL and MASTER options mean the same thing.
However, when an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to an ESP Workload Manager proxy, entering ROUTING LOCAL instructs the ESP Workload Manager proxy to process subsystem requests itself. Subsystem requests are usually ESP Workload Manager commands. If you enter ROUTING MASTER, this instructs the ESP Workload Manager proxy to route subsystem requests to the ESP Workload Manager master.
When an ESP Workload Manager client is connected to the local ESP Workload Manager proxy, subsystem requests can only be forwarded to the ESP Workload Manager master if an active XCF ROUTING connection exists between the local ESP Workload Manager proxy and the ESP Workload Manager master.
Examples
The following example instructs the connected ESP Workload Manager subsystem to route subsystem requests to the ESP Workload Manager master:
ROUTING MASTER
The following example instructs the connected ESP Workload Manager subsystem to process subsystem requests itself:
ROUTING LOCAL
XCF Scoreboard Service
Note: XCF scoreboard service is also available with the ESP Workload Manager High Availability Option (HAO).
XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the new XCF ROUTING and SCOREBD Services.
The SCOREBD Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and/or Workstation Servers) connected to the ESP Workload Manager proxy to view the ESP Workload Manager scoreboard. When an ESP
Chapter 13–ESP Workload Manager High Performance Option
ESP-5.4-UG-05 391
Workload Manager proxy’s XCF SCOREBD Service connects to the ESP Workload Manager master, the master transmits the contents of the scoreboard to the ESP Workload Manager proxy. Thereafter, the ESP Workload Manager master transmits every scoreboard update it makes to all ESP Workload Manager proxies connected to it via the XCF SCOREBD Service.
Benefit
The ESP Workload Manager proxies can maintain their own respective copies of the scoreboard.
The XCF SCOREBD Service makes it possible for an ESP Workload Manager TSO/ISPF client connected to an ESP Workload Manager proxy to view the scoreboard through CSF. It also makes scoreboard information accessible to Workstations connected to a Workstation Server that, in turn, is connected to an ESP Workload Manager proxy.
Enabling XCF SCOREBD
XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if that data set is different than the ESP Workload Manager master. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.
The following is the command syntax to enable XCF SCOREBD:
XCF START SERVICE SCOREBD
Section–XCF Scoreboard Service
392 ESP-5.4-UG-05
ESP-5.4-UG-05 393
ESP Workload Manager High Availability Option
This chapter provides you with information on the ESP Workload Manager High Availability Option.
This chapter contains the following topics:
• Shadow Manager• ARM Registration• XCF Status Monitoring• XCF Routing Service• XCF Scoreboard Service
Section–Shadow Manager
394 ESP-5.4-UG-05
Shadow Manager
Shadow manager provides your environment with the ability to shift the workload to another ESP Workload Manager master, so processing can continue.
Shadow manager can eliminate the single point of failure by providing a hot backup and instant switch over should a system fail.
Shadow manager is an ESP Workload Manager subsystem that reads its initialization parameters, joins an ESP Workload Manager XCF group, then monitors the ESP Workload Manager master in that XCF group for its termination. When the ESP Workload Manager master terminates, the shadow manager takes action based on its shadow goal for that type of termination or takes action from a direct command to take over as the ESP Workload Manager master.
An ESP Workload Manager master may or may not be shadow-enabled.
Shadow-enabled ESP Workload Manager master
A shadow-enabled ESP Workload Manager master is an ESP Workload Manager subsystem that will become a shadow manager if, when it is started, it detects that an active ESP Workload Manager master already exists in its XCF group.
Shadow-disabled ESP Workload Manager master
A shadow-disabled ESP Workload Manager master is an ESP Workload Manager subsystem that will terminate if, when it is started, it detects that an active ESP Workload Manager master already exists in its XCF group.
Data-set usage
Cybermation strongly recommends that a shadow manager read the same initialization parameter data set as the ESP Workload Manager master.
Shadow manager must have the same checkpoint file as the ESP Workload Manager master.
Shadow manager START parameters
An ESP Workload Manager master is defined as shadow-enabled through either the PRIMARY or SHADOW parameters. These can be specified in the START command or in the started task JCL.
An ESP Workload Manager subsystem is defined as a shadow manager through either the SECONDARY or SHADOW parameters. These can be specified in the START command or in the started task JCL.
For information on using the START command, see the ESP Workload Manager Operator’s Guide.
Chapter 14–ESP Workload Manager High Availability Option
ESP-5.4-UG-05 395
Symbolic variable: %SHADOW
%SHADOW is a symbolic variable that can be used anywhere in the initialization parameters. The %SHADOW symbolic variable is created only if the SHADOW operand is used in the START parameters or JCL, for the ESP Workload Manager subsystem.
The ESP Workload Manager master and shadow managers must have different XCF member names.
Using the %SHADOW symbolic variable is one way to ensure the ESP Workload Manager master and shadow managers have different XCF member names when they read the same initialization parameter data set.
For example:
SYSPLEX GROUP(ESP) MEMBER(ESPM%SHADOW)
Shadow Goal
A shadow goal is a set of actions that a shadow manager is instructed to perform when the ESP Workload Manager master terminates.
How a shadow goal works
A shadow manager can have one shadow goal for each way the ESP Workload Manager master can terminate. That is, it can have a QUIESCE shadow goal, a LEAVE shadow goal and/or a FAIL shadow goal.
A shadow manager takes action automatically only if it has a shadow goal for the way in which the ESP Workload Manager master terminates. For example, if the ESP Workload Manager master terminates and enters an XCF quiesced state, the shadow manager must have a QUIESCE shadow goal to take any specified action.
In addition to specifying actions that a shadow manager must perform, a shadow goal also specifies how long the shadow manager must wait before performing the actions.
What actions a shadow goal can take
A shadow goal can specify one or more of the following actions to take when the ESP Workload Manager master terminates:
• Issue warning message #4397• Issue a system command• Take over as the ESP Workload Manager master• Take over as the ESP Workload Manager master and trigger an ESP Event
SHADGOAL command
A shadow goal is defined by the SHADGOAL command or defined in the initialization parameters. The SHADGOAL command is documented in the ESP
Section–Shadow Manager
396 ESP-5.4-UG-05
Workload Manager Reference Guide. For information on the SHADGOAL initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.
XCF member termination
The ESP Workload Manager master (or any XCF group member) can terminate in one of three possible ways:
• QUIESCE• LEAVE• FAIL
QUIESCE
The ESP Workload Manager master terminates normally but leaves a trace of its membership in the group behind. An XCF DISPLAY GROUP ESP Workload Manager command will show the XCF member in a quiesced state.
LEAVE
The ESP Workload Manager master terminates normally but leaves no trace of its membership in the group behind. The XCF member goes into an undefined state. An XCF DISPLAY GROUP ESP Workload Manager command will not show the XCF member, because it does not exist in any way.
FAIL
This happens when the ESP Workload Manager master terminates abnormally (ABENDs). An XCF DISPLAY GROUP ESP Workload Manager command will show the XCF member in a failed state.
SHADGOAL Command
You can specify SHADGOAL in the ESP Workload Manager initialization file of a shadow manager or a shadow-enabled ESP Workload Manager master, or dynamically in a shadow manager, via the z/OS MODIFY command. You can also use the SHADGOAL command to delete a shadow goal or to list the shadow goals.
The SHADGOAL syntax varies in the initialization parameter and the z/OS MODIFY command. For information on the SHADGOAL initialization parameter, see the ESP Workload Manager Installation and Configuration Guide. For information on the z/OS MODIFY SHADGOAL command, see the ESP Workload Manager Reference Guide.
Chapter 14–ESP Workload Manager High Availability Option
ESP-5.4-UG-05 397
SHADGOAL examples
The following example specifies that 180 seconds (3 minutes) after the ESP Workload Manager master terminates and enters an XCF quiesced state, the shadow manager issues warning message #4397 and issues z/OS command S ESPM.
SHADGOAL MASTER(QUIESCE) AFTER(180) WARN +COMMAND('S ESPM')
The following example specifies that 300 seconds (5 minutes) after the ESP Workload Manager master abnormally terminates, the shadow manager issues warning message #4397 and takes over as the ESP Workload Manager master.
SHADGOAL MASTER(FAIL) AFTER(300) WARN TAKEOVER
The following example specifies the shadow goal for the LEAVE option is deleted immediately.
SHADGOAL DELETE MASTER(LEAVE)
Note: Once a shadow-enabled ESP Workload Manager becomes the active master in the XCF group, all shadow goals for that shadow-enabled ESP Workload Manager are deleted and the SHADGOAL command ceases to be available for that master.
Manually moving control
You can switch control of the workload to shadow manager, without shadow goals defined in your initialization parameters. You use an ESP Workload Manager XCF command or an z/OS MODIFY command issued manually. ESP Workload Manager XCF commands can be issued from the ESP Workload Manager master or from any ESP Workload Manager proxy that is joined to the same ESP Workload Manager XCF group as the target shadow manager.
Important: When you are connected to an ESP Workload Manager proxy, you must have the XCF ROUTING service enabled and the ROUTING LOCAL command must be issued to instruct the ESP Workload Manager proxy to process subsystem requests itself. Then you can issue the ESP Workload Manager XCF commands from the ESP Workload Manager proxy you are logged on to.
For more information on XCF ROUTING, see “XCF Routing Service” on page 400.
XCF command examples
The following is an example of shutting down the ESP Workload Manager master (ESPM), displaying the group to ensure ESPM is in a QUIESCE state, and then moving control of the workload to shadow manager (ESPS):
XCF STOP MEMBER ESPM XCF DISPLAY GROUPXCF SET MEMBER ESPS MASTER
Section–ARM Registration
398 ESP-5.4-UG-05
The following is an example of the ESP Workload Manager master (ESPM) being disabled and moving control of the workload to shadow manager (ESPS):
XCF FORCE MEMBER ESPMXCF DISPLAY GROUPXCF SET MEMBER ESPS MASTER
z/OS MODIFY command
Shadow manager will take control of the workload if the following z/OS MODIFY command is issued to the shadow manager when the ESP Workload Manager master is not active:
F jobname,SHADOW TAKEOVER
In the preceding command, jobname is the name of the shadow manager started task.
ARM Registration
The ESP Workload Manager High Availability Option provides support for the IBM Automatic Restart Management (ARM) function of OS/390.
The ARMELEM initialization parameter enables ESP Workload Manager to register with ARM. If an ESP Workload Manager fails, it can now be automatically restarted with ARM.
For more information on the ARMELEM initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.
How it works
ARM will restart a registered ESP Workload Manager subsystem that fails if an ARM policy (either the IBM default or a user-defined policy) is active on the system where the failure occurs and on the system where the restart is to occur.
If the ESP Workload Manager master fails or the system the ESP Workload Manager master is running on fails, the registered ESP Workload Manager master can be restarted on the same system or restarted on another system in the sysplex.
If an ESP Workload Manager proxy is registered with ARM and the ESP Workload Manager proxy fails, the ESP Workload Manager proxy will be restarted on the same system by default. Restarts should be limited to the system the ESP Workload Manager proxy runs on.
ARM couple data set
The ARMELEM initialization parameter requires the system the ESP Workload Manager is running on to be connected to an ARM couple data set.
Chapter 14–ESP Workload Manager High Availability Option
ESP-5.4-UG-05 399
ARM and shadow manager
If an installation uses shadow manager, it can consider ARM unnecessary for the ESP Workload Manager master and shadow managers. However, ARMELEM co-exists well with shadow manager. The default RESTART keyword value for shadow-enabled ESP Workload Manager masters and shadow managers has deliberately been set to ELEMENT_FAILURE, so that restarts on other systems in the sysplex do not occur when the system the ARM-registered ESP Workload Manager is running on fails.
An installation can use ARM instead of shadow manager for ESP Workload Manager master restarts.
Note: Shadow manager does not require an ARM couple data set and ARM policy.
XCF Status Monitoring
Note: XCF status monitoring is also available with the ESP Workload Manager High Performance Option (HPO)
XCF status monitoring is a feature that monitors ESP Workload Manager XCF members’ activity for any possible problems. An ESP Workload Manager XCF member requests XCF status monitoring when it joins the XCF group.
When XCF status monitoring is enabled, ESP Workload Manager notifies XCF of an interval period. The interval period is specified in seconds. ESP Workload Manager then updates its status with XCF according to the specified interval.
XCF status monitoring is enabled by coding the INTERVAL operand on the SYSPLEX initialization parameter.
How XCF status monitoring works
If an ESP Workload Manager subsystem has not updated its XCF status monitoring field for at least two intervals, XCF will warn the other members in the XCF group of a possible problem with that ESP Workload Manager. There can be either a loop or hang in the ESP Workload Manager main task. Message ESP4316I is issued.
ESP4316I XCF status update missing, possible main task loop or hang
Note: This message may not necessarily indicate a problem with the ESP Workload Manager. For example, the system that ESP Workload Manager is running under can be heavily loaded and z/OS is not dispatching ESP Workload Manager.
Second warning message
When XCF does not receive a positive response from the failing ESP Workload Manager subsystem, XCF will broadcast to all the other ESP Workload Manager XCF
Section–XCF Routing Service
400 ESP-5.4-UG-05
members in the XCF group that a status update missing condition exists for that member.
Message ESP4331W is issued:
ESP4331W XCF status update missing
XCF member failure
If the failing ESP Workload Manager subsystem terminates, message ESP4317I is issued:
ESP4317I XCF member state change
Normal operating status resumed
If the failing ESP Workload Manager subsystem resumes its normal operating status, message ESP4318I is issued:
ESP4318I XCF status update resumed
For the full explanation of the ESP Workload Manager messages indicated above, see the ESP Workload Manager Messages manual.
XCF Routing Service
Note: XCF routing service is also available with the ESP Workload Manager High Performance Option (HPO)
XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the XCF ROUTING and SCOREBD Services.
Note: Cybermation recommends that the default routing be changed from LOCAL to MASTER during installation. You can display your current routing status by using the ROUTING STATUS command.
Overview
The ROUTING Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and Workstation servers) connected to the ESP Workload Manager proxy the ability to route subsystem requests, usually ESP Workload Manager commands, to the ESP Workload Manager master. The ESP Workload Manager master processes the subsystem requests, and routes command responses back to the ESP Workload Manager client through the ESP Workload Manager proxy. In this scenario, the ROUTING MASTER command must be specified.
Chapter 14–ESP Workload Manager High Availability Option
ESP-5.4-UG-05 401
Description
Without ESP Workload Manager High Availability Option or High Performance Option
Typically installations run an ESP Workload Manager proxy on each system in the Sysplex and the ESP Workload Manager master runs on one of the systems. To issue subsystem requests to the ESP Workload Manager master, an ESP Workload Manager client must connect directly to the ESP Workload Manager master. Therefore, the TSO/ISPF user and/or Workstation Server must be on the same system as the ESP Workload Manager master.
With ESP Workload Manager High Availability Optionor High Performance Option
By connecting an ESP Workload Manager client to the ESP Workload Manager proxy rather than to the ESP Workload Manager master, the client (TSO/ISPF users or Workstation Servers) can run on any system in the sysplex and issue subsystem requests to the ESP Workload Manager master through the XCF ROUTING Service.
Benefit
It does not matter which system in the sysplex the ESP Workload Manager master is running on. The ESP Workload Manager proxy always knows through its XCF group member State Awareness capabilities, where the ESP Workload Manager master is and how to access it.
Enabling XCF ROUTING
XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.
The following is an example enabling XCF ROUTING:
XCF START SERVICE ROUTING
The ROUTING command
The ROUTING command is an ESP Workload Manager command that can be issued in ESP Workload Manager page mode or in a line mode interface. It can be issued by both TSO/ISPF users and ESP Workstation users.
Section–XCF Scoreboard Service
402 ESP-5.4-UG-05
Purpose of the ROUTING command
The ROUTING command is used to instruct the connected ESP Workload Manager subsystem to either process subsystem requests itself, or to route subsystem requests to the ESP Workload Manager master.
How it works
When an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to the ESP Workload Manager master, the ROUTING command is not needed, as the LOCAL and MASTER options mean the same thing.
However, when an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to an ESP Workload Manager proxy, entering ROUTING LOCAL instructs the ESP Workload Manager proxy to process subsystem requests itself. Subsystem requests are usually ESP Workload Manager commands. If you enter ROUTING MASTER, this instructs the ESP Workload Manager proxy to route subsystem requests to the ESP Workload Manager master.
When an ESP Workload Manager client is connected to the local ESP Workload Manager proxy, subsystem requests can only be forwarded to the ESP Workload Manager master if an active XCF ROUTING connection exists between the local ESP Workload Manager proxy and the ESP Workload Manager master.
Examples
The following example instructs the connected ESP Workload Manager subsystem to route subsystem requests to the ESP Workload Manager master:
ROUTING MASTER
The following example instructs the connected ESP Workload Manager subsystem to process subsystem requests itself:
ROUTING LOCAL
XCF Scoreboard Service
Note: XCF scoreboard service is also available with the ESP Workload Manager High Performance Option (HPO)
XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the new XCF ROUTING and SCOREBD Services.
The SCOREBD Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and/or Workstation Servers) connected to the ESP Workload Manager proxy, to view the ESP Workload Manager scoreboard. When an ESP
Chapter 14–ESP Workload Manager High Availability Option
ESP-5.4-UG-05 403
Workload Manager proxy’s XCF SCOREBD Service connects to the ESP Workload Manager master, the master transmits the contents of the scoreboard to the ESP Workload Manager proxy. Thereafter, the ESP Workload Manager master transmits every scoreboard update it makes to all ESP Workload Manager proxies connected to it via the XCF SCOREBD Service.
Benefit
The ESP Workload Manager proxies can maintain their own respective copies of the scoreboard.
The XCF SCOREBD Service makes it possible for an ESP Workload Manager TSO/ISPF client connected to an ESP Workload Manager proxy to view the scoreboard through CSF. It also makes scoreboard information accessible to Workstations connected to a Workstation Server that, in turn, is connected to an ESP Workload Manager proxy.
Enabling XCF SCOREBD
XCF START Services must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if the data set is different than the ESP Workload Manager master.
The following is the command syntax to enable XCF SCOREBD:
XCF START SERVICE SCOREBD
Section–XCF Scoreboard Service
404 ESP-5.4-UG-05
ESP-5.4-UG-05 405
Glossary
Absolute day By default, ESP Workload Manager considers each day to begin at 00:00. ESP Workload Manager refers to a day that begins at 00:00 as the absolute day.
Note: Cybermation recommends you use absolute days (as opposed to logical days) because of their ease of use and because they can handle almost all scheduling requirements.
AFM Automated Framework Message. A structured message used to communicate commands and status between clients and servers.
Agent See “ESP Agent” on page 407.
Agentmon Workload object that monitors the status of ESP Agents.
Alert A mechanism to trigger ESP Workload Manager activity when specific actions take place in your Application. For example, you can use ESP Workload Manager to trigger an Event when a job fails.
Application See “ESP Application” on page 407.
Audit log An audit trail of ESP Workload Manager activity. It stores information on administrative activities, operator commands, and Application and Event processing. The audit log is in the job log.
406 ESP-5.4-UG-05
AUTOVAR Automatic variable representing lines of JCL, data, or comments that ESP Workload Manager automatically includes at the beginning or end of a job’s JCL.
Calendar Used to specify what day is the first day of the week and what are the workdays. A collection of definitions of holidays and special days that are unique to your installation.
CCCHK Statement used to detect condition codes. Using it, you can immediately stop a failing job, without running any subsequent steps regardless of the conditional operands.
CCFAIL Abbreviation for condition code fail. CCFAIL statements define conditions that, if met, cause the job to fail.
CLANG Control language. This is a high level programming language developed for ESP Workload Manager.
Command A request made to ESP Workload Manager. The most frequent types of commands are:
• General commands—are issued without general restrictions• OPER commands—must be preceded by the word OPER• Authorized commands—can be issued by users authorized in the security
system• Authorized OPER commands—can be issued by users authorized in the
security system and must be preceded by the word OPER
Commands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.
Consolidated StatusFacility (CSF)
An ESP Workload Manager facility for displaying and manipulating the workload in ISPF.
COPYJCL A user data set containing a copy of the JCL for jobs submitted by ESP Workload Manager when you specify the COPYJCL statement.
Critical path The longest path to a workload object representing a critical point in the ESP Application. It is based on historical execution time.
Data object See “Variable” on page 412.
DJC Dependent Job Control. A Cybermation product used to control resources and job networks at the initiator level.
DJC job network A group of related jobs where dependencies are controlled at the initiator level.
DOCLIB A user data set containing job documentation entries.
DSTRIG A workload object used to build a dependency between an Event or an ESP Application and data set activity, such as FTP transfer or creation of a data set.
Enqueue Provides the capability for a job to request exclusive or shared use of a resource without the need to define the resource explicitly in advance. ESP Workload
Glossary
ESP-5.4-UG-05 407
Manager will prevent jobs with mutually exclusive requests from executing concurrently. ESP ENQUEUE behaves like the z/OS enqueues.
ESP Agent Software running on a distributed platform allowing ESP Workload Manager or ESP Espresso to control workload on distributed platforms, such as UNIX, OS/400, or Windows NT, or in distributed environments, such as SAP or PeopleSoft.
ESP Application A specific instance of a group of related workload objects. It is generated from one or more ESP Procedures when an Event is triggered and runs under the control of ESP Workload Manager. ESP Applications include the scheduling relationship between workload objects.
ESP Encore ESP Encore is a rerun/restart product that works with ESP Workload Manager to restart batch jobs with a minimum amount of intervention. ESP Encore makes the necessary adjustments to batch JCL to allow for an error-free restart. ESP Encore can automatically clean up data sets or back out batch jobs. ESP Encore can also predict errors.
ESP Espresso A decision-making product running on UNIX or Windows.
ESP Procedure A source list of statements and commands entered by users. ESP Workload Manager reads one or more ESP Procedures when an Event is triggered. ESP Procedures containing the APPL statement are used by ESP Workload Manager to generate ESP Applications. ESP Procedures are used to specify how the workload is scheduled.
ESP Workload Manager A decision-making product running on z/OS. It manages the workload across the enterprise.
ESP Workload ManagerHigh Availability Option
(HAO)
ESP Workload Manager High Availability Option takes full advantage of the IBM clustering sysplex technology to increase enterprise IT performance by improving the availability of system resources throughout the organization. It includes:
• Shadow manager: to provide your environment with the ability to shift the workload to another ESP Workload Manager master, so processing can continue.
• Support for the IBM Automatic Restart Management (ARM) function of OS/390.
• XCF status monitoring: to monitor ESP Workload Manager XCF members’ activity for any possible problems.
• XCF routing service: to connect an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave the ability to route subsystem requests to the ESP Workload Manager master.
• XCF scoreboard service: to connect between an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave to view the ESP Workload Manager scoreboard.
408 ESP-5.4-UG-05
ESP Workload ManagerHigh Performance
Option (HPO)
ESP Workload Manager High Performance Option optimizes workload to significantly increase the performance of the enterprise IT environment. It includes:
• Expedite: to define actions specifying how a job should be accelerated based on criteria you specify.
• Resource balancing: to enable ESP Workload Manager to monitor all the ESP Workload Manager resources in the ESP resource topology for availability and utilization.
• Workload balancing: to select where to run workload. • XCF status monitoring: to monitor ESP Workload Manager XCF members’
activity for any possible problems.• XCF routing service: to connect an ESP Workload Manager slave and the
ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave the ability to route subsystem requests to the ESP Workload Manager master.
• XCF scoreboard service: to connect between an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave to view the ESP Workload Manager scoreboard.
ESP Workstation A graphical user interface for defining, monitoring, and controlling the entire enterprise workload. It is a significant productivity tool for those defining and scheduling applications and for the data-center production personnel who manage them.
Event An anticipated scheduling milestone. Events include the conditions under which they are triggered and the commands to be performed when they are triggered. Events are used to determine the conditions under which workload objects are scheduled. An Event starts a function such as sending a message or invoking an ESP Procedure.
Event initiator class Event initiator classes classify ESP Workload Manager workload into distinct streams.
External job A job defined in an ESP Application that ESP Workload Manager submits from another Application.
EXTMON A workload object used to monitor a job executed by an external scheduler.
File trigger A workload object used to build a dependency between an ESP Application and file activities for a file located in an environment controlled by an ESP Agent.
Global variable See “Variable” on page 412.
HAO High Availability Option.
HPO High Performance Option.
Initialization parameter A request made to ESP Workload Manager at initialization time. Initialization parameters are listed alphabetically in the ESP Workload Manager Installation and Configuration Guide.
Glossary
ESP-5.4-UG-05 409
JCLLIB A user data set containing the JCL for jobs submitted by ESP Workload Manager.
Job ID An identification assigned automatically to every job by JES. The format of the Job ID varies according the following rules:
Note: The same format is used for the JES job identifier used by JOBONQ.
Job monitor An ESP Workload Manager facility for monitoring a job’s progress at any stage of processing and for taking action at significant points. ESP Workload Manager can automatically trigger an Event when a job reaches a particular stage in processing, such as the end of a step or job.
Link A workload object in an Application that is marked complete automatically when its dependencies are met. You can use a link to process commands such as sending messages, issuing operator commands, and so on. Common use of links include simplifying job relationships, keeping an Application active, notification when something happens and notification when something does not happen.
Logical day A day defined by your organization that begins at a time different than 00.00.
Note: Cybermation recommends you use absolute days because of their ease of use and because they can handle almost all scheduling requirements.
Manual job A dependency on a job that ESP Workload Manager does not submit either as part of an ESP Application or a DJC/JES3 job network.
Master An ESP Workload Manager subsystem that centrally controls the workload across multiple z/OS images.
Notwith A mechanism to prevent mutually incompatible jobs from running at the same time.
Operand A parameter of a statement, command, or initialization parameter.
Page mode A method to communicate with ESP Workload Manager using ISPF, producing scrollable output from ESP Workload Manager.
Condition Format
JES2 not running in z2 mode (with large job numbers disabled)
JOBnnnnn
JES2 running in z2 mode (with large job numbers enabled)
Jnnnnnnn
JES3 For job numbers less than 100000:JOBnnnnnFor job numbers greater than 99999:Jnnnnnnn
410 ESP-5.4-UG-05
Pnode Processing node. A processing stage through which a job must pass during its time on the system. At installation time, the input, exec and output Pnodes are defined. ESP tracks jobs through these Pnodes automatically. You can define additional (manual) Pnodes, for example, bursting of output, distribution, and so on.
Pnode Application states How ESP Workstation represents the Application Pnode. The Application Pnode is determined with a hybrid method that uses the status information supplied by ESP Workload Manager and the status of its workload objects.
Positional operand Variable that is passed to a script at the time it is invoked, and is assigned in the order it is passed.
Post To mark a workload object complete at a specific Pnode. For example, you can post a job complete.
Predecessor A workload object that must complete before another workload object can be submitted.
Procedure See “ESP Procedure” on page 407.
PROCLIB A user data set containing ESP Workload Manager procedural code, for defining work to be performed by ESP Workload Manager. This includes Application workload object definitions.
Qualifier An addition to the job’s name. It can be used to uniquely identify jobs with the same name. It is used only within the ESP Application. The qualifier has no meaning to the operating system that the object runs on.
Resource A resource can be an item of hardware or software, or it can be an abstract condition. Resources are used to ensure a job is not submitted until all of its requirements are met.
Depletable resource—a resource that is used up upon submittal of a workload object. The resource can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. A depletable resource could refer to the number of scratch tapes available or to a permanent DASD space.
Renewable resource—A resource that is removed from the resource pool upon submittal of a workload object and then is returned upon completion. Some examples include tape drives, a data base, or sort workspace.
Threshold resource—A sizing resource. ESP Workload Manager sizes the workload object against the current level of the threshold resource. For example, this type or resource could be used to prevent certain workload objects from executing until a NITESHIFT period begins.
Note: Enqueues are implicit resources.
REXX A high level, procedural language. You can invoke the REXX language interpreter from ESP Workload Manager to extend ESP Workload Manager capabilities.
Glossary
ESP-5.4-UG-05 411
SADGEN A user data set containing scheduled activity information on jobs. This data set is used for reports.
Schedule criteria Conditions related to date, time, or frequency, used to identify eligibility of workload for execution.
Script A file containing commands to be executed in an environment controlled by an ESP Agent.
Shadow Manager Provides your environment with the ability to transfer the control to another ESP Workload Manager master, so processing can continue seamlessly. Requires HAO.
Proxy An ESP Workload Manager subsystem that captures SMF data for the workload running on that z/OS image and transmits that data to the master.
Special day A custom defined day with special significance for scheduling at your installation.
Special period A period of processing with special significance for scheduling at your installation. A special period is the time between two identically named special days. An example is a fiscal month.
Statement A definition or part of a definition given to ESP Workload Manager. Statements are always specified in procedures.
Commands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.
SubApplication A logical grouping of workload objects within an ESP Application.
Successor A workload object that awaits the completion of another workload object before it can be submitted.
Symbolic variable See Variable.
SYMLIB A user data set containing symbolic variables.
Sysmsg A facility used to intercept system messages as they are written to the system message data set, and to take action subsequently.
Tag A user-defined field defining a workload object further.
Task A placeholder in your Application. A task may represent a process that requires manual intervention.
TEMPLIB A user data set containing temporary or override JCL to be used when you specify the TEMPLIB statement.
Tracking model A centralized definition of the attributes and processing phases of a group of jobs.
412 ESP-5.4-UG-05
User data sets See COPYJCL, DOCLIB, JCLLIB, PROCLIB, SADGEN, SYMLIB, and TEMPLIB.
Variable Data object—Serves as a data repository. It is coded in an Application as any other workload object.
Global variable—A variable available across Applications. Global variables are stored in global-variable tables. Using a global-variable trigger, global variables can also be used to trigger Events based on changes of their value.
Symbolic variable—An integer or a character string whose value may be changed during ESP Workload Manager processing. When ESP Workload Manager encounters a symbolic variable, it substitutes the current value of that variable. Symbolic variables are useful in defining date operands, specifying job names, and defining job dependencies. There are built-in symbolic variables and user-defined symbolic variables.
Workday Calendar definitions representing a site’s workdays. The default workdays are Monday trough Friday excluding any holiday that has been defined for the site.
Workload object Workload objects represent the work to be scheduled. For example, these objects can represent z/OS jobs, UNIX scripts, AS/400 programs, NT and OS/2 command files, data set and file trigger objects, commands, tasks, and links.
ESP-5.4-UG-05 413
Index
Symbols%ESPAPTAG, 205%ESPATIME, 203%ESPTRDSN, 81%ESPTRGDG, 203%SHADOW, 395
Numerics4-4-5 period, example, 70
Aabsolute day
definition, 405vs. logical day, 49
ABSOLUTE, scheduling term, 50ABSORB, statement, 343ACTIVE, built-in function, 118, 124Advancing job based on holiday, 67AFM, 405AFTER, statement, 165Agent
definition, 405workload balancing, 339, 385
agentmon, definition, 405alert processing
definition, 25uses, 26
alert, definition, 405ALTCAL
command, 62use to alter a calendar, 62
ALTER, Event command, 100Alternative input data sets, Panvalet
and Librarian, 42AND, scheduling term, 50ANYCLOSE
FTP trigger operand, 87indicate any closure of a data set, 194trigger an Event at closure, 82
ANYDAY, scheduling term, 50APPLEND
additional considerations, 191does not generate SMF, 191example, 18, 191how to use, 190limitations, 190setting, 190with link, 244
414 ESP-5.4-UG-05
workload object, 18APPLHOLD, Pnode field, 223Application, See ESP ApplicationAPPLJOB
command, 216example
bypassing a job, 217completing an Application, 217inserting a link to add a job relationship, 217requesting a job, 217
options, 217APPLWAIT, Pnode field, 223Arithmetic
expression, 115operations, 115
ARMand shadow manager, 399couple data set, 398how it works, 398registration, 398
ARMELEM, definition, 398audit log, definition, 405automated framework message, 405Automatic Restart Management
ARMELEM initialization parameter, 398description, 398
AUTOVAR, definition, 406
Bbatch
convert an existing PDS job documentation library, 271
creating history report in, 276creating schedule activity report in, 299defining a repetitive holiday, 66example of explicit-data-set trigger
notification, 90executing ESP Workload Manager
commands in, 38executing program CYBESDT1 in, 88invocation of ESP Workload Manager, 38issuing commands in, 4MAPGEN command, 304specifying input parameters
of CYBESDT1, 88use of hyphen, 276, 288using JOBMAP in, 306using JOBTREE in, 309
browsingCOPYJCL (CSF), 233last executed JCL (CSF), 233
built-in functionsdefinition, 117example
calculating the length of a symbol, 123checking available cartridge drives, 127checking if CICSPROD is active, 124combined functions, 128DAYS_BETWEEN to
calculate weeks, 120DAYS_BETWEEN to
calculate workdays, 119DAYS_FROM, 119DAYS_TO, 119defining an undefined variable, 123extracting the last character
of a variable length symbol, 124JOBONQ, 126selecting a job when
another is not selected, 122selecting one job based on another, 122TAPES, 127TODAY, 120TOMORROW, 121using a substring of a
time variable, 124YESTERDAY being a holiday, 121YESTERDAY being first day of month, 121
summary by function, 117testing for a true condition, 118using calendaring functions, 118using functions for job selection, 122using functions for symbolic variables, 123ACTIVE, 124DAYS_BETWEEN, 119DAYS_FROM, 119DAYS_TO, 118DEFINED, 123ESP Procedure, 117JOBONQ, 125LENGTH, 123SELECTED, 122SUBSTR, 124TAPES, 126TODAY, 120TOMORROW, 120
Index
ESP-5.4-UG-05 415
YESTERDAY, 121built-in symbolic variables, definition, 113BY, CSF command, 233BYPASSED, Pnode field, 223bypassing
a job (CSF), 233a job in CSF, 242a job without waiting for
predecessor, example of, 161a job, example of, 217a scheduled Event execution, 103Event, specific day, 78example
bypassing a job and wait for predecessor, 161
jobs and dependencies, 160execution of an Event, 104job dependencies, 160jobs, 160, 242
Ccaching an ESP Workload Manager Procedure, 135CALENDAR
command, 59, 61, 97command, to specify additional
calendars for an Event, 64, 97suppressing field in a report, 308suppressing the calendar field in reports, 308use in an Event to refer to two calendars, 64
calendaraccessing, 59altering, 62contents, 58default calendar, 60default values, 60defining, 60defining using panels, 61defining your organization’s
logical day in, 64deleting, 60, 63deleting of entries, 60display information about a specific, 62displaying, 62displaying holidays and special days, 63displaying more detailed information on
holidays and special days, 63example, 59
altering, 62
defining, 61defining the SYSTEM calendar, 61displaying, 63displaying the SYSTEM calendar, 63specifying in an Event, 97
first day of the week, 49LOGICAL as a default, 51main menu option, 33optional specifications, 61period intervals, 69planning, 59referencing, 64retaining entries, 60setting special, 97specifying in Event, 97SYSTEM, 59system, 59terms, implied periods, 48using, 9, 58using calendar terms, 59what it can contain, 9, 59workdays, 49, 53
calendar, definition, 406CCCHK, definition, 406CCFAIL, definition, 406changes in an ESP Apllication
that take effect immediately, 218changes in an ESP Application
that take effect for the next Application generation, 218
CLANGexample
calculating time periods, 133overriding an ESP Procedure on a particular
date, 134scheduling a job on the last day of the
month, 132taking different action based on time, 134taking different action on a weekday, 132taking different actions based on the status of
CICS, 133usage, 13using calendaring functions, 133
in templates, 129language elements, 110other techniques for schedule criteria, 57specifying different DELAYSUB
times for a job, example, 156
416 ESP-5.4-UG-05
using for job documentation, 258using in ESP Procedures, 110
CLANG, definition, 406CLASS, Event command, 100CLIST
calling ESP Workload Manager from, 40invoking the ESP Workload Manager
command from, 39to access ESP Workload Manager, 40
Coding RESDEF with WLM operand, 383command
definition, 406entering, 2example, 4, 212issuing, 211issuing from console, 4ALTCAL, 62APPLJOB, 216CALENDAR, 59, 61, 97COPYJCL, 94DEFHOL, 65DEFSPEC, 67DELCAL, 64ENQSELF, 171EVENT, 74EXPECT, 99HOLD, 104INFOMSG, 37INVOKE, 93, 131JOBMAP, 305JOBTREE, 309LDTE, 84LDXE, 84LIBSUB, 92, 131LIST, 101LISTCAL, 62LISTHOL, 63LISTSCH, 98LISTSPEC, 63LOAD, 40LSAR, 300NOSCHED, 78QUIESCE, 396RESDEF, 335RESREFR, 337RESUME, 81ROUTING, 389, 401SADGEN, 298
SADUPD, 301SCHEDULE, 77SEND, 131SHADGOAL, 396SIGCYCLE, 131SIGPOST, 131SIMULATE, 101SUBMIT, 131SUSPEND, 81SYMLIB, 96TEST, 57TRIGGER, 102USE, 35VS, 95XCF SPIN TRACE, 374XCF START SERVICE, 371
commentsadding in an Event, 98ESP Procedure, 3, 109how to include, 3in job documentation, 258procedure syntax, 109
comparison operators, definition and list of, 116COMPLETE
condition, 254Pnode field, 223scheduling term, 50STATUS, 293
complete, post, 410completing
an Application, example of, 217jobs, 242
Consolidated Status Facility, definition, 406Consolidated Status Facility, See CSFcontinuation character
ESP Procedure, 2, 109use of, 2
copying JCL, 94COPYJCL
changing the copy, 95command, 94compressing, 95, 148definition, 406editing, 234example of using, 95specifying a COPYJCL library, 147suppressing, 148using the JOBID operand, 95
Index
ESP-5.4-UG-05 417
using the JOBNAME operand, 95COREQ, statement, 165CPU availability, Resource representing the
percentage of, 385CPU service unit resources, use of, 383CRITICAL, 153critical path
analysis, for all Applications, 209analysis, using, 208CSF condition, 254definition, 406displaying, 211example, 208external jobs on, 210identifying critical jobs, 209label, 211multiple, 210overriding elapsed times, 210preparing to use, 209turn on analysis, 209using CSF, 211using the list Application command, 211with EXPEDITE, 378
CSFadding a job relationship in an
Application, 243adding a job with a delayed
submission time, 243adding a job with a time dependency, 243Adding a LINK process, 244adding a link that processes commands, 244adding a relationship between two
unrelated jobs in an Application, 243adding job dependencies, 243bases for filtering, examples, 248bypassing a job, 242changing a time dependency for a job, 240color options, 231command
BY, 233DD, 234for customizing views, 227HR, 234IJ, 234IJA, 234IJB, 234L, 234LI, 234
LR, 234, 245ME, 246MR, 246R, 234working with Applications, 233working with jobs, 233working with other ESP
Workload Manager definitions, 235working with subApplications, 233
completing a job, 242customizing, 20customizing a view, 227defining a view, 226defining your sorting requirements, 230definition, 20, 406deleting a view, 232deleting a view if you know the
name of the view you want to select, 232deleting a view, if you do not know
the name of the view you want to select, 232displaying data, 222entering a freeform filter, 248example
adding a job relationship in an Application, 244
adding a job to an Application with IJ, 236adding a job to an Application with IW, 236adding job dependencies, 243changing column position, 229display, 222removing dependency time, 241removing job dependencies, 239seeing all incomplete jobs, 228seeing all incomplete jobs in
Application Payroll, 228seeing all jobs that are complete OR
failed, 229seeing all jobs that are incomplete
AND not failed, 229setting the user status field, 245
extensions, 247fields, 223filter criteria syntax, 248filtering information, 227freeform filtering, 229, 247
conditions, 254examples of freeform filter, 250examples of substring notation, 249
418 ESP-5.4-UG-05
keywords, 250relational operators, 253term syntax, 248
inserting a jobIJ option, 236IW option, 236
logic applied to multiple filtering conditions, 228
Pnode fields, 223presentation column length, 230presentation titles, 230presenting information, 229removing job dependencies, 239rerunning multiple jobs, 238resetting a time dependency, 240resetting the User Status field to null, 226resubmitting a job, 237selecting color options, 231selecting views, 232setting and resetting the user status field, 244setting the user status field, 225setting up views, 222sort sequence, 230sorting information, 230status fields, 225storing views, 226updating a view, 231usage of extensions, 247using other commands, 247
customizing CSF, 20CYBESDT1
See also explicit-data-set triggeringdefinition, 88input parameters, 202return codes, 203syntax for submitting, 88
DDAILY, scheduling term, 50data object, definition, 406data set, prefix, 42data-set names in ESP Procedure, 3, 109data-set triggering
abnormal closures, 82any closure, 82concept, 10data-set creation, 82displaying Events, 84
example, 11job specific creation, 82running a compress
job after 100 closures of a data set, 84user specific creation, 83waiting on multiple data sets, 83
limiting data set activity to a job, 82limiting data set activity to a user, 83multiple closures, 83multiple data sets, 83process flow, 82usage, 81waiting for any closure of a data set, 82waiting on multiple closures
of the same data set, 83waiting on multiple data sets, 83XCF Service, 371
data-set-trigger workload objectcontrolling, 197displaying data-set-triggering information, 197example
data-set-trigger has a dependency, 197job specific creation, 195user specific creation, 197waiting for a data set creation, 194waiting for any closure of a data set, 195waiting on more than one data set, 196waiting on multiple closures of a data
set, 196limiting data set activity to a job, 195limiting data set activity to a user, 196preparing to use, 193setting up in an Application, 193using, 193visual perspective, 194waiting for any closure of a data set, 194waiting on multiple closures of the
same data set, 196waiting on multiple data sets, 195
data-set-triggered Eventsdisplaying, 84holding, 80specifying, 81
DAYS_BETWEEN, built-in function, 117, 119DAYS_FROM, built-in function, 117, 119DAYS_TO, built-in function, 117, 118DD, CSF command, 234DEFCAL
Index
ESP-5.4-UG-05 419
command, 60defining a calendar, 60defining a logical day, 64
DEFHOLcommand, 65defining holidays, 65
DEFINED, built-in function, 117, 123DEFSPEC
command, 67defining special days, 67defining the first day of a period, 68
DELCALcommand, 64deleting calendars, 64
DELETE, Event command, 100delimiter, 3dependencies, displaying, 234depletable resource, definition, 24, 327, 410detailed information about a job, displaying, 234displaying
holiday, 63special day, 63
distributed jobretrieving the spool file, 235selecting options, 235
Distributed Managerexample
not recommended structure, 362recommended structure, 361
features and limitations, 361planning optimal Applications, 360unsupported functions, 364
distributed workload objects, 19DJC
definition, 406job network, definition, 406
DOgrouping with DO-ENDDO, example, 112statement in procedures, 111
DOCLIBdefinition, 406
DOCMEM operand of JOB statement, 265DROPNOTW
example, 174excluding jobs from a
NOTWITH statement, 174dropping
all predecessors, 234
all resource dependencies, 234individual dependencies, 234
dsname, 200DSTRIG
and scheduled Events, 82command to trigger an Event, 81data-set-trigger object identification, 178definition, 406explicit data-set triggers, 87setting up a data-set-trigger object, 193specifying data-set -triggered Events, 81specifying several, 84XCF services, 370
DUEOUT EXEC time, setting with MAXRUNTIME, 162
dueout timesintroducing, 157propagating, 158propagating example, 159
EEACH, scheduling term, 50ELSE, statement in procedures, 110ENDDEF
command ending Event definition, 74example of Event definition, 74
ENDDOgrouping with DO-ENDO, example, 112statement in procedures, 111
ENDING, scheduling term, 50ENQSELF
command, 171disadvantage of setting to ALWAYS, 171displaying status, 171example, modify, 171modify the status of, 171
ENQUEUEautomatic generation by the NOTWITH
statement, 172capabilities, 166displaying enqueue status in
the resource file, 169example of displaying, 169examples, 167excluding jobs from
an ENQUEUE statement, 168removing mutual exclusivity, 168specifying mutually exclusive jobs, 167
420 ESP-5.4-UG-05
usage, 167use by NOTWITH feature, 166
enqueuedisplaying, status, 169manipulating enqueue list of a specified
job in a generated Application, 170enqueue, definition, 406enqueues, modifying, 234entering
commands, 2statements, 2
ESP Agent, definition, 407ESP Application
anticipated end times, 156changes
that take effect for the next Application generation, 218
that take effect immediately, 218changing definition, 218changing ownership of an, 367changing ownership of an, dynamically, 368coding a job-dependency relationship, 166completing, example of, 217compressing COPYJCL, 148controlling, 216controlling concurrent processing
of multiple generations, 142controlling the use of temporary JCL, 146creating an ESP Application that optimizes
the Distributed Manager's capabilities, 366creating distributed, 365critical path, 208defining, 14, 140defining ownership of an, 366definition, 13, 137, 407definition example, 141deselecting jobs, 176displaying, 215dueout times, 157dynamically changing ownership of an, 368ESP Procedure statements, 140example, 14
an Event invokes an ESP Procedure to create an Application, 219
deselecting jobs for submission with DESELECT, 176
deselecting jobs for submission with NORUN, 176
identifying JCL libraries, 143inheriting job relationships, 177inter-Application dependency, 178keeping active, 186limiting the use of temporary JCL, 147notification on submit and abend, 207notifying when complete, 187overdue notification, 207selecting jobs for submission
with RUN, 175selecting jobs for submission
with SELECT, 175tagging high priority jobs, 205tagging jobs with Application name, 205tagging jobs with the scheduled
day of week, 205using a different TEMPLIB based on year
and day, 147using COPYJCL, 148
excluding default resources for an, 335generating a report for a specific, 307generation number, 140generation phase, 139getting notified of progress, 206home and distant, 178identifying, 142identifying JCL libraries, 143identifying jobs, 149identifying that a job is part of another
Application, 178, 182inheriting job relationships, 176inserting a job in an active, 235inserting additional workload into
an active, 234introduction, 138invoking, 219invoking via an ESP Event, 219job types in an, 177limiting the use of temporary JCL, 147manipulating the enqueue list
in a generated, 170mutually exclusive run, 166naming, 142optimizing to use distributed manager, 359owner of an, 365phase status, 139phases, 139planning to optimize distributed manager, 360
Index
ESP-5.4-UG-05 421
process phase, 139processing, 138processing at the end of, with APPLEND, 190providing notification on job status, 206relationship with ESP Procedure, 12removing resource dependencies, 162reporting on, 287selecting jobs for submission, 175specifying a COPYJCL library, 147specifying a JCL library, 143specifying a member name for a JCL library
search, 145specifying an EXTERNAL job, 180specifying job relationships, 165specifying multiple jobs, 165specifying predecessor, 165specifying successor, 165specifying the JCL library for a single job, 145statements for different job types, 158streamlining, 14subApplications, 212submit time, 175suppressing COPYJCL, 148tagging jobs, 205using different job types, 177using SELECT vs. RUN statements, 176using the JOBID keyword, 148when ESP Workload Manager
completes an, 153working with, 215working with, in CSF, 233writing the JCL to a GDG, 148
ESP commands, loading, 40ESP distributed manager, 19ESP Encore
definition, 407viewing the panels, 235
ESP Espresso, definition, 407ESP Procedure
and Applications, 12arithmetic operators, 115browse in CSF, 235built-in functions, 117caching, 135comments, 3, 109comparison operators, 116continuing a line, 2, 109controlling processing requirements, 12
data-set names, 3, 109definition, 12, 107, 407delimiter, 109edit in CSF, 235example
an Event invoking, 109checking if CICS is active, 128CLANG usage, 13grouping with DO-ENDDO, 112retrieving a variable from
a global variable table, 114using IF-THEN-ELSE, 112using QUIT and EXIT, 113using symbolic variables, 114waiting for a job, 129
expressions, 115indentation, 3, 110invoking, 108label, 110logical operators, 116name, 109order of precedence, 116overview, 108re-executing, 128relationship with Event, 264statements in an Application, 140suppressing field in report, 308symbolic variables in, 113syntax, 109terminating with EXIT, 111terminating with QUIT, 112usage, 13uses of, 13using CLANG, 110using Event definition commands in, 131using expressions, 115using expressions and strings in, 114using literal strings, 114using operators, 115
ESP Workload Manageraccessing
as a program, 39as a TSO command processor, 40from a CLIST, 39in batch, 38ISPF option, 32
definition, 407exiting, 40
422 ESP-5.4-UG-05
master, 394ESP Workstation
benefit of XCF scoreboard service, 391, 403changing the ownership of an Application, 368defining the ownership of an Application, 366definition, 21, 408entering commands, 2graphical user interface, 21ROUTING command, 390, 402working with Applications, 215
ESP XCF commands, 370ESP_APPL_GEN, 139ESP_APPL_PROC, 139ESPAPQUAL, 266EVENT
command, 74Event
accessing, 75adding comments in, 98adding executions, 103advance/delay/ignore/processing, 79altering, 105browse in CSF, 235bypassing
a scheduled, 103execution of, 104one execution, 103
CALENDAR command, 59canceling
for specific day, 78next execution, 103
changing characteristics, 105classes, 105commands and their function, 100comments, 98controlling scheduling, 79data-set triggering, 10data-set-triggered, 82defining
example, 74how, 74system identifier, 76when it will execute, 76where it will execute, 76
definition, 408deleting, 106displaying
data-set-triggered Events, 84
names and times of the current schedule cycle, 98
names or definitions, 101the schedule, 98when it will execute, 99
duplicate, 75edit in CSF, 235example, 10
altering system identifier, 105changing processing, 79deleting, 106displaying the next execution time, 99displaying the schedule, 98expected time, 99holding, 104holding a data-set-triggered Event, 80naming, 76overdue, 105sending a message, 91setting symbol libraries, 96specifying a calendar, 97starting tasks, 96submitting a job, 92submitting multiple jobs, 92suspending, 104using comments, 98
expected time, 99explicit-data-set trigger, 87FTP data-set trigger, 11FTP data-set-triggered, 84function
issuing operator command, 95sending message, 91specifying, 91submitting job, 91
global-variable-table triggering, 12held and suspended, 81holding and releasing, 104holding from being processed at
a particular time, 80information in MAPGEN, 304initiator class, definition, 408invoking
an Application, 219an ESP Procedure, 93, 108
issuing operator commands, 95job mapping, 303listing names or definitions, 101
Index
ESP-5.4-UG-05 423
main menu options, 33missed, 78name, 75naming, 74next execution times, 99overdue, 78, 105overlapping criteria, 77pending execution, 80performing tasks, 10postponing execution of an, 104prefix, 75, 101, 332processing
advancing, 79delaying, 79ignoring, 79
processing of holiday, 66relationship procedure, 264replacing scheduled executions, 103report sorted by, 314resuming, 104schedule the deletion of, 79scheduled and data-set-triggered, 82scheduled Events, 82scheduling, 77, 79security, using the prefix, 75sending messages with, 91setting calendars, 97setting symbol libraries, 96simulating, 101specifying
data-set-triggered, 81FTP data-set-triggered, 84other requirements, 96scheduled Events, 77the function of, 91time and frequency, 48
submitting JCL, 91suppressing field in reports, 308suppressing name in reports, 308suspended and held, 81suspending and resuming, 104trigger, 76triggered in error, 103triggering expected, 99triggering manually, 102triggers for, 10using event definition commands
in procedures, 131
working with defined, 100Event initiator class, definition, 408EVERY, scheduling term, 50example
using the notification list in an Event, 98using the notification list in NOTIFY, 207
EXCEPT, scheduling term, 51exceptions
Event scheduling, 78handling, 78report on, 30using NORUN and DESELECT, 176
EXEC, Pnode field, 223EXIT
statement in procedures, 111using, 113
exiting, ESP Workload Manager, 40EXPECT
command, 99expected execution, 99triggering expected Events, 99
expected time of Event, 99EXPEDITE
example, 379example of statement, 380statement, 379
expediteactions, 378description, 378host security check, 380overview, 378usage, 378
expedite policyadding or altering an, 379associating with an Application, 379defining, 378definition, 378designating for one job only, 379host security resource name, 380
explicit data-set triggeringdefinition, 11SMF record requirement, 88, 201
explicit-data-set triggeringCYBESDT1, 88CYBESDT1 input parameters, 88CYBESDT1 return codes, 90example
Connect:Direct (NDM) run task, 90
424 ESP-5.4-UG-05
notification batch, 90invoking CYBESDT1 from page mode or line
mode, 90notification utility program, 88specifying, 87
explicit-data-set-trigger workload objectexample
explicit data-set trigger notification batch, 204
explicit data-set trigger notification Connect:Direct (NDM) run task example, 204
invoking CYBESDT1 from page mode or line mode, 203
notification utility program (CYBESDT1), 201using, 201
expressioncomparing, 116definition, 115logical, 115usage, 115
EXTERNAL jobauthorization string, 181controlling, 179definition, 408forced complete, 181job qualifiers usage, 181marking complete, 179posting options, 181specifying an Application, 180usage, 178USERMOD 30, 181
EXTERNAL, Pnode field, 223EXTMON, definition, 408
FFAIL, Pnode field, 223file trigger, definition, 408first day of week, 49FIRST, scheduling term, 51FLOWDOC
components, 313data base generation, 313data generation, 313definition, 312example
specific Application sorted by days, 317specific Application, specific period, 316
specific Application, specific period ending in the future, 316
specific Event, specific date, 316graphical representation, 312Report generation, 314Report headings, 315Report organization, 314sample JCL and report, 317
freeform filteringdefinition, 247to display the critical path, 211
FTP data-set triggeringANYCLOSE, 87, 200definition, 11direction, 85, 198dsname, 87, 200Event, 84example, 11
FTP RECEIVE and SEND, 85host specific creation, 85logon specific creation, 86user-specific creation, 86with operands, 87
HOST, 85, 198limiting data set activity to a host, 85limiting data set activity to a user ID, 86limiting data-set activity
to a logon ID, 86LOGON, 86, 199operand
ANYCLOSE, 87dsname, 87RENAME, 87
RECEIVE, 85, 198RENAME, 87, 200SEND, 85, 198specifying, 84specifying the direction
of the transfer, 85USER, 86, 199workload object, 198
FTP data-set-trigger workload objectexample
FTP RECEIVE and SEND, 198host specific creation, 199logon specific creation, 200sending a message, 200user-specific creation, 199
Index
ESP-5.4-UG-05 425
limiting data set activity to a logon ID, 199limiting data-set activity to a host, 198limiting data-set activity to a user ID, 199specifying the direction of the transfer, 198using, 198
Functions of ESP Workload Manager, 8
Ggeneration
number, of an application, 140phase of an Application, 139
GENTIME, 57global variable table
definition, 22retrieving a variable from, 114triggering, 12triggering, example, 12
global variable, definition, 408graphical user interface, 20groups, 332
HHAO
ARM support, 398definition, 393, 407XCF routing, 400XCF status monitoring, 399
HELP facility, 33Help panels, 35High Availability Option, 393, 407High Performance Option, 377, 408history
example of report, 28fields to use as selection criteria
for reporting, 28reporting, 28, 276
history reporting fieldaccumulating, 297list, 289numeric, 296
HOLDan Event from being processed at
a particular time, 80and APPLEND, 190application hold Pnode, 223command, 104controlling Event scheduling, 79
defining held jobs, 153Event command, 100field in reports, 315hold count, 138hold count field in reports, 315holding a data-set-triggered Event, 80holding an Application in CSF, 233holding an Event, 104holding and releasing an Event, 104holding subApplication in CSF, 233listing jobs on, 125manual hold Pnode, 223operand of JOB, 153postponing execution of an Event, 104suppressing hold count field in reports, 308
holidaydefining, 65defining a holiday using a panel, 66defining a repetitive, 66defining a static, 129displaying, 63Event processing of, 66example
advancing / delaying a job, 67defining, 65defining a repetitive, 66defining using a panel, 66
job processing of, 67LISTHOL command to list, 63start date, 65time duration, 65using to schedule, 66
HOLIDAYS, scheduling term, 51HOST
limiting data set activity to a, 85, 198security check (EXPEDITE), 380security programs, 30
HOURLY, scheduling term, 51HPO
definition, 377, 408expedite, 378resource balancing, 382XCF routing, 388XCF status monitoring, 387
IIF
statement in Procedure, 110
426 ESP-5.4-UG-05
use in documentation, 268using instead of TEMPLIB, 146using parenthesis, 115
IF-THEN-ELSEexample of use, 112in job documentation, 266
indentation, 3index entries, displaying, 234info records, displaying, 234INFOMSG command, 37inheriting, job relationships, 14initialization parameter, definition, 408Input line entry, 36INPUT, Pnode field, 223interception, system message, 26INVOKE
an ESP Procedure, 93, 109, 219, 264command, 131command, in Event, 93
ISPF interfacecontrolling Events, 100retrieving information, 269screen, 32
ISPF option, 32ISPF panels
accessing, 100exiting ESP Workload Manager, 40special periods, 69
Issuing operator command, using Event, 95IW, CSF command, 234
JJANCWAIT, Pnode field, 223JCL
control the use of temporary, 146copying, 94creating a copy, 94example
creating a scheduled activity data set, 301report generation, 317reporting in batch, 288tailoring, 22updating a scheduled activity data set, 301
executing ESP Workload Manager commands in batch, 38
FLOWDOC data base generation, 313FLOWDOC data generation, 313FLOWDOC report generation, 314
generate a copy for every job, 147identifying JCL libraries, 143issuing commands in batch, 4limiting the use of temporary, 147routing jobs to other systems, 329specifying a library, 143specifying a library for a single job, 145specifying a temporary library, 144submitting in an Event, 91submitting JCL from Librarian and
Panvalet data set, 92tailoring, 22writing to a GDG, 148
JCL, editing the last executed, 234JCLLIB, definition, 409JES status of a job, displaying, 234JES, format of job ID, 409job
bypassing, 160canceling a PeopleSoft, 235changing job attributes, 192completing, 233CRITICAL operand, 153defining
conditional jobs, 153critical jobs, 153held jobs, 153requirements, 155with different attributes, 192
delayrelease
using the RELDELAY statement, 156submission, 155
different types, 177displaying
resources, 234duplicate names, 150example
changing a job attribute, 192combined statement, 150delaying submission of a job from
ready time, 156identifying a delayed submission time, 156multiple runs of a job, 150on-request, 152qualified jobs, 150sending messages at different stages, 154specifying a due-out time, 158
Index
ESP-5.4-UG-05 427
specifying a late submission time, 158using different submission times, 156
expediting manually, 235external, 178holding with a reason, 234identifying as on-request, 151inserting, 234
after a selected, 234before a selected, 234
mapping, 29monitoring, 25on-request, 16other methods for handling on-request, 152qualifying, 149readying, 234releasing, 233REQUEST operand, 151requesting, 234requesting the job, 153rerunning, 234restarting, 234resubmitting, 234retrieving a distributed spool file, 235scope of a JOB statement, 154selecting distributed option, 235specifying time dependencies, 155tracking, 24tracking, example, 25un-bypassing, 235un-requesting, 235un-waiting, 235using symbolic variables as qualifiers, 149z/OS, canceling and purging in JES, 234z/OS, canceling in JES, 233z/OS, canceling in JES with a dump, 234z/OS, executing on a goal mode system, resuming
the original service class of, 234z/OS, executing on a goal mode, quiescing, 234z/OS, issuing
a JES hold command on a, 234a JES release command on a, 233a system STOP command on an
executing, 234z/OS, owner of a, 365
job documentation, 19commands, 272contents, 258control information, 258
converting an existing PDS job documentation library into an ESP Workload Manager documentation library, 271
converting existing, 271creating, 260creating a job documentation member
for a job, 261customized labels, 260DOCMEM method, 266example
control information, 259documenting a job and a link, 268documenting links and tasks, 268ESP Procedure, 264overriding, 265retrieving job-documentation
information, 270start of job documentation, 258storing phone numbers, 273updating, 263using GENDOC to convert job doc., 272with customized labels, 260
IF-THEN-ELSE method, 266job qualifier, 266other uses, 273overriding rules, 265referencing members, 265relationship with Event and Procedure, 264retrieving information, 269retrieving your existing job documentation
through ESP Workload Manager, 271storing requirements, 259temporary override, 266updating, 262user description, 259using, 263using an operator console, 270using CSF, 269using for links and tasks, 267using for qualified jobs, 266using the control information, 264using the jobs option, 261using TSO, 269
job ID, definition, 409job mapping, 303job monitor, definition, 409job relationships, inheriting, 14
428 ESP-5.4-UG-05
job submittingfrom Librarian, 92using Event, 91
job tracking, XCF Service, 371JOB, statement, 149JOBENQ, example, 170JOBMAP, command, 305JOBONQ
built-in function, 118, 125example, 126returning values, 125using with REEXEC, 126variables, 125
JOBRES, 338JOBTREE, command, 309JUMPTO, statement in Procedure, 112
Llabel
customizing for job documentation, 260in ESP Procedures, 110in job documentation, 259use in ESP Procedures, 110
LABEL, command of GENDOC, 272LAST, scheduling term, 51LDTE, command, 84LDXE
command, 84example, 197to display data-set-triggering information, 197
LENGTHbuilt-in function, 118, 123example
calculating the length of a symbol, 123extracting the last character of a
variable length symbol, 124LESS, scheduling term, 51Librarian
data setsas input, 42ESP Procedure, 3, 109submitting jobs, 92
data-set prefix, 42submitting a job directly from
a Librarian data set, 92LIBSUB, command, 92, 131line mode
exiting ESP Workload Manager in, 40
how to work in, 39invoking CYBESDT1, example, 90, 203invoking ESP Workload Manager
in, from CSF, 247retrieving job-documentation information, 270
linkdefinition, 16, 409example, 17
issuing a command, 186keeping an Application active, 186notifying when an Application
completes, 187sending messages, 185simplifying job relationships, 185starting a task, taking action after
completion, 187LINK operand of JOB statement, 184owner, 365usage, 16, 184uses, 186vs. task, 185
LISTcommand, 101Event command, 100listing Events, 101RESDEF command operand, 340
LISTCALcommand, 62display a calendar, 62displaying holidays and special days, 63
LISTHOL, command, 63LISTSCH
command, 98displaying scheduled Events, 98
LISTSPEC, command, 63LOAD
command, 40example, loading diagnostic commands
from a data set, 41load a report definition, 281load an Event definition, 74
loading commands, 40logical calendar, 65logical day
defining your organization, 64specifying, 64vs. absolute day, 49
logical day, definition, 409
Index
ESP-5.4-UG-05 429
logical expression, 115logical operators
list, 116order of precedence, 116
LOGICAL, scheduling term, 51logon ID, limiting data-set activity to a, 86, 199logon specific creation, example, 86, 200LR, CSF command, 245LSAR, command, 300
MMAILLIST, 97, 206main menu
options, 33screen, 32
MANHOLD, Pnode field, 223MANSUB, Pnode field, 223MANUAL job
authorization string, 184controlling, 183defining, 182definition, 409example
on certain days, 182sending a message, 182
forced complete, 184marking complete, 183posting options, 184usage, 182
mapping, jobs, 29master, definition, 409MAXRUNTIME, 162MAXRUNTIME, using to set DUEOUT EXEC
time, 162ME, CSF command, 246menu panels in ESP Workload Manager, 33MIDDAY, scheduling term, 51MIDNIGHT, scheduling term, 51MINRUNTIME, 162modeling
definition, 29reports, 30
MODIFY command, 4MONTHLY, scheduling term, 51MR, CSF command, 246mutual exclusivity, removing, 168, 174mutually exclusive run requirements
definition, 15
example, 15
NNEXT
command, 99displaying the next scheduled
executions of an Event, 99Non-z/OS workload, 19NOSCHED
command, 78handling exceptions, 78
notification list, 97, 206NOTWITH
automatic generation of ENQUEUE commands, 172
definition, 409examples, 173excluding jobs from a
NOTWITH statement, 174removing mutual exclusivity, 174specifying mutually exclusive jobs, 172statement, 171
NOWdifference with REALNOW, 53scheduling term, 51
OOF, scheduling term, 52ONCE, scheduling term, 52one-time Event
example, 78scheduling a, 77
on-request jobs, 16, 151operand, definition, 409operator commands
from Events, 95issuing, 95
operator precedence, 115operators
arithmetic, 115comparison, 116comparison, in reports, 279in CRITERIA command (reports), 282logical, 116order of precedence, 116relational, in CSF, 253using, 115
430 ESP-5.4-UG-05
OR, scheduling term, 52overdue Event, 78, 105OVERDUE, scheduling term, 52
Ppage mode
benefit, 32comparing with ISPF Browse, 36displaying informational messages, 37displaying informational messages
where they occur in the input instead of at the top of the screen, 37
exiting ESP Workload Manager in, 40how to use, 36invoking CYBESDT1, 90, 203retrieving job-documentation
information in, 270returning informational messages
to the top of the screen, 38screen example, 36switch to from main menu, 34usage, 36using JOBMAP in, 306using JOBTREE in, example, 309using other commands in CSF, 247using the screens, 37
page mode, definition, 409Panvalet data sets
as input, 42ESP Procedures, 3, 109submitting JCL from, 92submitting jobs, 93
Panvalet, prefix for data sets, 42PeopleSoft, canceling a job, 235period, See special periodplanning
Applications to optimize Distributed Manager, 360
calendars, 60example, planning for a system shutdown, 353
PLUS, scheduling term, 52Pnode
definition, 410list of, 223APPLHOLD, 223APPLWAIT, 223BYPASSED, 223COMPLETE, 223
EXEC, 223EXTERNAL, 223FAIL, 223INPUT, 223JANCWAIT, 223MANHOLD, 223MANSUB, 223PREDWAIT, 223READY, 223RESWAIT, 223SANCWAIT, 223SUBDELAY, 223, 224SUBERROR, 223, 224SYSERROR, 223TASK, 223WAITING, 223
Pnode Application states, definition, 410positional operand, definition, 410post, definition, 410POSTREQ, statement, 165predecessor, definition, 410PREDWAIT, Pnode field, 223PREMEND operand, notification and alerting
process, 162PREREQ, statement, 165previous line, re-entering, 36PRIORITY statement, using, 332Procedure, See ESP ProcedurePROCLIB, definition, 410propagating dueout times
example, 159how to, 158
proxy, definition, 411purging a service, example (XCF), 373
Qqualifier, definition, 410QUEUE file, 371QUIESCE, command, 396QUIT
encountered, SUBERROR Pnode, 225example, 113statement in Procedure, 112
RREADY, Pnode field, 223REALNOW
Index
ESP-5.4-UG-05 431
difference with NOW, 53scheduling term, 52
redirecting Event messages to a notification list, 97RELEASE
Event command, 100statement, 165
RELEASE command, in Event, 80RENAME, FTP data-set trigger operand, 87, 200renewable resource
definition, 24, 327example
controlling access to a data base, 349controlling mutually exclusive jobs, 345defining a, 336usage, 346
renewable resource, definition, 410replying to an AS/400 message, 234report
content, 277creating flowcharts, 318customizing your job-activity report, 307ending the report definition, 287example
creating a scheduled activity data set, 301DATEFORM, 285displaying scheduled activity data, 300job-descendent report specific
to an Application, 310multiple criteria, 286reporting in batch, 288reporting on an Application, 287SADGEN, 299sample batch job for putting it all
together, 311selecting jobs based on EXCP
and CPU time, 284selecting jobs based on multiple criteria, 284selecting jobs belonging to an
Application, 283selecting jobs submitted outside
an Application, 283selecting jobs that belong to an Application
and start with a letter, 283selecting jobs that belong to an Application
or start with a letter, 283selecting jobs that ended during
a certain time, 283selecting jobs that have restarted, 283
specifying a format, 287updating a scheduled activity data set, 301using JOBMAP in batch, 306using JOBMAP in Page mode, 306using JOBTREE in batch, 309using JOBTREE in page mode, 309with MAPGEN, all jobs, 304with MAPGEN, selected jobs, 305writing report output to a data set, 289
extracting data, 299extracting tape information, 302field
categories, 278character, 278comparisons, 279CPU time, 280date, 280elapsed time, 279example
character, 278comparisons, 279CPU time, 280date, 280elapsed time, 280numeric, 278time, 279
formats, 278numeric, 278time, 279
flowcharting, 318generating an index, 307generating data, 298generating data for the report, 304generating flow charts with ESP Workload
Manager and Timeline, 321generating flowcharts using MS Project, 319generating for a specific Application, 307generating projected versus actual data, 302generating scheduled versus actual report, 301identifying the history file, 281Invoking the function, 281job-mapping data set, 304producing a job-activity report, 305producing a job-descendent report, 309putting it all together, 311reviewing the job-activity output, 307reviewing the job-descendent output, 310scheduled activity, 298
432 ESP-5.4-UG-05
sections, 277separating data into different files, 284setting up job mapping, 304setting up schedule forecasting, 298specifying an output data set, 284specifying fields to display, 285specifying input criteria, 281specifying other formats, 286specifying output criteria, 284specifying the date format, 285specifying the selection criteria, 282specifying the sort criteria, 286specifying the time range, 282structuring, 276suppressing fields, 308testing and using the GENFLOW feature, 321testing and using the GENPROJ feature, 319using a history file other than current, 281using job mapping, 303using the JOBMAP command, 305using the JOBTREE command, 309
reportingdefinition, 27history, 28, 276in batch, 276
REQUEST, 151RESDEF with MONITOR(CPU) operand,
coding, 385RESDEF, command, 335resetting, User Status field, 235resource
absorption, 342adding requirements, 331balancing, 382changing, 337default, 333default assignments, 334defining, 335defining a real resource, 336defining using the RESDEF command, 335definition, 326, 410deleting, 339depletable, 327determining a default assignment, 334device counts, 328displaying information about a resource, 340displaying one or more resources, 340
displaying requirements for jobs not yet submitted in an active Application, 341
displaying the resources associated with a job and determine what jobs have resources allocated, 340
displaying the resources of a job, 234dropping default, 332dropping requirements, 331example
ABSORB statement, 343adding requirements, 331Application with absorption, 344Application with absorption (CSF), 344changing, 337controlling access to a data base, 349controlling access to an online system, 346controlling mutually exclusive
groups of jobs, 350controlling mutually exclusive jobs, 345default scratch tape resource, 334defining a real resource, 337defining a renewable resource, 336defining a threshold resource, 336dropping default, 332dropping requirements, 332long resource name with no restrictions, 336planning for a system shutdown - Part
1, 353planning for a system shutdown - Part
2, 354real devices, 328requesting resources, 331routing jobs on other systems, 329running jobs on a particular system, 349schedule dependency, 356setting priority for more than one job, 333setting priority for one job, 333STEPEND statement, 342time periods for low priority jobs, 347using a resource for a self-completing
task, 348examples of different, 326excluding default resources for
an Application, 335gravity, 329in reports, 315job requiring multiple, 329managing jobs, 329
Index
ESP-5.4-UG-05 433
modifying, 234removing dependencies, 162renewable, 327requesting, 330requirement, 24scope of, 328setting, 337setting quantities automatically, 337setting up default resources, 334step-level resource release, 341threshold, 327types, 24types of, 326using real devices, 328working with, 335
RESOURCE statementplacing, 330using, 330
RESREFR, command, 337RESUME
command, 81command, usage, 104Event command, 100resuming an Event, 104
RESWAIT, Pnode field, 223REXX
CSF extensions, 247definition, 410in job documentation, 258interface, 27use of, 27
ROUND, scheduling term, 52ROUTING
command, 389, 401enabling XCF, 389, 401examples, 390, 402purpose of command, 390, 402service, overview, 388, 400XCF service, 388, 400
routingJCL, 329jobs to other systems, 329
run times, minimum, maximum, average, 162RUN, vs. SELECT, 176
SSADGEN
command, 298
definition, 411SADUPD, command, 301SANCWAIT, Pnode field, 223SCHEDULE
command, 77data-set-triggered and scheduled Events, 82example
schedule exception, 78schedule exception once, 78
examples, 77handling exceptions, 78overdue Events, 105overlapping criteria, 77setting to execute only once, followed
by a deletion of the Event, 77schedule criteria
date format, 47date range, 47days of months, 46days of the week, 44definition, 411example
daily or multiple times a day, 54monthly, 55multiple times a month, 56multiple times a week, 54one-time examples, 56testing criteria, 57weekly, 54yearly, 56
how to use with data-set triggering, 76implied periods, 48Julian date, 47matching criteria, 48month names, 45ordinal numbers, 47, 53spaces, 49specifying, 44specifying both an algorithm
and a starting date and time, 49testing, 57time and frequency, 48time of day, 46time zones, 46using, 43using CLANG, 57using GENTIME, 57using other techniques for, 57
434 ESP-5.4-UG-05
using the first day of the week, 49using workdays, 49where you can use, 44
scheduled activity, report, 29, 300scheduled Event
adding execution, 103bypassing, 103displaying, 98
SCHEDULED, operand of JOB statement, 180scheduling
controlling Event, 79Event, 77example
a job on the last day of the month, 132an hourly Event during a time range, 81
one-time Event, 77time and date, 9time zone abbreviations for, 46
scheduling termlist, 50using in calendars, 64ABSOLUTE, 50AND, 50ANYDAY, 50COMPLETE, 50DAILY, 50EACH, 50ENDING, 50EVERY, 50EXCEPT, 51FIRST, 51first day of week, 49HOLIDAYS, 51HOURLY, 51LAST, 51LESS, 51LOGICAL, 51MIDDAY, 51MIDNIGHT, 51MONTHLY, 51NOW, 51OF, 52ONCE, 52OR, 52OVERDUE, 52PLUS, 52REALNOW, 52ROUND, 52
STARTING, 52TIMES, 51TODAY, 52TOMORROW, 53UNTIL, 53WEEKDAYS, 53WEEKENDS, 53WITHIN, 53workday, 49WORKDAYS, 53YEARLY, 53YESTERDAY, 53
SCOPEoperand of JOB statement, 154, 180report heading, 315suppressing field in a report, 308
screenISPF interface, 34Main Menu, 32Page mode, 36
script, definition, 411security
authorized commands, 3authorized OPER commands, 3calendar, 58definition, 30for Applications, 142for EXPEDITE statement, 380FTP transfer-triggered Event, 200limiting data set activity to a user, 83limiting data-set activity to a user ID, 86, 199naming Events, 74use of the Event prefix, 75
SELECT, vs. RUN, 176SELECTED
built-in function, 117, 122built-in function syntax, 122example
selecting a job when another is not selected, 122
selecting one job based on another, 122SEND
command, 131example, sending messages at different
stages, 154using Events to send messages, 91
sending messages, 91services
Index
ESP-5.4-UG-05 435
description, 370displaying, 372enabling, 371purging, 373starting, 372XCF DSTRIG, 370, 390, 402XCF SCOREBD, 390, 402XCF scoreboard, 390, 402XCF TRACKING, 370, 390, 402
setting symbol libraries, 96SHADGOAL
command, 395, 396defining a shadow goal, 395examples, 397
shadow goaldefining, 395definition, 395deleting, 396how does it work, 395listing, 396what action it can take, 395
shadow manager, 394%SHADOW symbolic variable, 395and ARM, 399data-set usage, 394definition, 411description, 394example of moving control to, 397SHADGOAL command, 396shadow goal, 395shadow-disabled ESP master, 394shadow-enabled, 394shadow-enabled ESP master, 394START operand, 394START operands, 394switching control to, 397usage, 394z/OS MODIFY command, 398
shadow-enabled ESP Workload Manager master, 394
SIGCYCLE, command, 131SIGPOST, command, 131SIMULATE
command, 101Event command, 100options, 102options to specify, 102results, 101
simulatingan Event, 101an Event, example, 102
special daydefining, 67definition, 411displaying, 63example, 68
defining, 68using REPEAT, 68
listing, 63usage, 58using to schedule, 68
special perioddefining, 67defining the first day of, 68defining using ISPF panels, 69definition, 68, 411example
defining fiscal years, 69defining payroll periods, 69quarters and fiscal years, 72
intervals, 69listing, 63using, 58using to schedule, 70working, 70
SPIN TRACE, 374start service, starting XCF services, 372START, shadow manager operand, 394STARTING, scheduling term, 52state awareness, 373statement
definition, 411entering, 2ABSORB, 343AFTER, 165COREQ, 165DO, 111ELSE, 110ENDDO, 111EXIT, 111EXPEDITE, 379IF, 110JOB, 149JUMPTO, 112NOTWITH, 171POSTREQ, 165
436 ESP-5.4-UG-05
PREREQ, 165PRIORITY, 332QUIT, 112RELEASE, 165RESOURCE, 330STEPEND, 341TAG, 205THEN, 110
status of ENQSELF, 171STEPEND, statement syntax, 341step-level statistics, displaying, 234STEPLIB, 38stopping XCF services, 372subApplication
controlling, 214definition, 411displaying, 214example
coding, 213requesting a subApplication, 214
identifying, 212selecting, 213using, 212
SUBDELAY, Pnode field, 223SUBERROR, Pnode field, 223SUBMIT
command, 91Event command, 131submitting multiple jobs, example, 92using Events to submit JCL, 91
SUBSTRbuilt-in function, 118, 123example
extracting the last character of a variable length symbol, 124
using a substring of a time variable, 124subsystem name, 38successor, definition, 411SUSPEND
bypassing execution of an Event, 104command, 81Event command, 100example
scheduling an hourly Event during a time range, 81
suspending an Event, 104usage, 104
symbol introducer character, 110, 114
symbol librarysetting, 96specifying in Event, 96
symbolic variable%SHADOW, 395‰ESPAPTAG, 205‰ESPATIME, 203‰ESPTRDSN, 81‰ESPTRGDG, 203as qualifiers, 149attributes of, 21definition, 21, 412determining length, 123embedding in strings, 114ESP_APPL_PROC, 139ESPAPQUAL, 266example
notifying when an Application completes, 187
representing a scheduled date, 22usage, 114using a different TEMPLIB based on year
and day, 147generating with GENTIME, 57MAXRUNTIME, 162MINRUNTIME, 162stored in SYMLIB, 411substring, 123symbol introducer, 110to tailor JCL, 22using function for, 123using in ESP Procedures, 113
SYMLIBcommand, 96setting symbol libraries, 96
SYMLIB, definition, 411syntax conventions, 5SYSERROR, Pnode field, 223sysmsg, definition, 411SYSTEM calendar
definition, 59example
changing the first day of the week, 62
defining, 61displaying, 63
referencing, 64search order, 97
Index
ESP-5.4-UG-05 437
system console, issuing command from, 4system identifier
altering, 105Event, 76
system message interceptiondefinition, 26example, 26
TTAG
definition, 411statement, 205
TAPES, built-in function, 118, 126task
definition, 17, 411example
checking a report, 188specifying a due-out time for a task, 158usage, 17
marking complete, 188owner, 365uses, 189using, 188vs. link, 185
TASK, Pnode field, 223template
defining, 129example
defining a static holiday, 129defining similar jobs, 130
using, 129using a template you have defined, 129
TEMPLIB, definition, 411TEST, command, 57testing schedule criteria, 57THEN
statement in Procedure, 110terminator of IF expression, 115
threshold resourcedefinition, 24, 327displaying, 340example
defining, 336schedule dependency, 356time periods for
low priority jobs, 347usage, 327
threshold resource, definition, 410
time and date scheduling, 9time dependency
resetting, 235TIMES, scheduling term, 51TODAY
built-in function, 117, 120example, 120scheduling term, 52
TOMORROWbuilt-in function, 117, 120example, 121scheduling term, 53
traceactivating XCF trace, 374SPIN TRACE, 374XCF trace facility, 374
trackingjobs, 24models, 25
tracking model, definition, 411TRIGGER
adding execution, 103command, 102Event command, 100example
creating and triggering an Event, 212triggering an Event, 212
triggerdifferent ways to trigger an Event, 10for a data set, 10kinds of, 109
triggering an Eventcreating and, example, 212example, 212manually, 102
triggering expected Events, 99TSO command processor, accessing ESP
Workload Manager through a, 40TSO mode message, 39turning on the TSO mode message, 39
UUNTIL, scheduling term, 53updating an Info record, 235USE, command, 35USER
example, user-specific creation, 199operand
438 ESP-5.4-UG-05
limiting data set activity to a user, 83, 196limiting data set activity to a user
ID, 86, 199user
setting and resetting the status field, 245setting the status field, 225
user data sets, definition, 412user-defined variables, definition, 113
Vvariable
AUTOVAR, definition, 406definition, 412example
basic, 21defining an undefined variable, 123retrieving a variable from
a global variable table, 114using a substring of a time variable, 124using symbolic variables, 114
global, definition, 412length, 123symbolic, definition, 412use of symbol introducer, 114using, 21
viewing ESP Encore panels, 234VS
command, 95Event command, 131issuing an operator command, 95
WWAITING, Pnode field, 223WEEKDAYS, scheduling term, 53WEEKENDS, scheduling term, 53wildcard, masking, 3WITHIN, scheduling term, 53WLM workload balancing
introduction, 382scenario using, 384using, 338
workdaydefault, 60using, 49
workday, definition, 412WORKDAYS, scheduling term, 53workload balancing
(Agent) requirements, 339, 385(Agent) scenario using, 386(WLM) requirements, 338, 382(WLM) scenario using, 384description, 382
workload objectdefinition, 137, 412establishing ownership of a, 364owner of a distributed, 365type in history file, 295
Workstation, See ESP Workstationwriting session data, 37
XXCF
command examples, 397commands, 370Display Service connections, 372displaying the members in the XCF group
and their respective states, 374how status monitoring works, 387, 399manually moving control, 397member failure, 388, 400member or group member termination, 396migrating from QUEUE file, 371Purging a Service, 373QUEUE file migration, 371routing service, 388, 400
benefit, 389, 401description, 389, 401overview, 388, 400
Services, 371Start Service, 372State awareness, 373status monitoring, 387, 399Stop Service, 372stopping all the XCF members in the
XCF group simultaneously, 374stopping an XCF member, 374Trace, 374
XCF ROUTINGcommand syntax, 389, 401enabling, 389, 401ROUTING command, 389, 401
XCF SCOREBOARD, 390, 402XCF service
description, 370displaying, 372
Index
ESP-5.4-UG-05 439
displaying active connections, 372enabling, 371example
purging, 373restarted, 373
purging, 373restarting on the fly after it has
been stopped, 372scoreboard
benefit, 391, 403definition, 390, 402
starting, 372stopping, 372XCF DSTRIG, 370, 390, 402XCF SCOREBD, 390, 402XCF scoreboard, 390, 402XCF TRACKING, 370, 390, 402
XCF SPIN TRACE, command, 374XCF START SERVICE
command, 371enabling XCF routing, 389, 391, 401
enabling XCF SCOREBD, 403restarting an XCF Service on
the fly after it has been stopped, 372starting XCF services, 372
XCF trace facilitydebug tool for XCF, 374definition, 374
XCF trace, activating and capturing data using, 374
YYEARLY, scheduling term, 53YESTERDAY
built-in function, 117, 121example
process only if YESTERDAY was a holiday, 121
process only if YESTERDAY was the first day of the month, 121
scheduling term, 53
440 ESP-5.4-UG-05