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.

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 SRL
www.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.

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

About this guide 1

Who should read this guide................................................................................ 2
How to use this guide ........................................................................................ 2
Entering commands ........................................................................................... 2
Entering statements............................................................................................ 2
Examples............................................................................................................ 4
Conventions used in this guide .......................................................................... 5
Summary of changes .......................................................................................... 6
1 Introduction to ESP Workload Manager Concepts 7
Functions of ESP Workload Manager ................................................................ 8
Time and date scheduling .................................................................................. 9
ESP Workload Manager Events ......................................................................... 9
Data-set triggering............................................................................................ 10
Global-variable-table triggering ........................................................................ 12
ESP Procedures ................................................................................................ 12
Applications ..................................................................................................... 13
Inheriting job relationships .............................................................................. 14
Mutually exclusive run requirements................................................................ 15
On-request jobs................................................................................................ 16
Links ................................................................................................................ 16
Tasks................................................................................................................ 17
APPLEND workload object ............................................................................. 18

ESP-5.4-UG-05 iii
 Distributed workload objects ........................................................................... 19
Job documentation........................................................................................... 19
Consolidated Status Facility (CSF)................................................................... 20
Graphical user interface.................................................................................... 20
Symbolic variables............................................................................................ 21
Tailoring Job Control Language....................................................................... 22
Resources ......................................................................................................... 23
Tracking jobs ................................................................................................... 24
Job monitoring and alert processing ................................................................. 25
System message interception ............................................................................ 26
REXX interface ................................................................................................ 27
Reporting......................................................................................................... 27
Modeling ......................................................................................................... 29
Security ............................................................................................................ 30
2 Getting Started 31
Accessing ESP Workload Manager ................................................................... 32
Accessing ESP Workload Manager as an ISPF option ...................................... 32
Accessing ESP Workload Manager through a batch program ........................... 38
Invoking ESP Workload Manager as a program in TSO .................................. 39
Accessing ESP Workload Manager through
a TSO command processor............................................................................ 40
Exiting ESP Workload Manager ...................................................................... 40
Loading commands.......................................................................................... 40
Alternative input data sets ................................................................................ 42
3 Schedule Criteria 43
Where you can use schedule criteria ................................................................. 44
Specifying schedule criteria............................................................................... 44
Schedule terms ................................................................................................. 50
Using other techniques for schedule criteria ..................................................... 57
Testing schedule criteria................................................................................... 57
Using calendars ................................................................................................ 58
Using calendar terms........................................................................................ 59
Working with calendars ................................................................................... 60
Defining holidays............................................................................................. 65
Defining special days........................................................................................ 67
Special periods ................................................................................................. 68
Working with periods ...................................................................................... 70
4 Processing ESP Events 73
Defining an ESP Event .................................................................................... 74
Specifying data-set-triggered Events ................................................................. 81
Specifying FTP data-set triggered Events.......................................................... 84
Specifying explicit-data-set triggers................................................................... 87
Specifying the function of an Event.................................................................. 91

iv ESP-5.4-UG-05
 Contents

Issuing operator commands.............................................................................. 95

Specifying other requirements .......................................................................... 96
Displaying the schedule.................................................................................... 98
Displaying when an Event will execute............................................................. 99
Working with defined Events......................................................................... 100
5 Working with ESP Procedures 107
Overview of ESP Procedures .......................................................................... 108
Invoking an ESP Procedure............................................................................ 108
ESP Procedure syntax..................................................................................... 109
Using ESP Workload Manager control language in Procedures...................... 110
Using symbolic variables in Procedures .......................................................... 113
Using expressions and strings in Procedures ................................................... 114
Built-in functions........................................................................................... 117
Using calendaring functions ........................................................................... 118
Using functions for job selection .................................................................... 122
Using functions for symbolic variables ........................................................... 123
Using system activity functions ...................................................................... 124
Combining functions ..................................................................................... 127
Re-executing an ESP Procedure ..................................................................... 128
Using templates.............................................................................................. 129
Using Event definition commands in Procedures ........................................... 131
CLANG examples .......................................................................................... 132
Caching an ESP Workload Manager Procedure ............................................. 135
6 Using Applications 137
Introducing Applications................................................................................ 138
Identifying the Application ............................................................................ 142
Identifying JCL libraries................................................................................. 143
Identifying jobs .............................................................................................. 149
Defining job requirements ............................................................................. 155
Specifying time dependencies ......................................................................... 155
Specifying job relationships ............................................................................ 165
Using Implicit Resources................................................................................ 166
Selecting jobs for submission.......................................................................... 175
Using different job types ................................................................................ 177
Defining external jobs .................................................................................... 178
Defining manual jobs..................................................................................... 182
Using links ..................................................................................................... 184
Using tasks ..................................................................................................... 188
Using APPLEND workload object................................................................. 190
Changing job attributes.................................................................................. 192
Using data-set-trigger workload objects .......................................................... 193
Using FTP data-set-trigger workload objects .................................................. 198
Using explicit-data-set-trigger workload objects ............................................. 201

ESP-5.4-UG-05 v
 Tagging jobs .................................................................................................. 205
Providing notification on Job status ............................................................... 206
Using critical-path analysis ............................................................................. 208
Issuing ESP Workload Manager commands ................................................... 211
Using subApplications.................................................................................... 212
Working with Applications ............................................................................ 215
Displaying an Application .............................................................................. 215
Controlling an Application ............................................................................ 216
Changing an Application definition ............................................................... 218
Invoking an ESP Application ......................................................................... 219
7 Consolidated Status Facility (CSF) 221
Setting up CSF views ..................................................................................... 222
CSF fields ...................................................................................................... 223
Defining a view .............................................................................................. 226
Customizing a view ........................................................................................ 227
Updating a view ............................................................................................. 231
Deleting a view .............................................................................................. 232
Selecting views ............................................................................................... 232
Commands .................................................................................................... 232
Inserting a job ................................................................................................ 235
Resubmitting a job......................................................................................... 237
Rerunning multiple jobs................................................................................. 238
Removing job dependencies ........................................................................... 239
Resetting a time dependency .......................................................................... 240
Bypassing and completing jobs....................................................................... 242
Adding job dependencies ............................................................................... 243
Adding a job with a time dependency ............................................................ 243
Adding a job relationship in an Application ................................................... 243
Adding a LINK process .................................................................................. 244
Setting and resetting the user status field ........................................................ 244
Modifying a Job Resources or Enqueues......................................................... 245
Using other commands .................................................................................. 247
Extensions to CSF.......................................................................................... 247
Freeform filtering ........................................................................................... 247
8 Job Documentation 257
Contents of job documentation...................................................................... 258
Control information....................................................................................... 258
User description ............................................................................................. 259
Creating job documentation .......................................................................... 260
Using the jobs option..................................................................................... 261
Updating job documentation ......................................................................... 262
Using job documentation............................................................................... 263
Using the control information........................................................................ 264

vi ESP-5.4-UG-05
 Contents

Referencing job-documentation members ...................................................... 265

Overriding job documentation....................................................................... 265
Using job documentation for qualified jobs.................................................... 266
Using job documentation for links and tasks.................................................. 267
Retrieving information................................................................................... 269
Converting existing job documentation.......................................................... 271
Other uses of job documentation ................................................................... 273
9 Creating Reports 275
History reporting ........................................................................................... 276
Structuring the report .................................................................................... 276
Reporting fields.............................................................................................. 277
Field formats .................................................................................................. 278
Invoking the report function .......................................................................... 281
Specifying input criteria ................................................................................. 281
Specifying output criteria ............................................................................... 284
Ending the report definition........................................................................... 287
ESP Workload Manager history reporting fields............................................. 289
Accumulating reporting fields ........................................................................ 297
Reporting on scheduled activity ..................................................................... 298
Generating data.............................................................................................. 298
Extracting data ............................................................................................... 299
Generating scheduled versus actual report ...................................................... 301
Generating projected versus actual data .......................................................... 302
Extracting tape information ........................................................................... 302
Using job mapping......................................................................................... 303
Producing a job-descendent report ................................................................. 309
Putting it all together ..................................................................................... 311
ESP Workload Manager FLOWDOC ........................................................... 312
Flowcharting .................................................................................................. 318
Generating flowcharts using MS Project......................................................... 319
Generating flow charts with ESP Workload Manager and Timeline............... 321
10 Using Resources 325
What is a resource?......................................................................................... 326
Types of resources .......................................................................................... 326
Scope of resources .......................................................................................... 328
Using real devices ........................................................................................... 328
Routing jobs to other systems......................................................................... 329
Managing jobs................................................................................................ 329
Requesting resources ...................................................................................... 330
Default resources............................................................................................ 333
Working with resources.................................................................................. 335
Defining resources.......................................................................................... 335
Setting resources............................................................................................. 337

ESP-5.4-UG-05 vii
 Modifying Resources...................................................................................... 338
WLM Workload Balancing............................................................................ 338
Agent Workload Balancing ............................................................................ 339
Deleting resources .......................................................................................... 339
Displaying resource information .................................................................... 340
Step-level resource release............................................................................... 341
Resource absorption ....................................................................................... 342
Example: Controlling mutually exclusive jobs ................................................ 345
Example: Controlling access to an online system ............................................ 346
Example: Time periods for low priority jobs .................................................. 347
Example: Using a resource for a self-completing task...................................... 348
Example: Controlling access to a data base ..................................................... 349
Example: Running jobs on a particular system ............................................... 349
Example: Controlling mutually exclusive groups of jobs................................. 350
Example: Planning for a system shutdown - Part 1......................................... 353
Example: Planning for a system shutdown - Part 2......................................... 354
Example: Schedule dependency...................................................................... 356
11 Optimizing ESP Applications to Use
Distributed Manager 359
Planning Applications to optimize Distributed Manager ................................ 360
Establishing ownership of a workload object .................................................. 364
Creating distributed Applications................................................................... 365
Defining ownership of an Application............................................................ 366
Changing ownership of an Application .......................................................... 367
Changing ownership of an Application dynamically....................................... 368
12 Using XCF with ESP Workload Manager 369
Commands .................................................................................................... 370
XCF Services.................................................................................................. 370
State awareness............................................................................................... 373
Trace.............................................................................................................. 374
13 ESP Workload Manager High Performance Option 377
Expedite ......................................................................................................... 378
Resource Balancing ........................................................................................ 382
Workload Balancing....................................................................................... 382
XCF Status Monitoring ................................................................................. 387
XCF Routing Service ..................................................................................... 388
XCF Scoreboard Service................................................................................. 390
14 ESP Workload Manager High Availability Option 393
Shadow Manager............................................................................................ 394
ARM Registration .......................................................................................... 398
XCF Status Monitoring ................................................................................. 399
XCF Routing Service ..................................................................................... 400

viii ESP-5.4-UG-05
 Contents

XCF Scoreboard Service................................................................................. 402

Glossary 405

Index 413

ESP-5.4-UG-05 ix
x ESP-5.4-UG-05
 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.

ESP-5.4-UG-05 1
 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.

2 ESP-5.4-UG-05
 About this guide

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

ESP-5.4-UG-05 3
 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 **

4 ESP-5.4-UG-05
 About this guide

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 An operand must be substituted. User supplied variable or
operand 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 Operand enclosed in parentheses is mandatory and must
special characters be entered as shown.
Single operand in Optional operand, do not type the brackets.
square brackets [ ]
Stacked operands in Mandatory, you must enter one of the operands. You
braces { } cannot enter more than one.
{ }
Stacked operands in Optional operand, you can enter one value, or none.
square brackets
[ ]
[ ]
Operands with OR- Optional, mutually exclusive operands. Enter one or none.
bars ( | ) and square
brackets [ ]|[ ]
Stacked operands in Mandatory, you must enter one of these operands. You can
square brackets within enter more than one.
braces {[ ]}

ESP-5.4-UG-05 5
 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.

6 ESP-5.4-UG-05
 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)

ESP-5.4-UG-05 7
 Section–Functions of ESP Workload Manager

• 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

8 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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 DAILY
2PM 1ST WEEKDAY OF EACH MONTH
7PM 3RD 13TH AND 23RD DAY OF MONTH
5PM 10TH-19TH DAY OF MONTH
2ND AND LAST FRIDAY OF EACH MONTH
EVERY 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_MONTH
5PM INVENTORY_DAY
CHRISTMAS PLUS 1 WORKDAY
8AM 8TH-10TH WORKDAY OF FISCAL_YEAR
2ND 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

ESP-5.4-UG-05 9
 Section–Data-set triggering

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.

10 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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.

ESP-5.4-UG-05 11
 Section–Global-variable-table triggering

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 MYTABLE
VT1='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.

12 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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

ESP-5.4-UG-05 13
 Section–Inheriting job relationships

Application definition
An Application definition looks like this:
APPL PAYROLL
JCLLIB 'CYBER.ESP.JCL'
JOB A A
RUN DAILY
RELEASE (B,C)
ENDJOB
JOB B B C
RUN DAILY Daily
RELEASE D
ENDJOB
JOB C
RUN DAILY D
RELEASE D
ENDJOB
JOB D
E Friday
RUN DAILY
RELEASE E
ENDJOB
JOB E
F Last workday
RUN FRIDAY of month
RELEASE F
ENDJOB
JOB F
RUN LAST WORKDAY OF THE MONTH
ENDJOB

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

14 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

relationships, ESP Workload Manager determines the relationships required under

different processing conditions.

Example
Consider the following three jobs and their schedule frequencies:

J1 Daily

J2 Friday

J3 Daily

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 NWN00C
JCLLIB 'CYBER.JCL.CNTL'
JOB NWN001
RUN WEEKDAYS
NOTWITH NWN003
ENDJOB
JOB NWN002

ESP-5.4-UG-05 15
 Section–On-request jobs

RUN WEEKDAYS
ENDJOB
JOB NWN003
RUN WEEKDAYS
NOTWITH NWN001
ENDJOB

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

16 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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.

A B C

LINK

D E F

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.

J1
(Job)

CHECKRPT.J1
(Task)

J2
(Job)

ESP-5.4-UG-05 17
 Section–APPLEND workload object

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 TESTAE1
JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 LINK

RUN DAILY
REL JOB2
ENDJOB

JOB JOB2 LINK

RUN DAILY
ENDJOB

APPLEND FRED
REL (AFTERAE1,AFTERAE2)
SE 'APPLEND RUNNING' U(*)
ENDJOB

JOB AFTERAE1 LINK

RUN DAILY
REL AFTRAELA
ENDJOB

JOB AFTERAE2 LINK

RUN DAILY
ENDJOB

JOB AFTRAELA TASK

RUN DAILY
ENDJOB

18 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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.

ESP-5.4-UG-05 19
 Section–Consolidated Status Facility (CSF)

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.

20 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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 X
X=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.

ESP-5.4-UG-05 21
 Section–Tailoring Job Control Language

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.

Substituted JCL on
Original JCL June 9, 2000

//SYSIN DD //SYSIN DD
%
*ESPSMM%ESPSDD%ESPSYEAR *06092000

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.

22 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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

ESP-5.4-UG-05 23
 Section–Tracking jobs

Resources
ESP Workload Manager supports the three following types of resources:

Type of Explanation
resource...
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.

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

24 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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 CYBJES
SUBMITTED BY ESP AT 10.06 ON TUE 13APR, EVENT CYBBP01.PAY
JCL FROM CYBBP01.ESP.DEMO.JCL(PAY008A)
JCL COPIED TO CYBBP01.ESP.DEMO.COPYJCL(PAY008A)
PROGRAMMER BOB, ACCOUNT CYBTEST
JOB IS IN APPL PAY
INFORMATION/MANAGEMENT RECORD 0000053 CREATED FOR THIS JOB
STEPNAME-PROCSTEP-PROGNAME—EXCEP-#T-S-N-CPU-TIME-SUNITS-REGION-CMPC
ENCORE ESPRM CYBRM000 30 0 0 0 0:00.48 2635 320K 0
STEP01 IEFBR14 0 0 0 0 0:00.00 0 4K 0
STEP02 IEBGENER 0 0 0 0 0:00.00 0 72K 0
STEP03 SOC1 1 0 0 0 0:00.13 428 8K SOC1
STEP04 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—SYS
INPUT 10.06 5 CYB1|EXEC 10.06 12 SYSTEM CYB1
OUTPUT 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.

ESP-5.4-UG-05 25
 Section–System message interception

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

26 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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

ESP-5.4-UG-05 27
 Section–Reporting

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 DATE
PAYD001A 2221 0 11.56 TUE 08MAY01 12.02 TUE 08MAY01 0:01
PAYD002A 2227 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00
PAYD003A 2226 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00
PAYD004A 2229 0 12.02 TUE 08MAY01 12.07 TUE 08MAY01 0:04
PAYD100A 2232 0 12.07 TUE 08MAY01 12.07 TUE 08MAY01 0:00
PAYD006A 2233 0 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00
PAYD008A 2234 SOC1 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00
PAYD008A 2270 SOC1 12.57 TUE 08MAY01 12.57 TUE 08MAY01 0:00
PAYD008A 2271 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00
PAYD009A 2272 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00
PAYD010A 2273 SOC1 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00
PAYD010A 2275 0 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00
PAYD011A 2276 0 12.59 TUE 08MAY01 13.04 TUE 08MAY01 0:01
SUBTOTAL (13) 0:06
TOTAL (13) 0:06

28 ESP-5.4-UG-05
 Chapter 1–Introduction to ESP Workload Manager Concepts

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

ESP-5.4-UG-05 29
 Section–Security

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.

30 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 31
 Section–Accessing ESP Workload Manager

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.

32 ESP-5.4-UG-05
 Chapter 2–Getting Started

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 • Display information about a user or group of users
Manager defaults • 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.

ESP-5.4-UG-05 33
 Section–Accessing ESP Workload Manager as an ISPF option

Option Use this option to...

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 • View information on jobs and Applications that ESP
(CSF) 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 • Load a series of ESP Workload Manager commands
Utilities • 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.

34 ESP-5.4-UG-05
 Chapter 2–Getting Started

Option Use this option to...

M ESP Workload Manager • This option is only available to the ESP Workload
Administration 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.

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 Last

Activity Year Month Day ESP Start
------------------------------------------------------------------------------
Applications completed 75 23 4 2
Applications created 77 25 4 1
Events executed 183 81 13 5
Jobs 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.

ESP-5.4-UG-05 35
 Section–Accessing ESP Workload Manager as an ISPF option

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.

36 ESP-5.4-UG-05
 Chapter 2–Getting Started

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

ESP-5.4-UG-05 37
 Section–Accessing ESP Workload Manager through a batch program

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

38 ESP-5.4-UG-05
 Chapter 2–Getting Started

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 0
WRITE Enter the name of the job you want to run
READ &J
ESP SUB(ESPX)
TRIGGER &USER.ADDJOB USER1("&J")
END

ESP-5.4-UG-05 39
 Section–Accessing ESP Workload Manager through a TSO command processor

Accessing ESP Workload Manager through

a 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 0
WRITE Enter the name of the job you want to run
READ &J
CALL 'CYB1.ESP510E.LOAD(ESP)' SUB(ESPX);-
TRIGGER &USER.ADDJOB USER1("&J");END'

Exiting ESP Workload Manager

To exit ESP Workload Manager at any time:

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

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,

40 ESP-5.4-UG-05
 Chapter 2–Getting Started

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:
SMFSTATS
LISTRAK
OPER LISTAPTF
LISTCKPT
LISTQ
You can process all of these commands by issuing the following command in Page
mode:
LOAD 'CYB.ESP.DATA(DIAG)'

Sample output
SMFSTATS
ESP SUBSYSTEM INITIALIZED AT 12.43.58 ON MONDAY JUNE 25TH, 2001
9213 ENTRIES TO SMFWTM, 1592 BY BRANCH ENTRY AND 7621 BY SVC
4863 ENTRIES TO ESP PHASE 2
7272 JOB STARTS, 595 STC STARTS, 645 TSU STARTS, 9051 STEP ENDS

LISTTRAK
TRAKFILECYB3.ESP430NV.TRAKFILE
FORMATTED AT 16.15.17 ON MONDAY SEPTEMBER 25TH, 2000
9296 SLOTS TOTAL, 8857 AVAILABLE, NEXT IS 6223

OPER LISTAPTF
DATASET CYB3.ESP430NV.APPLFILE
FORMATTED AT 15.00.54 ON MONDAY OCTOBER 16TH, 2000
6000 SLOTS TOTAL, 5735 AVAILABLE, NEXT IS 2504
---1 ENTRY DISPLAYED

LISTCKPT
PRIMARY CHECKPOINT CTB3.ESP430NV,CKPT
MAX CHECKPOINT SIZE 614400
HIGHEST ADDRESS USED 4032
80 BYTES IMBEDDED FREE SPACE

LISTQ
QUEUE DATASET CYB3.ESP430NV.QUEUE
FORMATTED AT 13.44.57 ON MONDAY JUNE 11TH, 2001
MAXIMUM SIZE 614400 BYTES
HIGHEST ADDRESS USED 3888, 480 BYTES IMBEDDED FREE SPACE

ESP-5.4-UG-05 41
 Section–Alternative input data sets

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:

Prefix Type of Data set

LIB- Librarian
PAN- Panvalet

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.

42 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 43
 Section–Where you can use schedule criteria

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.

44 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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 2001
you 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

ESP-5.4-UG-05 45
 Section–Specifying schedule criteria

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.

Format Example
hh.mm 12.30
hh:mm 01:25
hh.mm.ss 10.47.30
hh:mm:ss 11:00:01

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.

46 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

Julian date
A Julian date is recognized in the following formats, where yy or yyyy = year number
and ddd = day number.

Format Example
yy.ddd 01.056
yyyy.ddd 2001.056

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.

Format Example
yy/mm/dd 00/12/28
dd/mm/yy 28/12/00
mm/dd/yy 12/28/00

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 MONTH
1ST 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

ESP-5.4-UG-05 47
 Section–Specifying schedule criteria

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 MONTH
3RD DAY OF LAST WEEK OF YEAR
5TH 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

48 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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.

Workday Weekend Weekend Holiday Workday Workday Workday

1 X X X 2 3 4

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.

Absolute Calendar Logical Calendar

SCHEDULE 2AM MONDAY SCHEDULE 2AM MONDAY

Event scheduled at 2 am Monday Event scheduled at 2 am Tuesday

ESP-5.4-UG-05 49
 Section–Schedule terms

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 Explanation

Workload Manager
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.

50 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

Term recognized by ESP Explanation

Workload Manager
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.

ESP-5.4-UG-05 51
 Section–Schedule terms

Term recognized by ESP Explanation

Workload Manager
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.

52 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

Term recognized by ESP Explanation

Workload Manager
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.

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:

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

ESP-5.4-UG-05 53
 Section–Schedule terms

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

54 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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.

ESP-5.4-UG-05 55
 Section–Schedule terms

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 2003
00.00.00 SATURDAY AUGUST 30TH 2003 DAY 242
00.00.00 SATURDAY SEPTEMBER 4TH 2004 DAY 248
00.00.00 SATURDAY SEPTEMBER 3RD 2005 DAY 246

TEST (3) 5TH SATURDAY WITHIN AUGUST STARTING 2003

00.00.00 SATURDAY AUGUST 30TH 2003 DAY 242

56 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

00.00.00 SATURDAY AUGUST 30TH 2008 DAY 243

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

ESP Workload Explanation

Manager Command
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.

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-5.4-UG-05 57
 Section–Using calendars

ESP Workload Manager displays output similar to the following:

00.00.00 THURSDAY MAY 31ST, 2001, DAY 151
00.00.00 FRIDAY JUNE 29TH, 2001, DAY 180
00.00.00 TUESDAY JULY 31ST, 2001, DAY 212
00.00.00 FRIDAY AUGUST 31ST, 2001, DAY 243
00.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.

58 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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.

ESP-5.4-UG-05 59
 Section–Working with calendars

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.

60 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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.

ESP-5.4-UG-05 61
 Section–Working with calendars

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.

62 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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 system
CALENDAR NAME:SYSTEM
DEPARTMENT:NONE
DEFINED:AT 11.45 ON THU 13TH AUG 2001 BY CYBBT01
OWNER:CYBBT01
WORKDAYS:MON TUE WED THU FRI
WEEK STARTS:MON
SIZE:280 BYTES
HOLIDAYS:CHRISTMAS, NEW_YEARS, CHRISTMAS, NEW_YEARS
SPECIAL 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 paycal
CALENDAR NAME:PAYCAL
DEPARTMENT:PAYROLL
DEFINED:AT 08.21 ON FRI 14TH SEP 2001 BY BP01
OWNER:BP01
WORKDAYS:MON TUE WED THU FRI SAT
WEEK STARTS:MON
SIZE:472 BYTES
HOLIDAYS:NONE
SPECIAL 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.

ESP-5.4-UG-05 63
 Section–Working with calendars

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.

64 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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)

ESP-5.4-UG-05 65
 Section–Defining holidays

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.

66 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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 WORKDAYS
RUN 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.

ESP-5.4-UG-05 67
 Section–Special periods

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

68 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

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.

ESP-5.4-UG-05 69
 Section–Working with periods

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.

70 ESP-5.4-UG-05
 Chapter 3–Schedule Criteria

The first few periods look like this:

Start of P eriod D uration Length of Q uarter

June 28
4 weeks
July 26
4 weeks 13 weeks
August 23
5 weeks
Septem ber 27
4 weeks
O ctober 25
4 weeks 13 weeks
N ovem ber 22
5 weeks
D ecem ber 27

Option L
Using option L.4 you can define these periods, for a year, as follows:

ESP ------------------------------ CALENDARS ----------------------------- ESP

COMMAND ===>

Define a special day

For each occurrence of the special day you want to define, complete SPECIAL
DAY NAME, ON, and CALENDAR if required, then press,ENTER.
The ON fields can contain specific dates and times, or schedule statements
for 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)

ESP-5.4-UG-05 71
 Section–Working with periods

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

72 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 73
 Section–Defining an ESP Event

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 MONTH
SUBMIT '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.

74 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

Event name
An Event name has two parts:

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.

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.

DOROTHY

DOROTHY.PHONE_BILL PROD.TRAINING

PROD.PAYROLL

ESP-5.4-UG-05 75
 Section–Defining an ESP Event

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.

76 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 WEEKDAYS
SCHEDULE 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 DAILY
SCHEDULE EVERY 6 HOURS ROUND WEEKDAYS

Examples: SCHEDULE commands

Some examples of schedule commands follow:
SCHEDULE 7PM DAILY
SCHEDULE 10:00 LAST WORKDAY OF MONTH
SCHEDULE 16:00 3RD 13TH 23RD DAY OF MONTH
SCHEDULE 9AM 2ND LAST DAY OF MONTH
SCHEDULE 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.

ESP-5.4-UG-05 77
 Section–Defining an ESP Event

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 ONCE
SEND '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 WORKDAYS
NOSCHED 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 WORKDAYS
NOSCHED 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

78 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 MONTH
ON WEEKEND DELAY 1 WEEKDAY
ON HOLIDAY DELAY 1 WEEKDAY
INVOKE '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.

ESP-5.4-UG-05 79
 Section–Defining an ESP Event

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.INPUT
HOLD DAILY AT 6AM
RELEASE DAILY AT 10PM
INVOKE 'ESP.PROCS(PAYJOBS)'
ENDDEF

80 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 TODAY
SEND 'TIME IS %ESPATIME' U(*)
SUSPEND 16:01 WORKDAYS
RESUME 7:59 WORKDAYS
ENDDEF

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.

ESP-5.4-UG-05 81
 Section–Specifying data-set-triggered Events

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 ANYCLOSE
INVOKE 'CYB.ESP.PROCS(NIGHTLY)'
ENDDEF

Process flow
Visually, the flow looks like this:

PROD.CICS.FILE1602 PROD.NIGHTLY
(data set) (Event)

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)

82 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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.

ESP-5.4-UG-05 83
 Section–Specifying FTP data-set triggered Events

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.

Command Use this command to ...

LDXE display data-set-triggered Events.
LDTE display data sets being checked for closures, creations, or renames.

Output from these commands looks like this:

ldxe
Event/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

ldte
The 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.

84 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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

ESP-5.4-UG-05 85
 Section–Specifying FTP data-set triggered Events

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

86 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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.

ESP-5.4-UG-05 87
 Section–Specifying explicit-data-set triggers

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]

88 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 generation
You 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.

ESP-5.4-UG-05 89
 Section–Specifying explicit-data-set triggers

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) EXPLICIT
ENDDEF

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.

90 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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=NODE1
STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET -
TO(SNODE DSN=NEW.DATA.SET DISP=(NEW,CATLG,DELETE))
IF (STEP1 EQ 0) THEN
STEP2 RUN TASK (PGM=CYBESDT1 -
PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) SNODE
EIF

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 DAILY
SEND '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.

ESP-5.4-UG-05 91
 Section–Specifying the function of an Event

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 MONTH
SUBMIT '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 MONTH
SUBMIT '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.

92 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 DAILY
INVOKE '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.

ESP-5.4-UG-05 93
 Section–Specifying the function of an Event

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 6PM
PROC
APPL WITHPROC
JCLLIB PROD.JCL
JOB A
RUN DAILY
RELEASE JOB B
ENDJOB
JOB B
RUN DAILY
ENDJOB
ENDPROC
ENDDEF

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.

94 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 WORKDAYS
INVOKE 'EMP.ESP.PROC(WKJOBS)'
COPYJCL 'CYBER.JCL.COPY' GEN(0) JOBNAME
ENDDEF

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.

ESP-5.4-UG-05 95
 Section–Specifying other requirements

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 DAILY
VS '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 DATES
INVOKE '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.

96 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 FISCAL
SCHEDULE 2ND DAY OF FISCAL_MONTH
SUBMIT '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.

ESP-5.4-UG-05 97
 Section–Displaying the schedule

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 DATES
INVOKE '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 JOBX
SUBMIT '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.

98 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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 DAILY
DSTRIG MY.DATA.SET ANYCLOSE
ENDDEF

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.LWD
SCHED AT 19.00.00 ON SATURDAY JANUARY 31ST, 2000

ESP-5.4-UG-05 99
 Section–Working with defined Events

SCHED AT 19.00.00 ON SATURDAY FEBRUARY 28TH, 2000

SCHED AT 19.00.00 ON TUESDAY MARCH 31ST, 2000
SCHED AT 19.00.00 ON THURSDAY APRIL 30TH, 2000
SCHED 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:

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.

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.

100 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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.

ESP-5.4-UG-05 101
 Section–Working with defined Events

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.

102 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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

ESP-5.4-UG-05 103
 Section–Working with defined Events

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

104 ESP-5.4-UG-05
 Chapter 4–Processing ESP Events

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

ESP-5.4-UG-05 105
 Section–Working with defined Events

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.

106 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 107
 Section–Overview of ESP Procedures

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

108 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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.

ESP-5.4-UG-05 109
 Section–Using ESP Workload Manager control language in Procedures

Syntax Rules Explanation

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.

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

110 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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
statement
ENDDO

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

ESP-5.4-UG-05 111
 Section–Using ESP Workload Manager control language in Procedures

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: Afteryou 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

112 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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 QUIT
IF TODAY('HOLIDAY') THEN DO
SEND 'NO WORK TODAY' U(BOSS)
EXIT
ENDDO
SEND '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.

ESP-5.4-UG-05 113
 Section–Using expressions and strings in Procedures

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: Yourinstallation 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 NUMBER
NUMBER=52
NAME='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 NUMOFRUN
VGET 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.

114 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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
** Power
Prefix - 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

ESP-5.4-UG-05 115
 Section–Using expressions and strings in Procedures

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)
AND
OR
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: Ifthe 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.

116 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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:

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.

Summary by function
The following table summarizes the functions by category:

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.

ESP-5.4-UG-05 117
 Section–Using calendaring functions

Category Function Description

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.

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.

118 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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 X
X=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')

ESP-5.4-UG-05 119
 Section–Using calendaring functions

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 = true
0 = 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 = true
0 = false

120 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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 = true
0 = 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.

ESP-5.4-UG-05 121
 Section–Using functions for job selection

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 MONTH
ENDJOB
JOB Z
IF NOT SELECTED('X') THEN RUN TODAY
ENDJOB
The above results are valid only at Application generation time and not at Application
process time.

122 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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 = true
0 = 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 SIZE
LETTER='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)

ESP-5.4-UG-05 123
 Section–Using system activity functions

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 = true
0 = 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)

124 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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.

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.

Returning values
The following list contains all the acceptable search criteria codes:

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.

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.

ESP-5.4-UG-05 125
 Section–Using system activity functions

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 JOBCOUNT
JOBCOUNT = 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:

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.

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.

126 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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:

Option Explanation
C Cartridge drives.
R Reel-to-reel drives.
T Total drives.

You can choose one of the following as the second operand:

Option Explanation
A Available.
O Online.
D Defined.

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 TAPEJOB1
IF 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.

ESP-5.4-UG-05 127
 Section–Re-executing an ESP Procedure

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

128 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

Example: Waiting for a job

This ESP Procedure checks to see if a job called RMTJOB is on the input queue.
INTEGER COUNT
COUNT=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.

ESP-5.4-UG-05 129
 Section–Using templates

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)
ENDTEMPL
XMAS 2001
XMAS 2002
XMAS 2003
XMAS 2004
XMAS 2005
XMAS 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 PAYROLL
JCLLIB 'CYB.JOBS.CNTL'
JOB USERA
SUBAPPL PRTJOBS
RUN DAILY
ENDJOB
JOB USERB
SUBAPPL PRTJOBS
RUN DAILY
ENDJOB
JOB USERC
SUBAPPL PRTJOBS
RUN DAILY
ENDJOB
JOB USERD
SUBAPPL PRTJOBS

130 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

RUN DAILY
ENDJOB
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 PAYROLL
JCLLIB 'CYB.JOBS.CNTL'
TEMPLATE PRTJOBS (1,NAME)
JOB %NAME
SUBAPPL PRTJOBS
RUN DAILY
ENDJOB
ENDTEMPL
PRTJOBS USERA
PRTJOBS USERB
PRTJOBS USERC
PRTJOBS 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).

ESP-5.4-UG-05 131
 Section–CLANG examples

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 TODAY
ENDJOB

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)'
ENDDO
ELSE DO
SEND 'TODAY IS A WEEKEND' U(*)
SUBMIT 'CYB.ESP.JCL(JOB2)'
ENDDO

132 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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 STOP
ELSE JUMPTO GO
STOP:
VS 'F CICS SHUTDOWN'
REEXEC IN(5)
EXIT
GO:
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,Z
X=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.

ESP-5.4-UG-05 133
 Section–CLANG examples

The ESP Procedure looks like this:

INTEGER X,Y
X=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:ESPPROC
IF 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

134 ESP-5.4-UG-05
 Chapter 5–Working with ESP Procedures

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.

ESP-5.4-UG-05 135
 Section–Caching an ESP Workload Manager Procedure

136 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 137
 Section–Introducing Applications

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

138 ESP-5.4-UG-05
 Chapter 6–Using Applications

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

ESP-5.4-UG-05 139
 Section–Introducing Applications

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

140 ESP-5.4-UG-05
 Chapter 6–Using Applications

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:

B C Daily

E Friday

F Last workday
of month

Application definition
The corresponding Application definition looks like this:
APPL PAYROLL
JCLLIB 'CYBER.ESP.JCL'
JOB A
RUN DAILY
RELEASE (B,C)
ENDJOB
JOB B
RUN DAILY
RELEASE D
ENDJOB
JOB C
RUN DAILY
RELEASE D
ENDJOB
JOB D
RUN DAILY
RELEASE E
ENDJOB
JOB E
RUN FRIDAY
RELEASE F
ENDJOB
JOB F
RUN LAST WORKDAY OF MONTH
ENDJOB
The following sections discuss how to define an Application.

ESP-5.4-UG-05 141
 Section–Identifying the Application

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 APPL PAYROLL WAIT
Application must wait until its
previous generation is complete.
WAIT operand on the SUBAPPL Specifies that the subApplication SUBAPPL PAYREQ WAIT
statement must wait until the same
subApplication in the previous
generation is complete.
JOB_ANCESTOR_WAIT(ANY) Indicates that a job is not eligible APPL PAYROLL +
operand on the APPL statement for submission if the same job in JOB_ANCESTOR_WAIT(ANY)
any previous generation of the
Application has not completed
successfully.
JOB_ANCESTOR_WAIT(LAST) Indicates that a job is not eligible APPL PAYROLL -
operand on the APPL statement for submission if the same job in the JOB_ANCESTOR_WAIT(LAST)
previous generation of the
Application has not completed
successfully. ESP Workload
Manager only looks at the -1
generation.
None of the above operands Specifies that the Applications can APPL PAYROLL
process at the same time.

142 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 BILLJOBS
JCLLIB '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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
JOB PAYJOB1
RUN WORKDAYS
ENDJOB
JOB PAYJOB2
RUN WORKDAYS
ENDJOB
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”.

ESP-5.4-UG-05 143
 Section–Identifying JCL libraries

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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
TEMPLIB 'PROD.OVERRIDE.JCL'
JOB PAYJOB1
RUN WORKDAYS
ENDJOB
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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
JOB PAYJOB1
RUN WORKDAYS
ENDJOB
TEMPLIB 'PROD.OVERRIDE.JCL'
JOB PAYJOB2
RUN WORKDAYS
ENDJOB
JOB PAYJOB3
RUN WORKDAYS
ENDJOB
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.

144 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
JOB PAYJOB1
MEMBER PJOB
JOB PAYJOB2
MEMBER PJOB
ENDJOB
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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
TEMPLIB 'PROD.OVERRIDE.JCL' JOBNAME
JOB PAYJOB1
MEMBER PJOB
JOB PAYJOB2
MEMBER PJOB
ENDJOB
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.

ESP-5.4-UG-05 145
 Section–Identifying JCL libraries

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 PAYROLL
JCLLIB 'PROD.JCL.CNTL'
JOB PAYJOB1
RUN DAILY
RELEASE PAYJOB2
ENDJOB
JOB PAYJOB2
DATASET 'PROD.OVERRIDE.JCL'
RUN DAILY
RELEASE PAYJOB3
ENDJOB
JOB PAYJOB3
RUN DAILY
ENDJOB
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 PAYJOB3
ENDJOB

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.

146 ESP-5.4-UG-05
 Chapter 6–Using Applications

• 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

ESP-5.4-UG-05 147
 Section–Identifying JCL libraries

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 MISC
COPYJCL 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.

148 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 PATJOB2
ENDJOB

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.

ESP-5.4-UG-05 149
 Section–Identifying jobs

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.RUN1
JOB STILL.RUNNING
JOB BACKUP.SYSRES
JOB 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 TESTQUAL
JCLLIB 'CYB.TESTJOBS.CNTL'
JOB A.THIS
RUN ANY
RELEASE A.THAT
ENDJOB
JOB A.THAT
RUN ANY
ENDJOB

Combined statement
The following procedure segment:
JOB A
DUEOUT EXEC 23:59
RUN WEEKDAYS

150 ESP-5.4-UG-05
 Chapter 6–Using Applications

NOTIFY OVERDUE ALERT(TRDY)

RELEASE B
ENDJOB
... (other job definitions)
JOB A
DUEOUT EXEC 13:00
RUN SUN
RELEASE C
ENDJOB
is equivalent to:
JOB A
DUEOUT EXEC 13:00
RUN WEEKDAYS AND SUN
NOTIFY OVERDUE ALERT(TRDY)
RELEASE B
RELEASE C
ENDJOB
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.

ESP-5.4-UG-05 151
 Section–Identifying jobs

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.

J1 Daily

J2 REQUEST

J3 Daily

The Application looks like this:

APPL APPL1
JCLLIB...
JOB J1
RUN DAILY
RELEASE J2
ENDJOB
JOB J2 REQUEST
RELEASE J3
RUN DAILY
ENDJOB
JOB J3
RUN DAILY
ENDJOB

152 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 153
 Section–Identifying jobs

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 ABC
JCLLIB . . .
SEND 'MESSAGE1' U(*)
JOB A
SEND 'MESSAGE2' U(*)
RUN DAILY
RELEASE B
ENDJOB
JOB B
SEND 'MESSAGE3' U(*)

154 ESP-5.4-UG-05
 Chapter 6–Using Applications

RUN DAILY
ENDJOB

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:

Dependency

Timing Selection

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.

ESP-5.4-UG-05 155
 Section–Specifying time dependencies

Example: Identifying a delayed submission time

This example specifies that job J2 should not be submitted prior to 9 pm:
JOB J2
DELAYSUB 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 5PM
ENDJOB

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 5
ENDJOB

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

156 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 157
 Section–Specifying time dependencies

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.

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

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 DAILY
ENDJOB

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 DAILY
ENDJOB

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 DAILY
ENDJOB

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

158 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

PAYJOB1

PAYJOB2

PAYJOB3 PAYJOB4 PAYJOB5

PAYJOB6

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 PAYROLL
JCLLIB 'CYBER.JCL.CNTL'
JOB PAYJOB1
RELEASE PAYJOB2
ENDJOB
JOB PAYJOB2
RELEASE (PAYJOB3,PAYJOB4,PAYJOB5)
ENDJOB
JOB PAYJOB3
RELEASE PAYJOB6
ENDJOB
JOB PAYJOB4
RELEASE PAYJOB6
ENDJOB
JOB PAYJOB5
RELEASE PAYJOB6
ENDJOB

ESP-5.4-UG-05 159
 Section–Specifying time dependencies

JOB PAYJOB6
LATESUB 7AM
ENDJOB
SELECT (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 APPL3
JCLLIB...
JOB J1
RUN DAILY
RELEASE J2
ENDJOB
JOB J2
RUN DAILY
ABANDON DEPENDENCIES 10PM
RELEASE J3
ENDJOB
JOB J3
RUN DAILY
ABANDON SUBMISSION 11PM
RELEASE J4
ENDJOB
JOB J4
RUN DAILY
ENDJOB

160 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 B
ENDJOB
JOB B
RUN DAILY
RELEASE C
DELAYSUB 9AM
ABANDON SUBMISSION 10AM
ENDJOB
JOB C
RUN DAILY
ENDJOB

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 B
ENDJOB
JOB B
RUN DAILY
RELEASE C
DELAYSUB 9AM
ABANDON SUBMISSION 10AM
ABANDON DEPENDENCIES 10:01AM
ENDJOB
JOB C
RUN DAILY
ENDJOB

ESP-5.4-UG-05 161
 Section–Specifying time dependencies

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

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

162 ESP-5.4-UG-05
 Chapter 6–Using Applications

global notification
APPL PAYROLL
JCLLIB 'CYBER.JCL.CNTL'

IF %ESP_APPL_PROC THEN DO
MINRUNTIME = AVGRUNTIME * 25 / 100
MAXRUNTIME = AVGRUNTIME * 175 / 100
ENDDO

NOTIFY OVERDUE USER(CYBER02)

NOTIFY PREMEND USER(CYBER02)

JOB PAY1
RUN NOW
ENDJOB

JOB PAY2
RUN NOW
ENDJOB
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 1
COMMAND ===> 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 JAN
2004, APPL TSTRFES.47

TT54_1022W JOB WAIT3#5S IN APPL TSTRFES.47, LATE END TIME EXCEEDED

***

ESP-5.4-UG-05 163
 Section–Specifying time dependencies

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:
REPORT
INPUT DATASET('CYB1.TONYT540.HISTFILE')
CRITERIA JOBNAME EQ WAIT- OR JOBNAME EQ CALC
FROM DEC 1 2003
DISPLAY JOBNAME,JOBNO,APPLSYS,MINRUNT,MAXRUNT,AVGRUNT,
EXECQT,OVDEND,EXECSDATE 12,EXECST 10
SORT EXECSDATE EXECST JOBNAME EXECQT
ENDR
CYBERMATION 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 START
WAIT3 42148 - - - 3M01 - THU 4DEC03 14.41.38
WAIT5 42299 - - - 4M59 - THU 4DEC03 17.16.56
WAIT5 42305 - - - 5M00 - THU 4DEC03 17.26.23
WAIT5 42326 - - - 4M59 - THU 4DEC03 17.33.01
WAIT5 42370 - - - 5M01 - THU 4DEC03 17.35.18
WAIT5 54085 TSTRFES 7M00 12M00 5M00 5M09 0 TUE 9DEC03 08.17.13
WAIT3#5S 54086 TSTRFES 7M00 12M00 16M00 16M10 4M12 TUE 9DEC03 08.17.23
WAIT5 54541 TSTRFES 7M00 12M00 5M00 5M01 0 TUE 9DEC03 08.45.55
WAIT3#5S 54542 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 08.45.56
WAIT5 54615 TSTRFES 7M00 12M00 5M00 5M00 0 TUE 9DEC03 09.21.50
WAIT3#5S 54616 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 09.21.51
WAIT3 55327 - - - 3M00 - TUE 9DEC03 15.04.20
WAIT3#5S 55329 - - - 16M01 - TUE 9DEC03 15.04.28

164 ESP-5.4-UG-05
 Chapter 6–Using Applications

Specifying job relationships

To specify predecessor and successor job relationships:
Include the appropriate job-dependency statements.
A list of job-dependency statements appears below:

Job-Dependency Explanation
Statement
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.

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)

ESP-5.4-UG-05 165
 Section–Using Implicit Resources

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.

Method Code
1 JOB A
RELEASE B
2 JOB B
AFTER A

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.

166 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 NWN00A
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
ENQUEUE NAME(FRED) SHARED
ENDJOB

JOB NWN002
RUN DAILY
ENDJOB
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 NWN00A
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
ENQUEUE NAME(FRED) SHARED
ENDJOB

JOB NWN002
RUN DAILY
ENQUEUE NAME(FRED) EXCLUSIVE
ENDJOB

ESP-5.4-UG-05 167
 Section–Using Implicit Resources

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 NWN00A
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
ENQUEUE NAME(FRED) SHARED
ENDJOB

JOB NWN002
RUN DAILY
ENQUEUE NAME(FRED) EXCLUSIVE
ENDJOB

JOB NWN003
RUN DAILY
ENQUEUE NAME(FRED) SHARED
ENDJOB

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 NWN00B
JCLLIB 'CYBER.JCL.CNTL'
ENQUEUE NAME(FRED) SHARED
JOB NWN001
RUN DAILY
ENDJOB

JOB NWN002

168 ESP-5.4-UG-05
 Chapter 6–Using Applications

RUN DAILY
DEQUEUE NAME(FRED)
ENDJOB

JOB NWN003
RUN DAILY
ENDJOB

JOB NWN004
RUN DAILY
ENDJOB

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 NWN00G
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
ENQUEUE NAME(B-C) SHARED
ENDJOB

JOB NWN002
RUN DAILY
ENQUEUE NAME(BBC) EXCLUSIVE
ENDJOB
The ENQUEUE B- command produces the following:
BBC

(Gen) Held Shr NWN001, Appl NWN00G.1

Required Excl NWN002, Appl NWN00G.1

ESP-5.4-UG-05 169
 Section–Using Implicit Resources

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 NWN00G
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
ENQUEUE NAME(B-C) SHARED
ENDJOB

JOB NWN002
RUN DAILY
ENQUEUE NAME(BBC) EXCLUSIVE
ENDJOB
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

170 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 ALWAYS
ESP1573I 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.

ESP-5.4-UG-05 171
 Section–Using Implicit Resources

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 TEST
JOB MYJOB
NOTWITH BILLSJOB.-;
RUN DAILY
ENDJOB
The above Application results in the JOB MYJOB having the two following
enqueues:
ESPENQ_JOB(MYJOB.)_APPL(TEST.21)Exclusive
ESPENQ_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.

172 ESP-5.4-UG-05
 Chapter 6–Using Applications

Examples of ESP ENQUEUES with NOTWITH

APPL NWN00C
JCLLIB 'CYBER.JCL.CNTL'
JOB NWN001
RUN WEEKDAYS
NOTWITH NWN003
ENDJOB
JOB NWN002
RUN WEEKDAYS
ENDJOB
JOB NWN003
RUN WEEKDAYS
NOTWITH NWN001
ENDJOB
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.1
ESPENQ_JOB(NWN001.)_APPL(NWN00C.1)
Held Excl NWN001, Appl NWN00C.1
(Gen) Required Shr NWN003, Appl NWN00C.1
ESPENQ_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 NWN00D
JCLLIB 'CYBER.JCL.CNTL'
JOB NWN001
RUN WEEKDAYS
NOTWITH NWN003
ENDJOB
JOB NWN002
RUN WEEKDAYS
ENDJOB
JOB NWN003
RUN WEEKDAYS
ENDJOB
You can use unmatched NOTWITH statements in combination with the ENQSELF
command. For more information, see “ENQSELF” on page 171.

ESP-5.4-UG-05 173
 Section–Using Implicit Resources

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 NWN00E
JCLLIB 'CYBER.JCL.CNTL'

JOB NWN001
RUN DAILY
NOTWITH (NWN002,NWN003)
ENDJOB

NOTWITH NWN001

JOB NWN002
RUN DAILY
ENDJOB

JOB NWN003
RUN DAILY
ENDJOB

JOB NWN004
RUN DAILY
DROPNOTW NWN001
ENDJOB

174 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 B
ENDJOB
JOB B
RUN FRIDAY
ENDJOB

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 B
ENDJOB
JOB B
ENDJOB
SELECT A
IF 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.

ESP-5.4-UG-05 175
 Section–Selecting jobs for submission

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 MONTH
ENDJOB

Example 2
This example uses a DESELECT statement to achieve the same results.
SELECT X
IF 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.

176 ESP-5.4-UG-05
 Chapter 6–Using Applications

Example
Consider the following three jobs and their schedule frequencies.

J1 Daily

J2 Friday

J3 Daily

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.

Type Description Identification

Job JCL submitted by ESP Workload Manager Blank
(default).
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 LINK operand
completion.

ESP-5.4-UG-05 177
 Section–Defining external jobs

Type Description Identification

Task Task that requires manual completion. TASK operand
Data-set trigger Object that completes based on data set DSTRIG statement
object trigger activity.
APPLEND Self completing task that runs automatically APPLEND statement
at the end of an Application.

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.

178 ESP-5.4-UG-05
 Chapter 6–Using Applications

Visually, the dependencies look like this:

APPL1 APPL2

A X
(job) (External job)

X Z
(job) (job)

The Application definition for APPL1 looks like this:

APPL APPL1
JCLLIB....
JOB A
RUN DAILY
RELEASE X
ENDJOB
JOB X
RUN FRIDAY
ENDJOB
The Application definition for APPL2 looks like this:
APPL APPL2
JCLLIB....
JOB X EXTERNAL
RUN FRIDAY
RELEASE Z
ENDJOB
JOB Z
RUN DAILY
ENDJOB
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.

ESP-5.4-UG-05 179
 Section–Defining external jobs

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 sunday
ENDJOB

180 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 181
 Section–Defining manual jobs

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 SMALL
JOB ZZ
AFTER YY
RUN DAILY
ENDJOB
JOB YY MANUAL
RUN MON WED FRI
ENDJOB

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.

182 ESP-5.4-UG-05
 Chapter 6–Using Applications

Visually, the flow of jobs looks like this:

MANUALLY
B SUBMITTED

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 ABC
JOB A
RELEASE B
RUN DAILY
ENDJOB
JOB B MANUAL PROCESS
SEND 'TIME TO SUBMIT JOB B' USER(SW)
RUN DAILY
RELEASE C
ENDJOB
JOB C
RUN DAILY
ENDJOB

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.

ESP-5.4-UG-05 183
 Section–Using links

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.

184 ESP-5.4-UG-05
 Chapter 6–Using Applications

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:

A B C

D E F

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.

ESP-5.4-UG-05 185
 Section–Using links

Visually, the dependencies look like this:

A B C

LINKJOB

D E F

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 DAILY
ENDJOB

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 DAILY
ENDJOB

186 ESP-5.4-UG-05
 Chapter 6–Using Applications

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:

START.STC1
(Link)

STC1
(Manual)

BATCHJOB
(Job)

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.

ESP-5.4-UG-05 187
 Section–Using tasks

Application
The Application looks like this:
APPL MYAPPL
JCLLIB 'SYS1.JCL'
JOB START.STC1 LINK PROCESS
RUN DAILY
VS 'S STC1'
ENDJOB
JOB STC1 MANUAL
RUN DAILY
RELEASE BATCHJOB
ENDJOB
JOB BATCHJOB
RUN DAILY
ENDJOB

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.

188 ESP-5.4-UG-05
 Chapter 6–Using Applications

Visually, the dependencies look like this:

J1
(Job)

CHECKRPT.J
(Task)

J2
(Job)

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 WAIT
JOB J1
RUN DAILY
RELEASE CHECKRPT.J1
ENDJOB
JOB CHECKRPT.J1 TASK
RUN WORKDAYS
SEND 'JOB J1 HAS COMPLETED SUCCESSFULLY ' USER(BP01)
SEND 'COMPLETE THE CHECKRPT.J1 TASK' USER(BP01)
RELEASE J2
ENDJOB
JOB J2
RUN DAILY
ENDJOB

Uses for tasks

You can choose to use tasks for:
• Balancing reports
• Input tapes
• Step-level dependencies
• Any other special handling jobs

ESP-5.4-UG-05 189
 Section–Using APPLEND workload object

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.

190 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 TESTAE1
JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 LINK

RUN DAILY
REL JOB2
ENDJOB

JOB JOB2 LINK

RUN DAILY
ENDJOB

APPLEND FRED
REL (AFTERAE1,AFTERAE2)
SE 'APPLEND RUNNING' U(*)
ENDJOB

JOB AFTERAE1 LINK

RUN DAILY
REL AFTRAELA
ENDJOB

JOB AFTERAE2 LINK

RUN DAILY
ENDJOB

JOB AFTRAELA TASK

RUN DAILY
ENDJOB

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.

ESP-5.4-UG-05 191
 Section–Changing job attributes

To generate SMF, a S/390 job will need to be run as a successor to the APPLEND
object. For example:
APPL EXAMPLE
JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1
RUN DAILY
ENDJOB

APPLEND TERMIN8
POSTREQ TERMIN8R
ENDJOB

JOB TERMIN8R
MEMBER IEFBR14
ENDJOB

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

192 ESP-5.4-UG-05
 Chapter 6–Using Applications

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,

ESP-5.4-UG-05 193
 Section–Using data-set-trigger workload objects

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 ABCJOB
ENDJOB
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:

PROD.CICS.FILE1602 ABCJOB
(data set) (Job)

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.

194 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 PAYROLL
JCLLIB 'CYB.JCL.CNTL'
DSTRIG WAIT4.DS
DSNAME PROD.WEEKLY.ACCNTS ANYCLOSE
RUN DAILY
RELEASE PAYJOB1
ENDJOB
JOB PAYJOB1
RUN DAILY
ENDJOB

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(ABC
ENDJOB

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.

ESP-5.4-UG-05 195
 Section–Using data-set-trigger workload objects

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 PAYROLL
JCLLIB 'CYB.JCL.CNTL'
DSTRIG FILEA
DSNAME CYBER.DATA111.CNTL ANYCLOSE
RUN DAILY
RELEASE XYZ
ENDJOB
DSTRIG FILEB
DSNAME CYBER.DATA999.CNTL ANYCLOSE
RUN DAILY
RELEASE XYZ
ENDJOB
JOB XYZ
RUN DAILY
ENDJOB

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

196 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 BILLJOB1
ENDJOB

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.
LDXE
EVENT/APPL (WOB)-------DATASET
PAYROLL.1 (WAIT4.DS) CYBER.PAYROLL.DATA1, ANYCLOSE
CYBER.CYCLES USER.INPUT.CYCLE
2 ENTRIES DISPLAYED

ESP-5.4-UG-05 197
 Section–Using FTP data-set-trigger workload objects

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.

198 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 199
 Section–Using FTP data-set-trigger workload objects

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

200 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 201
 Section–Using explicit-data-set-trigger workload objects

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 Specifies the data-set name.
DATASET(dsname)
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 generation
You 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 Specifies the volume serial number that the data set resides on.
VOLUME(volser) It is required for uncataloged data sets and optional for
cataloged data sets.
SUBSYSTEM(subsystem) or Is the ESP Workload Manager subsystem identifier keyword.
SSID(subsystem) 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.

202 ESP-5.4-UG-05
 Chapter 6–Using Applications

Parameter Description
NOVERIFY Specifies that CYBESDT1 will set the explicit data-set trigger
whether or not the criteria described for the VERIFY
parameter are met.

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

ESP-5.4-UG-05 203
 Section–Using explicit-data-set-trigger workload objects

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) EXPLICIT
ENDDEF
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=NODE1
STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET -
TO(SNODE DSN=NEW.DATA.SET -
DISP=(NEW,CATLG,DELETE))
IF (STEP1 EQ 0) THEN
STEP2 RUN TASK (PGM=CYBESDT1 -
PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) -
SNODE
EIF

204 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 205
 Section–Providing notification on Job status

Sample Application
A sample Application looks like this:
APPL PAYROLL
JCLLIB . . .
TAG 'PAYROLL'
JOB A
RUN DAILY
RELEASE B
ENDJOB
JOB B
RUN DAILY
RELEASE C
ENDJOB
JOB C
RUN DAILY
AFTER X
ENDJOB
JOB X EXTERNAL
TAG 'BILLING'
RUN DAILY
ENDJOB

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.

206 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 DAILY
ENDJOB

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 DAILY
ENDJOB

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.

ESP-5.4-UG-05 207
 Section–Using critical-path analysis

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.

A 15 Mins

B 15 Mins

10 Mins E X 60 Mins C 30 Mins

20 Mins F Y 30 Mins D 15 Mins

10 Mins Z CRITICAL

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

208 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 BILLING
JCLLIB 'CYBER.JCL'
CRITPATH ON
JOB 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.

ESP-5.4-UG-05 209
 Section–Using critical-path analysis

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

B C D E F

G H I

K L M

N O P Q

R S T

U V

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 120
ENDJOB

210 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 211
 Section–Using subApplications

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 ADD
ENDJOB

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_EVENT
ENDJOB

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.

212 ESP-5.4-UG-05
 Chapter 6–Using Applications

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 ACJOBS
SUBAPPL PREPJOBS
JOB CYB1
RELEASE CYB3
ENDJOB
JOB CYB2
RELEASE CYB3
ENDJOB
SUBAPPL NIGHTLY WAIT
JOB CYB3
RELEASE CYB4
ENDJOB
JOB CYB4
ENDJOB
SELECT (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.

ESP-5.4-UG-05 213
 Section–Using subApplications

In the following example, subApplications PREPJOBS and NIGHTLY are selected.

APPL ACJOBS
SUBAPPL PREPJOBS
JOB CYB1
RELEASE CYB3
ENDJOB
JOB CYB2
RELEASE CYB3
ENDJOB
SUBAPPL NIGHTLY WAIT
JOB CYB3
RELEASE CYB4
ENDJOB
JOB CYB4
ENDJOB
SELECT (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)

214 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 215
 Section–Controlling an Application

Sample output
Sample output from an LAP command looks like this:
LAP PAYROLL.23 ALL
APPL 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.

216 ESP-5.4-UG-05
 Chapter 6–Using Applications

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.

ESP-5.4-UG-05 217
 Section–Changing an Application definition

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

218 ESP-5.4-UG-05
 Chapter 6–Using Applications

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

ESP-5.4-UG-05 219
 Section–Invoking an ESP Application

220 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 221
 Section–Setting up CSF views

• 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:

222 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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:

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.

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.

ESP-5.4-UG-05 223
 Section–CSF fields

SUBDELAY Pnode
The following table provides more information on what you see in the Status field if a
job is in the SUBDELAY Pnode.

Pnode Status Description

SUBDELAY Submit delayed by REEXEC The submission of the job has been
n delayed.
SUBDELAY Submit delayed, eventset The eventset in which the Event is stored
closed is currently closed. As soon as it is opened,
the Event will be scheduled.
SUBDELAY Submit delayed, DS The execution of the Event was delayed
contention 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.

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

SUBERROR 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 The ESP Workload Manager Group
defined definition for the Event has been
deleted. It will need to be redefined.
SUBERROR Submit error, applfile not The APPLFILE in which the APPL
found 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.

224 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Pnode Status Description

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

Status fields
You can display the following status fields on CSF:

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.

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 STATUS
TAPEJOB BYPASSED NO INPUT TODAY
ESP Workload Manager does not reset the User Status field.

ESP-5.4-UG-05 225
 Section–Defining a view

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.

226 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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:

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.

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.

ESP-5.4-UG-05 227
 Section–Customizing a view

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.

ESP Consolidated Status: Filter Specification for View,REP

COMMAND ===>

Enter conditions in this section (N, blank or Y).

Column 1 Column 2 Column 3
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)

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.

228 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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 2A
Application 2
Completion Code 3

ESP-5.4-UG-05 229
 Section–Customizing a view

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: Ifa 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.

230 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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.

ESP-5.4-UG-05 231
 Section–Deleting a view

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.

232 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Working with Applications

The following table lists the available commands for working with Applications.

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.

Working with subApplications

The following table lists the available commands for working with subApplications.

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.

Working with jobs

The following table lists the available commands for working with jobs.

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.

ESP-5.4-UG-05 233
 Section–Commands

Command Description
$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).

234 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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

Working with other ESP Workload Manager definitions

The following table lists the available commands for working with other ESP
Workload Manager definitions.

Command Description
BD Browses job documentation.
BE Browses Event.
BP Browses ESP Procedure.
ED Edits job documentation.
EE Edits Event.
EP Edits ESP Procedure.

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.

ESP-5.4-UG-05 235
 Section–Inserting a job

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 PAYD008A
ENDJOB
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.

236 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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.

ESP-5.4-UG-05 237
 Section–Rerunning multiple jobs

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.

238 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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

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-5.4-UG-05 239
 Section–Resetting a time dependency

You can enter a D in front of any predecessor that is not yet completed, to drop a
dependency.
JOB PAYD008A

PREDECESSORS
D 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.
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

Example
Suppose a job has an early submission time of 5 pm.

240 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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.

Overdue for... Field description CSF screen heading

(Presentation or Sort
screen)
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

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.

ESP-5.4-UG-05 241
 Section–Bypassing and completing jobs

Sample CSF display of an overdue job

ESP4 Consolidated Status: View 1 ------------ Row 1 of 8, Col 1
COMMAND ===> 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(COMPL
ETE) 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) UpdatedO
n(08.59.03 THU 13 MAY 2004) ReaderTime(200405130854) StartTime(08.54.02 THU 13
MAY 2004) EndTime(08.59.05 THU 13 MAY 2004) Cmpc(CC 0) OrigJno(19974) ExecJno(1
9974) Jes(2) Class(A) Priority(7) ASID(0022) SID(SYSA) SrvClass(JES) Sysname(SY
SA) 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.02
THU 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.

242 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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.

ESP-5.4-UG-05 243
 Section–Adding a LINK process

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:

A B

LINKME

Adding a LINK process

Note: If the Application containsan 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

244 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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 STATUS
TAPEJOB 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

ESP-5.4-UG-05 245
 Section–Modifying a Job Resources or Enqueues

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

246 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Using other commands

You can also enter the following commands on the COMMAND line of the
Consolidated Status View panel:

Command Invokes ESP Workload Manager in ...

ESP Line mode.
ESPPM Page mode.

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

ESP-5.4-UG-05 247
 Section–Freeform filtering

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

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.

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

248 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

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.

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:

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

ESP-5.4-UG-05 249
 Section–Freeform filtering

Examples of freeform filter

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 Workload objects in the PAYROLL
RESTART_STEP_PRESENT Application that have a restart step.
JOBNAME(1,1) EQ 'P' AND JSBYTE Failed workload objects that start with P.
EQ 'F'
CMPC EQ 'S222' AND SUBAPPL EQ Workload objects with a completion code
'PAYJOBS' of S222 in the PAYJOBS subApplication.
(JOBNAME(1,3) EQ 'PAY' OR Workload Objects that start with PAY or
JOBNAME(1,3) EQ 'ACC')AND APPL ACC and belong to an Application called
EQ 'FINANCE' FINANCE.
JOBNAME(1,4) EQ 'TEST' AND Workload Objects in Application
APPL EQ 'TESTAPPL' AND TESTAPPL that start with TEST and are
INCOMPLETE not complete.
APPL EQ 'CYBER' AND Workload Objects in Application CYBER
OVERDUE_START AND REQUEST whose execution start time is overdue and
that are requestable.
JOBNAME(1,3) EQ 'CYB' AND Workload Objects whose names start with
STIME> TIME(11AM TODAY) CYB that started later than 11 am today.
WOBTYPE EQ 'HP' AND APPL EQ All HP workload objects in the BILLING
'BILLING' Application.
JOBNAME(1,1) EQ 'X' AND APPL EQ Workload Objects that start with X in
'MYAPPL' AND NOT_REQUESTED Application MYAPPL that have not been
requested.
(JOBNAME EQ 'TESTJOB' OR Workload Objects called TESTJOB or
JOBNAME(1,1) EQ 'A' OR whose names start with the characters A or
JOBNAME(1,2) EQ 'BC') AND BC and are contained within Application
(APPL EQ 'MYAPPL' OR APPL (1,2) MYAPPL or any Application whose name
EQ 'PA') AND OVERDUE_START 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.

Keywords:

Keyword Description
ACCOUNT Account number
AGENT Agent name
APPL Application name

250 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Keyword Description
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 follow
Value 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

ESP-5.4-UG-05 251
 Section–Freeform filtering

Keyword Description
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

252 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Keyword Description
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

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:

>= GE greater than or equal

<= LE less than or equal
> GT greater than
< LT less than
= EQ equal
¬= NE not equal to

ESP-5.4-UG-05 253
 Section–Freeform filtering

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.

254 ESP-5.4-UG-05
 Chapter 7–Consolidated Status Facility (CSF)

Condition Description
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.

Note: Common conditions are available on the Filter Specifications screen and may
not require a freeform filter.

ESP-5.4-UG-05 255
 Section–Freeform filtering

256 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 257
 Section–Contents of job documentation

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

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.

258 ESP-5.4-UG-05
 Chapter 8–Job Documentation

Example control information

Control information is specified as shown below:
PAYJOB: JOBDOC
DATASET PROD.JCL.CNTL
RELEASE (PAYJOB2,PAYJOB3)
CCFAIL (STEP,GT,4)
RUN WORKDAYS
IF MONDAY('MONDAY') THEN DELAYSUB 7PM
ELSE 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 Use this Label to…
Manager Label
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.

ESP-5.4-UG-05 259
 Section–Creating job documentation

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 (:).
USERDESC
FUNCTION:
sort and merge payroll files
PROGRAMMER:
joan smith
ABENDS:
#SB37 -
space problem - double space requirements and restart
job from failing step
MESSAGES:
#AC101 -
number of available accounts <50 – warning
#Z001 -
user not authorized
SEVERITY: 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.

260 ESP-5.4-UG-05
 Chapter 8–Job Documentation

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.

ESP-5.4-UG-05 261
 Section–Updating job documentation

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: JOBDOC
DATASET PROD.JCL.CNTL
RELEASE (PAYJOB2,PAYJOB3)
CCFAIL (STEP1 GT 4)
USERDESC
FUNCTION:
sort and merge payroll files
PROGRAMMER:
joan smith
ABENDS:
#SB37 -
space problem - double space requirements and restart
job from failing step
MESSAGES:
#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.

262 ESP-5.4-UG-05
 Chapter 8–Job Documentation

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: JOBDOC
DATASET PROD.JCL.CNTL
RELEASE (PAYJOB2,PAYJOB3)
CCFAIL (STEP1 GT 4)
RUN WORKDAYS
IF TODAY('MONDAY') THEN DELAYSUB 7PM
ELSE DELAYSUB 6PM
USERDESC
FUNCTION:
sort and merge payroll files
PROGRAMMER:
joan smith
ABENDS:
#SB37 -
space problem - double space requirements and restart
job from failing step
MESSAGES:
#AC101 -
number of available accounts <50 - warning
#Z001 -
user not authorized
SEVERITY: 3

Using job documentation

You can use job documentation in the following ways:
• To control processing using the control information directly
• To retrieve information

ESP-5.4-UG-05 263
 Section–Using the control information

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 PAYJOBS
JCLLIB 'CYB.JCL.CNTL'
DOCLIB 'CYBER.JOBS.DOC'
JOB PAYJOB1
ENDJOB
JOB PAYJOB2
ENDJOB
JOB PAYJOB3
ENDJOB
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.

Job Documentation
Library

A: JOBDOC
RUN DAILY
ESP Procedure RELEASE B
Event

DOCLIB . . .
INVOKE . . . JOB A

264 ESP-5.4-UG-05
 Chapter 8–Job Documentation

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:
Type of information …overrides corresponding
ESP Procedure information… … job documentation information.
Job documentation information… …tracking model information.

Example
For example, if you specify a HISTFILE as below, it overrides the HISTFILE specified
in a tracking model for the job.
APPL PAYJOBS
DOCLIB 'CYBER.JOBS.DOC'
JCLLIB 'CYBER.JOBS.JCL'
JOB PAYJOB1
HISTFILE HIST2
RUN DAILY
ENDJOB

ESP-5.4-UG-05 265
 Section–Using job documentation for qualified jobs

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 PAYJOBS
JOB PAYJOB1
RELEASE NEXTJOB
ENDJOB

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.

266 ESP-5.4-UG-05
 Chapter 8–Job Documentation

Visually, the dependencies look like this:

A.RUN1 A.RUN2

Y Z

Job-documentation member
The job-documentation member looks like this:
A: JOBDOC
IF ESPAPQUAL='RUN1' THEN DO
RUN DAILY
RELEASE Y
ENDDO
IF ESPAPQUAL='RUN2' THEN DO
RUN WORKDAYS
RELEASE Z
ENDDO

Using job documentation for links and tasks

You can use job documentation for links and tasks that you have identified in an ESP
Application.

ESP-5.4-UG-05 267
 Section–Using job documentation for links and tasks

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:
Job Documentation
ESP Procedure Member

A: JOBDOC
DOCLIB 'CYBER.JOBS.DOC RUN DAILY
JCLLIB 'CYBER.JOBS.DOC RELEASE CHECK
APPL ABC
JOB A
JOB CHECK TASK CHECK: JOBDOC
JOB ENDAPPL LINK RUN DAILY
PROCESS SEND 'CHECK REPORT FOR JOB A'
ENDJOB

ENDAPPL: JOBDOC
RUN DAILY
RELEASE CHECK

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.

268 ESP-5.4-UG-05
 Chapter 8–Job Documentation

The ESP Procedure and job documentation member look like this:

ESP Procedure
DOCLIB 'CYBER.JOBS.DOC'
JCLLIB 'CYBER.JOBS.JCL'
APPL MEMO
JOB MEMOBACK
RUN WORKDAYS Job Documentation
RELEASE MEMOBACK.MSG Member
JOB MEMOBACK.MSG LINK PROCESS
RUN WORKDAYS
SE 'MEMOBACK IS DONE' U(*) MEMOBACK: JOBDOC
ENDJOB IF ESPAPQUAL=' ' THEN +
RESOURCE (1,DB2TAB)

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.
Command Explanation
BD Browses job documentation
ED Edits job documentation

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.

ESP-5.4-UG-05 269
 Section–Retrieving information

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.

270 ESP-5.4-UG-05
 Chapter 8–Job Documentation

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:
USERDESC
THIS 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.

ESP-5.4-UG-05 271
 Section–Converting existing job documentation

Commands
You can use the following commands:
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

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: JOBDOC
USERDESC
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-) SNUM
REMOVE '**'
LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINE
LABEL '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.

272 ESP-5.4-UG-05
 Chapter 8–Job Documentation

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-5021
CICS:
(905) 123-4567
.
.
.
If you call the above member SUPPORT, you can retrieve support phone numbers for
ESP Workload Manager by typing the following:

Input Output
ESP:
JI SUPPORT FIELD(ESP) REGULAR (905) 479-4611
AFTER_HOURS (416) 287-5021

ESP-5.4-UG-05 273
 Section–Other uses of job documentation

274 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 275
 Section–History reporting

• 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: Youcan 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.

276 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.

ESP-5.4-UG-05 277
 Section–Field formats

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'

278 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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:
ESP Workload Explanation
Manager Form
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.

You can select elapsed times by requesting them in the same formats as those that
appear above.

ESP-5.4-UG-05 279
 Section–Field formats

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

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

280 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.

ESP-5.4-UG-05 281
 Section–Specifying input criteria

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 TODAY
FROM 8AM YESTERDAY TO 8AM TODAY
FROM 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 (=).
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.

If you want to compare a field to a null string, use a blank enclosed in single quotes, as
in ' '.
Note: Youcan specify several criteria sections in a single report, using multiple
CRITERIA commands; ESP Workload Manager selects a job if it satisfies any criteria
section.

282 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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 PAYROLL
CRITERIA 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 ' '

ESP-5.4-UG-05 283
 Section–Specifying output criteria

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 10000
CRITERIA 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 10000
CRITERIA 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:
REPORT
HISTFILE HIST1
CRITERIA RDRON GT TODAY LESS 12 WEEKS
COPY SELECT FILE(DISK1)
COPY REJECT FILE(TAPE1)

284 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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:
DATEFORM Results Example
DMY Day DDMMMYY MON14MAY01
This is the default.
JULIAN Day DDDYY MON13401
YM Day YYYYMMM MON200105
YMD Day YYYYMMMDD MON20010514
MDY Day MMMDDYY MON051401

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.

ESP-5.4-UG-05 285
 Section–Specifying output criteria

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.

286 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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 TEXCP
SORT ACCOUNT JOBNAME
BREAK ACCOUNT 3 EJECT SUBTOTAL
BREAK 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 CPUTIME
ENDR
Sample output from the above commands is shown below.

JOBNAME JOBNO COMP EXEC START EXEC END END CPU TIME
CODE START DATE DATE
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

ESP-5.4-UG-05 287
 Section–Ending the report definition

JOBNAME JOBNO COMP EXEC START EXEC END END CPU TIME
CODE START DATE DATE
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

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 *
REPORT
HISTFILE HIST1
FROM 6PM YESTERDAY TO 8AM TODAY
CRITERIA ACCOUNT EQ PAY-;
DISPLAY JOBNAME, JOBNO, ACCOUNT, DEXCP, TEXCP
SORT ACCOUNT
BREAK ACCOUNT 4 EJECT SUBTOTAL
ENDR
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-;).

288 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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 *
REPORT
HISTFILE HIST1
CRITERIA JOBNAME EQ CYB-;
FROM 4PM TODAY
DISPLAY JOBNAME JOBNO CMPC MXCMPC EXECST EXECQT CPUTIME
SORT JOBNAME D
BREAK JOBNAME 4 EJECT SUBTOTAL
ENDR

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.

ESP-5.4-UG-05 289
 Section–ESP Workload Manager history reporting fields

Field Explanation
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.

290 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Field Explanation
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.

ESP-5.4-UG-05 291
 Section–ESP Workload Manager history reporting fields

Field Explanation
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.

292 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Field Explanation
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.

ESP-5.4-UG-05 293
 Section–ESP Workload Manager history reporting fields

Field Explanation
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.

294 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Field Explanation
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

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.

ESP-5.4-UG-05 295
 Section–ESP Workload Manager history reporting fields

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

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.

296 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Example: History report showing overdue jobs

REPORT
INPUT DATASET('CYB1.TONYT540.HISTFILE')
CRITERIA JOBNAME EQ WAIT5 OR JOBNAME EQ CALC
FROM MAY 1 2004
DISPLAY JOBNAME,JOBNO,APPLSYS,OVDSUBAT,OVDBEGAT,OVDENDAT,OVDEND
SORT EXECSDATE EXECST JOBNAME
ENDR
CYBERMATION 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 FOR
WAIT5 52329 - - - -
WAIT5 52701 TESTSAD - - - -
WAIT5 57042 TESTSAD - - - -
WAIT5 57780 RFE1214A 5MAY04 13.00 5MAY04 13.01 5MAY04 13.04 3M02
WAIT5 57998 RFE1214 - - 5MAY04 14.56 3M01
WAIT5 58016 RFE1214 - - 5MAY04 15.06 1M13
WAIT5 58178 TESTSAD - - - -
WAIT5 60836 RFE1214 - - 6MAY04 10.39 3M01
WAIT5 60846 RFE1214A 6MAY04 10.38 6MAY04 10.39 6MAY04 10.42 3M03
WAIT5 60894 RFE1214 - - 6MAY04 11.01 3M01
WAIT5 60961 RFE1214 - - 6MAY04 11.10 3M01
WAIT5 60997 TSTRFES - - 6MAY04 11.19 1M02
WAIT5 61218 RFE1214 - - 6MAY04 12.40 3M02
WAIT5 61231 RFE1214A 6MAY04 12.48 6MAY04 12.49 6MAY04 12.52 3M01
WAIT5 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 3M00
WAIT5 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

ESP-5.4-UG-05 297
 Section–Reporting on scheduled activity

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.

298 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.

ESP-5.4-UG-05 299
 Section–Extracting data

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

300 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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

ESP-5.4-UG-05 301
 Section–Generating projected versus actual data

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.

302 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.JCL
APPL PAYROLL
JOB JOB1
RELEASE JOB2
ENDJOB
JOB JOB2
INPUTDS PROD.GDG(-1)
ENDJOB
SELECT (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:
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.

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.

ESP-5.4-UG-05 303
 Section–Using job mapping

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.
Explanation Attributes for 3390 DASD Otherwise use
Organization PS PS
Record format VBS VBS
Record length 32756 32756
Block size 27998 16384

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

304 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.

ESP-5.4-UG-05 305
 Section–Using job mapping

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

306 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Reviewing the output

For each job, ESP Workload Manager produces output similar to the following:
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:

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

ESP-5.4-UG-05 307
 Section–Using job mapping

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 1
PAYJOB02 PAYROLL 2
PAYJOB03 PAYROLL 2
END OF LIST
The following is a sample index of Applications that will appear at the end of your
job-activity report:
APPLICATION INDEX PAGE
APPL NAME JOB NAME PAGE
--------- -------- ----
PAYROLL PAYJOB01 1
PAYJOB02 2
PAYJOB03 2
END 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).

308 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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)

ESP-5.4-UG-05 309
 Section–Producing a job-descendent report

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:
PAYJOBA

PAYJOBB PAYJOBC

PAYJOBD

PAYJOBE

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 TREE
PAYJOBA JOB PAYROLL
PAYJOBB JOB PAYROLL
PAYJOBD JOB PAYROLL
PAYJOBE JOB PAYROLL
PAYJOBC JOB PAYROLL
PAYJOBD JOB PAYROLL
PAYJOBE JOB PAYROLL

310 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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) JOBINDEX
JOBTREE DSN('MY.MAPGEN') JOB(START.APPL) APPL(PAYROLL)
/*

ESP-5.4-UG-05 311
 Section–ESP Workload Manager FLOWDOC

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
UserInput
Input ESP
ESP SAD
SADFile
File

CYBES090
CYBES090 VSAM
VSAM

CYBES091 FlowDoc
CYBES091 FlowDoc

312 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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

ESP-5.4-UG-05 313
 Section–ESP Workload Manager FLOWDOC

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.

314 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Report headings
The following shows the headings as they appear in the report, and what they mean:
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.

Sample report generation jobs

The following are examples of report generation jobs that could be used to produce
ESP Workload Manager FLOWDOC reports.

ESP-5.4-UG-05 315
 Section–ESP Workload Manager FLOWDOC

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

316 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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

ESP-5.4-UG-05 317
 Section–Flowcharting

Sample ESP Workload Manager FLOWDOC report

The following FLOWDOC report results from the previous JCL:

APPLICATION: PAYROLL
RUN DATES: FRI 15 SEP ***SUCCESSOR
2000 ***
HOLD TAG TYPE SUBTIME JOBNAME HC RELEASES RESOURCE SCOPE APPL JO
BN
AM
E
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 AC
CT
1
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 AC
CT
1
N PAYROLL JOB 20.00 PAY9 1 PAY10
N PAYROLL JOB 20.00 PAY10 3 END CPUABS

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

318 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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 TESTAPPL
JOB JOB1
EARLYSUB NOW PLUS 24 HOURS
RUN DAILY
RELEASE JOB2
ENDJOB
3. Use the GENPROJ command to extract data from the Application. For example:
GENPROJ TESTAPPL.0 DATASET('SYS1.TESTAPPL.GENPROJ')

ESP-5.4-UG-05 319
 Section–Generating flowcharts using MS Project

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 GENPROJ mydsn

APPLFILE

download

mydsn.mpx Convert mydsn.txt

MS Project

mydsn.mpp

320 ESP-5.4-UG-05
 Chapter 9–Creating Reports

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.

ESP-5.4-UG-05 321
 Section–Generating flow charts with ESP Workload Manager and Timeline

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.

322 ESP-5.4-UG-05
 Chapter 9–Creating Reports

Illustration of steps 1 to 8
These steps are illustrated below:

GENFLOW
FLOW
GO
SADGEN file mydsn

download

Split file mydsn.txt

chart1t.csv

chart1d.csv

Timeline

mydsn.mlp

ESP-5.4-UG-05 323
 Section–Generating flow charts with ESP Workload Manager and Timeline

324 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 325
 Section–What is a resource?

• 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

326 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

ESP-5.4-UG-05 327
 Section–Scope of resources

Scope of resources
You can classify the scope of the resources you define according to the following
resource levels:
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.

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.

328 ESP-5.4-UG-05
 Chapter 10–Using Resources

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

ESP-5.4-UG-05 329
 Section–Requesting resources

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

330 ESP-5.4-UG-05
 Chapter 10–Using Resources

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 ABC
JCLLIB 'CYB.ESP.JCL'
RESOURCE (1,NITESHFT)
JOB A
RESOURCE (1,CICS)
RUN DAILY
ENDJOB
JOB B
RUN DAILY
ENDJOB
JOB C
RUN DAILY
ENDJOB

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)

ESP-5.4-UG-05 331
 Section–Requesting resources

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.

332 ESP-5.4-UG-05
 Chapter 10–Using Resources

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)
ENDJOB
JOB B
RUN DAILY
RESOURCE (1,MSTRFILE)
PRIORITY 10
ENDJOB
JOB C
RUN DAILY
RESOURCE (1,MSTRFILE)
PRIORITY 20
ENDJOB
JOB D
RUN DAILY
RESOURCE (1,MSTRFILE)
PRIORITY 30
ENDJOB

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.

ESP-5.4-UG-05 333
 Section–Default resources

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.

334 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

ESP-5.4-UG-05 335
 Section–Defining resources

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.

336 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

ESP-5.4-UG-05 337
 Section–Modifying Resources

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.

338 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

ESP-5.4-UG-05 339
 Section–Displaying resource information

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 Wait
Resource LOCKOUT Global Renewable
1 needed by PAYJOBD, Appl PAYROLL.396
TORONTO * 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 LIST
Resource CICSUP Local Threshold
NODE1 CPU1 Avail=1
NODE1 CPU2 Avail=0
The following command is used to display all resources.
RESDEF – LIST

340 ESP-5.4-UG-05
 Chapter 10–Using Resources

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 ALL
APPL 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.

ESP-5.4-UG-05 341
 Section–Resource absorption

Examples – Stepend statement

The following example shows releasing one unit of a resource after STEP1, PROCA
finishes:
APPL ONE
JCLLIB '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.

342 ESP-5.4-UG-05
 Chapter 10–Using Resources

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 ABSRES
JCLLIB '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

ESP-5.4-UG-05 343
 Section–Resource absorption

Example 1: Application with absorption

The following example shows an Application with an Absorb statement:
APPL ABSRES
JCLLIB 'CYBER.JCLLIB.CNTL'
JOB A
RESOURCE (1,T3480)
ENDJOB
JOB B
RESOURCE (1,T3480)
ENDJOB
JOB C
RESOURCE (1,T3480)
ENDJOB
JOB D
ABSORB
RESOURCE (3,T3480)
ENDJOB
JOB E
RESOURCE (1,T3480)
ENDJOB
JOB F
RESOURCE (1,T3480)
ENDJOB
SELECT (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 Status
A ABSRES 10 EXEC EXECUTING STEP2
B ABSRES 10 EXEC EXECUTING STEP1
C ABSRES 10 EXEC EXECUTING STEP1
D ABSRES 10 RESWAIT Waiting for Resources
E ABSRES 10 RESWAIT Waiting for Resources
F ABSRES 10 RESWAIT Waiting for Resources
The following example shows the current resource allocations:
Resource ABSRES List Own Wait
Resource ABSRES Global Renewable
3 needed by D, Appl ABSRES.11
1 needed by E, Appl ABSRES.11
1 needed by F, Appl ABSRES.11
TOR1 * 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

344 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

Resource DB2TAB1

Job A Job B
Waiting for Resource

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.

ESP-5.4-UG-05 345
 Section–Example: Controlling access to an online system

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:

1,IMS A

IMS 3 2,IMS B

2,IMS C

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:

Job RESOURCE Statement

A RESOURCE (1,IMS)
B RESOURCE (2,IMS)
C RESOURCE (2,IMS)

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.

346 ESP-5.4-UG-05
 Chapter 10–Using Resources

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 DAILY
ENDJOB
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

ESP-5.4-UG-05 347
 Section–Example: Using a resource for a self-completing task

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.

9 a.m. to 4 p.m.
Allow low priority

RESDEF LOWPRIO SET AVAIL(1)

4 p.m. to 9 a.m.
Disallow low priority

RESDEF LOWPRIO SET AVAIL(0)

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.

348 ESP-5.4-UG-05
 Chapter 10–Using Resources

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:

Job RESOURCE Statement

A RESOURCE (999,DBASE1)
B RESOURCE (1,DBASE1)
C RESOURCE (1,DBASE1)
Z RESOURCE (999,DBASE1)

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.

ESP-5.4-UG-05 349
 Section–Example: Controlling mutually exclusive groups of jobs

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')-
CURRENT
CPU 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 DAILY
ENDJOB
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.

350 ESP-5.4-UG-05
 Chapter 10–Using Resources

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:

A
(job)

START.1 START.2
(task) (task)

B C
(job) (job)

D E
(job) (job)

RESET.1 RESET.2
(link) (link)

ESP-5.4-UG-05 351
 Section–Example: Controlling mutually exclusive groups of jobs

Sample Application
JCLLIB 'SYS1.JCL'
APPL MUTUAL
JOB A
RUN DAILY
RELEASE (START.1,START.2)
ENDJOB
JOB START.1 TASK PROCESS
RUN DAILY
RELEASE B
RESOURCE (1,MUTUAL)
ESP AJ START.1 COMPLETE APPL(MUTUAL.%ESPAPGEN)
ENDJOB
JOB B
RUN DAILY
RELEASE D
ENDJOB
JOB D
RUN DAILY
RELEASE RESET.1
ENDJOB
JOB RESET.1 LINK PROCESS
RUN DAILY
ESP RESDEF MUTUAL SET MAX(1)
ENDJOB
JOB START.2 TASK PROCESS
RUN DAILY
RELEASE C
RESOURCE (1,MUTUAL)
ESP AJ START.2 COMPLETE APPL(MUTUAL.%ESPAPGEN)
ENDJOB
JOB C
RUN DAILY
RELEASE E
ENDJOB
JOB E
RUN DAILY
RELEASE RESET.2
ENDJOB
JOB RESET.2 LINK PROCESS
RUN DAILY
ESP RESDEF MUTUAL SET MAX(1)
ENDJOB

352 ESP-5.4-UG-05
 Chapter 10–Using Resources

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.

ESP-5.4-UG-05 353
 Section–Example: Planning for a system shutdown - Part 2

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 TIME
TIME=USER1
SEND 'SYSTEM COMING DOWN IN %TIME MINUTES' CN(01)
RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)
TIME=TIME-1
IF 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.

354 ESP-5.4-UG-05
 Chapter 10–Using Resources

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)

ESP-5.4-UG-05 355
 Section–Example: Schedule dependency

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

356 ESP-5.4-UG-05
 Chapter 10–Using Resources

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:

PAYJOB1 PAYJOB2
(job) (job)

END.PAYJOB1 END.PAYJOB2
(link) (link)

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.

ESP-5.4-UG-05 357
 Section–Example: Schedule dependency

358 ESP-5.4-UG-05
 Optimizing ESP Applications to Use
Distributed 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.

ESP-5.4-UG-05 359
 Section–Planning Applications to optimize Distributed Manager

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.

360 ESP-5.4-UG-05
 Chapter 11–Optimizing ESP Applications to Use Distributed Manager

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

ESP-5.4-UG-05 361
 Section–Planning Applications to optimize Distributed Manager

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.

Central ESP Workload Manager

JOB A

JOB B

Distributed Manager 1 Distributed Manager 2

Change

UNIX_JOB F NT_JOB S

NT_JOB T

UNIX_JOB G
NT_JOB V

Change

UNIX_JOB H

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

362 ESP-5.4-UG-05
 Chapter 11–Optimizing ESP Applications to Use Distributed Manager

the next workload object will not be released until the mainframe becomes available
again. This Application structure defeats the purpose of the Distributed Manager.

Central ESP Manager

JOB A

Distributed Manager 1 Distributed Manager 2

Change Change

UNIX_JOB F NT_JOB S

Change Change
JOB B

Change
NT_JOB S

Change

UNIX_JOB G NT_JOB S

Change

Central ESP Manager

JOB C

ESP-5.4-UG-05 363
 Section–Establishing ownership of a workload object

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:

State of central ESP Functions Unavailable if Functions Unavailable if

Workload Manager Owned by ESP Workload Owned by a Distributed
Manager Manager
ESP Workload Manager • Runtime symbolic
available variables
• Runtime scripting of
CLANG and REXX
• EXTERNAL
• MANUAL
• Alerts
ESP Workload Manager • Runtime symbolic variables • Runtime symbolic
unavailable • Runtime scripting of variables
CLANG and REXX • Runtime scripting of
• EXTERNAL CLANG and REXX
• MANUAL • EXTERNAL
• Alerts • MANUAL
• Alerts

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

364 ESP-5.4-UG-05
 Chapter 11–Optimizing ESP Applications to Use Distributed Manager

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.

ESP-5.4-UG-05 365
 Section–Defining ownership of an Application

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.

366 ESP-5.4-UG-05
 Chapter 11–Optimizing ESP Applications to Use Distributed Manager

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.

ESP-5.4-UG-05 367
 Section–Changing ownership of an Application dynamically

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.

368 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 369
 Section–Commands

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 member
DISPLAY|D ACTIVITY|ACTIVE|ACT|A
DISPLAY|D GROUPS|GROUP|GR|G
DISPLAY|D SERVICES|SERVICE|SERV|S
DISPLAY|D SYSTEMS|SYSTEM|SYS
DISPLAY|D TRACE|TR
FORCE MEMBER|MEM|M member
HELP|H|?
PURGE|PG CONNECTION|CON connection
PURGE|PG SERVICE|SERV|S service
RESTART|RES|RS|SPIN|SP TRACE|TR
SET|T INTERVAL|INT interval
SET|T MEMBER|MEM|M member MASTER|M
SET|T SERVICE|SERV|S service SUSPEND|S(seconds)
SET|T TERMOPT|TO LEAVE|L|QUIESCE|Q
SET|T TRACE|TR SYSOUT|S(class)
START|S SERVICE|SERV|S service
START|S TRACE|TR
STOP|P GROUP|GR|G
STOP|P MEMBER|MEM|M(member)
STOP|P SERVICE|SERV|S service
STOP|P TRACE|TR
VERIFY|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)

370 ESP-5.4-UG-05
 Chapter 12–Using XCF with ESP Workload Manager

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.

ESP-5.4-UG-05 371
 Section–XCF Services

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 DSTRIG
XCF 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 Susp
DSTRIG Active QS10 QS10M3 120
ROUTING Active QS10 QS10M3 120
SCOREBD Active QS10 QS10M3 120
TRACKING 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 Susp
DSTRIG Active QS10 QS10S 120
ROUTING Active QS10 QS10S 100
SCOREBD Active QS10 QS10S 120
TRACKING 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=P521
Partner Service Status Connection
Listener DSTRIG Active
Listener TRACKING Active
P522 DSTRIG Active 1,5
P522 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

372 ESP-5.4-UG-05
 Chapter 12–Using XCF with ESP Workload Manager

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=P521
Partner Service Status Connection
Listener TRACKING Active
Listener DSTRIG Active
P522 TRACKING Active 3,7
P522 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.

ESP-5.4-UG-05 373
 Section–Trace

To display the members in the XCF group and their respective states:
• Use the XCF DISPLAY GROUP command.
XCF DISPLAY GROUP
Group=QS10 Member=QS10M3 Interval=60 TermOpt=Quiesce
Group Member System ASID Jobname SSID ESP Status
QS10 QS10M1 SYSC 0056 QS10 QS10 Shadow Active
QS10 QS10M3 SYSA 009B QS10SHAD QS10 Master Active
QS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow Active
QS10 QS10S SYSA 009F QS10S QS1S Proxy Active
QS10 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.

374 ESP-5.4-UG-05
 Chapter 12–Using XCF with ESP Workload Manager

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.

ESP-5.4-UG-05 375
 Section–Trace

376 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 377
 Section–Expedite

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.

378 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

The following Expedite actions are available for executing jobs. The objective of a job
expedite is to increase the job dispatching priority.

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.

The following Expedite action is available for a job that is not yet submitted.

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.

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.

ESP-5.4-UG-05 379
 Section–Expedite

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

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.

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)

380 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

Example Application:
APPL DAILYRUN
JCLLIB 'DEPT01.JCLLIB'
EXPEDITE FAST

JOB JOB001
DUEOUT EXEC REAL PLUS 10 MINUTES
RELEASE JOB002
RUN DAILY
ENDJOB
JOB JOB002
EXPEDITE OFF
RELEASE JOB003
RUN DAILY
ENDJOB
JOB JOB003
EXPEDITE SUPER
RUN DAILY
ENDJOB
JOB JOB004
EXPEDITE OFF
RUN DAILY
ENDJOB
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.

ESP-5.4-UG-05 381
 Section–Resource Balancing

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.

382 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

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

ESP-5.4-UG-05 383
 Section–Workload Balancing

Scenario using WLM workload balancing

Assumptions:
• 2 CPUs in node Toronto
• 3 CPUs in node Chicago
Setting the topology:
NODE TORONTO ADD SYSPLEX
NODE CHICAGO ADD SYSPLEX
CPU T1 ADD NODE(TORONTO) CURRENT
CPU 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.

384 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

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.

ESP-5.4-UG-05 385
 Section–Workload Balancing

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 ADD
NODE UNIX ADD
CPU 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.exe
ENDJOB
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.

386 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

Specifying a UNIX job:

UNIX_JOB myunjob
RUN DAILY
RESOURCE(1,RESUNIX)
AGENT AGunix1 ROUTING
SCRIPTNAME /SW/myjob
ENDJOB
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.

ESP-5.4-UG-05 387
 Section–XCF Routing Service

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

388 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

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

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

ESP-5.4-UG-05 389
 Section–XCF Scoreboard Service

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

390 ESP-5.4-UG-05
 Chapter 13–ESP Workload Manager High Performance Option

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

ESP-5.4-UG-05 391
 Section–XCF Scoreboard Service

392 ESP-5.4-UG-05
 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

ESP-5.4-UG-05 393
 Section–Shadow Manager

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.

394 ESP-5.4-UG-05
 Chapter 14–ESP Workload Manager High Availability Option

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

ESP-5.4-UG-05 395
 Section–Shadow Manager

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.

396 ESP-5.4-UG-05
 Chapter 14–ESP Workload Manager High Availability Option

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 GROUP
XCF SET MEMBER ESPS MASTER

ESP-5.4-UG-05 397
 Section–ARM Registration

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 ESPM
XCF DISPLAY GROUP
XCF 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.

398 ESP-5.4-UG-05
 Chapter 14–ESP Workload Manager High Availability Option

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

ESP-5.4-UG-05 399
 Section–XCF Routing Service

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.

400 ESP-5.4-UG-05
 Chapter 14–ESP Workload Manager High Availability Option

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 Option

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

ESP-5.4-UG-05 401
 Section–XCF Scoreboard Service

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

402 ESP-5.4-UG-05
 Chapter 14–ESP Workload Manager High Availability Option

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

ESP-5.4-UG-05 403
 Section–XCF Scoreboard Service

404 ESP-5.4-UG-05
 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.

ESP-5.4-UG-05 405
 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 Status An ESP Workload Manager facility for displaying and manipulating the
Facility (CSF) 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

406 ESP-5.4-UG-05
 Glossary

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 Manager ESP Workload Manager High Availability Option takes full advantage of the
High Availability Option IBM clustering sysplex technology to increase enterprise IT performance by
(HAO) 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.

ESP-5.4-UG-05 407
 ESP Workload Manager ESP Workload Manager High Performance Option optimizes workload to
High Performance significantly increase the performance of the enterprise IT environment. It
Option (HPO) 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.

408 ESP-5.4-UG-05
 Glossary

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:

Condition Format
JES2 not running in z2 mode JOBnnnnn
(with large job numbers disabled)
JES2 running in z2 mode (with Jnnnnnnn
large job numbers enabled)
JES3 For job numbers less than
100000:
JOBnnnnn
For job numbers greater than
99999:
Jnnnnnnn

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.

ESP-5.4-UG-05 409
 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.

410 ESP-5.4-UG-05
 Glossary

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.

ESP-5.4-UG-05 411
 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.

412 ESP-5.4-UG-05
 Index

Symbols agentmon, definition, 405

%ESPAPTAG, 205 alert processing
%ESPATIME, 203 definition, 25
%ESPTRDSN, 81 uses, 26
%ESPTRGDG, 203 alert, definition, 405
%SHADOW, 395 ALTCAL
command, 62
use to alter a calendar, 62
Numerics ALTER, Event command, 100
4-4-5 period, example, 70 Alternative input data sets, Panvalet
and Librarian, 42
A AND, scheduling term, 50
ANYCLOSE
absolute day
FTP trigger operand, 87
definition, 405
indicate any closure of a data set, 194
vs. logical day, 49
trigger an Event at closure, 82
ABSOLUTE, scheduling term, 50
ANYDAY, scheduling term, 50
ABSORB, statement, 343
APPLEND
ACTIVE, built-in function, 118, 124
additional considerations, 191
Advancing job based on holiday, 67
does not generate SMF, 191
AFM, 405
example, 18, 191
AFTER, statement, 165
how to use, 190
Agent
limitations, 190
definition, 405
setting, 190
workload balancing, 339, 385
with link, 244

ESP-5.4-UG-05 413
 workload object, 18 browsing
APPLHOLD, Pnode field, 223 COPYJCL (CSF), 233
Application, See ESP Application last executed JCL (CSF), 233
APPLJOB built-in functions
command, 216 definition, 117
example example
bypassing a job, 217 calculating the length of a symbol, 123
completing an Application, 217 checking available cartridge drives, 127
inserting a link to add a job relationship, 217 checking if CICSPROD is active, 124
requesting a job, 217 combined functions, 128
options, 217 DAYS_BETWEEN to
APPLWAIT, Pnode field, 223 calculate weeks, 120
Arithmetic DAYS_BETWEEN to
expression, 115 calculate workdays, 119
operations, 115 DAYS_FROM, 119
ARM DAYS_TO, 119
and shadow manager, 399 defining an undefined variable, 123
couple data set, 398 extracting the last character
how it works, 398 of a variable length symbol, 124
registration, 398 JOBONQ, 126
ARMELEM, definition, 398 selecting a job when
audit log, definition, 405 another is not selected, 122
automated framework message, 405 selecting one job based on another, 122
Automatic Restart Management TAPES, 127
ARMELEM initialization parameter, 398 TODAY, 120
description, 398 TOMORROW, 121
AUTOVAR, definition, 406 using a substring of a
time variable, 124
YESTERDAY being a holiday, 121
B
YESTERDAY being first day of month, 121
batch summary by function, 117
convert an existing PDS job testing for a true condition, 118
documentation library, 271 using calendaring functions, 118
creating history report in, 276 using functions for job selection, 122
creating schedule activity report in, 299 using functions for symbolic variables, 123
defining a repetitive holiday, 66 ACTIVE, 124
example of explicit-data-set trigger DAYS_BETWEEN, 119
notification, 90 DAYS_FROM, 119
executing ESP Workload Manager DAYS_TO, 118
commands in, 38 DEFINED, 123
executing program CYBESDT1 in, 88 ESP Procedure, 117
invocation of ESP Workload Manager, 38 JOBONQ, 125
issuing commands in, 4 LENGTH, 123
MAPGEN command, 304 SELECTED, 122
specifying input parameters SUBSTR, 124
of CYBESDT1, 88 TAPES, 126
use of hyphen, 276, 288 TODAY, 120
using JOBMAP in, 306 TOMORROW, 120
using JOBTREE in, 309

414 ESP-5.4-UG-05
 Index

YESTERDAY, 121 defining, 61

built-in symbolic variables, definition, 113 defining the SYSTEM calendar, 61
BY, CSF command, 233 displaying, 63
BYPASSED, Pnode field, 223 displaying the SYSTEM calendar, 63
bypassing specifying in an Event, 97
a job (CSF), 233 first day of the week, 49
a job in CSF, 242 LOGICAL as a default, 51
a job without waiting for main menu option, 33
predecessor, example of, 161 optional specifications, 61
a job, example of, 217 period intervals, 69
a scheduled Event execution, 103 planning, 59
Event, specific day, 78 referencing, 64
example retaining entries, 60
bypassing a job and wait setting special, 97
for predecessor, 161 specifying in Event, 97
jobs and dependencies, 160 SYSTEM, 59
execution of an Event, 104 system, 59
job dependencies, 160 terms, implied periods, 48
jobs, 160, 242 using, 9, 58
using calendar terms, 59
what it can contain, 9, 59
C workdays, 49, 53
caching an ESP Workload Manager Procedure, 135 calendar, definition, 406
CALENDAR CCCHK, definition, 406
command, 59, 61, 97 CCFAIL, definition, 406
command, to specify additional changes in an ESP Apllication
calendars for an Event, 64, 97 that take effect immediately, 218
suppressing field in a report, 308 changes in an ESP Application
suppressing the calendar field in reports, 308 that take effect for the next Application
use in an Event to refer to two calendars, 64 generation, 218
calendar CLANG
accessing, 59 example
altering, 62 calculating time periods, 133
contents, 58 overriding an ESP Procedure on a particular
default calendar, 60 date, 134
default values, 60 scheduling a job on the last day of the
defining, 60 month, 132
defining using panels, 61 taking different action based on time, 134
defining your organization’s taking different action on a weekday, 132
logical day in, 64 taking different actions based on the status of
deleting, 60, 63 CICS, 133
deleting of entries, 60 usage, 13
display information about a specific, 62 using calendaring functions, 133
displaying, 62 in templates, 129
displaying holidays and special days, 63 language elements, 110
displaying more detailed information on other techniques for schedule criteria, 57
holidays and special days, 63 specifying different DELAYSUB
example, 59 times for a job, example, 156
altering, 62

ESP-5.4-UG-05 415
 using for job documentation, 258 SADUPD, 301
using in ESP Procedures, 110 SCHEDULE, 77
CLANG, definition, 406 SEND, 131
CLASS, Event command, 100 SHADGOAL, 396
CLIST SIGCYCLE, 131
calling ESP Workload Manager from, 40 SIGPOST, 131
invoking the ESP Workload Manager SIMULATE, 101
command from, 39 SUBMIT, 131
to access ESP Workload Manager, 40 SUSPEND, 81
Coding RESDEF with WLM operand, 383 SYMLIB, 96
command TEST, 57
definition, 406 TRIGGER, 102
entering, 2 USE, 35
example, 4, 212 VS, 95
issuing, 211 XCF SPIN TRACE, 374
issuing from console, 4 XCF START SERVICE, 371
ALTCAL, 62 comments
APPLJOB, 216 adding in an Event, 98
CALENDAR, 59, 61, 97 ESP Procedure, 3, 109
COPYJCL, 94 how to include, 3
DEFHOL, 65 in job documentation, 258
DEFSPEC, 67 procedure syntax, 109
DELCAL, 64 comparison operators, definition and list of, 116
ENQSELF, 171 COMPLETE
EVENT, 74 condition, 254
EXPECT, 99 Pnode field, 223
HOLD, 104 scheduling term, 50
INFOMSG, 37 STATUS, 293
INVOKE, 93, 131 complete, post, 410
JOBMAP, 305 completing
JOBTREE, 309 an Application, example of, 217
LDTE, 84 jobs, 242
LDXE, 84 Consolidated Status Facility, definition, 406
LIBSUB, 92, 131 Consolidated Status Facility, See CSF
LIST, 101 continuation character
LISTCAL, 62 ESP Procedure, 2, 109
LISTHOL, 63 use of, 2
LISTSCH, 98 copying JCL, 94
LISTSPEC, 63 COPYJCL
LOAD, 40 changing the copy, 95
LSAR, 300 command, 94
NOSCHED, 78 compressing, 95, 148
QUIESCE, 396 definition, 406
RESDEF, 335 editing, 234
RESREFR, 337 example of using, 95
RESUME, 81 specifying a COPYJCL library, 147
ROUTING, 389, 401 suppressing, 148
SADGEN, 298 using the JOBID operand, 95

416 ESP-5.4-UG-05
 Index

using the JOBNAME operand, 95 LR, 234, 245

COREQ, statement, 165 ME, 246
CPU availability, Resource representing the MR, 246
percentage of, 385 R, 234
CPU service unit resources, use of, 383 working with Applications, 233
CRITICAL, 153 working with jobs, 233
critical path working with other ESP
analysis, for all Applications, 209 Workload Manager definitions, 235
analysis, using, 208 working with subApplications, 233
CSF condition, 254 completing a job, 242
definition, 406 customizing, 20
displaying, 211 customizing a view, 227
example, 208 defining a view, 226
external jobs on, 210 defining your sorting requirements, 230
identifying critical jobs, 209 definition, 20, 406
label, 211 deleting a view, 232
multiple, 210 deleting a view if you know the
overriding elapsed times, 210 name of the view you want to select, 232
preparing to use, 209 deleting a view, if you do not know
turn on analysis, 209 the name of the view you want to select, 232
using CSF, 211 displaying data, 222
using the list Application command, 211 entering a freeform filter, 248
with EXPEDITE, 378 example
CSF adding a job relationship in an
adding a job relationship in an Application, 244
Application, 243 adding a job to an Application with IJ, 236
adding a job with a delayed adding a job to an Application with IW, 236
submission time, 243 adding job dependencies, 243
adding a job with a time dependency, 243 changing column position, 229
Adding a LINK process, 244 display, 222
adding a link that processes commands, 244 removing dependency time, 241
adding a relationship between two removing job dependencies, 239
unrelated jobs in an Application, 243 seeing all incomplete jobs, 228
adding job dependencies, 243 seeing all incomplete jobs in
bases for filtering, examples, 248 Application Payroll, 228
bypassing a job, 242 seeing all jobs that are complete OR
changing a time dependency for a job, 240 failed, 229
color options, 231 seeing all jobs that are incomplete
command AND not failed, 229
BY, 233 setting the user status field, 245
DD, 234 extensions, 247
for customizing views, 227 fields, 223
HR, 234 filter criteria syntax, 248
IJ, 234 filtering information, 227
IJA, 234 freeform filtering, 229, 247
IJB, 234 conditions, 254
L, 234 examples of freeform filter, 250
LI, 234 examples of substring notation, 249

ESP-5.4-UG-05 417
 keywords, 250 example, 11
relational operators, 253 job specific creation, 82
term syntax, 248 running a compress
inserting a job job after 100 closures of a data set, 84
IJ option, 236 user specific creation, 83
IW option, 236 waiting on multiple data sets, 83
logic applied to multiple filtering limiting data set activity to a job, 82
conditions, 228 limiting data set activity to a user, 83
Pnode fields, 223 multiple closures, 83
presentation column length, 230 multiple data sets, 83
presentation titles, 230 process flow, 82
presenting information, 229 usage, 81
removing job dependencies, 239 waiting for any closure of a data set, 82
rerunning multiple jobs, 238 waiting on multiple closures
resetting a time dependency, 240 of the same data set, 83
resetting the User Status field to null, 226 waiting on multiple data sets, 83
resubmitting a job, 237 XCF Service, 371
selecting color options, 231 data-set-trigger workload object
selecting views, 232 controlling, 197
setting and resetting the user status field, 244 displaying data-set-triggering information, 197
setting the user status field, 225 example
setting up views, 222 data-set-trigger has a dependency, 197
sort sequence, 230 job specific creation, 195
sorting information, 230 user specific creation, 197
status fields, 225 waiting for a data set creation, 194
storing views, 226 waiting for any closure of a data set, 195
updating a view, 231 waiting on more than one data set, 196
usage of extensions, 247 waiting on multiple closures of a data
using other commands, 247 set, 196
customizing CSF, 20 limiting data set activity to a job, 195
CYBESDT1 limiting data set activity to a user, 196
See also explicit-data-set triggering preparing to use, 193
definition, 88 setting up in an Application, 193
input parameters, 202 using, 193
return codes, 203 visual perspective, 194
syntax for submitting, 88 waiting for any closure of a data set, 194
waiting on multiple closures of the
same data set, 196
D
waiting on multiple data sets, 195
DAILY, scheduling term, 50 data-set-triggered Events
data object, definition, 406 displaying, 84
data set, prefix, 42 holding, 80
data-set names in ESP Procedure, 3, 109 specifying, 81
data-set triggering DAYS_BETWEEN, built-in function, 117, 119
abnormal closures, 82 DAYS_FROM, built-in function, 117, 119
any closure, 82 DAYS_TO, built-in function, 117, 118
concept, 10 DD, CSF command, 234
data-set creation, 82 DEFCAL
displaying Events, 84

418 ESP-5.4-UG-05
 Index

command, 60 all resource dependencies, 234

defining a calendar, 60 individual dependencies, 234
defining a logical day, 64 dsname, 200
DEFHOL DSTRIG
command, 65 and scheduled Events, 82
defining holidays, 65 command to trigger an Event, 81
DEFINED, built-in function, 117, 123 data-set-trigger object identification, 178
DEFSPEC definition, 406
command, 67 explicit data-set triggers, 87
defining special days, 67 setting up a data-set-trigger object, 193
defining the first day of a period, 68 specifying data-set -triggered Events, 81
DELCAL specifying several, 84
command, 64 XCF services, 370
deleting calendars, 64 DUEOUT EXEC time, setting with
DELETE, Event command, 100 MAXRUNTIME, 162
delimiter, 3 dueout times
dependencies, displaying, 234 introducing, 157
depletable resource, definition, 24, 327, 410 propagating, 158
detailed information about a job, displaying, 234 propagating example, 159
displaying
holiday, 63
special day, 63
E
distributed job EACH, scheduling term, 50
retrieving the spool file, 235 ELSE, statement in procedures, 110
selecting options, 235 ENDDEF
Distributed Manager command ending Event definition, 74
example example of Event definition, 74
not recommended structure, 362 ENDDO
recommended structure, 361 grouping with DO-ENDO, example, 112
features and limitations, 361 statement in procedures, 111
planning optimal Applications, 360 ENDING, scheduling term, 50
unsupported functions, 364 ENQSELF
distributed workload objects, 19 command, 171
DJC disadvantage of setting to ALWAYS, 171
definition, 406 displaying status, 171
job network, definition, 406 example, modify, 171
DO modify the status of, 171
grouping with DO-ENDDO, example, 112 ENQUEUE
statement in procedures, 111 automatic generation by the NOTWITH
DOCLIB statement, 172
definition, 406 capabilities, 166
DOCMEM operand of JOB statement, 265 displaying enqueue status in
DROPNOTW the resource file, 169
example, 174 example of displaying, 169
excluding jobs from a examples, 167
NOTWITH statement, 174 excluding jobs from
dropping an ENQUEUE statement, 168
all predecessors, 234 removing mutual exclusivity, 168
specifying mutually exclusive jobs, 167

ESP-5.4-UG-05 419
 usage, 167 identifying JCL libraries, 143
use by NOTWITH feature, 166 inheriting job relationships, 177
enqueue inter-Application dependency, 178
displaying, status, 169 keeping active, 186
manipulating enqueue list of a specified limiting the use of temporary JCL, 147
job in a generated Application, 170 notification on submit and abend, 207
enqueue, definition, 406 notifying when complete, 187
enqueues, modifying, 234 overdue notification, 207
entering selecting jobs for submission
commands, 2 with RUN, 175
statements, 2 selecting jobs for submission
ESP Agent, definition, 407 with SELECT, 175
ESP Application tagging high priority jobs, 205
anticipated end times, 156 tagging jobs with Application name, 205
changes tagging jobs with the scheduled
that take effect for the next Application day of week, 205
generation, 218 using a different TEMPLIB based on year
that take effect immediately, 218 and day, 147
changing definition, 218 using COPYJCL, 148
changing ownership of an, 367 excluding default resources for an, 335
changing ownership of an, dynamically, 368 generating a report for a specific, 307
coding a job-dependency relationship, 166 generation number, 140
completing, example of, 217 generation phase, 139
compressing COPYJCL, 148 getting notified of progress, 206
controlling, 216 home and distant, 178
controlling concurrent processing identifying, 142
of multiple generations, 142 identifying JCL libraries, 143
controlling the use of temporary JCL, 146 identifying jobs, 149
creating an ESP Application that optimizes identifying that a job is part of another
the Distributed Manager's capabilities, 366 Application, 178, 182
creating distributed, 365 inheriting job relationships, 176
critical path, 208 inserting a job in an active, 235
defining, 14, 140 inserting additional workload into
defining ownership of an, 366 an active, 234
definition, 13, 137, 407 introduction, 138
definition example, 141 invoking, 219
deselecting jobs, 176 invoking via an ESP Event, 219
displaying, 215 job types in an, 177
dueout times, 157 limiting the use of temporary JCL, 147
dynamically changing ownership of an, 368 manipulating the enqueue list
ESP Procedure statements, 140 in a generated, 170
example, 14 mutually exclusive run, 166
an Event invokes an ESP Procedure naming, 142
to create an Application, 219 optimizing to use distributed manager, 359
deselecting jobs for submission owner of an, 365
with DESELECT, 176 phase status, 139
deselecting jobs for submission phases, 139
with NORUN, 176 planning to optimize distributed manager, 360

420 ESP-5.4-UG-05
 Index

process phase, 139 data-set names, 3, 109

processing, 138 definition, 12, 107, 407
processing at the end of, with APPLEND, 190 delimiter, 109
providing notification on job status, 206 edit in CSF, 235
relationship with ESP Procedure, 12 example
removing resource dependencies, 162 an Event invoking, 109
reporting on, 287 checking if CICS is active, 128
selecting jobs for submission, 175 CLANG usage, 13
specifying a COPYJCL library, 147 grouping with DO-ENDDO, 112
specifying a JCL library, 143 retrieving a variable from
specifying a member name for a JCL library a global variable table, 114
search, 145 using IF-THEN-ELSE, 112
specifying an EXTERNAL job, 180 using QUIT and EXIT, 113
specifying job relationships, 165 using symbolic variables, 114
specifying multiple jobs, 165 waiting for a job, 129
specifying predecessor, 165 expressions, 115
specifying successor, 165 indentation, 3, 110
specifying the JCL library for a single job, 145 invoking, 108
statements for different job types, 158 label, 110
streamlining, 14 logical operators, 116
subApplications, 212 name, 109
submit time, 175 order of precedence, 116
suppressing COPYJCL, 148 overview, 108
tagging jobs, 205 re-executing, 128
using different job types, 177 relationship with Event, 264
using SELECT vs. RUN statements, 176 statements in an Application, 140
using the JOBID keyword, 148 suppressing field in report, 308
when ESP Workload Manager symbolic variables in, 113
completes an, 153 syntax, 109
working with, 215 terminating with EXIT, 111
working with, in CSF, 233 terminating with QUIT, 112
writing the JCL to a GDG, 148 usage, 13
ESP commands, loading, 40 uses of, 13
ESP distributed manager, 19 using CLANG, 110
ESP Encore using Event definition commands in, 131
definition, 407 using expressions, 115
viewing the panels, 235 using expressions and strings in, 114
ESP Espresso, definition, 407 using literal strings, 114
ESP Procedure using operators, 115
and Applications, 12 ESP Workload Manager
arithmetic operators, 115 accessing
browse in CSF, 235 as a program, 39
built-in functions, 117 as a TSO command processor, 40
caching, 135 from a CLIST, 39
comments, 3, 109 in batch, 38
comparison operators, 116 ISPF option, 32
continuing a line, 2, 109 definition, 407
controlling processing requirements, 12 exiting, 40

ESP-5.4-UG-05 421
 master, 394 names and times of the
ESP Workstation current schedule cycle, 98
benefit of XCF scoreboard service, 391, 403 names or definitions, 101
changing the ownership of an Application, 368 the schedule, 98
defining the ownership of an Application, 366 when it will execute, 99
definition, 21, 408 duplicate, 75
entering commands, 2 edit in CSF, 235
graphical user interface, 21 example, 10
ROUTING command, 390, 402 altering system identifier, 105
working with Applications, 215 changing processing, 79
ESP XCF commands, 370 deleting, 106
ESP_APPL_GEN, 139 displaying the next execution time, 99
ESP_APPL_PROC, 139 displaying the schedule, 98
ESPAPQUAL, 266 expected time, 99
EVENT holding, 104
command, 74 holding a data-set-triggered Event, 80
Event naming, 76
accessing, 75 overdue, 105
adding comments in, 98 sending a message, 91
adding executions, 103 setting symbol libraries, 96
advance/delay/ignore/processing, 79 specifying a calendar, 97
altering, 105 starting tasks, 96
browse in CSF, 235 submitting a job, 92
bypassing submitting multiple jobs, 92
a scheduled, 103 suspending, 104
execution of, 104 using comments, 98
one execution, 103 expected time, 99
CALENDAR command, 59 explicit-data-set trigger, 87
canceling FTP data-set trigger, 11
for specific day, 78 FTP data-set-triggered, 84
next execution, 103 function
changing characteristics, 105 issuing operator command, 95
classes, 105 sending message, 91
commands and their function, 100 specifying, 91
comments, 98 submitting job, 91
controlling scheduling, 79 global-variable-table triggering, 12
data-set triggering, 10 held and suspended, 81
data-set-triggered, 82 holding and releasing, 104
defining holding from being processed at
example, 74 a particular time, 80
how, 74 information in MAPGEN, 304
system identifier, 76 initiator class, definition, 408
when it will execute, 76 invoking
where it will execute, 76 an Application, 219
definition, 408 an ESP Procedure, 93, 108
deleting, 106 issuing operator commands, 95
displaying job mapping, 303
data-set-triggered Events, 84 listing names or definitions, 101

422 ESP-5.4-UG-05
 Index

main menu options, 33 working with defined, 100

missed, 78 Event initiator class, definition, 408
name, 75 EVERY, scheduling term, 50
naming, 74 example
next execution times, 99 using the notification list in an Event, 98
overdue, 78, 105 using the notification list in NOTIFY, 207
overlapping criteria, 77 EXCEPT, scheduling term, 51
pending execution, 80 exceptions
performing tasks, 10 Event scheduling, 78
postponing execution of an, 104 handling, 78
prefix, 75, 101, 332 report on, 30
processing using NORUN and DESELECT, 176
advancing, 79 EXEC, Pnode field, 223
delaying, 79 EXIT
ignoring, 79 statement in procedures, 111
processing of holiday, 66 using, 113
relationship procedure, 264 exiting, ESP Workload Manager, 40
replacing scheduled executions, 103 EXPECT
report sorted by, 314 command, 99
resuming, 104 expected execution, 99
schedule the deletion of, 79 triggering expected Events, 99
scheduled and data-set-triggered, 82 expected time of Event, 99
scheduled Events, 82 EXPEDITE
scheduling, 77, 79 example, 379
security, using the prefix, 75 example of statement, 380
sending messages with, 91 statement, 379
setting calendars, 97 expedite
setting symbol libraries, 96 actions, 378
simulating, 101 description, 378
specifying host security check, 380
data-set-triggered, 81 overview, 378
FTP data-set-triggered, 84 usage, 378
other requirements, 96 expedite policy
scheduled Events, 77 adding or altering an, 379
the function of, 91 associating with an Application, 379
time and frequency, 48 defining, 378
submitting JCL, 91 definition, 378
suppressing field in reports, 308 designating for one job only, 379
suppressing name in reports, 308 host security resource name, 380
suspended and held, 81 explicit data-set triggering
suspending and resuming, 104 definition, 11
trigger, 76 SMF record requirement, 88, 201
triggered in error, 103 explicit-data-set triggering
triggering expected, 99 CYBESDT1, 88
triggering manually, 102 CYBESDT1 input parameters, 88
triggers for, 10 CYBESDT1 return codes, 90
using event definition commands example
in procedures, 131 Connect:Direct (NDM) run task, 90

ESP-5.4-UG-05 423
 notification batch, 90 specific Application, specific period
invoking CYBESDT1 from page mode or line ending in the future, 316
mode, 90 specific Event, specific date, 316
notification utility program, 88 graphical representation, 312
specifying, 87 Report generation, 314
explicit-data-set-trigger workload object Report headings, 315
example Report organization, 314
explicit data-set trigger notification sample JCL and report, 317
batch, 204 freeform filtering
explicit data-set trigger notification definition, 247
Connect:Direct (NDM) run task to display the critical path, 211
example, 204 FTP data-set triggering
invoking CYBESDT1 from page mode ANYCLOSE, 87, 200
or line mode, 203 definition, 11
notification utility program (CYBESDT1), 201 direction, 85, 198
using, 201 dsname, 87, 200
expression Event, 84
comparing, 116 example, 11
definition, 115 FTP RECEIVE and SEND, 85
logical, 115 host specific creation, 85
usage, 115 logon specific creation, 86
EXTERNAL job user-specific creation, 86
authorization string, 181 with operands, 87
controlling, 179 HOST, 85, 198
definition, 408 limiting data set activity to a host, 85
forced complete, 181 limiting data set activity to a user ID, 86
job qualifiers usage, 181 limiting data-set activity
marking complete, 179 to a logon ID, 86
posting options, 181 LOGON, 86, 199
specifying an Application, 180 operand
usage, 178 ANYCLOSE, 87
USERMOD 30, 181 dsname, 87
EXTERNAL, Pnode field, 223 RENAME, 87
EXTMON, definition, 408 RECEIVE, 85, 198
RENAME, 87, 200
SEND, 85, 198
F specifying, 84
FAIL, Pnode field, 223 specifying the direction
file trigger, definition, 408 of the transfer, 85
first day of week, 49 USER, 86, 199
FIRST, scheduling term, 51 workload object, 198
FLOWDOC FTP data-set-trigger workload object
components, 313 example
data base generation, 313 FTP RECEIVE and SEND, 198
data generation, 313 host specific creation, 199
definition, 312 logon specific creation, 200
example sending a message, 200
specific Application sorted by days, 317 user-specific creation, 199
specific Application, specific period, 316

424 ESP-5.4-UG-05
 Index

limiting data set activity to a logon ID, 199 defining held jobs, 153
limiting data-set activity to a host, 198 Event command, 100
limiting data-set activity to a user ID, 199 field in reports, 315
specifying the direction of the transfer, 198 hold count, 138
using, 198 hold count field in reports, 315
Functions of ESP Workload Manager, 8 holding a data-set-triggered Event, 80
holding an Application in CSF, 233
holding an Event, 104
G holding and releasing an Event, 104
generation holding subApplication in CSF, 233
number, of an application, 140 listing jobs on, 125
phase of an Application, 139 manual hold Pnode, 223
GENTIME, 57 operand of JOB, 153
global variable table postponing execution of an Event, 104
definition, 22 suppressing hold count field in reports, 308
retrieving a variable from, 114 holiday
triggering, 12 defining, 65
triggering, example, 12 defining a holiday using a panel, 66
global variable, definition, 408 defining a repetitive, 66
graphical user interface, 20 defining a static, 129
groups, 332 displaying, 63
Event processing of, 66
H example
HAO advancing / delaying a job, 67
ARM support, 398 defining, 65
definition, 393, 407 defining a repetitive, 66
XCF routing, 400 defining using a panel, 66
XCF status monitoring, 399 job processing of, 67
HELP facility, 33 LISTHOL command to list, 63
Help panels, 35 start date, 65
High Availability Option, 393, 407 time duration, 65
High Performance Option, 377, 408 using to schedule, 66
history HOLIDAYS, scheduling term, 51
example of report, 28 HOST
fields to use as selection criteria limiting data set activity to a, 85, 198
for reporting, 28 security check (EXPEDITE), 380
reporting, 28, 276 security programs, 30
history reporting field HOURLY, scheduling term, 51
accumulating, 297 HPO
list, 289 definition, 377, 408
numeric, 296 expedite, 378
HOLD resource balancing, 382
an Event from being processed at XCF routing, 388
a particular time, 80 XCF status monitoring, 387
and APPLEND, 190
application hold Pnode, 223 I
command, 104 IF
controlling Event scheduling, 79 statement in Procedure, 110

ESP-5.4-UG-05 425
 use in documentation, 268 generate a copy for every job, 147
using instead of TEMPLIB, 146 identifying JCL libraries, 143
using parenthesis, 115 issuing commands in batch, 4
IF-THEN-ELSE limiting the use of temporary, 147
example of use, 112 routing jobs to other systems, 329
in job documentation, 266 specifying a library, 143
indentation, 3 specifying a library for a single job, 145
index entries, displaying, 234 specifying a temporary library, 144
info records, displaying, 234 submitting in an Event, 91
INFOMSG command, 37 submitting JCL from Librarian and
inheriting, job relationships, 14 Panvalet data set, 92
initialization parameter, definition, 408 tailoring, 22
Input line entry, 36 writing to a GDG, 148
INPUT, Pnode field, 223 JCL, editing the last executed, 234
interception, system message, 26 JCLLIB, definition, 409
INVOKE JES status of a job, displaying, 234
an ESP Procedure, 93, 109, 219, 264 JES, format of job ID, 409
command, 131 job
command, in Event, 93 bypassing, 160
ISPF interface canceling a PeopleSoft, 235
controlling Events, 100 changing job attributes, 192
retrieving information, 269 completing, 233
screen, 32 CRITICAL operand, 153
ISPF option, 32 defining
ISPF panels conditional jobs, 153
accessing, 100 critical jobs, 153
exiting ESP Workload Manager, 40 held jobs, 153
special periods, 69 requirements, 155
Issuing operator command, using Event, 95 with different attributes, 192
IW, CSF command, 234 delay
release
using the RELDELAY statement, 156
J
submission, 155
JANCWAIT, Pnode field, 223 different types, 177
JCL displaying
control the use of temporary, 146 resources, 234
copying, 94 duplicate names, 150
creating a copy, 94 example
example changing a job attribute, 192
creating a scheduled activity data set, 301 combined statement, 150
report generation, 317 delaying submission of a job from
reporting in batch, 288 ready time, 156
tailoring, 22 identifying a delayed submission time, 156
updating a scheduled activity data set, 301 multiple runs of a job, 150
executing ESP Workload Manager on-request, 152
commands in batch, 38 qualified jobs, 150
FLOWDOC data base generation, 313 sending messages at different stages, 154
FLOWDOC data generation, 313 specifying a due-out time, 158
FLOWDOC report generation, 314

426 ESP-5.4-UG-05
 Index

specifying a late submission time, 158 converting an existing PDS job

using different submission times, 156 documentation library into an
expediting manually, 235 ESP Workload Manager documentation
external, 178 library, 271
holding with a reason, 234 converting existing, 271
identifying as on-request, 151 creating, 260
inserting, 234 creating a job documentation member
after a selected, 234 for a job, 261
before a selected, 234 customized labels, 260
mapping, 29 DOCMEM method, 266
monitoring, 25 example
on-request, 16 control information, 259
other methods for handling on-request, 152 documenting a job and a link, 268
qualifying, 149 documenting links and tasks, 268
readying, 234 ESP Procedure, 264
releasing, 233 overriding, 265
REQUEST operand, 151 retrieving job-documentation
requesting, 234 information, 270
requesting the job, 153 start of job documentation, 258
rerunning, 234 storing phone numbers, 273
restarting, 234 updating, 263
resubmitting, 234 using GENDOC to convert job doc., 272
retrieving a distributed spool file, 235 with customized labels, 260
scope of a JOB statement, 154 IF-THEN-ELSE method, 266
selecting distributed option, 235 job qualifier, 266
specifying time dependencies, 155 other uses, 273
tracking, 24 overriding rules, 265
tracking, example, 25 referencing members, 265
un-bypassing, 235 relationship with Event and Procedure, 264
un-requesting, 235 retrieving information, 269
un-waiting, 235 retrieving your existing job documentation
using symbolic variables as qualifiers, 149 through ESP Workload Manager, 271
z/OS, canceling and purging in JES, 234 storing requirements, 259
z/OS, canceling in JES, 233 temporary override, 266
z/OS, canceling in JES with a dump, 234 updating, 262
z/OS, executing on a goal mode system, resuming user description, 259
the original service class of, 234 using, 263
z/OS, executing on a goal mode, quiescing, 234 using an operator console, 270
z/OS, issuing using CSF, 269
a JES hold command on a, 234 using for links and tasks, 267
a JES release command on a, 233 using for qualified jobs, 266
a system STOP command on an using the control information, 264
executing, 234 using the jobs option, 261
z/OS, owner of a, 365 using TSO, 269
job documentation, 19 job ID, definition, 409
commands, 272 job mapping, 303
contents, 258 job monitor, definition, 409
control information, 258 job relationships, inheriting, 14

ESP-5.4-UG-05 427
 job submitting how to work in, 39
from Librarian, 92 invoking CYBESDT1, example, 90, 203
using Event, 91 invoking ESP Workload Manager
job tracking, XCF Service, 371 in, from CSF, 247
JOB, statement, 149 retrieving job-documentation information, 270
JOBENQ, example, 170 link
JOBMAP, command, 305 definition, 16, 409
JOBONQ example, 17
built-in function, 118, 125 issuing a command, 186
example, 126 keeping an Application active, 186
returning values, 125 notifying when an Application
using with REEXEC, 126 completes, 187
variables, 125 sending messages, 185
JOBRES, 338 simplifying job relationships, 185
JOBTREE, command, 309 starting a task, taking action after
JUMPTO, statement in Procedure, 112 completion, 187
LINK operand of JOB statement, 184
owner, 365
L
usage, 16, 184
label uses, 186
customizing for job documentation, 260 vs. task, 185
in ESP Procedures, 110 LIST
in job documentation, 259 command, 101
use in ESP Procedures, 110 Event command, 100
LABEL, command of GENDOC, 272 listing Events, 101
LAST, scheduling term, 51 RESDEF command operand, 340
LDTE, command, 84 LISTCAL
LDXE command, 62
command, 84 display a calendar, 62
example, 197 displaying holidays and special days, 63
to display data-set-triggering information, 197 LISTHOL, command, 63
LENGTH LISTSCH
built-in function, 118, 123 command, 98
example displaying scheduled Events, 98
calculating the length of a symbol, 123 LISTSPEC, command, 63
extracting the last character of a LOAD
variable length symbol, 124 command, 40
LESS, scheduling term, 51 example, loading diagnostic commands
Librarian from a data set, 41
data sets load a report definition, 281
as input, 42 load an Event definition, 74
ESP Procedure, 3, 109 loading commands, 40
submitting jobs, 92 logical calendar, 65
data-set prefix, 42 logical day
submitting a job directly from defining your organization, 64
a Librarian data set, 92 specifying, 64
LIBSUB, command, 92, 131 vs. absolute day, 49
line mode logical day, definition, 409
exiting ESP Workload Manager in, 40

428 ESP-5.4-UG-05
 Index

logical expression, 115 example, 15

logical operators
list, 116
N
order of precedence, 116
LOGICAL, scheduling term, 51 NEXT
logon ID, limiting data-set activity to a, 86, 199 command, 99
logon specific creation, example, 86, 200 displaying the next scheduled
LR, CSF command, 245 executions of an Event, 99
LSAR, command, 300 Non-z/OS workload, 19
NOSCHED
command, 78
M handling exceptions, 78
MAILLIST, 97, 206 notification list, 97, 206
main menu NOTWITH
options, 33 automatic generation of
screen, 32 ENQUEUE commands, 172
MANHOLD, Pnode field, 223 definition, 409
MANSUB, Pnode field, 223 examples, 173
MANUAL job excluding jobs from a
authorization string, 184 NOTWITH statement, 174
controlling, 183 removing mutual exclusivity, 174
defining, 182 specifying mutually exclusive jobs, 172
definition, 409 statement, 171
example NOW
on certain days, 182 difference with REALNOW, 53
sending a message, 182 scheduling term, 51
forced complete, 184
marking complete, 183
O
posting options, 184
usage, 182 OF, scheduling term, 52
mapping, jobs, 29 ONCE, scheduling term, 52
master, definition, 409 one-time Event
MAXRUNTIME, 162 example, 78
MAXRUNTIME, using to set DUEOUT EXEC scheduling a, 77
time, 162 on-request jobs, 16, 151
ME, CSF command, 246 operand, definition, 409
menu panels in ESP Workload Manager, 33 operator commands
MIDDAY, scheduling term, 51 from Events, 95
MIDNIGHT, scheduling term, 51 issuing, 95
MINRUNTIME, 162 operator precedence, 115
modeling operators
definition, 29 arithmetic, 115
reports, 30 comparison, 116
MODIFY command, 4 comparison, in reports, 279
MONTHLY, scheduling term, 51 in CRITERIA command (reports), 282
MR, CSF command, 246 logical, 116
mutual exclusivity, removing, 168, 174 order of precedence, 116
mutually exclusive run requirements relational, in CSF, 253
definition, 15 using, 115

ESP-5.4-UG-05 429
 OR, scheduling term, 52 EXEC, 223
overdue Event, 78, 105 EXTERNAL, 223
OVERDUE, scheduling term, 52 FAIL, 223
INPUT, 223
JANCWAIT, 223
P MANHOLD, 223
page mode MANSUB, 223
benefit, 32 PREDWAIT, 223
comparing with ISPF Browse, 36 READY, 223
displaying informational messages, 37 RESWAIT, 223
displaying informational messages SANCWAIT, 223
where they occur in the input instead of SUBDELAY, 223, 224
at the top of the screen, 37 SUBERROR, 223, 224
exiting ESP Workload Manager in, 40 SYSERROR, 223
how to use, 36 TASK, 223
invoking CYBESDT1, 90, 203 WAITING, 223
retrieving job-documentation Pnode Application states, definition, 410
information in, 270 positional operand, definition, 410
returning informational messages post, definition, 410
to the top of the screen, 38 POSTREQ, statement, 165
screen example, 36 predecessor, definition, 410
switch to from main menu, 34 PREDWAIT, Pnode field, 223
usage, 36 PREMEND operand, notification and alerting
using JOBMAP in, 306 process, 162
using JOBTREE in, example, 309 PREREQ, statement, 165
using other commands in CSF, 247 previous line, re-entering, 36
using the screens, 37 PRIORITY statement, using, 332
page mode, definition, 409 Procedure, See ESP Procedure
Panvalet data sets PROCLIB, definition, 410
as input, 42 propagating dueout times
ESP Procedures, 3, 109 example, 159
submitting JCL from, 92 how to, 158
submitting jobs, 93 proxy, definition, 411
Panvalet, prefix for data sets, 42 purging a service, example (XCF), 373
PeopleSoft, canceling a job, 235
period, See special period
planning Q
Applications to optimize qualifier, definition, 410
Distributed Manager, 360 QUEUE file, 371
calendars, 60 QUIESCE, command, 396
example, planning for a system shutdown, 353 QUIT
PLUS, scheduling term, 52 encountered, SUBERROR Pnode, 225
Pnode example, 113
definition, 410 statement in Procedure, 112
list of, 223
APPLHOLD, 223
R
APPLWAIT, 223
BYPASSED, 223 READY, Pnode field, 223
COMPLETE, 223 REALNOW

430 ESP-5.4-UG-05
 Index

difference with NOW, 53 specifying a format, 287

scheduling term, 52 updating a scheduled activity data set, 301
redirecting Event messages to a notification list, 97 using JOBMAP in batch, 306
RELEASE using JOBMAP in Page mode, 306
Event command, 100 using JOBTREE in batch, 309
statement, 165 using JOBTREE in page mode, 309
RELEASE command, in Event, 80 with MAPGEN, all jobs, 304
RENAME, FTP data-set trigger operand, 87, 200 with MAPGEN, selected jobs, 305
renewable resource writing report output to a data set, 289
definition, 24, 327 extracting data, 299
example extracting tape information, 302
controlling access to a data base, 349 field
controlling mutually exclusive jobs, 345 categories, 278
defining a, 336 character, 278
usage, 346 comparisons, 279
renewable resource, definition, 410 CPU time, 280
replying to an AS/400 message, 234 date, 280
report elapsed time, 279
content, 277 example
creating flowcharts, 318 character, 278
customizing your job-activity report, 307 comparisons, 279
ending the report definition, 287 CPU time, 280
example date, 280
creating a scheduled activity data set, 301 elapsed time, 280
DATEFORM, 285 numeric, 278
displaying scheduled activity data, 300 time, 279
job-descendent report specific formats, 278
to an Application, 310 numeric, 278
multiple criteria, 286 time, 279
reporting in batch, 288 flowcharting, 318
reporting on an Application, 287 generating an index, 307
SADGEN, 299 generating data, 298
sample batch job for putting it all generating data for the report, 304
together, 311 generating flow charts with ESP Workload
selecting jobs based on EXCP Manager and Timeline, 321
and CPU time, 284 generating flowcharts using MS Project, 319
selecting jobs based on multiple criteria, 284 generating for a specific Application, 307
selecting jobs belonging to an generating projected versus actual data, 302
Application, 283 generating scheduled versus actual report, 301
selecting jobs submitted outside identifying the history file, 281
an Application, 283 Invoking the function, 281
selecting jobs that belong to an Application job-mapping data set, 304
and start with a letter, 283 producing a job-activity report, 305
selecting jobs that belong to an Application producing a job-descendent report, 309
or start with a letter, 283 putting it all together, 311
selecting jobs that ended during reviewing the job-activity output, 307
a certain time, 283 reviewing the job-descendent output, 310
selecting jobs that have restarted, 283 scheduled activity, 298

ESP-5.4-UG-05 431
 sections, 277 displaying requirements for jobs not yet
separating data into different files, 284 submitted in an active Application, 341
setting up job mapping, 304 displaying the resources associated with
setting up schedule forecasting, 298 a job and determine what jobs have
specifying an output data set, 284 resources allocated, 340
specifying fields to display, 285 displaying the resources of a job, 234
specifying input criteria, 281 dropping default, 332
specifying other formats, 286 dropping requirements, 331
specifying output criteria, 284 example
specifying the date format, 285 ABSORB statement, 343
specifying the selection criteria, 282 adding requirements, 331
specifying the sort criteria, 286 Application with absorption, 344
specifying the time range, 282 Application with absorption (CSF), 344
structuring, 276 changing, 337
suppressing fields, 308 controlling access to a data base, 349
testing and using the GENFLOW feature, 321 controlling access to an online system, 346
testing and using the GENPROJ feature, 319 controlling mutually exclusive
using a history file other than current, 281 groups of jobs, 350
using job mapping, 303 controlling mutually exclusive jobs, 345
using the JOBMAP command, 305 default scratch tape resource, 334
using the JOBTREE command, 309 defining a real resource, 337
reporting defining a renewable resource, 336
definition, 27 defining a threshold resource, 336
history, 28, 276 dropping default, 332
in batch, 276 dropping requirements, 332
REQUEST, 151 long resource name with no restrictions, 336
RESDEF with MONITOR(CPU) operand, planning for a system shutdown - Part
coding, 385 1, 353
RESDEF, command, 335 planning for a system shutdown - Part
resetting, User Status field, 235 2, 354
resource real devices, 328
absorption, 342 requesting resources, 331
adding requirements, 331 routing jobs on other systems, 329
balancing, 382 running jobs on a particular system, 349
changing, 337 schedule dependency, 356
default, 333 setting priority for more than one job, 333
default assignments, 334 setting priority for one job, 333
defining, 335 STEPEND statement, 342
defining a real resource, 336 time periods for low priority jobs, 347
defining using the RESDEF command, 335 using a resource for a self-completing
definition, 326, 410 task, 348
deleting, 339 examples of different, 326
depletable, 327 excluding default resources for
determining a default assignment, 334 an Application, 335
device counts, 328 gravity, 329
displaying information about a resource, 340 in reports, 315
displaying one or more resources, 340 job requiring multiple, 329
managing jobs, 329

432 ESP-5.4-UG-05
 Index

modifying, 234 definition, 411

removing dependencies, 162 SADUPD, command, 301
renewable, 327 SANCWAIT, Pnode field, 223
requesting, 330 SCHEDULE
requirement, 24 command, 77
scope of, 328 data-set-triggered and scheduled Events, 82
setting, 337 example
setting quantities automatically, 337 schedule exception, 78
setting up default resources, 334 schedule exception once, 78
step-level resource release, 341 examples, 77
threshold, 327 handling exceptions, 78
types, 24 overdue Events, 105
types of, 326 overlapping criteria, 77
using real devices, 328 setting to execute only once, followed
working with, 335 by a deletion of the Event, 77
RESOURCE statement schedule criteria
placing, 330 date format, 47
using, 330 date range, 47
RESREFR, command, 337 days of months, 46
RESUME days of the week, 44
command, 81 definition, 411
command, usage, 104 example
Event command, 100 daily or multiple times a day, 54
resuming an Event, 104 monthly, 55
RESWAIT, Pnode field, 223 multiple times a month, 56
REXX multiple times a week, 54
CSF extensions, 247 one-time examples, 56
definition, 410 testing criteria, 57
in job documentation, 258 weekly, 54
interface, 27 yearly, 56
use of, 27 how to use with data-set triggering, 76
ROUND, scheduling term, 52 implied periods, 48
ROUTING Julian date, 47
command, 389, 401 matching criteria, 48
enabling XCF, 389, 401 month names, 45
examples, 390, 402 ordinal numbers, 47, 53
purpose of command, 390, 402 spaces, 49
service, overview, 388, 400 specifying, 44
XCF service, 388, 400 specifying both an algorithm
routing and a starting date and time, 49
JCL, 329 testing, 57
jobs to other systems, 329 time and frequency, 48
run times, minimum, maximum, average, 162 time of day, 46
RUN, vs. SELECT, 176 time zones, 46
using, 43
using CLANG, 57
S
using GENTIME, 57
SADGEN using other techniques for, 57
command, 298

ESP-5.4-UG-05 433
 using the first day of the week, 49 STARTING, 52
using workdays, 49 TIMES, 51
where you can use, 44 TODAY, 52
scheduled activity, report, 29, 300 TOMORROW, 53
scheduled Event UNTIL, 53
adding execution, 103 WEEKDAYS, 53
bypassing, 103 WEEKENDS, 53
displaying, 98 WITHIN, 53
SCHEDULED, operand of JOB statement, 180 workday, 49
scheduling WORKDAYS, 53
controlling Event, 79 YEARLY, 53
Event, 77 YESTERDAY, 53
example SCOPE
a job on the last day of the month, 132 operand of JOB statement, 154, 180
an hourly Event during a time range, 81 report heading, 315
one-time Event, 77 suppressing field in a report, 308
time and date, 9 screen
time zone abbreviations for, 46 ISPF interface, 34
scheduling term Main Menu, 32
list, 50 Page mode, 36
using in calendars, 64 script, definition, 411
ABSOLUTE, 50 security
AND, 50 authorized commands, 3
ANYDAY, 50 authorized OPER commands, 3
COMPLETE, 50 calendar, 58
DAILY, 50 definition, 30
EACH, 50 for Applications, 142
ENDING, 50 for EXPEDITE statement, 380
EVERY, 50 FTP transfer-triggered Event, 200
EXCEPT, 51 limiting data set activity to a user, 83
FIRST, 51 limiting data-set activity to a user ID, 86, 199
first day of week, 49 naming Events, 74
HOLIDAYS, 51 use of the Event prefix, 75
HOURLY, 51 SELECT, vs. RUN, 176
LAST, 51 SELECTED
LESS, 51 built-in function, 117, 122
LOGICAL, 51 built-in function syntax, 122
MIDDAY, 51 example
MIDNIGHT, 51 selecting a job when
MONTHLY, 51 another is not selected, 122
NOW, 51 selecting one job based on another, 122
OF, 52 SEND
ONCE, 52 command, 131
OR, 52 example, sending messages at different
OVERDUE, 52 stages, 154
PLUS, 52 using Events to send messages, 91
REALNOW, 52 sending messages, 91
ROUND, 52 services

434 ESP-5.4-UG-05
 Index

description, 370 simulating

displaying, 372 an Event, 101
enabling, 371 an Event, example, 102
purging, 373 special day
starting, 372 defining, 67
XCF DSTRIG, 370, 390, 402 definition, 411
XCF SCOREBD, 390, 402 displaying, 63
XCF scoreboard, 390, 402 example, 68
XCF TRACKING, 370, 390, 402 defining, 68
setting symbol libraries, 96 using REPEAT, 68
SHADGOAL listing, 63
command, 395, 396 usage, 58
defining a shadow goal, 395 using to schedule, 68
examples, 397 special period
shadow goal defining, 67
defining, 395 defining the first day of, 68
definition, 395 defining using ISPF panels, 69
deleting, 396 definition, 68, 411
how does it work, 395 example
listing, 396 defining fiscal years, 69
what action it can take, 395 defining payroll periods, 69
shadow manager, 394 quarters and fiscal years, 72
%SHADOW symbolic variable, 395 intervals, 69
and ARM, 399 listing, 63
data-set usage, 394 using, 58
definition, 411 using to schedule, 70
description, 394 working, 70
example of moving control to, 397 SPIN TRACE, 374
SHADGOAL command, 396 start service, starting XCF services, 372
shadow goal, 395 START, shadow manager operand, 394
shadow-disabled ESP master, 394 STARTING, scheduling term, 52
shadow-enabled, 394 state awareness, 373
shadow-enabled ESP master, 394 statement
START operand, 394 definition, 411
START operands, 394 entering, 2
switching control to, 397 ABSORB, 343
usage, 394 AFTER, 165
z/OS MODIFY command, 398 COREQ, 165
shadow-enabled ESP Workload Manager DO, 111
master, 394 ELSE, 110
SIGCYCLE, command, 131 ENDDO, 111
SIGPOST, command, 131 EXIT, 111
SIMULATE EXPEDITE, 379
command, 101 IF, 110
Event command, 100 JOB, 149
options, 102 JUMPTO, 112
options to specify, 102 NOTWITH, 171
results, 101 POSTREQ, 165

ESP-5.4-UG-05 435
 PREREQ, 165 symbol library
PRIORITY, 332 setting, 96
QUIT, 112 specifying in Event, 96
RELEASE, 165 symbolic variable
RESOURCE, 330 %SHADOW, 395
STEPEND, 341 ‰ESPAPTAG, 205
TAG, 205 ‰ESPATIME, 203
THEN, 110 ‰ESPTRDSN, 81
status of ENQSELF, 171 ‰ESPTRGDG, 203
STEPEND, statement syntax, 341 as qualifiers, 149
step-level statistics, displaying, 234 attributes of, 21
STEPLIB, 38 definition, 21, 412
stopping XCF services, 372 determining length, 123
subApplication embedding in strings, 114
controlling, 214 ESP_APPL_PROC, 139
definition, 411 ESPAPQUAL, 266
displaying, 214 example
example notifying when an
coding, 213 Application completes, 187
requesting a subApplication, 214 representing a scheduled date, 22
identifying, 212 usage, 114
selecting, 213 using a different TEMPLIB based on year
using, 212 and day, 147
SUBDELAY, Pnode field, 223 generating with GENTIME, 57
SUBERROR, Pnode field, 223 MAXRUNTIME, 162
SUBMIT MINRUNTIME, 162
command, 91 stored in SYMLIB, 411
Event command, 131 substring, 123
submitting multiple jobs, example, 92 symbol introducer, 110
using Events to submit JCL, 91 to tailor JCL, 22
SUBSTR using function for, 123
built-in function, 118, 123 using in ESP Procedures, 113
example SYMLIB
extracting the last character command, 96
of a variable length symbol, 124 setting symbol libraries, 96
using a substring of a time variable, 124 SYMLIB, definition, 411
subsystem name, 38 syntax conventions, 5
successor, definition, 411 SYSERROR, Pnode field, 223
SUSPEND sysmsg, definition, 411
bypassing execution of an Event, 104 SYSTEM calendar
command, 81 definition, 59
Event command, 100 example
example changing the first
scheduling an hourly Event day of the week, 62
during a time range, 81 defining, 61
suspending an Event, 104 displaying, 63
usage, 104 referencing, 64
symbol introducer character, 110, 114 search order, 97

436 ESP-5.4-UG-05
 Index

system console, issuing command from, 4 time and date scheduling, 9

system identifier time dependency
altering, 105 resetting, 235
Event, 76 TIMES, scheduling term, 51
system message interception TODAY
definition, 26 built-in function, 117, 120
example, 26 example, 120
scheduling term, 52
TOMORROW
T
built-in function, 117, 120
TAG example, 121
definition, 411 scheduling term, 53
statement, 205 trace
TAPES, built-in function, 118, 126 activating XCF trace, 374
task SPIN TRACE, 374
definition, 17, 411 XCF trace facility, 374
example tracking
checking a report, 188 jobs, 24
specifying a due-out time for a task, 158 models, 25
usage, 17 tracking model, definition, 411
marking complete, 188 TRIGGER
owner, 365 adding execution, 103
uses, 189 command, 102
using, 188 Event command, 100
vs. link, 185 example
TASK, Pnode field, 223 creating and triggering an Event, 212
template triggering an Event, 212
defining, 129 trigger
example different ways to trigger an Event, 10
defining a static holiday, 129 for a data set, 10
defining similar jobs, 130 kinds of, 109
using, 129 triggering an Event
using a template you have defined, 129 creating and, example, 212
TEMPLIB, definition, 411 example, 212
TEST, command, 57 manually, 102
testing schedule criteria, 57 triggering expected Events, 99
THEN TSO command processor, accessing ESP
statement in Procedure, 110 Workload Manager through a, 40
terminator of IF expression, 115 TSO mode message, 39
threshold resource turning on the TSO mode message, 39
definition, 24, 327
displaying, 340
example U
defining, 336 UNTIL, scheduling term, 53
schedule dependency, 356 updating an Info record, 235
time periods for USE, command, 35
low priority jobs, 347 USER
usage, 327 example, user-specific creation, 199
threshold resource, definition, 410 operand

ESP-5.4-UG-05 437
 limiting data set activity to a user, 83, 196 (Agent) requirements, 339, 385
limiting data set activity to a user (Agent) scenario using, 386
ID, 86, 199 (WLM) requirements, 338, 382
user (WLM) scenario using, 384
setting and resetting the status field, 245 description, 382
setting the status field, 225 workload object
user data sets, definition, 412 definition, 137, 412
user-defined variables, definition, 113 establishing ownership of a, 364
owner of a distributed, 365
type in history file, 295
V
Workstation, See ESP Workstation
variable writing session data, 37
AUTOVAR, definition, 406
definition, 412
example X
basic, 21 XCF
defining an undefined variable, 123 command examples, 397
retrieving a variable from commands, 370
a global variable table, 114 Display Service connections, 372
using a substring of a time variable, 124 displaying the members in the XCF group
using symbolic variables, 114 and their respective states, 374
global, definition, 412 how status monitoring works, 387, 399
length, 123 manually moving control, 397
symbolic, definition, 412 member failure, 388, 400
use of symbol introducer, 114 member or group member termination, 396
using, 21 migrating from QUEUE file, 371
viewing ESP Encore panels, 234 Purging a Service, 373
VS QUEUE file migration, 371
command, 95 routing service, 388, 400
Event command, 131 benefit, 389, 401
issuing an operator command, 95 description, 389, 401
overview, 388, 400
Services, 371
W
Start Service, 372
WAITING, Pnode field, 223 State awareness, 373
WEEKDAYS, scheduling term, 53 status monitoring, 387, 399
WEEKENDS, scheduling term, 53 Stop Service, 372
wildcard, masking, 3 stopping all the XCF members in the
WITHIN, scheduling term, 53 XCF group simultaneously, 374
WLM workload balancing stopping an XCF member, 374
introduction, 382 Trace, 374
scenario using, 384 XCF ROUTING
using, 338 command syntax, 389, 401
workday enabling, 389, 401
default, 60 ROUTING command, 389, 401
using, 49 XCF SCOREBOARD, 390, 402
workday, definition, 412 XCF service
WORKDAYS, scheduling term, 53 description, 370
workload balancing displaying, 372

438 ESP-5.4-UG-05
 Index

displaying active connections, 372 enabling XCF SCOREBD, 403

enabling, 371 restarting an XCF Service on
example the fly after it has been stopped, 372
purging, 373 starting XCF services, 372
restarted, 373 XCF trace facility
purging, 373 debug tool for XCF, 374
restarting on the fly after it has definition, 374
been stopped, 372 XCF trace, activating and capturing
scoreboard data using, 374
benefit, 391, 403
definition, 390, 402
starting, 372
Y
stopping, 372 YEARLY, scheduling term, 53
XCF DSTRIG, 370, 390, 402 YESTERDAY
XCF SCOREBD, 390, 402 built-in function, 117, 121
XCF scoreboard, 390, 402 example
XCF TRACKING, 370, 390, 402 process only if YESTERDAY
XCF SPIN TRACE, command, 374 was a holiday, 121
XCF START SERVICE process only if YESTERDAY
command, 371 was the first day of the month, 121
enabling XCF routing, 389, 391, 401 scheduling term, 53

ESP-5.4-UG-05 439
440 ESP-5.4-UG-05