esp workload manager user’s guide

ESP Workload Manager Version 5.4

User’s Guide

ESP-5.4-UG-05

Fifth Edition (April 2005)

This edition applies to Version 5 Release 4 of ESP Workload Manager documentation. The software and related manuals are protected by copyright law.

Trademark Notice

Cybermation and ESP Workload Manager are registered trademarks of Cybermation, Inc.

IBM, AS/400, and z/OS are registered trademarks of IBM.

All other brand and product names are trademarks or registered trademarks of their respective companies.

ESP Workload Manager documentation© 2005 Cybermation Inc. All rights reserved.

No portion of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written permission of

Cybermation International Distribution SRLwww.cybermation.com

U.S. Government Users. RESTRICTED RIGHTS—Use, duplication or disclosure restricted by the GSA ADP Schedule Contract with Cybermation USA, Inc., a subsidiary of Cybermation International Distribution SRL.

ESP-5.4-UG-05 iii

Contents

About this guide 1Who should read this guide................................................................................ 2How to use this guide ........................................................................................ 2Entering commands ........................................................................................... 2Entering statements............................................................................................ 2Examples............................................................................................................ 4Conventions used in this guide .......................................................................... 5Summary of changes .......................................................................................... 6

1 Introduction to ESP Workload Manager Concepts 7Functions of ESP Workload Manager ................................................................ 8Time and date scheduling .................................................................................. 9ESP Workload Manager Events ......................................................................... 9Data-set triggering............................................................................................ 10Global-variable-table triggering ........................................................................ 12ESP Procedures ................................................................................................ 12Applications ..................................................................................................... 13Inheriting job relationships .............................................................................. 14Mutually exclusive run requirements................................................................ 15On-request jobs................................................................................................ 16Links ................................................................................................................ 16Tasks................................................................................................................ 17APPLEND workload object ............................................................................. 18

iv ESP-5.4-UG-05

Distributed workload objects ........................................................................... 19Job documentation........................................................................................... 19Consolidated Status Facility (CSF)................................................................... 20Graphical user interface.................................................................................... 20Symbolic variables ............................................................................................ 21Tailoring Job Control Language....................................................................... 22Resources ......................................................................................................... 23Tracking jobs ................................................................................................... 24Job monitoring and alert processing ................................................................. 25System message interception ............................................................................ 26REXX interface ................................................................................................ 27Reporting......................................................................................................... 27Modeling ......................................................................................................... 29Security ............................................................................................................ 30

2 Getting Started 31Accessing ESP Workload Manager ................................................................... 32Accessing ESP Workload Manager as an ISPF option ...................................... 32Accessing ESP Workload Manager through a batch program ........................... 38Invoking ESP Workload Manager as a program in TSO .................................. 39Accessing ESP Workload Manager through

a TSO command processor............................................................................ 40Exiting ESP Workload Manager ...................................................................... 40Loading commands.......................................................................................... 40Alternative input data sets ................................................................................ 42

3 Schedule Criteria 43Where you can use schedule criteria ................................................................. 44Specifying schedule criteria............................................................................... 44Schedule terms ................................................................................................. 50Using other techniques for schedule criteria ..................................................... 57Testing schedule criteria ................................................................................... 57Using calendars ................................................................................................ 58Using calendar terms........................................................................................ 59Working with calendars ................................................................................... 60Defining holidays............................................................................................. 65Defining special days........................................................................................ 67Special periods ................................................................................................. 68Working with periods ...................................................................................... 70

4 Processing ESP Events 73Defining an ESP Event .................................................................................... 74Specifying data-set-triggered Events ................................................................. 81Specifying FTP data-set triggered Events.......................................................... 84Specifying explicit-data-set triggers................................................................... 87Specifying the function of an Event.................................................................. 91

Contents

ESP-5.4-UG-05 v

Issuing operator commands.............................................................................. 95Specifying other requirements .......................................................................... 96Displaying the schedule.................................................................................... 98Displaying when an Event will execute............................................................. 99Working with defined Events......................................................................... 100

5 Working with ESP Procedures 107Overview of ESP Procedures .......................................................................... 108Invoking an ESP Procedure............................................................................ 108ESP Procedure syntax..................................................................................... 109Using ESP Workload Manager control language in Procedures...................... 110Using symbolic variables in Procedures .......................................................... 113Using expressions and strings in Procedures ................................................... 114Built-in functions........................................................................................... 117Using calendaring functions ........................................................................... 118Using functions for job selection .................................................................... 122Using functions for symbolic variables ........................................................... 123Using system activity functions ...................................................................... 124Combining functions ..................................................................................... 127Re-executing an ESP Procedure ..................................................................... 128Using templates.............................................................................................. 129Using Event definition commands in Procedures ........................................... 131CLANG examples .......................................................................................... 132Caching an ESP Workload Manager Procedure ............................................. 135

6 Using Applications 137Introducing Applications................................................................................ 138Identifying the Application ............................................................................ 142Identifying JCL libraries................................................................................. 143Identifying jobs .............................................................................................. 149Defining job requirements ............................................................................. 155Specifying time dependencies ......................................................................... 155Specifying job relationships ............................................................................ 165Using Implicit Resources................................................................................ 166Selecting jobs for submission.......................................................................... 175Using different job types ................................................................................ 177Defining external jobs .................................................................................... 178Defining manual jobs..................................................................................... 182Using links ..................................................................................................... 184Using tasks ..................................................................................................... 188Using APPLEND workload object................................................................. 190Changing job attributes.................................................................................. 192Using data-set-trigger workload objects .......................................................... 193Using FTP data-set-trigger workload objects .................................................. 198Using explicit-data-set-trigger workload objects ............................................. 201

vi ESP-5.4-UG-05

Tagging jobs .................................................................................................. 205Providing notification on Job status ............................................................... 206Using critical-path analysis ............................................................................. 208Issuing ESP Workload Manager commands ................................................... 211Using subApplications.................................................................................... 212Working with Applications ............................................................................ 215Displaying an Application .............................................................................. 215Controlling an Application ............................................................................ 216Changing an Application definition ............................................................... 218Invoking an ESP Application ......................................................................... 219

7 Consolidated Status Facility (CSF) 221Setting up CSF views ..................................................................................... 222CSF fields ...................................................................................................... 223Defining a view .............................................................................................. 226Customizing a view ........................................................................................ 227Updating a view ............................................................................................. 231Deleting a view .............................................................................................. 232Selecting views ............................................................................................... 232Commands .................................................................................................... 232Inserting a job ................................................................................................ 235Resubmitting a job......................................................................................... 237Rerunning multiple jobs................................................................................. 238Removing job dependencies ........................................................................... 239Resetting a time dependency .......................................................................... 240Bypassing and completing jobs....................................................................... 242Adding job dependencies ............................................................................... 243Adding a job with a time dependency ............................................................ 243Adding a job relationship in an Application ................................................... 243Adding a LINK process .................................................................................. 244Setting and resetting the user status field ........................................................ 244Modifying a Job Resources or Enqueues......................................................... 245Using other commands .................................................................................. 247Extensions to CSF.......................................................................................... 247Freeform filtering ........................................................................................... 247

8 Job Documentation 257Contents of job documentation...................................................................... 258Control information....................................................................................... 258User description ............................................................................................. 259Creating job documentation .......................................................................... 260Using the jobs option..................................................................................... 261Updating job documentation ......................................................................... 262Using job documentation............................................................................... 263Using the control information........................................................................ 264

Contents

ESP-5.4-UG-05 vii

Referencing job-documentation members ...................................................... 265Overriding job documentation....................................................................... 265Using job documentation for qualified jobs.................................................... 266Using job documentation for links and tasks.................................................. 267Retrieving information................................................................................... 269Converting existing job documentation.......................................................... 271Other uses of job documentation ................................................................... 273

9 Creating Reports 275History reporting ........................................................................................... 276Structuring the report .................................................................................... 276Reporting fields.............................................................................................. 277Field formats .................................................................................................. 278Invoking the report function .......................................................................... 281Specifying input criteria ................................................................................. 281Specifying output criteria ............................................................................... 284Ending the report definition........................................................................... 287ESP Workload Manager history reporting fields............................................. 289Accumulating reporting fields ........................................................................ 297Reporting on scheduled activity ..................................................................... 298Generating data.............................................................................................. 298Extracting data ............................................................................................... 299Generating scheduled versus actual report ...................................................... 301Generating projected versus actual data .......................................................... 302Extracting tape information ........................................................................... 302Using job mapping......................................................................................... 303Producing a job-descendent report ................................................................. 309Putting it all together ..................................................................................... 311ESP Workload Manager FLOWDOC ........................................................... 312Flowcharting .................................................................................................. 318Generating flowcharts using MS Project......................................................... 319Generating flow charts with ESP Workload Manager and Timeline............... 321

10 Using Resources 325What is a resource?......................................................................................... 326Types of resources .......................................................................................... 326Scope of resources .......................................................................................... 328Using real devices ........................................................................................... 328Routing jobs to other systems......................................................................... 329Managing jobs................................................................................................ 329Requesting resources ...................................................................................... 330Default resources............................................................................................ 333Working with resources.................................................................................. 335Defining resources.......................................................................................... 335Setting resources............................................................................................. 337

viii ESP-5.4-UG-05

Modifying Resources...................................................................................... 338WLM Workload Balancing............................................................................ 338Agent Workload Balancing ............................................................................ 339Deleting resources .......................................................................................... 339Displaying resource information .................................................................... 340Step-level resource release............................................................................... 341Resource absorption ....................................................................................... 342Example: Controlling mutually exclusive jobs ................................................ 345Example: Controlling access to an online system............................................ 346Example: Time periods for low priority jobs .................................................. 347Example: Using a resource for a self-completing task...................................... 348Example: Controlling access to a data base ..................................................... 349Example: Running jobs on a particular system ............................................... 349Example: Controlling mutually exclusive groups of jobs................................. 350Example: Planning for a system shutdown - Part 1......................................... 353Example: Planning for a system shutdown - Part 2......................................... 354Example: Schedule dependency...................................................................... 356

11 Optimizing ESP Applications to UseDistributed Manager 359Planning Applications to optimize Distributed Manager ................................ 360Establishing ownership of a workload object .................................................. 364Creating distributed Applications................................................................... 365Defining ownership of an Application............................................................ 366Changing ownership of an Application .......................................................... 367Changing ownership of an Application dynamically....................................... 368

12 Using XCF with ESP Workload Manager 369Commands .................................................................................................... 370XCF Services .................................................................................................. 370State awareness............................................................................................... 373Trace.............................................................................................................. 374

13 ESP Workload Manager High Performance Option 377Expedite ......................................................................................................... 378Resource Balancing ........................................................................................ 382Workload Balancing....................................................................................... 382XCF Status Monitoring ................................................................................. 387XCF Routing Service ..................................................................................... 388XCF Scoreboard Service................................................................................. 390

14 ESP Workload Manager High Availability Option 393Shadow Manager............................................................................................ 394ARM Registration .......................................................................................... 398XCF Status Monitoring ................................................................................. 399XCF Routing Service ..................................................................................... 400

Contents

ESP-5.4-UG-05 ix

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

Glossary 405

Index 413

x ESP-5.4-UG-05

ESP-5.4-UG-05 1

About this guide

This guide provides you with an intermediate level of instruction for using Enterprise Systems Platform (ESP) Workload Manager, a powerful and versatile system for scheduling jobs and managing workload.

2 ESP-5.4-UG-05

Who should read this guide

This guide’s audience is users whose activities involves scheduling and managing jobs. Because this guide expects users to already have a basic understanding of ESP Workload Manager, Cybermation recommends that new users work through the ESP Workload Manager Getting Started guide first.

How to use this guide

The preliminary chapters, “Introduction to ESP Workload Manager Concepts” on page 7 and “Getting Started” on page 31, provide important background information as a starting point. These sections, along with the glossary and index, are useful reference tools both now and when you are more familiar with the aspects of ESP Workload Manager discussed in this guide. The remaining chapters, Processing ESP Events to ESP Workload Manager High Performance Option, explain ESP Workload Manager in more detail.

Entering commands

ESP Workload Manager commands can be entered in Line mode, Page mode, batch, loaded from a data set (using the LOAD command), or ESP Workstation. Many can also be entered from a system console.

ESP Workload Manager statements must be entered in a data set specific to the type of statement used.

Entering statements

Note: The content of this section also applies to commands and initialization parameters when contained in a data set.

Continuation

Type either a hyphen or a plus sign as the last non-blank character on a line to continue a line of input. If you use a hyphen, leading blanks on the next line are included. If you use a plus sign, leading blanks on the next line are deleted. Blanks preceding the hyphen or the plus sign are retained. Statements cannot extend beyond column 72. The continuation character can be placed in column 72 or before.

About this guide

ESP-5.4-UG-05 3

Note: A hyphen can also be used as a wildcard character. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */).

Wildcards and masking

Many statements, commands, or initialization parameters permit the use of the following wildcard characters (also called masking.):

• An asterisk matches a specific single character.• An hyphen matches zero or more characters. It must be used as the last character

of the value of the operand. If the wildcard hyphen is the last character on the line, it will be interpreted as a continuation character and not as a wildcard. For the hyphen to be interpreted as a wildcard, it must be followed by a semicolon or something else on the line such as a comment: (/* */).

Comments

Enclose comments between /* and */. Comments can be written anywhere in an ESP Workload Manager Procedure or initialization parameter files.

Data sets

Enclose all data-set names in single quotation marks, otherwise ESP Workload Manager adds your TSO data set prefix to the name. Use LIB- or PAN- prefixes to identify Librarian and Panvalet data sets.

Delimiters

Use single quotation marks when you want to denote character strings in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks.

Indentation

You can use indentation to improve readability.

Types of commands

The most frequent types of commands are:

• General commands—issued without general restrictions• OPER commands—must be preceded by the word OPER• Authorized commands—can be issued by users authorized in the security system• Authorized OPER commands—can be issued by users authorized in the security

system and must be preceded by the word OPER

4 ESP-5.4-UG-05

Examples

Issuing console commands

To issue a command from the system console, use the MODIFY command, as in F ESP, where ESP is the started task name. For example:

F ESP,STATUS

Issuing commands in batch

To issue a command in batch, use the following JCL after your job card:

//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *ESP command...ESP command

Subsystem name

If the subsystem name for ESP is not ESP, you need to type the subsystem name when entering a command in batch. For example, if the subsystem name is ESPA, type:

//EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K

Steplib

If the TSO command processor is not in a LINKLIST library, you need a STEPLIB or JOBLIB statement in your JCL. Your statement looks like:

//STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR

Wildcards and masking

To display all calendars:

LISTCAL –

To display all calendars with names containing XY in character positions three and four:

LISTCAL **XY-

To display all calendars with two-character names:

LISTCAL **

About this guide

ESP-5.4-UG-05 5

Conventions used in this guide

Input

ESP Workload Manager is not case sensitive. Even though this guide shows commands in uppercase, when you type a command on the command line, you do not need to type the command in uppercase letters.

Syntax conventions

The syntax diagrams in this guide use the following conventions:

Notation Meaning

Quote marks '' or ' Must be entered as shown.

Comma , Must be entered as shown.

Ellipsis … The operand can be repeated. Do not enter ellipsis.

Lower Case Italics operand

An operand must be substituted. User supplied variable or character string.

Uppercase operand The operand must be spelled as shown. You can enter the command and the operand in either upper or lower case.

OR-bar ( | ) Indicates an exclusive value on left or right of bar. You must enter one of the items. You cannot enter more than one.

Underline _______ If you do not enter one of the operands, the system supplies the underlined operand, this is the default

Parentheses ( ) and special characters

Operand enclosed in parentheses is mandatory and must be entered as shown.

Single operand in square brackets [ ]

Optional operand, do not type the brackets.

Stacked operands in braces { } { }

Mandatory, you must enter one of the operands. You cannot enter more than one.

Stacked operands in square brackets [ ] [ ]

Optional operand, you can enter one value, or none.

Operands with OR-bars ( | ) and square brackets [ ]|[ ]

Optional, mutually exclusive operands. Enter one or none.

Stacked operands in square brackets within braces {[ ]}

Mandatory, you must enter one of these operands. You can enter more than one.

6 ESP-5.4-UG-05

Summary of changes

Changes in edition five

• PTFs SU01813, SU01814, and SU1815; defect DEF12612:

Implement limits for

• Defining a holiday and a special day with the same name• Defining holidays with the same name, start date, and start time

See “Defining holidays” and “Defining special days” in the “Schedule Criteria chapter.

• RFE 2978: Added note about updating a cached procedure. See “Changing an Application definition” section

Changes in edition four

• Corrected screen shot in “Working with periods” on page 70. The third entry, “4 TIMES EVERY 13 WEEKS STARTING AUG 23”should read, “5 TIMES EVERY 13 WEEKS STARTING AUG 23”.

• Changed note in “Using Implicit Resources” on page 166.

ESP-5.4-UG-05 7

Introduction to ESP Workload Manager Concepts

ESP Workload Manager is a flexible and versatile job-scheduling and workload-management system. Many of its basic features are outlined in this guide. Other, more complex and lesser-used functions, are covered in the ESP Workload Manager Advanced User’s Guide.

This chapter contains the following topics:

• Functions of ESP Workload Manager• Time and date scheduling• ESP Workload Manager Events• Data-set triggering• Global-variable-table triggering• ESP Procedures• Applications• Inheriting job relationships• Mutually exclusive run requirements• On-request jobs• Links• Tasks• APPLEND workload object• Distributed workload objects• Job documentation• Consolidated Status Facility (CSF)

Section–Functions of ESP Workload Manager

8 ESP-5.4-UG-05

• Graphical user interface• Symbolic variables• Tailoring Job Control Language• Resources• Tracking jobs• Job monitoring and alert processing• System message interception• REXX interface• Reporting• Modeling• Security

Functions of ESP Workload Manager

You can automate and manage workload in your installation through a variety of functions. They include:

• Scheduling production and non-production jobs• Managing job dependencies• Monitoring and controlling workload on many other platforms in addition to

z/OS• Tailoring JCL• Tracking jobs and started tasks• Providing critical path analysis• Intercepting system messages• Sending messages• Automating start up and shut down of systems• Reporting on jobs• Forecasting future workload• Assessing the impact of a new job or Application• Providing online documentation• Issuing operator commands

Chapter 1–Introduction to ESP Workload Manager Concepts

ESP-5.4-UG-05 9

Time and date scheduling

With ESP Workload Manager, you use simple, everyday English to schedule work. It has a built-in understanding of common scheduling terms and can handle any variety and combination of schedule statements, such as:

9AM DAILY2PM 1ST WEEKDAY OF EACH MONTH7PM 3RD 13TH AND 23RD DAY OF MONTH5PM 10TH-19TH DAY OF MONTH2ND AND LAST FRIDAY OF EACH MONTHEVERY 30 MINUTES STARTING 6PM TODAY

Using calendars

Although ESP Workload Manager is familiar with the standard calendar, you can use scheduling terms that are specific to your installation. To define your own customized set of scheduling terms, you can define one or more calendars. A calendar can contain:

• A list of holidays. Holidays can span one day, several days, or just parts of a day.• Lists of special processing dates.• Descriptions of periods, such as fiscal months, fiscal years, 4-4-5 periods.• A specification as to which days of the week are eligible to be workdays. The

default is Monday to Friday.

After defining your unique scheduling terms, you can use schedule criteria like these:

8AM LAST DAY OF FISCAL_MONTH5PM INVENTORY_DAYCHRISTMAS PLUS 1 WORKDAY8AM 8TH-10TH WORKDAY OF FISCAL_YEAR2ND WORKDAY OF 3RD FISCAL_MONTH OF FISCAL_YEAR

ESP Workload Manager Events

An Event is a basic unit of work. Information in an Event defines:

• When the work must be performed• What actions perform the work

Section–Data-set triggering

10 ESP-5.4-UG-05

Triggers for an Event

• A scheduled date and time • A data-set trigger• A global-variable-table trigger• A manual trigger• A job monitor or alert trigger• A signal with a scheduled date and time

Performing tasks

ESP Workload Manager can perform a variety of tasks through the Events you define. An Event must do one of the following:

• Send a message to you, other users, or operator consoles• Submit JCL • Invoke an ESP Procedure• Issue an operating-system command

Example

An example of an Event appears below. The Event is scheduled at 8 am each day that invokes a Procedure.

EVENT ID(USER.MESSAGE) SCHEDULE 8AM DAILY INVOKE 'SYS1.PROCLIB(PAYJOB1)'ENDDEF

Additional information

For more information on Events, see “Processing ESP Events” on page 73.

Data-set triggering

You can tell ESP Workload Manager when to process your Events depending on data-set activity. This feature is called data-set triggering. You can use it in conjunction with, or instead of, time-and-date scheduling.

Triggers for a data set

An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of job-names. Events can also be made to wait for triggers from activity in more than one data set.


ESP-5.4-UG-05 11

Example

An example of a data-set-triggered Event follows. This Event sends a message to a user each time the data set CYB.APPL.BASKET closes.

EVENT ID(USER.APPL_RECEIVE) DSTRIG CYB.APPL.BASKET ANYCLOSE SEND 'APPLICATION RECEIVED FROM ESP WORKSTATION' USER(BP)ENDDEF

You can also use data-set triggering for establishing individual job dependencies within your ESP Applications.

FTP data set trigger

An FTP data-set-trigger Event is triggered when a successful FTP file transfer or FTP rename completes. The closure of a data set through an FTP transfer requires special handling to ensure that the transfer is successful and complete.

Example

The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged-on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.

EVENT ID (USER.APPL_RECEIVE) DSTRIG CYBER.DATA.SET USER(CYB-) FTP(RECEIVE) HOST(AIXHOST)- LOGON(aixuser) SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDDEF

Explicit data-set trigger

An explicit data-set trigger is used when ESP Workload Manager needs to be explicitly notified of a data-set activity because no system SMF record exists to implicitly detect it.

The feature consists of two parts:

• The explicit data-set trigger notification utility program (CYBESDT1)• The parameter EXPLICIT in the DSTRIG command or in the DSNAME

statement


For more information on data-set triggering, see “Processing ESP Events” on page 73 and “Using Applications” on page 137.

Section–Global-variable-table triggering

12 ESP-5.4-UG-05

Global-variable-table triggering

You can set a global-variable-table trigger to trigger an Event when a specified variable changes.

Example

In this example, the Event CYBER.MYEVENT is triggered when the global variable VT1 of the global-variable table named MYTABLE changes.

For the Event to be triggered, the table MYTABLE, the variable VT1, and the (optional) trigger ID TR07 are set as follows:

VTDEFINE MYTABLEVT1='ONE'VTPUT VT1 TABLE(MYTABLE)VTRDEF ID(TR07) VARIABLE(VT1) TABLE(MYTABLE)- EVENT(CYBER.MYEVENT)

Any change of the value of the global variable VT1 will trigger the CYBER.MYEVENT Event. For example, setting the value of VT1 to TWO as follows:

VSET VT1 TWO TABLE(MYTABLE)


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.


ESP-5.4-UG-05 13

Uses of an ESP Procedure

The main uses of an ESP Procedure are to:

• Define processing requirements for a group of jobs and tasks in an ESP Application

• Define and work with symbolic variables• Take different actions based on other criteria, such as a job failure

Example

The following is an example of using CLANG. In this example, ESP Workload Manager:

• Sends a message on workdays• Submits job PAYJOB on the last workday of each month

IF TODAY('WORKDAY') THEN - SEND 'ANOTHER DAY OF HARD LABOR' U(BOSS)IF TODAY('LAST WORKDAY OF MONTH') THEN - SUBMIT 'SYS1.JCLLIB(PAYJOB)'


For more information on Procedures, see “Working with ESP Procedures” on page 107.

Applications

An ESP Application consists of one or more workload objects (for example: job, message, command, script, manual task). An ESP Procedure describes an Application to ESP Workload Manager. A Procedure consists of a series of statements to:

• Identify the Application• Tell ESP Workload Manager where the appropriate JCL is located• Identify the jobs• Describe the job relationships• Describe when ESP Workload Manager should select the jobs to run• Describe other job dependencies, such as time and resources• Optionally, it may also state such things as a job documentation library and what

condition codes cause a job to fail

Section–Inheriting job relationships

14 ESP-5.4-UG-05

Application definition

An Application definition looks like this:

APPL PAYROLLJCLLIB 'CYBER.ESP.JCL'JOB A RUN DAILY RELEASE (B,C)ENDJOBJOB B RUN DAILY RELEASE DENDJOBJOB C RUN DAILY RELEASE DENDJOBJOB D RUN DAILY RELEASE EENDJOBJOB E RUN FRIDAY RELEASE FENDJOBJOB F RUN LAST WORKDAY OF THE MONTHENDJOB

Streamlining Applications

You can streamline the way you schedule and manage entire Applications. When ESP Workload Manager creates an Application, it assigns a generation number to it. One generation does not need to complete before the next one starts. Several generations of the Application can run concurrently. ESP Workload Manager manages dependencies within the Application as well as between different Applications.


For more information on Applications, see “Using Applications” on page 137.

Inheriting job relationships

All jobs in an Application do not require to be run at the same interval. When ESP Workload Manager selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited. Once you specify your job

A

B C

E

F

D

Daily

Friday

Last workdayof month


ESP-5.4-UG-05 15

relationships, ESP Workload Manager determines the relationships required under different processing conditions.

Example

Consider the following three jobs and their schedule frequencies:

On Fridays, all three jobs execute in order, but on any other day of the week job J2 does not run. On these other days, J1 and J3 are selected and they inherit their mutual relationships from J2. When J1 completes successfully, it releases J3.


For more information on how ESP Workload Manager inherits job relationships, see “Inheriting job relationships” on page 176.

Mutually exclusive run requirements

ESP Workload Manager can specify mutually exclusive run requirements through Application and job-level statements. These statements provide an alternative to defining ESP Resources and the corresponding coding of ESP Resource statements to handle mutually exclusive run requirements. For information on resources, see “Resources” on page 23.

Example

In this example, jobs NWN001 and NWN003 are set up so they cannot run at the same time.

APPL NWN00CJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002

J2

J3

J1 Daily

Friday

Daily

Section–On-request jobs

16 ESP-5.4-UG-05

RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYS NOTWITH NWN001ENDJOB


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.


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


ESP-5.4-UG-05 17

Example

In the example below, a link is a successor to jobs A, B, and C. The link could send a message, issue an operator command, or simply link two groups of jobs together.


For more information on using links, see “Using links” on page 184.

Tasks

You can define tasks in an Application and establish dependencies between them and other tasks and jobs. You must mark a task complete before its successors become eligible for submission.

A task can represent a manual process that requires intervention, or it can represent a process that can be automated. You can choose to use tasks for:

• Balancing reports• Receipt of input tapes• Completion of a job step• Any other special handling requirements

Example

In this example, a report needs to be checked after job J1 completes successfully. A task called CHECKRPT.J1 represents the task of checking the report.

B CA

E FD

LINK

J1(Job)

CHECKRPT.J1(Task)

J2(Job)

Section–APPLEND workload object

18 ESP-5.4-UG-05


For more information on using tasks, see “Using tasks” on page 188.

APPLEND workload object

You can use the APPLEND workload object to automatically perform processing at the end of an Application. The APPLEND workload object acts like a self-completing task.

Note: The APPLEND workload object does not need a RUN statement because this object always runs at the end of the Application.

Example

In the following example, the APPLEND workload object named FRED will be made a successor of JOB2, because JOB2 has no other successors. However, job AFTERAE2 and AFTRAELA, which also do not have successors, are successors to APPLEND FRED, so are not made predecessors to it.

APPL TESTAE1JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 LINK RUN DAILY REL JOB2ENDJOB

JOB JOB2 LINK RUN DAILYENDJOB

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

JOB AFTERAE1 LINK RUN DAILY REL AFTRAELAENDJOB

JOB AFTERAE2 LINK RUN DAILYENDJOB

JOB AFTRAELA TASK RUN DAILYENDJOB


ESP-5.4-UG-05 19


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.


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.


For more information on job documentation, see “Job Documentation” on page 257.

Section–Consolidated Status Facility (CSF)

20 ESP-5.4-UG-05

Consolidated Status Facility (CSF)

The Consolidated Status Facility (CSF) provides a real-time view of the current workload. CSF shows you which jobs have executed, which ones are currently on the system, and which jobs have yet to execute. You can zoom in on any job or workload object to find out more information. You can also manipulate jobs, edit JCL, and restart jobs while in CSF. With CSF you can create customized views where you choose what you want to see and how you want it displayed. You may want to focus on one particular Application, or view all jobs that have failed.

Example

This example demonstrates the kind of job information that CSF can provide:

Customizing CSF

Through the use of CSF Extensions, you can further customize your use of CSF by writing your own commands, or by replacing existing commands. For example, you can launch other ISPF applications, provide additional panels, and force the use of certain fields.


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.


ESP-5.4-UG-05 21

ESP Workstation

ESP Workstation is a graphical user interface for ESP Workload Manager. From a single point, You can define, monitor, and control your entire workload across multiple platforms. You can:

• Use graphics to create ESP Applications• Manage workload in real time


For more information on ESP Workload Manager graphical user interface, see the ESP Workstation User's Guide.

Symbolic variables

A symbolic variable is an object whose value can be changed during ESP Workload Manager processing. ESP Workload Manager provides powerful substitution capabilities through the use of symbolic variables. When it encounters a symbolic variable, it substitutes the current value of that variable. With symbolic variables, you have all the flexibility you need to define date operands, specify job names, and define job dependencies.

Using variables

ESP Workload Manager provides you with several built-in variables (such as times and dates) that can be substituted in Events, ESP Procedures, and the JCL input stream. Also, you can define as many of your own symbolic variables as you need.

Example

NAME, DATE, and X are some examples of variables:

NAME='PATRICK'DATE='%ESPSMM%ESPSDD%ESPSYEAR'INTEGER XX=293

Attributes of symbolic variables

Each symbolic variable has a name and a value, and starts with a symbolic introducer character. The percent sign (%) is the default introducer character, although you can change this symbol at installation to suit your requirements. There are many operations that you can perform on symbols, such as concatenation and using sub-strings.

Section–Tailoring Job Control Language

22 ESP-5.4-UG-05

Global variable tables

You can store global variables in global variable tables, retrieve them from those tables, and trigger Events when the stored variables change. See the “Global Variable Table” chapter of the ESP Workload Manager Advanced User’s Guide.


For more information on symbolic variables and symbol libraries, see the “Symbolic Variables” chapter of the ESP Workload Manager Advanced User’s Guide.

Tailoring Job Control Language

You can selectively tailor the JCL that ESP Workload Manager submits to the JES internal reader by entering symbolic variables and control statements in JCL. For example, you can automatically include the current date in a job, or to add a job step every Monday. You can also add a restart step, route a job to another JES node, or add a condition code check step to the JCL.

Example 1

ESP Workload Manager has a number of built-in symbolic variables; many relate to dates and times. The following example shows how to represent the scheduled date of a job in the format MMDDYYYY using built-in symbolic variables. In this example, a user requests date information as data; you can use also symbolic variables as part of JCL.

//SYSIN DD *%ESPSMM%ESPSDD%ESPSYEAR

Example 2

When ESP Workload Manager submits this JCL for an Event scheduled on June 9, 2000, it substitutes the built-in symbolic variable as shown below.

You could generate another set of symbolic variables to complement the built-in set of date and time symbolic variables for any date in the future or in the past.

//SYSIN DD*%ESPSMM%ESPSDD%ESPSYEAR

//SYSIN DD*06092000

Original JCL Substituted JCL onJune 9, 2000


ESP-5.4-UG-05 23

Additional tailoring

In addition to using symbolic variables to insert different operands, such as time, date, day of week, and data-set name into JCL, you can further tailor your JCL by using:

• Selective inclusion and exclusion of JCL and data• JCL exclusion symbols• Different symbol introducers• Secured symbols• Automatic variable insertion


For more information on tailoring JCL, see the ESP Workload Manager Advanced User’s Guide.

Resources

A resource can be any hardware, software, or abstract condition. Within ESP Workload Manager, there is no limit to what you can define as a resource.

Examples

Common examples of resources include:

• Disk space• Scratch tapes• Execution time• An entity to control mutually exclusive jobs• Online system availability• DASD space• Time periods• Tape drives

Section–Tracking jobs

24 ESP-5.4-UG-05

Resources

ESP Workload Manager supports the three following types of resources:

Resource requirement

You can define resource requirements for any job. You can also use default resources where ESP Workload Manager automatically determines resource requirements for a job based on historical data.


For more information on resources, see “Using Resources” on page 325.

Tracking jobs

The ESP Workload Manager job-tracking facility tracks job data in real time as jobs are being processed. You can use the job tracking facility to track your jobs and keep information on the progress of these jobs. You can track both jobs that ESP Workload Manager submits and jobs that it does not submit. Also, you can track Started Tasks (STCs) and TSO users (TSUs). You see detailed step-level statistics in real-time. ESP Workload Manager maintains completion codes for each job step, and provides data

Type of resource...

Explanation

Renewable A renewable resource is a borrowed resource. When ESP Workload Manager submits a job, the job removes the resource from the resource pool and returns it upon completion. Some examples of renewable resources include tape drives, a data base, or sort work space.

Depletable A depletable resource is a consumed resource. When ESP Workload Manager submits a job, it removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. A depletable resource could refer to the number of scratch tapes available or to permanent DASD space.

Threshold A threshold resource is a sizing resource. You can think of a threshold resource as a variable-height doorway into the system. If the resource quantity is set to two, any number of jobs requiring two or fewer units can be submitted. However, any job requiring three or more units is too high to pass through the door and so it is not submitted. In other words, ESP Workload Manager sizes the job against the current level of the threshold resource. This type of resource could be used to prevent certain jobs from executing until a NITESHFT period begins, for example.


ESP-5.4-UG-05 25

such as CPU time, elapsed time, disk and tape I/O counts, number of tape mounts, tape drives, and so on.

Example

The following example shows a sample output from a command to display tracking data for job PAY008A:

LJ PAY008A(6308)PAY008A JO6308, COMPLETED, CC SOC1, NODE CYBJESSUBMITTED BY ESP AT 10.06 ON TUE 13APR, EVENT CYBBP01.PAYJCL FROM CYBBP01.ESP.DEMO.JCL(PAY008A)JCL COPIED TO CYBBP01.ESP.DEMO.COPYJCL(PAY008A)PROGRAMMER BOB, ACCOUNT CYBTESTJOB IS IN APPL PAYINFORMATION/MANAGEMENT RECORD 0000053 CREATED FOR THIS JOBSTEPNAME-PROCSTEP-PROGNAME—EXCEP-#T-S-N-CPU-TIME-SUNITS-REGION-CMPCENCORE ESPRM CYBRM000 30 0 0 0 0:00.48 2635 320K 0STEP01 IEFBR14 0 0 0 0 0:00.00 0 4K 0STEP02 IEBGENER 0 0 0 0 0:00.00 0 72K 0STEP03 SOC1 1 0 0 0 0:00.13 428 8K SOC1STEP04 IEFBR14 0 0 0 0 0:00.00 0 0K -STEP05 IEBGENER 0 0 0 0 0:00.00 0 0K -ESPCCFCK IEFBR14 0 0 0 0 0:00.00 0 0K -PNODE----OUT---QTIME-POST_BY—SYS-|PNODE----OUT---QTIME-POST_BY—SYSINPUT 10.06 5 CYB1|EXEC 10.06 12 SYSTEM CYB1OUTPUT 10.06 13 SYSTEM CYB1

Tracking models

You can define a tracking model to track a group of jobs with similar characteristics. This tracking model enables you to define and modify the tracking characteristics of multiple jobs at the same time. You can, for example, use a tracking model to identify jobs where you want to keep long-term historical data and then use the data with ESP Workload Manager history reporting facility. For more information on setting up your job-tracking environment, see the ESP Workload Manager Installation and Configuration Guide.

Job monitoring and alert processing

The ESP Workload Manager job-monitor facility and alert processing facility can automatically take action at different processing points, for example, stepend, jobend, and overdue.

Section–System message interception

26 ESP-5.4-UG-05

Uses

For example, you can use job monitoring and alert processing to:

• Automatically start a subsystem• Restart a job by automatically resubmitting it• Automatically restart an abended job• Create a problem record in an information/management data base.• Submit a recovery job• Activate or deactivate resources by issuing the appropriate command.• Cause SNMP traps to be sent by an ESP Management Agent appearing as if they

were sent from ESP Workload Manager

You can use a number of symbolic variables with either facility.


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


ESP-5.4-UG-05 27

specifies to route this message to consoles with the default route code two. Descriptor code two is used to make the message non-deletable:

SYSMSGS 'NOT CATLGD' COL(50:60) CANCEL DESC(2)


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


For more information on using REXX with ESP Workload Manager, see the ESP Workload Manager Advanced User’s Guide.

Reporting

The ESP Workload Manager reporting facilities can give you up-to-date information about scheduled jobs that executed in the past or will execute in the future. Reporting facilities include:

• History• Scheduled activity• Job mapping

Section–Reporting

28 ESP-5.4-UG-05

History reporting

A powerful and versatile generalized reporting facility provides details about the progress of your jobs at any time up to the present. This facility extracts and formats data from the ESP Workload Manager history files to meet a variety of requirements. The reports specified can be as detailed or as simple as you require. You can include a variety of job aspects such as job name, status, tape allocation, and so on. The report formats you define can be named and used repeatedly. In addition, reports are available online and in hard-copy.

Fields to use as selection criteria

ESP Workload Manager retains over 60 items of history data for each tracked job. The fields you can use as selection criteria and for display in your reports include, but are not limited to:

• Execution queue time• Print time• Start and end dates• Start and end times• Overdue times• EXCP counts• Number of job steps

Example

The following is an example of a report on all PAY- jobs that executed on May 8, 2001:

JOBNAME JOB COMP EXEC START EXEC END CPUTIME NO CODE START DATE END DATEPAYD001A 2221 0 11.56 TUE 08MAY01 12.02 TUE 08MAY01 0:01PAYD002A 2227 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00PAYD003A 2226 0 12.02 TUE 08MAY01 12.02 TUE 08MAY01 0:00PAYD004A 2229 0 12.02 TUE 08MAY01 12.07 TUE 08MAY01 0:04PAYD100A 2232 0 12.07 TUE 08MAY01 12.07 TUE 08MAY01 0:00PAYD006A 2233 0 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00PAYD008A 2234 SOC1 12.08 TUE 08MAY01 12.08 TUE 08MAY01 0:00PAYD008A 2270 SOC1 12.57 TUE 08MAY01 12.57 TUE 08MAY01 0:00PAYD008A 2271 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00PAYD009A 2272 0 12.58 TUE 08MAY01 12.58 TUE 08MAY01 0:00PAYD010A 2273 SOC1 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00PAYD010A 2275 0 12.59 TUE 08MAY01 12.59 TUE 08MAY01 0:00PAYD011A 2276 0 12.59 TUE 08MAY01 13.04 TUE 08MAY01 0:01SUBTOTAL (13) 0:06TOTAL (13) 0:06


ESP-5.4-UG-05 29


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


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.


For more information on using job mapping, see “Using job mapping” on page 303.

Modeling

ESP Workload Manager has a modeling feature that forecasts how it processes a group of jobs in your particular systems environment. Scheduled activity reporting provides you with information based on what is scheduled. Modeling takes this one step further. ESP Workload Manager combines the schedule with what it knows about the scheduling environment to predict future activity. You define your environment and then ESP Workload Manager creates a picture showing how a future schedule period

Section–Security

30 ESP-5.4-UG-05

looks. Modeling allows ESP Workload Manager to forecast the influence of factors such as CPUs, initiators, and resources.

Modeling reports

Modeling generates reports on jobs, resources, and exceptions. For example, you can generate a report that shows you all jobs that will not meet their scheduled due out time.

Use of modeling reports

You can use the data shown on the modeling reports to:

• Assist you in capacity planning• Test the effects of underinitiating or overinitiating• Determine the impact of changes to a schedule• Uncover potential resource problems


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.


For more information on security, see the ESP Workload Manager Security Guide.

ESP-5.4-UG-05 31

Getting Started

This chapter gives you some general information on how you can use ESP Workload Manager.

When you have finished this chapter you should be able to access ESP Workload Manager, load commands into it, and use different data set types as input.


• Accessing ESP Workload Manager• Accessing ESP Workload Manager as an ISPF option• Accessing ESP Workload Manager through a batch program• Invoking ESP Workload Manager as a program in TSO• Accessing ESP Workload Manager through a TSO command processor• Exiting ESP Workload Manager• Loading commands• Alternative input data sets

Section–Accessing ESP Workload Manager

32 ESP-5.4-UG-05

Accessing ESP Workload Manager

You can access ESP Workload Manager in one of several ways:

• An ISPF Option• A Batch Program• A Program in TSO• A TSO Command Processor

Accessing ESP Workload Manager as an ISPF option

If your z/OS system has ISPF you can use the menus and panels of ESP Workload Manager. The panels step you through the definition of Events, Applications, calendars, and jobs. You use other panels to display job tracking information and for reporting scheduled activity. The ISPF interface uses the dialog manager for functions such as split screen, edit, and multiple sessions. As well as menus and panels, Page mode provides scrollable data, and the ability to edit and save any portion of an ESP Workload Manager session. The method for accessing ESP Workload Manager from ISPF differs with each installation. Check with your administrator for the method that your site uses.

Screens for ISPF interface

The layout of each screen is designed to look like the panels you are already accustomed to when using ISPF. The Command or Option field is always at the left of the second panel line. Short messages are displayed top right, while long messages occupy line three, which is otherwise blank. The maximum length of most panels is 23 lines. This facilitates the use of split-screen mode where it is available. Panels with scrollable data will extend to the entire screen capacity.

Main Menu screen

The screen below shows the ESP Workload Manager Main Menu.

Chapter 2–Getting Started

ESP-5.4-UG-05 33

When you invoke ESP Workload Manager, the Main Menu appears. It displays the available options including Events, Calendars, Consolidated Status Facility. Many ESP Workload Manager commands are available through menu mode. There is a wide choice of menus, entry panels and help screens.

Menu panels in ESP Workload Manager

To use a command, first select an option from any menu or selection panel. Then specify your requirements by entering appropriate data in labeled fields on the entry panel. All entry fields are indicated with an arrow (===>).

Required fields are indicated, and you are prompted if you omit required information or make a recognized error in any of your entries. If a short message prompt is insufficient to clarify an error or omission, you can display a longer message by entering the HELP command (PF1).

Main Menu options

The Main Menu is the first ISPF panel. It provides the following options:

Option Use this option to...

O Set your ESP Workload Manager defaults

• Display information about a user or group of users• Set security parameters• Set (CSF) display options• Specify default names for data sets that you use frequently

during your ISPF sessions. Your input is automatically transferred to the appropriate panels. For example, ESP Workload Manager can use a default ESP Procedure Library when you define an Event. You can override information in any field.

E Events • Test schedule criteria• Add a new Event definition• Display the next execution times of an Event• Alter, browse, delete, edit, simulate, hold, release,

suspend, resume, or trigger an Event you have already defined

• Obtain a list of Events by prefix

L Calendars • Define and display calendar information including holidays, special days, and special periods

J Jobs • Set up job documentation. You can specify processing requirements for any job as well as user information such as ABEND codes and messages.

Section–Accessing ESP Workload Manager as an ISPF option

34 ESP-5.4-UG-05

T Job Tracking • Display job status• Access commands to display job tracking information• Display tracking models• Use Pnodes• Display the number of jobs on each Pnode queue• Display the names of jobs on Pnode queues• Display jobs on the ABEND queue

S Scheduled Activity • View information on the scheduled activities you want performed. This information gives you a snapshot of which jobs will be on the schedule during a specified future time. It also provides some additional information about the jobs, such as estimates on:

• Execution time• CPU time• Print lines• Tape specifications• CPU absorption

C Consolidated Status Facility (CSF)

• View information on jobs and Applications that ESP Workload Manager tracks. Once you have chosen a display, you can use commands to manipulate jobs, Applications, subApplications, or any of the related ESP Workload Manager definitions.

U ESP Workload Manager Utilities

• Load a series of ESP Workload Manager commands• Display information on key ESP Workload Manager data

sets, tracking cells, data set triggers and system attributes

G Page Mode • Switch directly into the Page mode method of communicating with ESP Workload Manager. In this mode you can use the command line for input, while receiving scrollable output in return. See “Using ESP Workload Manager Page mode” on page 36 for detailed information on using this option.



ESP-5.4-UG-05 35

USE command sample

This screen shows the result of the USE command:

ESP ---------------------------------- Usage ----------------- Row 1 to 4 of 4 Command ===> Scroll ===> PAGE

This This This Since LastActivity Year Month Day ESP Start------------------------------------------------------------------------------Applications completed 75 23 4 2Applications created 77 25 4 1Events executed 183 81 13 5Jobs submitted 99 55 8 3 **END**

Using the Help option

While you work with ESP Workload Manager you can access the online, panel-specific Help screens at any time. By pressing the Help key (PF1/PF13) you access Help about the particular screen on which you are working.

M ESP Workload Manager Administration

• This option is only available to the ESP Workload Manager Administrator and departmental administrators. The administrator can use this option to define and update users, groups, and calendars, and to test and modify job tracking definition tables. If your installation uses your host security system for ESP Workload Manager security, you do not use this option to define users and groups.

R ESP Encore • Take you to the Job List Panel of ESP Encore, Cybermation’s rerun/restart product. This option only appears on your menu if you have ESP Encore installed.

USE Command • Enter the USE command on the OPTION line, from the ESP Workload Manager main menu, to display statistics on various activities. These statistics are reset to zero following an ESP Workload Manager cold start.


Section–Accessing ESP Workload Manager as an ISPF option

36 ESP-5.4-UG-05

Using ESP Workload Manager Page mode

To use Page mode, type the information in free format, line by line, on the command entry line. The data and resultant output appear in a scrollable field below the command line.

Example: Page mode screen

The following is an example of using Page mode:

Input line entry

Each time you complete an input line, press Enter. The line is highlighted and added to the bottom of the input display.

To re-enter a previous line:

1. Move the cursor to that line using the arrow keys.

2. Press Enter. The line appears on the command line.

3. Edit the line.

4. Press Enter.

Similarities to ISPF Browse

Page mode appears very similar to ISPF Browse. However, not all Browse commands are available. If you want to use the delete and find features, you must type EDIT on the command line. The EDIT command lets you delete or change the Page mode output and store it.

When you use the EDIT command, all the session’s data is copied into a temporary work file that is displayed immediately. You can write the data into a more permanent existing data set or a new member of a PDS using the CREATE or REPLACE commands.


ESP-5.4-UG-05 37

To write session data:

1. Use the CC or MM block commands to select the lines you want to copy to the data set.

2. Type either CREATE or REPLACE on the command line. CREATE makes a new member for the data. REPLACE overwrites an existing data set with the new information.

3. Press Enter.

4. Respond to the prompt for a data-set name:

• If you used the CREATE command, enter the name for your new member and the existing data set to which it will belong.

OR

• If you use the REPLACE command, enter the name of the existing data set that you want to overwrite.

Important: Do not use the SAVE command. The SAVE command writes the data back to the temporary work file that is discarded at the end of your session.

Using the Page mode screen

In Page mode, ESP Workload Manager retains your entire session on the screen. As you enter more data, the screen scrolls up to make room. You can scroll the screen up or down to view all of the data. If any headings are attached to your input, the headings remain in view at the top of your screen while the data scrolls below them. Also, any informational, warning, and error messages appear in the short message fields at the top of the screen, as in ISPF.

Note:

• To scroll, use the standard scroll keys: PF7 to move up, and PF8 to move down.• To scroll more quickly, enter TOP or BOTTOM in the command line.• To access a specific line number quickly, use the LOCATE command.

To display informational messages where they occur in the input instead of at the top of the screen:

Enter on the command line:

INFOMSG SET

You can prefix these messages with a string of your choice by entering on the command line:

INFOMSG SET PR('STRING')

Section–Accessing ESP Workload Manager through a batch program

38 ESP-5.4-UG-05

To return informational messages to the top of the screen:

Type on the command line:

INFOMSG RESET

Accessing ESP Workload Manager through a batch program

Although many of ESP Workload Manager commands are available through the ISPF interface, there can be times when you want to execute ESP Workload Manager commands in batch. Perhaps you want a hardcopy report, or you need to execute a repetitive series of commands.

To execute ESP Workload Manager commands in batch:

Use the following JCL after your jobcard:

//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *ESP command...ESP command

Note: Do not end a line with a hyphen (-) else it will be treated as a continuation character. If you are using a hyphen as a mask, you should follow it with a semi-colon. For example, LTJ -;

Subsystem name

If the subsystem name for ESP is not ESP, you need to type the subsystem name. For example, if the subsystem name is ESPA, type:

//EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K

Steplib

If the TSO command processor is not in a LINKLIST library, you will need a STEPLIB or JOBLIB statement in your JCL. Your statement looks like:

//STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR


ESP-5.4-UG-05 39

Invoking ESP Workload Manager as a program in TSO

To invoke ESP Workload Manager as a program in TSO:

Type the following at the TSO prompt:

ESP

If the subsystem name for ESP is not ESP, you will need to type the subsystem name. For example, if the subsystem name is ESPA, type:

ESP SUB(ESPA)

When you access ESP Workload Manager through TSO, TSO prompts you for input with an arrow:

==>

TSO refers to this prompt as a MODE message.

To turn on the TSO mode message, at the TSO prompt:

Type:

PROFILE MODE

You are now in ESP Workload Manager Line mode.

To work in Line mode:

Enter all of the commands for the work you want directly on the TSO command line. When you have finished, type END to exit. This method is quick and direct, but you must know the commands and their syntax. You can find the ESP Workload Manager commands and syntax in the ESP Workload Manager Reference Guide.

Example: Invoking the ESP Workload Manager command from a CLIST

The following is an example of a CLIST that invokes the ESP Workload Manager command processor directly. The CLIST:

• Prompts a user for the name of a job to be submitted • Accepts the name of the job • Invokes the ESP Workload Manager command processor• Triggers an Event, passing the name of the job as a user parameter

PROC 0WRITE Enter the name of the job you want to runREAD &JESP SUB(ESPX)TRIGGER &USER.ADDJOB USER1("&J")END

Section–Accessing ESP Workload Manager through a TSO command processor

40 ESP-5.4-UG-05

Accessing ESP Workload Manager througha TSO command processor

Calling ESP Workload Manager from a CLIST

You can also access ESP Workload Manager as a TSO command processor by using a CALL instruction to the ESP Workload Manager load library.

Note: Using this method, you can be limited by the size of the parameter list you pass on the CALL instruction.

Example: Calling ESP Workload Manager from a CLIST

The following is an example of a CLIST using a CALL instruction. In this example the subsystem name for ESP is ESPX. The CLIST:

• Prompts a user for the name of a job to be submitted • Accepts the name of the job • Calls the ESP Workload Manager TSO command processor• Triggers an Event, passing the name of the job as a user parameter

PROC 0WRITE Enter the name of the job you want to runREAD &JCALL 'CYB1.ESP510E.LOAD(ESP)' SUB(ESPX);-TRIGGER &USER.ADDJOB USER1("&J");END'

Exiting ESP Workload Manager

To exit ESP Workload Manager at any time:

Loading commands

The LOAD command lets you load a series of ESP Workload Manager commands for execution. You can enter your commands into a PDS or sequential data set. Later,

If you are... Action

using the ISPF panels... Press the END key (F3/15) until you return to the ISPF Primary Option Menu

in Line mode... Type END

in Page mode... Press F3/15


ESP-5.4-UG-05 41

when you issue the LOAD command in Page mode, you can process this series of commands.

Example: Loading diagnostic commands from a data set

Suppose you have a member DIAG of a data set called CYB.ESP.DATA that contains a number of ESP Workload Manager diagnostic commands, like this:

SMFSTATSLISTRAKOPER LISTAPTFLISTCKPTLISTQ

You can process all of these commands by issuing the following command in Page mode:

LOAD 'CYB.ESP.DATA(DIAG)'

Sample output

SMFSTATSESP SUBSYSTEM INITIALIZED AT 12.43.58 ON MONDAY JUNE 25TH, 2001 9213 ENTRIES TO SMFWTM, 1592 BY BRANCH ENTRY AND 7621 BY SVC4863 ENTRIES TO ESP PHASE 27272 JOB STARTS, 595 STC STARTS, 645 TSU STARTS, 9051 STEP ENDS

LISTTRAKTRAKFILECYB3.ESP430NV.TRAKFILEFORMATTED AT 16.15.17 ON MONDAY SEPTEMBER 25TH, 20009296 SLOTS TOTAL, 8857 AVAILABLE, NEXT IS 6223

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

LISTCKPTPRIMARY CHECKPOINT CTB3.ESP430NV,CKPT MAX CHECKPOINT SIZE 614400HIGHEST ADDRESS USED 403280 BYTES IMBEDDED FREE SPACE

LISTQQUEUE DATASET CYB3.ESP430NV.QUEUEFORMATTED AT 13.44.57 ON MONDAY JUNE 11TH, 2001MAXIMUM SIZE 614400 BYTESHIGHEST ADDRESS USED 3888, 480 BYTES IMBEDDED FREE SPACE

Section–Alternative input data sets

42 ESP-5.4-UG-05

Alternative input data sets

In addition to standard operating system and VSAM data sets, you can input commands from Librarian and Panvalet data sets. Each of these data-set types has specific conventions.

Prefixes for data sets

You can use the following prefixes when you need to use one of these types of data sets:

Example

The following statement identifies a JCL library as a Panvalet data set.

JCLLIB PAN-PROD.JCL

Note: You cannot use ESP Workload Manager to write to Librarian and Panvalet data sets.

Prefix Type of Data set

LIB- Librarian

PAN- Panvalet

ESP-5.4-UG-05 43

Schedule Criteria

You can use free format, everyday English, to specify schedule criteria when scheduling Events and jobs. ESP Workload Manager has a built-in understanding of general scheduling terms. You can also add your own unique scheduling terms. These include special processing periods, holidays, and other special days. You can specify schedule criteria up to the year 2042.


• Where you can use schedule criteria• Specifying schedule criteria• Schedule terms• Using other techniques for schedule criteria• Testing schedule criteria• Using calendars• Using calendar terms• Working with calendars• Defining holidays• Defining special days• Special periods• Working with periods

Section–Where you can use schedule criteria

44 ESP-5.4-UG-05

Where you can use schedule criteria

You can use schedule criteria in the following ways:

• In SCHEDULE, NOSCHED, and EXPECT commands in Events• In HOLD, RELEASE, SUSPEND, RESUME, and DELETE commands in

Events • In commands that control Events (for example, HOLD, SUSPEND, TRIGGER)• In RUN/NORUN statements in an Application to specify schedule frequencies

for individual jobs• To specify other time dependencies for jobs in an Application (for example, early

start time, late submission time)• To define holidays, special days, and special processing periods in calendars• As part of the GENTIME command to generate date and time symbolic variables• To specify reporting times for history, scheduled activity, job mapping, and

modeling reports• In combination with many of the built-in functions (for example, TODAY,

DAYS_FROM) available with ESP Procedures• In CLANG

Specifying schedule criteria

Days of the week

ESP Workload Manager recognizes the following days of the week:

• Sunday• Monday• Tuesday • Wednesday• Thursday• Friday• Saturday

You can use the plural forms, such as Mondays and Fridays, and you can abbreviate the names to a minimum of three letters such as: sun, thu, fri. You can also specify multiple days of the week, for example, Monday Wednesday Friday.

Chapter 3–Schedule Criteria

ESP-5.4-UG-05 45

If you specify a day and a date that do not match each other, ESP Workload Manager automatically calculates the first specified day of the week on or after the date you requested. For example, May 14th, 2001 falls on a Monday.If you mistakenly specify the following:

TUESDAY MAY 14TH 2001you actually get this:

TUESDAY MAY 15TH 2001

Month names

ESP Workload Manager recognizes the following months of the year:

• January• February• March• April• May• June• July• August• September• October• November• December

You can abbreviate any month specification to a minimum of three letters, for example:

• APR• AUG

Section–Specifying schedule criteria

46 ESP-5.4-UG-05

Time zones

You can use the following time zone abbreviations for scheduling in ESP Workload Manager:

• LT: Local time• LOCAL: Local time• ADT: Atlantic Daylight Time• AST: Atlantic Standard Time• EDT: Eastern Daylight Time• EST: Eastern Standard Time• CDT: Central Daylight Time• CST: Central Standard Time• MDT: Mountain Daylight Time• MST: Mountain Standard Time• PDT: Pacific Daylight Time• PST: Pacific Standard Time• BST: British Summer Time• GMT: Greenwich Mean Time

You do not need to specify your own time zone in your schedule criteria. These are set in ESP Workload Manager initialization parameters.

Note: ESP Workload Manager assumes that any number preceding a time zone abbreviation is a time specification.

Time of day

The following table shows time-of-day formats that ESP Workload Manager accepts, where h and hh = hours, mm = minutes and ss = seconds.

Note: ESP Workload Manager assumes that any number preceding the letters AM or PM is a time specification, for example:

• 3AM• 6PM

Days of months

A number joined to the name of a month is recognized as a day of the month (for example jun3, 22oct, 6nov2001). The ordinal qualifiers st, nd, rd or th are also used

with a month name. For example, January21st, August29th.

Format Example

hh.mm 12.30

hh:mm 01:25

hh.mm.ss 10.47.30

hh:mm:ss 11:00:01


ESP-5.4-UG-05 47

Julian date

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

Date format

ESP Workload Manager recognizes the date format xx/xx/xx. The DATEFORM initialization parameter instructs ESP Workload Manager how to interpret this format. The following table shows the different formats (yy=year number, mm=month number, dd=day number) and how to express January 2, 2000 using them.

Note: Only one of these formats is valid at your installation. Check with your systems programmer or issue the DATEFORM operator command to determine which format you can use.

Ordinal numbers

Use ordinal numbers (for example, 1st or 5th) to refer to scheduling terms other than just day of month. For example, 2nd Monday of year. You can use more than one ordinal, as in 3rd and 4th month of year.

The following examples specify the first Monday of each month.

1ST MONDAY OF MONTH1ST MONDAY MONTHLY

The following example requests activity at 10 am on the third day of each month.

10AM 3RD MONTHLY

The next example requests activity at 10 am on the first Monday after the third day of each month.

10AM MONDAY 3RD MONTHLY

Date range

Use a hyphen to designate a range of dates. For example,

3RD-6TH DAY OF MONTH

Format Example

yy.ddd 01.056

yyyy.ddd 2001.056

Format Example

yy/mm/dd 00/12/28

dd/mm/yy 28/12/00

mm/dd/yy 12/28/00

Section–Specifying schedule criteria

48 ESP-5.4-UG-05

represents the 3rd, 4th, 5th, and 6th day of the month.

Implied periods

The following calendar terms are implied periods:

• WEEK• WEEKEND

Note: A weekend is defined as both Saturday and Sunday. Therefore, the first weekend

of a month starting on Sunday 1st consists of the Saturday 7th and the Sunday 8th.

• MONTH• YEAR

The following are valid:

2ND WEEKEND OF THE MONTH3RD DAY OF LAST WEEK OF YEAR5TH WORKDAY OF 2ND WEEK OF YEAR

Specifying a time and frequency

A schedule specification in an Event can consist of two parts. One part gives a starting date and time, while the other part describes an algorithm for computing subsequent dates and times. In an ESP Application, you must use separate statements to specify the time and the frequency of a job.

Starting Date and Time

• 9AM JANUARY 1ST• MIDNIGHT 9 DECEMBER 2000• 3PM

Subsequent Times

• DAILY • EVERY 2 WEEKS• MONTHLY• 4 TIMES

Matching criteria

Normally, you do not need to specify a starting time and date when you define a schedule. The first time and date that match the criteria you have entered is automatically selected.

• DAILY AT 19.00• WEDNESDAYS AT 3PM• WORKDAYS


ESP-5.4-UG-05 49

To specify both an algorithm and a starting date and time:

Separate the two parts of the schedule specification with the scheduling term STARTING.

• 3PM DAILY STARTING JAN 1• WEEKDAYS EXCEPT WEDNESDAYS STARTING 2ND JUNE

Spaces

Spaces between words are not necessary if there are other delimiting factors in your date and time specification.

• SAT25JUN• EVERY5MINUTES

Using the first day of the week

Each calendar identifies the day that ESP Workload Manager considers the first day of the week. By default ESP Workload Manager considers Sunday to be the first day of each week. If you specify 1st day of week, ESP Workload Manager uses the calendar to determine what day this is.

Using workdays

Each calendar has its own workdays. By default workdays are Monday through Friday excluding holidays. If you specify 2nd workday of month, ESP Workload Manager looks for the second day of the month which is not a weekend or holiday.

Absolute vs. logical days

By default a day is considered to be an absolute day beginning at midnight (00:00). To override the default, you can define a calendar as logical and identify the start time of your logical day.

For example, if your logical day begins at 08:00 and you schedule an Event to execute Monday at 2 a.m., the Event actually executes Tuesday morning at 2 a.m.

Workday Weekend Weekend Holiday Workday Workday Workday

1 X X X 2 3 4

Absolute Calendar

SCHEDULE 2AM MONDAY

Event scheduled at 2 am Monday

Logical Calendar

SCHEDULE 2AM MONDAY

Event scheduled at 2 am Tuesday

Section–Schedule terms

50 ESP-5.4-UG-05

Important: Cybermation recommends you use absolute calendars because of their ease of use.

Schedule terms

You can use words and phrases other than specific dates and times to define schedule criteria. The following is a list of other terms recognized by ESP Workload Manager.

Term recognized by ESP Workload Manager

Explanation

ABSOLUTE Specifies that you are using an absolute day (that is, beginning at 00:00). This is only required when your calendar is a logical calendar, with a start time other than 00:00.

AND Specifies multiple similar scheduling terms (for example days of the month or months of the year) and ordinal numbers. For example, Monday and Tuesday, 1st, 4th, and 9th, Monday of June July and August. AND cannot be used with times of day; separate schedule commands are required.

ANYDAY Specifies that there is no day of the week restriction. You can abbreviate this term to ANY.

COMPLETE Ensures that the schedule only occurs during a complete period. Used only with the LAST scheduling term. For example, you can specify last complete week of year or last complete week of quarter If a fiscal week starts in one quarter but finishes in the next quarter, ESP Workload Manager provides a schedule for the previous complete fiscal week.

DAILY Means every day.

ENDING Allows you to specify the end date for any schedule interval, for example, daily at 9 am starting tomorrow ending 1jul2000. You cannot use this qualifier in a RUN/NORUN statement.

EACH Means every occurrence of.

EVERY n units Requests a recurrence of the Event at every n units of time. The units can be any of SECONDS, MINUTES, HOURS, WORKDAYS, DAYS, WEEKS, MONTHS, or YEARS, while n can be any number from one to 32767. For example, every one hour round less five minutes requests an Event at five minutes before the hour, every hour. Note that five minutes are subtracted from the base time (every hour on the hour). You cannot use this qualifier in a RUN/NORUN statement.


ESP-5.4-UG-05 51

EXCEPT Excludes a day of the week or holidays. For example “weekdays except Wednesdays” limits activity to Monday, Tuesday, Thursday, and Friday. “daily except holidays” limits activity to days which are not holidays. You cannot use EXCEPT with a term other than a day of the week or the term HOLIDAYS.

FIRST Specifies the first occurrence of a particular day or period. For example, you can specify “first Monday of month”, “first fiscal_month of fiscal_year”. You can also use the ordinal number 1st.

HOURLY Means every one hour. You cannot use this term in a RUN/NORUN statement.

HOLIDAYS Refers to all holidays. You can refer to specific holidays by name.

LAST Specifies the last (for example, final) occurrence of a particular day or period. For example, you can specify last holiday of year, last workday of fiscal_month, first and last Tuesday of month.

LESS n units Specifies a value to be subtracted from the base time to produce a time/date execution time. n must be a whole number. For example, you can specify less two weekdays, less one month, less zero workdays.

LOGICAL Specifies that you are using a logical as opposed to an absolute day (that is, beginning at 00:00). The start time of your logical day must be specified in a calendar. For example, you can specify 2 am logical Tuesday, 7 am first logical workday of month. LOGICAL can be set as a default at calendar definition time.

MIDDAY Specifies 12.00, noon.

MIDNIGHT Specifies 24.00, midnight. 24.00 is normally recognized as being the same as 00.00. Thus, if you specify Monday at 24.00 it will be stored as 00.00 Tuesday.

MONTHLY Means every month. You cannot use this qualifier by itself in a RUN/NORUN statement (for example, you can use RUN 15TH MONTHLY, but you cannot use RUN MONTHLY).

n TIMES Specifies the number of times you want a schedule to occur, such as daily at 9 am six times starting tomorrow. You cannot use this qualifier in a RUN/NORUN statement.

NOW Refers to the scheduled time. This is useful when you need up-to-the minute information, as when obtaining a report for example. You could request a report from any time in the past until NOW. You cannot use this qualifier in an Event definition on its own. See note at the end of this section.


Explanation


52 ESP-5.4-UG-05

OF Restricts the schedule action to a period such as a month.

Note: If you specify 5TH SATURDAY OF JUNE, you get results in July when June has only 4 Saturdays. Use WITHIN if you want the result absolutely restricted to the specified period.

ONCE Means that a scheduled command will be processed once only, at the time specified. If you specify a date in an Event without ONCE, the default frequency is DAILY. You cannot use this qualifier in a RUN/NORUN statement.

OR Specifies either of two similar scheduling terms, such as Monday or Tuesday. OR implies whichever happens first, and as such can only be used where it is meaningful and does not lead to ambiguity.

OVERDUE(n) Specifies how many overdue occurrences of an Event are to be initiated should an Event miss its scheduled time. ESP Workload Manager schedules the Event once for each missed occurrence, up to the number specified. You can only use this on a SCHEDULE command in an Event definition.

PLUS n units Specifies a value to be added to the base time to produce a time/date execution time. n must be a whole number. For example, you can specify plus two weekdays, plus zero workdays, plus one week.

REALNOW Refers to the actual time. You cannot use this term in an Event definition on its own. See note at the end of this section.

ROUND Specifies that the computed time is an integral multiple of the units parameter. This word can be used together with the EVERY n UNITS phrase. For example, specifying every one hour round requests every hour at the hour mark. Every six hours round requests the times 00.00, 06.00, 12.00, and 18.00. Specifying every five hours round provides the next hour that is an integral multiple of five hours starting at 00.00 on January1st, 1900.

STARTING Specifies a starting date and time. It splits the schedule specification into two parts. The first part is an algorithm, and the second part is the starting time or date. The time or date to the left of STARTING is the time when you want the Event to execute. The time or date to the right of STARTING is the time when you want the first execution to occur. Use an actual date or time after STARTING. A repetition, such as every five minutes, is not valid. You cannot use this qualifier in a RUN/NORUN statement.

TODAY Specifies today.


Explanation


ESP-5.4-UG-05 53

Note: When working with jobs in an ESP Application, NOW refers to the scheduled time of the Event that triggered the ESP Application; REALNOW refers to the actual time the Event was triggered.

Using ordinal numbers

If you use an ordinal number as part of the STARTING operand with a special period or special day, and without using nested levels, ESP Workload Manager assumes that you mean from today. For example, 10 pm daily starting 5th payroll_day provides the fifth payroll day from now.

If you use an ordinal number with a schedule term (other than with the STARTING operand) without stating what the schedule term refers to, ESP Workload Manager assumes the following defaults:

TOMORROW Specifies tomorrow. You cannot use this term in a RUN/NORUN statement.

UNTIL Specifies the end date for any schedule interval, for example, daily at 9 am starting tomorrow until 1jul2001. You cannot use this qualifier in a RUN/NORUN statement.

WEEKDAYS Requests that the schedule actions occur only on weekdays (Monday through Friday).

WEEKENDS Requests that the scheduled actions occur only on Saturday and Sunday.

WITHIN Restricts the schedule action to be within a period such as a specific month.

WORKDAYS Requests that the schedule actions occur only on workdays. Each calendar identifies workdays. Workdays exclude holidays. Default workdays are Monday through Friday.

YEARLY Means every one year. You cannot use this qualifier in a RUN/NORUN statement.

YESTERDAY Specifies yesterday. This term is useful in reporting. You cannot use YESTERDAY in an Event definition or in a RUN/NORUN statement.

Schedule Term ESP Workload Manager Default

date, day name, or workday of month

week or month of year

holiday of year

special day or period of year


Explanation


54 ESP-5.4-UG-05

For example, if you specify 3rd Friday at 9 am the schedule occurs at 9 am on the third Friday of every month, while 9 am last holiday provides a schedule on the last holiday of the calendar year.

Examples of schedule criteria

Here are some examples of schedule criteria, each of which can be handled with one statement. See “Using other techniques for schedule criteria” on page 57 for information on handling more complex criteria.

Daily or multiple times a day

• 6 am each day:

6AM DAILY

• Every day in October:

ANYDAY WITHIN 10TH MONTH OF YEAR

• Every 30 minutes beginning at 2 pm today:

EVERY 30 MINUTES ROUND STARTING 2PM TODAY

Multiple times a week

• Monday, Wednesday and Friday:

MON WED FRI

• Everyday except Mondays:

DAILY EXCEPT MONDAYS

• 19:00 on Saturdays and Sundays:

19.00 WEEKENDS

• Every other workday beginning this Friday:

EVERY 2 WORKDAYS STARTING FRIDAY

Weekly

• Last workday of each week:

LAST WORKDAY OF WEEK

• Every Saturday in June:

SATURDAY OF JUNE


ESP-5.4-UG-05 55

Monthly

• 8 am on the last Saturday of each month, beginning in October 2004:

8:00 LAST SATURDAY OF MONTH STARTING OCTOBER, 2004

• 8 am on the 3rd workday of each month:

8AM 3RD WORKDAY

• 15th day of March, June and August:

15TH DAY OF MARCH JUNE AUGUST

• 2nd last workday of each month:

LAST WORKDAY OF MONTH LESS 1 WORKDAY

• First Friday of each month. If this is not a workday, then run on the next workday after the first Friday of the month:

FIRST FRIDAY OF MONTH PLUS 0 WORKDAYS

• First weekday (for example, Monday through Friday) on or after the 15th day of the month:

15TH DAY OF MONTH PLUS 0 WEEKDAYS

• Friday after the 1st Sunday of the month:

1ST SUNDAY OF MONTH PLUS 5 DAYS

• 1st Saturday of the month. If this is also the first day of the month then run on 2nd Saturday of month:

SATURDAY 2ND MONTHLY

ESP Workload Manager interprets the above expression as the first Saturday on or after the 2nd day of the month.

• 31st day of the month, but only if there are 31 days in the month:

31ST DAY WITHIN MONTH

ESP Workload Manager interprets the above expression as the 31st of January, March, May, July, August, October, or December.

• 31st day of the month, regardless of the number of days in the month:

31ST DAY OF MONTH

ESP Workload Manager interprets the above expression as the 31st of January, 3rd of March (2nd of March for leap years), 31st of March., 1st of May, 31st of May, 1st of July, 31st of July, 31st of August, 1st of October, 31st of October, 1st of December, and 31st of December.


56 ESP-5.4-UG-05

Multiple times a month

• 10 am on the 3rd, 13th, and 23rd day of month:

10AM 3RD 13TH 23RD DAY OF MONTH

• 6 am from the 10th to the 20th day of each month:

6AM 10TH - 20TH DAY WITHIN MONTH

• 3rd, 9th, 10th, 11th, 12th, and 14th workday of each month:

3RD 9TH - 12TH 14TH WORKDAY WITHIN MONTH

• Every other Monday beginning next Monday:

EVERY 2 WEEKS STARTING MONDAY

• Every other Monday beginning in a week from next Monday:

EVERY 2 WEEKS STARTING MONDAY PLUS 1 WEEK

• 3rd and 4th Sunday of month if there are four Sundays in the month;3rd and 5th Sunday of month if there are five Sundays in the month:

3RD AND LAST SUNDAY OF MONTH

Yearly

• Each year on July 23:

JULY 23 YEARLY

One-time examples

• 11 pm on April 26, 2000:

11PM APRIL 26, 2000 ONCE

• 300th day of 2000:

00.300

• December 21, 2001 (assuming date format is mm/dd/yy):

12/21/01

Difference between OF and WITHIN

In most situations, you will obtain the same result when using OF or WITHIN. The following examples shows the different result between the two schedule terms:

TEST (3) 5TH SATURDAY OF AUGUST STARTING 200300.00.00 SATURDAY AUGUST 30TH 2003 DAY 24200.00.00 SATURDAY SEPTEMBER 4TH 2004 DAY 24800.00.00 SATURDAY SEPTEMBER 3RD 2005 DAY 246

TEST (3) 5TH SATURDAY WITHIN AUGUST STARTING 200300.00.00 SATURDAY AUGUST 30TH 2003 DAY 242


ESP-5.4-UG-05 57

00.00.00 SATURDAY AUGUST 30TH 2008 DAY 24300.00.00 SATURDAY AUGUST 29TH 2009 DAY 241

Using other techniques for schedule criteria

CLANG and GENTIME

For some criteria, you can use ESP Workload Manager CLANG (Control Language) or the GENTIME command.

The ESP Workload Manager Advanced User’s Guide contains some examples of schedule criteria that use the above techniques. For instance, it describes how to:

• Run a job every two weeks in an Application• Run a job based on what day of the week a particular criteria falls on• Use symbolic variables for schedule criteria• Schedule on even days of the month

Testing schedule criteria

You can test schedule criteria, prior to actually using them, with the TEST command. This tests any date or schedule specification. ESP Workload Manager responds with the actual date and time. If you specify a number in parentheses after the command, ESP Workload Manager displays as many subsequent dates and times as you indicated. This facility is also available through option E.4 from the ESP Workload Manager Main Menu.

Example: Testing criteria

If you want to test last workday of month for the next five months, type

TEST (5) LAST WORKDAY OF MONTH

ESP Workload Manager Command

Explanation

CLANG Provides you with IF-THEN-ELSE logic and some built-in functions (for example, DAYS_TO). See “Working with ESP Procedures” on page 107 for more information.

GENTIME Allows you to generate date and time symbolic variables for any date/time.

Section–Using calendars

58 ESP-5.4-UG-05

ESP Workload Manager displays output similar to the following:

00.00.00 THURSDAY MAY 31ST, 2001, DAY 15100.00.00 FRIDAY JUNE 29TH, 2001, DAY 18000.00.00 TUESDAY JULY 31ST, 2001, DAY 21200.00.00 FRIDAY AUGUST 31ST, 2001, DAY 24300.00.00 FRIDAY SEPTEMBER 28TH, 2001, DAY 271

Using calendars

ESP Workload Manager has a built-in understanding of scheduling terms, such as dates and times, based on the Gregorian calendar. Your installation can have other scheduling terms specific to it, such as holidays, special days, and special processing periods. You must define these terms to ESP Workload Manager through an ESP Workload Manager calendar. You must be aware of the security authority necessary to perform each action.

You do not need to define most calendar terms to ESP Workload Manager to use them. ESP Workload Manager already recognizes general scheduling terms. Administrators can create calendars to store definitions of scheduling elements unique to your installation—your holidays, special days and special processing periods. A calendar also identifies workdays, the first day of the week, and the start time for a day. Your administrator defines calendars and controls access to them.

Special days and periods

A special day is useful when a particular schedule criteria is difficult to describe with an algorithm. Special periods are defined the same way as special days. A set of periods with the same name can occur at regular intervals, such as fiscal year, or a trading period. You can also define periods that have irregular intervals and then refer to these special periods when specifying a schedule. A single calendar can contain many different special days and periods.

Users at your installation need to use an ESP Workload Manager calendar to define scheduling terms that satisfy their specific processing requirements. Users can define and control their own unique scheduling terms, beyond the default calendar terms. Upon installation of ESP Workload Manager, a calendar called SYSTEM is defined. It can be sufficient for your installation. All Events have read access to this calendar.

The reasons users can define their own terms include the following:

• They need to schedule work to accommodate holidays. With ESP Workload Manager you can advance, delay, or ignore processing on holidays.

• Departments have special processing requirements at specific times of the year.


ESP-5.4-UG-05 59

Example

The accounting department:

• Can consider the period from September 01 to August 31 its fiscal year• Can then define a special period in a calendar and call that period fiscal_ year • Can have ESP Workload Manager perform specific tasks in that period by

referring to the name fiscal_year when setting up schedule criteria for the tasks

Using calendar terms

Different groups of users can have their own set of unique holidays, special days and periods. Even if they choose the same names for a set of special days or periods, the reference only applies to the special day or period in the calendar named in an Event.

A calendar can contain the following:

• A list of holidays, which can span one day, several days, or just parts of a day• Lists of special processing dates• Descriptions of periods, such as fiscal months, fiscal years, and 4-4-5 periods

SYSTEM calendar

Only global holidays and special days should be stored in the SYSTEM calendar. Department-specific holidays and special days can be stored in as many calendars as required. ESP Workload Manager always uses the system calendar.

CALENDAR command

Use a CALENDAR command in an Event to refer to a maximum of two calendars. If you do not refer to a calendar in the Event, ESP Workload Manager automatically uses the default calendars your administrator assigned to you or your group. ESP Workload Manager merges holiday definitions in all calendars associated with an Event. For special days, workdays, and the first day of the week, ESP Workload Manager uses the first definition it encounters.

Note: The system calendar is always used. For example, if

• Your system calendar defines July 1st as a holiday

• You define July 2nd in calendar A and July 3rd in calendar B as holidays• You use the CALENDAR command to refer to calendars A and B

ESP Workload Manager consider that July 1st, 2nd, and 3rd are holidays.

Section–Working with calendars

60 ESP-5.4-UG-05

Default calendar

When defining holidays, special days and special periods, specify which calendar will be used to store the definition. If you do not specify a calendar name, your first default calendar as defined in your user ID entry will be used. If you do not have a first default calendar, your second default calendar is used. If you do not have any default calendars defined, the entry automatically goes into the SYSTEM calendar.

Default values for a calendar

ESP Workload Manager provides the following default values for a calendar:

• Workdays of the week—Monday to Friday, inclusively, and excluding any holidays

• Absolute days (each day starts at midnight)• The first day of the week (Sunday)

Retaining entries

ESP Workload Manager checks for and deletes old entries only when a calendar is updated for other define and delete requests. When more than two days have gone by since holiday and special day entries have occurred, they are automatically deleted unless you specify otherwise using the RETAIN operand at definition time.

Working with calendars

Defining a calendar

Before you define ESP Workload Manager calendars, you should review:

• How many calendars you need to define• Which days you need to define as workdays• Which day will be considered the first day of the week• Which group or user will own which calendar• Who will own the SYSTEM calendar

To define a calendar:

Use the DEFCAL command.

When defining a calendar, you must specify a calendar name.


ESP-5.4-UG-05 61

Optional specifications

• An owner for the calendar• A department to which the calendar belongs• The definition of the calendar as absolute or logical (defaults to absolute if not

specified)• The start time of a logical day (defaults to midnight if not specified)• The first day of the week (defaults to Sunday if not specified)• Workdays (defaults to Monday to Friday if not specified)

Example 1

This example defines the SYSTEM calendar. By default, the week starts on Sunday, and the workdays are Monday to Friday inclusively.

DEFCAL SYSTEM

Example 2

This example defines calendar FISCAL. The first day of the week is Monday, and workdays are Monday to Saturday inclusively.

DEFCAL FISCAL WEEKSTART(MON) -WORKDAYS(MON,TUE,WED,THU,FRI,SAT)

To define a calendar using panels:

1. Select option M from the Main menu.

2. Select option 3 from the Administrator Subcommands menu. The Calendar Definitions panel appears.


62 ESP-5.4-UG-05

3. Type A to define a new calendar, and specify the calendar name. The Define a Calendar panel appears.

4. Specify values as applicable.

Altering a calendar

To alter a calendar

• Use the ALTCAL command.

Example

This example changes the first day of the week for the SYSTEM calendar:

ALTCAL SYSTEM WEEKSTART(MON)

Note: You can also use the Calendar Definitions panel to alter a calendar.

Displaying a calendar

After you have defined a calendar, and those users with update access have defined their scheduling terms in the calendar, you or any other user can review information about the calendar. You can review the calendar information for troubleshooting and maintenance. Other users who have read access to the calendar will find it useful to review the calendar information before using it in an Event or Application.

To display a calendar:

• Use the LISTCAL command to display information about a calendar.

To display information about a specific calendar:

• Specify its name.

If you do not specify the calendar name, ESP Workload Manager displays information about the most recent calendar it retrieved. If you did not specify a calendar name, you are prompted for one.


ESP-5.4-UG-05 63

Example 1

This example displays information about the SYSTEM calendar. Workdays are Monday through Friday. CHRISTMAS and NEW_YEARS are two holidays defined for two years. There is one definition of a special day called INVENTORY_DAY.

listcal systemCALENDAR NAME:SYSTEMDEPARTMENT:NONEDEFINED:AT 11.45 ON THU 13TH AUG 2001 BY CYBBT01OWNER:CYBBT01WORKDAYS:MON TUE WED THU FRIWEEK STARTS:MONSIZE:280 BYTESHOLIDAYS:CHRISTMAS, NEW_YEARS, CHRISTMAS, NEW_YEARSSPECIAL DAYS:INVENTORY_DAY(1)

Example 2

This example displays information about a calendar called PAYCAL. It belongs to the PAYROLL department, and workdays are Monday through Saturday. The week starts on Monday. No holidays are defined. There are 24 definitions of PAYROLL_PERIOD and one definition of PAYROLL_REVIEW.

listcal paycalCALENDAR NAME:PAYCALDEPARTMENT:PAYROLLDEFINED:AT 08.21 ON FRI 14TH SEP 2001 BY BP01OWNER:BP01WORKDAYS:MON TUE WED THU FRI SATWEEK STARTS:MONSIZE:472 BYTESHOLIDAYS:NONESPECIAL DAYS PAYROLL_PERIOD(24), PAYROLL_REVIEW(1)

Displaying holidays and special days

The LISTCAL command displays a summary of holidays and special days.

Note: You can also use the Calendar Definitions panel to display a calendar.

To display more detailed information on these calendar items:

• Use the LISTHOL command to list holiday definitions.• Use the LISTSPEC command to list special day and special period definitions.

Deleting a calendar

A calendar can exist for a specific purpose after which the user can decide to delete it.


64 ESP-5.4-UG-05

To delete a calendar:

• Use the DELCAL command. Specify the name of the calendar you want deleted.

Note: Deleting a calendar that is referenced from an Event causes the Event to have a processing error.

In this example, ESP Workload Manager deletes calendar CENTRAL and all of its contents.

DELCAL CENTRAL

Note: You can also use the Calendar Definitions panel to delete a calendar.

Referencing a calendar

Using the DEFCAL command, you can define as many calendars as are needed for your organization.

Users can then use a CALENDAR command in an Event to refer to a maximum of two calendars plus the SYSTEM calendar. If a user does not refer to a calendar in the Event, ESP Workload Manager automatically uses the default calendars you assigned to the user or to the group to which the user belongs.

Scheduling terms

After you create a calendar, users define their unique scheduling terms in the calendar. ESP Workload Manager merges holiday definitions in all calendars associated with an Event. For special days, workdays, and the first day of the week, it uses the first definition it encounters.

The example below shows an Event with a calendar command that references the PAYCAL calendar. When ESP Workload Manager executes this Event, it reads this calendar and the SYSTEM calendar for scheduling terms.

EVENT ID(PAYROLL.PROCESSING)CALENDAR PAYCAL

Specifying a logical day

By default, ESP Workload Manager considers each day to begin at 00:00. It refers to a day that begins at 00:00 as the absolute day. However, your organization can consider its day starting at 7:30 a.m—that is, a logical day.

To define your organization’s logical day in a calendar:

1. Specify the LOGICAL parameter on the DEFCAL or ALTCAL commands.

2. Assign a value to the SHIFT parameter on the DEFCAL or ALTCAL commands.


ESP-5.4-UG-05 65

This example defines the calendar BPCAL and specifies the start of the logical day at 7:30 am

DEFCAL BPCAL OWNER(BP) LOGICAL SHIFT(07:30)

Note: You should not need to use logical calendars. They can cause unanticipated results. Cybermation recommends you use absolute calendars because of their ease of use and because they can handle almost all scheduling requirements.

Defining holidays

To define holidays:

Use the DEFHOL command.

or

Use Option L of the Main Menu.

You can use up to 16 characters to name each holiday, and you must give a start date in each holiday definition. The time duration for a holiday is 24 hours, unless you specify otherwise.

You can define multiple holidays with the same name. However, if they are on the same calendar, each holiday must have a different starting date and time. If you are creating consecutive holidays, you may find it simpler to combine them into one holiday with the duration set to the total duration of the separate holidays.

If the holiday you define was a workday, this day is no longer considered to be a workday for scheduling purposes.

Note: For logical day processing, holidays should be defined in ABSOLUTE terms even if stored in a LOGICAL calendar.

You cannot define a holiday in a given calendar if there is a special day with the same name defined in that calendar or in the system calendar. However, if the special day is defined elsewhere, you can define a holiday with the same name as the special day. In that case, a warning appears in the audit log.

Example: Defining a holiday

This example defines a 24-hour holiday, called BANK_HOLIDAY, on the next occurrence of the 1st Monday of August:

DEFHOL BANK_HOLIDAY START('1ST MONDAY OF AUGUST') FOR(24)

Section–Defining holidays

66 ESP-5.4-UG-05

Example: Defining a holiday using a panel

This example uses Option L to define a holiday.

Example: Defining a repetitive holiday

This example shows how a batch job defines a 24-hour holiday called CHRISTMAS for three years. The subsystem name for ESP Workload Manager in this example is ESPM:

//HOLIDAY JOB ...//EXEC PGM=ESP,PARM='SUBSYS(ESPM)',REGION=4000K//SYSPRINT DD SYSOUT=*//SYSIN DD *DEFHOL CHRISTMAS START('DEC25,2001') FOR(24)DEFHOL CHRISTMAS START('DEC25,2002') FOR(24)DEFHOL CHRISTMAS START('DEC25,2003') FOR(24)

Using holidays

Once holidays are defined, you can use them as you would any other scheduling terms. Some examples are shown below:

• 16:00 every holiday:16:00 HOLIDAY

• One workday before BANK_HOLIDAY:BANK_HOLIDAY LESS 1 WORKDAY

Event processing of holidays

In an Event definition, you can schedule on holidays. You can bypass, delay, or advance the schedule if it normally falls on a holiday or a particular day of the week. The calendars associated with the Event and the SYSTEM calendar are searched for holiday entries. If no calendars are specified in the Event, the owning group’s or user’s default calendars and the SYSTEM calendar are used.


ESP-5.4-UG-05 67

Job processing of holidays

The RUN statement identifies schedule criteria for a job in an ESP Application. For more information, see “Using Applications” on page 137.

• Run every holiday: RUN HOLIDAY

• Run on Christmas: RUN CHRISTMAS

• Run on workdays: RUN WORKDAYS

Example: Advancing / delaying a job

When specifying the frequency of a job in an ESP Application, you can advance or delay processing based on a holiday. For example:

RUN FRIDAY PLUS 0 WORKDAYSRUN FRIDAY LESS 0 WORKDAYS

• The first statement instructs ESP Workload Manager to run a job on Friday. If this is a holiday, run the job on the following workday.

• The second statement instructs ESP Workload Manager to run a job on Friday. If this is a holiday, run the job on the previous workday.

Defining special days

Your installation can consider its fiscal year to be from September 1 to August 31. You can define this special period to ESP Workload Manager in a calendar. Then, you can use the period in an ESP Event by specifying the calendar in the Event. However, you can only define the special period, or a special day, in the calendar if the calendar is one of your default calendars, or if you have access to the calendar. If neither of these conditions is true, ESP Workload Manager defines the special period, or a special day, in the SYSTEM calendar.

You cannot define a special day in a given calendar if there is a holiday with the same name defined in that calendar or in the system calendar. However, if the holiday is defined elsewhere, you can define a special day with the same name as the holiday. In that case, a warning appears in the audit log.

To define special days:

• Use the DEFSPEC command or use Option L of the Main Menu.

Section–Special periods

68 ESP-5.4-UG-05

Example

The following example defines April 20, 2000 as a special day called BALANCE_DAY:

DEFSPEC BALANCE_DAY ON('APR20,2000')

You can define more than one day as BALANCE_DAY.

For example:

DEFSPEC BALANCE_DAY ON('AUG23,2000')DEFSPEC BALANCE_DAY ON('OCT17,2000')

Using special days

Once you define a special day, you can then use it as a scheduling term. Some examples are shown below:

• 17:00 on BALANCE_DAY:17:00 BALANCE_DAY

• two workdays before BALANCE_DAY at 10 am:10AM BALANCE_DAY LESS 2 WORKDAYS

• One week after BALANCE_DAY at 4 pm:4PM BALANCE_DAY PLUS 1 WEEK

Example

If there is a pattern to the special days you are defining, use the REPEAT operand to define multiple special days using a single command.

The following example shows how to define the next 10 fiscal years on February 1st.

Each FISCAL_YEAR definition will be retained in the calendar called FISCAL for two years.

DEFSPEC FISCAL_YEAR REPEAT('10 TIMES FEB1 YEARLY') –CALENDAR(FISCAL) RETAIN(2,YEARS)

Special periods

A special period is the period between two special days. Therefore, you need at least two special days to use special periods.

To define the first day of each period:

• Use the DEFSPEC command.

When defining multiple regular periods, you can use the REPEAT operand of the DEFSPEC command. Specify either n times for the special period or until... to define


ESP-5.4-UG-05 69

as many periods as you need. If you are not using REPEAT, include one extra period at the end of your definitions to give ESP Workload Manager a final reference point. For example, define the first day of at least two consecutive fiscal years, so that ESP Workload Manager can calculate the start and finish of the first year. Use an alphanumeric name of up to 16 characters for the name of your special period. The first character must be alphabetic, and you should not use blanks. You can also specify the name of a particular calendar to which the period definitions apply.

Example

This example defines fiscal years:

DEFSPEC FISCAL_YEAR ON(1APRIL97) RETAIN(2,YEARS)DEFSPEC FISCAL_YEAR ON(1APRIL98) RETAIN(2,YEARS)DEFSPEC FISCAL_YEAR ON(1APRIL99) RETAIN(2,YEARS)

Period intervals

Period intervals do not have to be regular. One trading period, for example, can start three weeks after the beginning of the previous trading period, and five weeks before the beginning of the next. Simply tell ESP Workload Manager when each period starts. When two special days of the same names are defined in a calendar, you have essentially defined a period from the first special day up to the second special day. In the above example, ESP Workload Manager knows that the last day of each FISCAL_YEAR is 31st March.

Use this method for any special period you want to define, regardless of the intervals between the start of each period: every five days, three weeks, or four months.

Example

This example shows how to define payroll periods every two weeks for the next year using the REPEAT operand. Each PAYROLL_PERIOD is retained on the PAYCAL calendar for one year after it occurs.

DEFSPEC PAYROLL_PERIOD REPEAT('26 TIMES EVERY 2 -WEEKS STARTING THURSDAY') CALENDAR(PAYCAL) -RETAIN(1,YEAR)

Using ISPF panels

To achieve the same result using the ISPF panels:

1. Select Option L (Calendars) from the Main Selection Menu.

2. Select Option 4 (Define a Special Day) from the Calendar Control Menu.

Section–Working with periods

70 ESP-5.4-UG-05

3. Proceed as illustrated below:

Using special periods

Once you define a special period, you can use criteria as illustrated below:

• Last day of PAYROLL_PERIOD:LAST DAY OF PAYROLL_PERIOD

• 2nd, 3rd, and 4th day of PAYROLL_PERIOD:2ND-4TH DAY OF PAYROLL_PERIOD

• 1st day of the current PAYROLL_PERIOD:FIRST DAY OF PAYROLL_PERIOD STARTING TODAY

• 1st day of the next PAYROLL_PERIOD:PAYROLL_PERIOD

Working with periods

This example illustrates the use of 4-4-5 periods, where there is a four week period, followed by a four week period, followed by a five week period.


ESP-5.4-UG-05 71

The first few periods look like this:

Option L

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

Length of Quarter

13 weeks

13 weeks

Duration

4 weeks

4 weeks

5 weeks

4 weeks

4 weeks

5 weeks

Start of Period

June 28

July 26

August 23

Septem ber 27

October 25

Novem ber 22

Decem ber 27

ESP ------------------------------ CALENDARS ----------------------------- ESPCOMMAND ===>

Define a special day

For each occurrence of the special day you want to define, complete SPECIALDAY NAME, ON, and CALENDAR if required, then press,ENTER.The ON fields can contain specific dates and times, or schedule statementsfor special days that occur at regular intervals.

SPECIAL DAY NAME ===> PERIOD445

ON ===> 4 TIMES EVERY 13 WEEKS STARTING JUN 28 ON ===> 4 TIMES EVERY 13 WEEKS STARTING JUL 26 ON ===> 5 TIMES EVERY 13 WEEKS STARTING AUG 23 ON ===> ON ===> ON ===> ON ===> TARGET CALENDAR ===> PAYCAL SOURCE CALENDAR ===> ===>, RETAIN COUNT ===> 1 UNITS,===> Y (D=DAYS, W=WEEKS, Y=YEARS)ANY MORE? ===> (Enter Y to define more special days)

Section–Working with periods

72 ESP-5.4-UG-05

Quarters and fiscal years

You can also define quarters and fiscal years, if you need to. Once you have, you can use such criteria as shown below. You do not need to know the day of the week or the date to which each statement refers. ESP Workload Manager calculates this for you.

• First workday of PERIOD445:1ST WORKDAY OF PERIOD445

• First workday of the current PERIOD445:1ST WORKDAY OF PERIOD445 STARTING TODAY

• Last workday of the 2nd week of PERIOD445:LAST WORKDAY OF 2ND WEEK OF PERIOD445

• 4th workday of the 3rd PERIOD445 of FISCAL_YEAR:4TH WORKDAY OF 3RD PERIOD445 OF FISCAL_YEAR

ESP-5.4-UG-05 73

Processing ESP Events

An Event is a basic unit of work. Information in an Event defines when ESP Workload Manager must perform the work and the actions it must take to do so.


• Defining an ESP Event• Specifying data-set-triggered Events• Specifying FTP data-set triggered Events• Specifying explicit-data-set triggers• Specifying the function of an Event• Issuing operator commands• Specifying other requirements• Displaying the schedule• Displaying when an Event will execute• Working with defined Events

Section–Defining an ESP Event

74 ESP-5.4-UG-05

Defining an ESP Event

When you define an ESP Event, you define what you want ESP Workload Manager to perform and when you want it performed. Before saving an Event, ESP Workload Manager evaluates the schedule criteria, if any, and decides when to first schedule it. Events are saved in an EVENTSET, which is a VSAM data set defined to ESP Workload Manager. You can later display or manipulate your Event if you need to look at or change it. You can also add or delete Events at any time.

To define an Event:

Use one of the following methods:

• Use the ISPF panels • Modify and save an existing Event under a new name• Load an Event definition from a sequential data set or member of a PDS, using

the LOAD command• Define the individual commands of an Event line by line

Example

EVENT ID(PROD.FIRST_EVENT)SCHEDULE 5PM FIRST WORKDAY OF MONTHSUBMIT 'TEST.JCL.CNTL(JOB1)'ENDDEF

In this example:

• The definition begins with the EVENT command and the Event name. • The SCHEDULE command tells ESP Workload Manager when to schedule the

Event.• The SUBMIT command tells ESP Workload Manager what to do; in this case,

submit a job.• The ENDDEF command indicates the end of the definition.

When ESP Workload Manager encounters the ENDDEF command, it sends the Event to the ESP Workload Manager subsystem for processing. It also sends a message to the user who defined it, telling the date and time on which the Event will first execute, or warning the user that no schedule elements exist.

Naming an Event

The first step in defining the Event is naming. Naming an Event establishes its ownership, which is important for security. Not all users have the same authority or access to functions and resources. A security system such as RACF, CA-ACF2, or CA-Top Secret, as well as ESP Workload Manager internal security, can control the authority and access users have.

Chapter 4–Processing ESP Events

ESP-5.4-UG-05 75

Event name

An Event name has two parts:

Duplicate Events

When an Event with the same name already exists, ESP Workload Manager ignores your new definition. To replace the old definition with the new one, use the REPLACE operand.

Use of the prefix

When ESP Workload Manager triggers an Event, it must verify the security requirements of the actions the Event performs. The security identifier is determined by a number of settings. For more information on security, see the ESP Workload Manager Security Guide.

Event prefixes

In the next diagram:

• The prefix for Events TRAINING and PAYROLL is PROD.• The prefix for Event PHONE_BILL is DOROTHY.• The user DOROTHY has access to her own Events and to Events starting with

the prefix PROD.

Part of Event name Explanation

Prefix Specifies the name of a user or group containing up to 8 alphanumeric characters, including the national characters. This prefix must be a prefix you are allowed to use. Your ESP Workload Manager administrator controls which prefixes you are allowed to use.

Descriptive name Specifies a description that can contain up to 16 characters, including the national characters and the underscore. The first character must be alphabetic.

DOROTHY

PROD.TRAINING

PROD.PAYROLL

DOROTHY.PHONE_BILL


76 ESP-5.4-UG-05

Example: Naming an Event

A production scheduling group uses a prefix of PROD. They use the descriptive name PAYROLL_PROC to describe an ESP Event:

PROD.PAYROLL_PROC

Defining where an Event will execute

In a multiple CPU environment, you should use the SYSTEM operand on the EVENT command to identify the system on which the Event is to activate. This applies to Events that are not manually triggered. This is the name by which ESP Workload Manager knows the system and can not necessarily be the same as the SMF identifier. Check with your administrator or use the LSYS command for the correct name to use.

Systems

All Events that create ESP Applications should point to the ESP Workload Manager system designated as the master system. Other Events can execute on a specific system because they need to process commands for that system. If the system does not matter, you can specify SYSTEM(-).

Note: This does not affect where jobs run; JES controls that.

Example

This example identifies a system identifier of ESPM for the Event PROD.BILLING.

EVENT ID(PROD.BILLING) SYSTEM(ESPM)

Defining when an Event will execute

Trigger for an Event

The trigger for an Event can be:

• A scheduled date and time • A data-set trigger• A global-variable-table trigger• A manual trigger• A job monitor or alert trigger• A signal with a scheduled date and time


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.


ESP-5.4-UG-05 77

Specifying scheduled Events

The schedule criteria you enter specifies when to execute your Event. You can use the SCHEDULE command to specify these criteria, which generally includes a time and a frequency.

SCHEDULE command

Each command, or scheduling statement, begins with SCHEDULE followed by the time period for execution. For example:

SCHEDULE 10AM DAILY

You can specify as many SCHEDULE commands as you need. For example, you can schedule an Event at different times during a week.

SCHEDULE 4PM WEEKDAYSSCHEDULE 2PM WEEKENDS

Overlapping criteria

If the times in more than one SCHEDULE command coincide, the Event only executes once. The following example only executes once at midnight, even though the second statement also schedules an execution at midnight every fourth execution.

SCHEDULE MIDNIGHT DAILYSCHEDULE EVERY 6 HOURS ROUND WEEKDAYS

Examples: SCHEDULE commands

Some examples of schedule commands follow:

SCHEDULE 7PM DAILYSCHEDULE 10:00 LAST WORKDAY OF MONTHSCHEDULE 16:00 3RD 13TH 23RD DAY OF MONTHSCHEDULE 9AM 2ND LAST DAY OF MONTHSCHEDULE EVERY 4 HOURS ROUND


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.


78 ESP-5.4-UG-05

Example: One-time Event

The following Event executes once at 8 am on August 29, 2000. Because of the ONCE operand, the Event deletes itself 24 hours later.

EVENT ID(USER1.SPECIAL)SCHEDULE 8AM AUG29,2000 ONCESEND 'HAPPY 50TH BIRTHDAY' U(*)ENDDEF

Important: If you schedule an Event for a particular date and omit the ONCE operand, ESP Workload Manager assumes a default schedule frequency of DAILY.

Handling exceptions

An Event executes once at every time and date you specified in your SCHEDULE commands. You can use the NOSCHED command to handle exceptions.

If your SCHEDULE command has a time, then you must use the same time on the NOSCHED command.

Example: Schedule exception

This example schedules an Event at 8 am each workday, except at 8 am on the last workday of each month:

SCHEDULE 8AM WORKDAYSNOSCHED 8AM LAST WORKDAY OF MONTH

Example: Schedule exception-once

This example schedules an Event at 8 am each workday, except on February 13, 2000. The use of the operand ONCE causes the Event not be scheduled on this date only.

SCHEDULE 8AM WORKDAYSNOSCHED 8AM FEB13,2000 ONCE

Missed Events

An Event can miss its scheduled time for reasons such as:

• System trouble (system crash, power outage)• The Event is on hold• The Event class is on hold• ESP Workload Manager is placed in a suspended (quiesced) state• The Event data set is suspended at the scheduled execution time

When ESP Workload Manager cannot to execute an Event at the time you scheduled, the Event is considered overdue. When the Event becomes eligible to be processed, for


ESP-5.4-UG-05 79

example after an outage, ESP Workload Manager checks the Event definition to determine how to process the Event. The overdue count specifies how many overdue occurrences of the Event ESP Workload Manager must process.

Advance/delay/ignore/processing

Your scheduling criteria for Event execution can create conflicts. For example, if you want the Event to execute on the second day of every month except on a weekend, tell ESP Workload Manager to either:

• Advance the Event (run it sooner than usual) by any number of days or weekdays• Delay the Event (run it later than usual) by any number of days or weekdays• Ignore the Event (do not run it at all)

You can use the ON command with a SCHEDULE command to advance, delay, or ignore Event processing if the Event falls on a holiday, weekday, weekend, or particular day of the week. You can use multiple ON commands in an Event.

Example: Changing processing

If you schedule your Event to run on the 12th day of every month, but do not want it

to run if the 12th falls on a weekend or holiday, you can delay the processing using the ON command. Type ON followed by the criteria you do not want the Event to run. Then type your DELAY operand and the amount of time you want the Event delayed.

Your Event looks like this:

EVENT ID(CYBER.TWELVE)SCHEDULE 12TH DAY OF MONTHON WEEKEND DELAY 1 WEEKDAYON HOLIDAY DELAY 1 WEEKDAYINVOKE 'TEST.ESP.PROC(MYAPPL)'ENDDEF

By indicating a delay of one weekday, you ensure that, even if the 12th falls on a Saturday, Sunday, or a Holiday, it runs during the week.

Controlling Event scheduling

There are five commands you can use when you define an Event to control the processing of that Event. For example, you can schedule a deletion of an Event or schedule an Event to be suspended at some time in the future. These commands are: DELETE, HOLD and RELEASE, SUSPEND, and RESUME.

To schedule the deletion of an Event:

Use the DELETE command.


80 ESP-5.4-UG-05

You can use the DELETE command if, for example, you want to delete an Event that is only temporary. Perhaps you want to delete a daily Event after a particular date.

DELETE 10AM AUG 23, 2000

To hold an Event from being processed at a particular time:

Use the HOLD command in an Event.

When ESP Workload Manager encounters a HOLD command in an Event, it increases the Event’s hold count by one at the time and date specified in the command. As long as the hold count has a value of at least one, ESP Workload Manager delays the Event’s execution. This way you can use the HOLD command to postpone an Event.

Conversely, the RELEASE command decreases the Event’s hold count at the time and date specified in the command. When the hold count equals zero, the Event is eligible for execution.

If the Event’s scheduled time comes up while it is being held, ESP Workload Manager marks the Event as overdue. ESP Workload Manager adds a comment to a held Event if it misses its scheduled time, indicating that execution is pending and the time it should have executed.

For example:

//*EXECPEND AT('9:30 2000 JUN7')

See “Missed Events” on page 78 for a further explanation of the overdue count. After you release the Event, ESP Workload Manager checks the overdue count. If you specified a number other than zero, or let the count default to one, the Event executes immediately for every occurrence it missed while on hold, up to the value of the overdue count.

Example: Holding a data-set-triggered Event

You have an Event, PROD.PAYROLL, that is triggered by the close of the data set PAYROLL.INPUT, but you do not want it to run between 6 am and 10 pm To prevent the Event from executing in that time period, you can use the HOLD command to delay PROD.PAYROLL if the data set PAYROLL.INPUT closes between 6 am and 10 pm. The RELEASE command reduces the Event’s hold count to zero at 10 pm, letting the Event trigger if the data set was created:

EVENT ID(PROD.PAYROLL)DSTRIG PAYROLL.INPUTHOLD DAILY AT 6AMRELEASE DAILY AT 10PMINVOKE 'ESP.PROCS(PAYJOBS)'ENDDEF


ESP-5.4-UG-05 81

SUSPEND and RESUME commands

The SUSPEND command works similarly to HOLD, but has a slightly different purpose. If an Event misses its scheduled execution time while suspended, ESP Workload Manager ignores the Event and does not execute it at all or mark it overdue. Each time ESP Workload Manager encounters SUSPEND, it increases the Event suspend count by one at the specified time and date. When the suspend count is greater than zero, ESP Workload Manager bypasses the Event without executing it.

The RESUME command reduces the suspend count by one at each occurrence. When the suspend count is zero, ESP Workload Manager can execute the Event at the next scheduled time.

Example: Scheduling an hourly Event during a time range

In the following example, an Event notifies the user of the time (%ESPATIME is a symbolic variable) once an hour, on the hour, workdays, from 8 am to 4 pm. The SUSPEND command stops ESP Workload Manager from sending the message after 4:01 pm, and the RESUME command restarts the message again at 7:59 am:

EVENT ID(CYBER.HOUR_MESSAGE)SCHEDULE WORKDAYS HOURLY ROUND STARTING TODAYSEND 'TIME IS %ESPATIME' U(*)SUSPEND 16:01 WORKDAYSRESUME 7:59 WORKDAYSENDDEF

Suspended and held Event

If an Event is both suspended and held at its scheduled execution time, ESP Workload Manager ignores the hold state and considers the Event suspended.

Specifying data-set-triggered Events

An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of job names. Events can also be made to wait for triggers from activity in more than one data set. When more than one DD (data definition) statement in a step references the data set, the Event is only triggered if the DD being closed is the one that specifies DISP=NEW. See “Using data-set-trigger workload objects” on page 193 for techniques on setting up data set triggering for individual jobs in an ESP Application.

You can use data-set activity to trigger an Event through the DSTRIG command.

You can also use the DSTRIG command to set FTP data-set-triggered Events. See “Specifying FTP data-set triggered Events” on page 84.

Section–Specifying data-set-triggered Events

82 ESP-5.4-UG-05

Data-set-triggered and scheduled Events

You can use this command in addition to an Event’s time and date schedule, or instead of it. When your Event contains both SCHEDULE commands as well as DSTRIG commands, executions caused by the time schedule do not affect the DSTRIG conditions. The Event executes at both the scheduled times and, in addition, when the DSTRIG conditions are satisfied.

Abnormal closures

ESP Workload Manager does not trigger a data-set-triggered Event when the data set closes during an abnormal termination of a task or job step.

Waiting for any closure of a data set

You can use the ANYCLOSE operand to trigger an Event at closure of a data set. This means the creation of a new data set or the updating of an existing data set will trigger the Event. If you do not specify ANYCLOSE, ESP Workload Manager triggers the Event only when the applicable data set is created.

Example: Any closure

If you want any closure of data set PROD.CICS.FILE1602 to trigger your Event, type:

EVENT ID(PROD.NIGHTLY)DSTRIG PROD.CICS.FILE1602 ANYCLOSEINVOKE 'CYB.ESP.PROCS(NIGHTLY)'ENDDEF

Process flow

Visually, the flow looks like this:

Limiting data set activity to a job

You can restrict the trigger to only specific data sets created by a particular job. Use the JOB operand followed by the full name or job name prefix of the job.

Example: Job specific creation

The following Event triggers when job ABC creates a generation of the data set USER1.PAYROLL.

EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- JOB(ABC)

PROD.NIGHTLY(Event)

PROD.CICS.FILE1602(data set)


ESP-5.4-UG-05 83

INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF

Limiting data set activity to a user

You can restrict the trigger to only specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. It refers to the host security user ID of the job task closing or renaming the data set.

Example: User specific creation

The following Event triggers when user CYBER1 creates a generation of the data set USER1.PAYROLL.

EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- USER(CYBER1)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF

Waiting on multiple data sets

You can have an Event that needs multiple data sets to close before it is triggered. You can indicate each of the multiple data sets with the MULTIPLE operand. When ESP Workload Manager encounters the MULTIPLE operand, it notes the individual closures of data sets, but it does not trigger the Event until all the DSTRIG commands containing a MULTIPLE operand have been satisfied by a data set closure.

Example: Waiting on multiple data sets

EVENT ID(PROD.MULTI_CLOSE)DSTRIG USER1.PAYROLL.REPORT ANYCLOSE MULTIPLE DSTRIG USER.PAYROLL.G- MULTIPLE JOB(ABC)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF

When both of the following criteria have been met, the Event is triggered:

• Any closure of data set USER1.PAYROLL.REPORT• Job ABC creates a generation of data set USER1.PAYROLL

Note: When you display an Event definition containing the MULTIPLE operand, ESP Workload Manager shows each detected data set closure as PRIMED.

Waiting on multiple closures of the same data set

It is possible that a data set will be closed several times. You can use the COUNT operand to specify how many closures will actually trigger the Event. With each closure, ESP Workload Manager increases its internal counter by one. When the counter reaches the number you set in your COUNT statement, the Event is triggered and the counter resets to zero. You can display the Event at any time to see the current value of the counter.

Section–Specifying FTP data-set triggered Events

84 ESP-5.4-UG-05

You can specify several DSTRIG commands for one Event, and each can maintain its own separate counters.

Example: Running a compress job after 100 closures of a data set

If you want a job to submit automatically after every 100 closures of a data set, you could use the COUNT operand followed by 100 as below. This example Event submits a COMPRESS job for a COPYJCL data set after every 100 closures of that data set:

EVENT ID(CYBER.COPYJCL_COMPRESS)DSTRIG CYBER.COPY.JCL COUNT(100)SUBMIT PROD.JCL.CNTL(COMPRESS)ENDDEF

Displaying data-set-triggering information

Below are commands that relate to data-set triggering. They are useful for displaying data set trigger information.

Output from these commands looks like this:

ldxeEvent/Appl -- Wob ------------ Data set --- CYB001.EVENT.DAILY1 CYB001.DATA.SET1, AnyClose, User(CYB-)CYB002.EVENT.DAILY2 CYB002.DATA.SET2, AnyClose, Job(CYB002), User(CYB002), Ftp(Send), Logon(aixuser-), Host(AIXHOST)APPL001.26 DSTRIG1 CYBER.DATA.SET1, AnyClose, Job(FTPSERVE), User(CYB001), Ftp(Receive), Host(10.23.100.5)3 entries displayed

ldteThe following data set(s) are being checked for data set triggers: CYB001.DATA.SET1, AnyClose, User(CYB-) CYB002.DATA.SET2, AnyClose, Job(CYB002), User(CYB002), Ftp(Send) Logon(aixuser-) CYBER.DATA.SET1, AnyClose, Job(FTPSERVE), User(CYB001) Ftp(Receive)3 data set triggers found

Specifying FTP data-set triggered Events

FTP data-set-triggered Events are a particular kind of data-set-triggered Event where an Event is triggered when a successful FTP file transfer or FTP rename completes.

Command Use this command to ...

LDXE display data-set-triggered Events.

LDTE display data sets being checked for closures, creations, or renames.


ESP-5.4-UG-05 85

When setting up an FTP data-set Event, the file transfer causing the Event to be triggered can be defined by:

• Specifying the direction of the transfer• Limiting data set activity to a host• Limiting data set activity to a user ID• Limiting data-set activity to a logon ID

Specifying the direction of the transfer

You can specify that the data-file-transfer direction is from the remote FTP partner to the local mainframe FTP partner or vice versa. Use the FTP operand followed by RECEIVE or RECV if the transfer is from the remote FTP partner to the local mainframe FTP partner. Use the FTP operand followed by SEND if the transfer is from the local mainframe FTP partner to the remote FTP partner.

Examples: FTP RECEIVE and SEND

The following Event triggers when a file is successfully received from a remote FTP partner, creating a generation of the data set USER1.PAYROLL.

EVENT ID(PROD.PAY_DATA)DSTRIG USER1.PAYROLL.G- FTP(RECEIVE)INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF

The following Event triggers when the data set CYBER.XFER.001 is successfully sent from the local mainframe FTP partner to a remote FTP partner.

EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(SEND)INVOKE 'PURGE.XFER(001)'ENDDEF

Limiting data set activity to a host

You can restrict the trigger to FTP transfer from a specific host only. Use the HOST operand followed by the IP address of the specified host in dotted decimal format or DNS host name format.

Example: Host specific creation

The following Event triggers when a remote FTP partner with the IP address 10.1.3.1 successfully transfers a file creating the data set CYBER.XFER.001.

EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) HOST(10.1.3.1)INVOKE 'PROCESS.XFER(001)'ENDDEF

Section–Specifying FTP data-set triggered Events

86 ESP-5.4-UG-05

Limiting data set activity to a user ID

You can restrict the trigger to specific data sets created or renamed by a particular user ID. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the local FTP partner’s job task regardless of whether the local FTP partner is the client or the server.

Note: Because user ID always refers to a local mainframe host security user ID, lower case characters are translated to upper case.

Example: User-specific creation

The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the user ID prefix of the local FTP partner is CYB.

EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) USER(CYB-)INVOKE 'PROCESS.XFER(001)'ENDDEF

Limiting data-set activity to a logon ID

You can restrict the trigger only to specific data sets created or renamed by a particular user. Use the LOGON operand followed by the logon ID of the user.

The logon ID refers to the user ID that the FTP client uses to logon to the FTP server.

If the FTP client is the remote partner, the logon ID is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).

If the FTP client is the local partner, then logon ID is the user ID of the remote FTP partner.

Note: When logon ID is a remote user ID, it can be case sensitive, as for example on UNIX hosts. Therefore logon ID lower case characters are not translated to upper case.

Example: Logon specific creation

The following Event triggers when a remote FTP partner successfully transfer a file creating the data set CYBER.XFER.001, assuming that the remote FTP partner did logon to the FTP server with the CYBER005 user ID.

EVENT ID(CYBER.XFER)DSTRIG CYBER.XFER.001 FTP(RECEIVE) LOGON(CYBER005)INVOKE 'PROCESS.XFER(001)'ENDDEF


ESP-5.4-UG-05 87

Notes on FTP trigger operands

dsname

The data set name of the DSTRIG Event command always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).

ANYCLOSE

FTP triggers cannot distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition.

RENAME

When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename the data set to the specified data set name. Because data set name always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore, the RENAME and FTP(SEND) operands are mutually exclusive.

Example

The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.

EVENT ID (USER.APPL_RECEIVE)DSTRIG CYBER.DATA.SET USER(CYB-) FTP(RECEIVE) HOST(AIXHOST)-LOGON(aixuser)SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDDEF

Specifying explicit-data-set triggers



• The explicit data-set trigger notification utility program (CYBESDT1).• The operand EXPLICIT in the DSTRIG command.

Section–Specifying explicit-data-set triggers

88 ESP-5.4-UG-05

You invoke CYBESDT1 in a job, as an additional step, conditionally to the successful execution of the step manipulating a specified data set. This program writes an SMF record type 132 subtype 1.

An explicit data-set trigger is defined to ESP Workload Manager via the EXPLICIT operand in the DSTRIG command.

Explicit data-set trigger SMF record requirement

An installation must cut SMF type 132 subtype 1 SMF record for explicit data-set triggering to function.

Explicit data-set trigger notification utility program (CYBESDT1)

ESP Workload Manager receives notification of an explicit data-set trigger when CYBESDT1 is executed.

CYBESDT1 requires the following input parameters:

• The DSNAME of the data set causing the activation of the data-set trigger• The volume serial number where the data set resides, if the data set is uncataloged.• The SUBSYSTEM identifier of the ESP Workload Manager that the explicit data-

set trigger will be sent to

CYBESDT1 writes a user SMF type 132 subtype 1 record containing information required for the explicit data-set trigger.

The target ESP Workload Manager subsystem examines the SMF record, and if a matching explicit data-set trigger definition is found, activates the data-set trigger.

Program CYBESDT1 can execute in a batch, TSO, started task, or run task environment (for example, Connect:Direct (NDM)). It must also be APF-authorized or the attempt to write the explicit data-set-trigger SMF record fails with an ABEND047.

Program CYBESDT1 is reentrant.

Note: If you execute CYBESDT1 with a relative GDG in a job that creates new generations, the position of the CYBESDT1 step in the job determines the generation being selected. CYBESDT1 considers that the current generation (relative generation (0)) is the latest generation created when it executes.

CYBESDT1 input parameters

The input parameters of CYBESDT1 are specified in the JCL EXEC PARM for a batch job, and as operands when running as a TSO command.

The syntax is as follows:

DSNAME|DATASET(dsname[(member)|(relgen)]) - {VOLSER|VOLUME(volser)} [SUBSYSTEM|SSID(subsystem)] - [VERIFY|NOVERIFY]


ESP-5.4-UG-05 89

Parameter Description

DSNAME or DATASET Is the data-set name keyword.

dsname Specifies the name of a data set.

member Specifies a member name of a PDS.

relgen Specifies the relative generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in CYBESDT1 and in the corresponding DSTRIG command or DSNAME statement exactly the same, including leading zeros.

Note: you can also include the absolute generation in dsname. For example:

CYB4.ENCXX.BACKO01A.G0027V00

VOLSER or VOLUME Is the volume serial number keyword.

volser Specifies the volume serial number that the data set resides on. It is required for uncataloged data sets and optional for cataloged data sets.

SUBSYSTEM or SSID Is the ESP Workload Manager subsystem identifier keyword.This parameter is optional, if omitted, all tracking ESP Workload Manager subsystems will receive the explicit data-set trigger SMF record that program CYBESDT1 writes.

subsystem Specifies the subsystem name of a tracking ESP Workload Manager that will receive the explicit data-set trigger SMF record that program CYBESDT1 writes.

Note: A tracking ESP Workload Manager subsystem is one whose ESPPARM initialization file does not contain the following statement:

SMFINT OFF

VERIFY Specifies that CYBESDT1 will set the explicit data-set trigger only if the following criteria are met:• The specified data set is catalogued if the VOLSER or

VOLUME parameter is omitted.• The specified data set resides on the specified volume.

(From the volser parameter if specified, from the catalog if not.)

• The owning user of the job executing CYBESDT1 has update access to the data set specified.

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

Section–Specifying explicit-data-set triggers

90 ESP-5.4-UG-05

CYBESDT1 return codes

CYBESDT1 issues a zero return code if the explicit data-set trigger SMF record was successfully written, and a non-zero return code if any error condition occurs that causes the explicit data-set trigger SMF record not to be written.

Examples

Invoking CYBESDT1 from page mode or line mode

To run CYBESDT1 from page or line mode, you must prefix the command with TSO because CYBESDT1 is external to ESP Workload Manager.

TSO command example:

TSO CYBESDT1 D(PDS.DATA.SET(MEMBER1))

TSO call example:

CALL 'CYBER.SSCPLINK(CYBESDT1)' 'D(PDS.DATA.SET(MEMBER1))'

Explicit data-set trigger notification batch example

In the following example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.

If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.

//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK

You use the following to trigger MYEVENT when the data set PDS.DATA.SET(MEMBER1) has been created or updated:

EVENT ID(MYEVENT)DSTRIG PDS.DATA.SET(MEMBER1) EXPLICITENDDEF

Explicit data-set trigger notification Connect:Direct (NDM) run task example

In the following example, STEP1 copies the data set OLD.DATA.SET from Connect:Direct node NODE1 to the local Connect:Direct node as data set NEW.DATA.SET.


ESP-5.4-UG-05 91

If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set NEW.DATA.SET has been created by the Connect:Direct copy operation.

PROCESS1 PROCESS SNODE=NODE1STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET - TO(SNODE DSN=NEW.DATA.SET DISP=(NEW,CATLG,DELETE))IF (STEP1 EQ 0) THENSTEP2 RUN TASK (PGM=CYBESDT1 - PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) SNODEEIF

Specifying the function of an Event

ESP Workload Manager can perform a variety of tasks through the Events you define. An Event must do one of the following:

• Send a message to you, other users, or operator consoles• Submit JCL • Invoke an ESP Procedure• Execute an instream Procedure• Generate a copy of the JCL for every job• Issue an operating system command

This section describes these tasks and the commands associated with each.

Sending messages

You can use an Event to send a message to yourself, another user, a group of users, or an operator console. To send a message, enter the SEND command followed by the message in single quotes, and the user ID or console identifier to which the message is being sent. You can include several SEND commands in any single Event.

Example: Sending a message

The following Event is scheduled at 8 am each day and sends a message to USER1.

EVENT ID(USER1.MESSAGE)SCHEDULE 8AM DAILYSEND 'SCHEDULING IS EASY WITH ESP' USER(USER1)ENDDEF

Submitting JCL

You can use an ESP Event to submit JCL from a data set to JES using the SUBMIT command. A single Event can submit more than one job. If there are relationships between the jobs you are submitting, you must use an ESP Procedure to submit them.

Section–Specifying the function of an Event

92 ESP-5.4-UG-05

For more information on submitting related jobs, see “Using Applications” on page 137.

You can also use ESP Workload Manager to submit jobs from Librarian and Panvalet data sets using different statements as outlined in the next section.

Note: You cannot use the Consolidated Status Facility to monitor and control jobs submitted from an Event.

Example: Submitting a job

You can create an Event PROD.INVENTORY that, at 7 am on the last workday of every month, submits member BACKUP1 of data set PROD.JCL.CNTL. The Event looks like this:

EVENT ID(PROD.INVENTORY)SCHEDULE 7AM LAST WORKDAY OF MONTHSUBMIT 'PROD.JCL.CNTL(BACKUP1)'ENDDEF

Example: Submitting multiple jobs

The following Event submits two jobs at 7 am on the last workday of each month. The jobs can run in any order or concurrently. The Event looks like this:

EVENT ID(PROD.INVENTORY)SCHEDULE 7AM LAST WORKDAY OF MONTHSUBMIT 'PROD.JCL.CNTL(BACKUP1)'SUBMIT 'PROD.JCL.CNTL(BACKUP2)'ENDDEF

Submitting JCL from Librarian and Panvalet data sets

In addition to the SUBMIT command, there are special commands to submit jobs directly from Librarian and Panvalet data sets. You can use multiple commands in an Event. ESP Workload Manager effectively concatenates the input data to form one or more jobs.

Librarian data sets

To submit a job directly from a Librarian data set:

Enter the LIBSUB command followed by the data-set name and the name of the data-set member you want to submit, like this:

LIBSUB LIB1.DATA(PRODCNTL)

ESP Workload Manager supports multiple LIBSUB commands.

Note: You do not need to specify the LIB- data-set identifier because the LIBSUB command implies a Librarian data set.


ESP-5.4-UG-05 93

Panvalet data sets

To submit a job directly from a Panvalet data set:

Enter the PANSUB command followed by the data set name and the name of the member you want to submit:

PANSUB PANDS.DATA MEMBER(DLYPAYROLL)

OR

Use this format, if the member name is no more than eight characters:

PANSUB PANDS.DATA(PAYROLL)

ESP Workload Manager supports multiple PANSUB commands.

Note: You do not need to specify the PAN- data-set identifier because the PANSUB command implies a Panvalet data set.

Invoking ESP Procedures

You can create an Event to invoke an ESP Procedure. An ESP Procedure is a set of instructions for ESP Workload Manager. The most common use of an ESP Procedure is to define an ESP Application. A Procedure can contain statements that:

• Define a group of related jobs• Define and assign values to symbolic variables• Define complex processing requirements

Invoking an ESP Procedure causes ESP Workload Manager to execute the instructions within the ESP Procedure. To invoke any ESP Procedure, you must first create the ESP Procedure, and then define an Event to invoke that ESP Procedure.

The INVOKE command invokes an ESP Procedure by specifying where the ESP Procedure is stored. In the following example, the ESP Procedure is stored in the PAYROLL member of the data set PROCS.ESP.PAY:

EVENT ID(PROD.PAYJOBS)SCHEDULE 17:00 DAILYINVOKE 'PROCS.ESP.PAY(PAYROLL)'ENDDEF

Note: ESP Workload Manager allows multiple INVOKE commands. However, an Event can only generate one Application. If you need more than one Application, you must create one Event per Application.

Executing an instream ESP Procedure

You can include an ESP Procedure in an Event. The ESP Procedure statements are enclosed between the PROC and ENDPROC commands.

Section–Specifying the function of an Event

94 ESP-5.4-UG-05

Important: You must code the ENDPROC command at the end of an instream Procedure

Note: You cannot use panels to add an instream procedures in an Event. Create the Event first with the panels and, then, add the instream procedure by editing the Event.

To browse or edit instream procedures from the CSF, use the BE and EE commands. This is because the instream procedure is inside the Event and cannot be browsed or edited independently.

The following is an example of an Event including an instream ESP Procedure:

EVENT ID(PROD.WITHPROC)SCHEDULE DAILY AT 6PMPROCAPPL WITHPROCJCLLIB PROD.JCLJOB ARUN DAILYRELEASE JOB BENDJOBJOB BRUN DAILYENDJOBENDPROCENDDEF


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.


ESP-5.4-UG-05 95

You can also specify COPYJCL within a Procedure to identify one or more jobs for which you want to use COPYJCL. This gives you the advantage of using COPYJCL for specific jobs.

When you use the COPYJCL command, you must also specify the library that is to receive the copy, followed by either the JOBNAME or JOBID operand. The operands you use influence the member name ESP Workload Manager assigns to the JCL copy.

Using the JOBNAME operand

The JOBNAME operand requests that the member name used for storing the JCL for a job is the same as the job name. This is the default. Each submission of a particular job overwrites the previous copy of that job JCL.

Using the JOBID operand

Use the JOBID keyword when you want ESP Workload Manager to store the copy of the JCL by job number. ESP Workload Manager creates a member name in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary. Job numbers are assigned sequentially and the sequence is restarted (“rolled over”) when the maximum number is reached. After the roll-over, member names are overwritten when the corresponding job number reoccurs.

Example: Using COPYJCL

This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by job name.

EVENT ID(EMP.MYJOBS)SCHEDULE 5PM WORKDAYSINVOKE 'EMP.ESP.PROC(WKJOBS)'COPYJCL 'CYBER.JCL.COPY' GEN(0) JOBNAMEENDDEF

Compressing COPYJCL

If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You could use a data-set-triggered Event to submit the compress job automatically after a number of closures.

Issuing operator commands

To issue an operator command:

Enter the VS command followed by the operator command you want to issue.

Section–Specifying other requirements

96 ESP-5.4-UG-05

Example: Starting tasks

If you want ESP Workload Manager to start IMS10 and IMS20 each day at 6 am, use the VS command in your definition, as shown below. The commands will be issued on the SYSB system.

EVENT ID(OPER1.START_IMS) SYSTEM(SYSB)SCHEDULE 6AM DAILYVS 'S IMS10'VS 'S IMS20'ENDDEF

There are restrictions on which users can issue operator commands. Contact your administrator to find out if you are authorized to issue any operator commands.

Specifying other requirements

When you define an Event, you can also specify:

• Symbol library names• Calendar names• Notification list (MAILLIST)• Comments

Setting symbol libraries

ESP Workload Manager has a set of built-in symbolic variables. Your ESP Workload Manager administrator can define symbol libraries to store user-defined symbolic variables. A symbol library consists of one or more data sets or data-set members. Variables can include date formats, control cards, and other information ESP Workload Manager can use when processing the workload. You can use the SYMLIB command in an Event to specify symbol libraries. If a variable is assigned more than one value, ESP Workload Manager uses the last assigned value.

Example

This example references the symbol library called DATES. When ESP Workload Manager processes the Event, it opens each data set associated with this symbol library and uses this information to perform substitution of symbolic variables.

EVENT ID(CYBER.PAYROLL)SYMLIB DATESINVOKE 'CYB.ESP.PROCS(PAYROLL)'ENDDEF

You can also define and work with symbols as part of an ESP Procedure. See the ESP Workload Manager Advanced User’s Guide for detailed information on creating and using symbolic variables.


ESP-5.4-UG-05 97

Setting special calendars

ESP Workload Manager lets you define dates that can be unique to your organization. If, for example, Labor Day is a regular holiday at your installation, you can define it as such in your calendar.

ESP Workload Manager contains an installation defined SYSTEM calendar based on the 12-month Gregorian calendar. You can use the CALENDAR command to specify up to two additional calendars for the Event, so that you can schedule Events in terms that can be unique to your calendar. If you do not specify a calendar, ESP Workload Manager uses the calendars assigned by default to the group or user that owns the Event. For more information on calendars, see “Schedule Criteria” on page 43.

ESP Workload Manager merges holiday definitions in all calendars associated with an Event. When special days or periods use the same name in different calendars, ESP Workload Manager uses the first definition it finds. ESP Workload Manager searches in this order:

1. The first calendar you define for the Event, or the first default calendar.

2. The second calendar you define for the Event, or the second default calendar.

3. The SYSTEM calendar.

Example: Specifying a calendar in an Event

If you want your Event to execute on the second day of your fiscal month, you must first set the calendar so that ESP Workload Manager knows where to look for the definition of what a fiscal month is. In the Event below, the CALENDAR command tells ESP Workload Manager which previously defined calendar (for example, FISCAL) to refer to when scheduling the Event:

EVENT ID(CYBER.FISCAL_JOBS)CALENDAR FISCALSCHEDULE 2ND DAY OF FISCAL_MONTHSUBMIT 'PROD.JCL.CNTL(FISJOB1)'ENDDEF

Notification list (MAILLIST)

If an Event needs to send messages the messages are sent to the user that owns the Event. You can redirect those messages to a notification list instead.

The notification lists are included in the MAILLIST data set. The MAILLIST data set contains any number of MAILBOX initialization parameters, each of them containing any number of TSO user IDs and email addresses. You select where the Event sends messages by coding a mailbox name in the MAILBOX operand. Messages will be sent to all TSO user IDs and email addresses specified in the mailbox. See the “MAILLIST data set” section in the ESP Workload Manager Installation and Configuration Guide for information on how to set up the MAILLIST data set and the mailboxes.

Section–Displaying the schedule

98 ESP-5.4-UG-05

Example: Using the notification list

In the following example, all messages from Event CYBER.PAYROLL are directed to all TSO user IDs and email addresses contained in the CYBERBOX mailbox.

EVENT ID(CYBER.PAYROLL) MAILBOX(CYBERBOX)SYMLIB DATESINVOKE 'CYB.ESP.PROCS(PAYROLL)'ENDDEF

Adding comments

You can use the COM command to add any number of comments, anywhere in an Event. ESP Workload Manager ignores them when it executes the Event.

Example: Using comments in an Event

If you want to include a comment in your Event that tells you the Event is a manually triggered Event to submit JOBX, you could use the COM command, like this:

EVENT ID(PROD.JOBX)COM MANUALLY TRIGGERED EVENT TO SUBMIT JOBXSUBMIT 'PROD.JCL.CNTL(JOBX)'ENDDEF

Displaying the schedule

You can use the LISTSCH command to display the Event names and times of the current schedule cycle (normally 24 hours). These elements include the names and execution times of all the Events in the schedule, and the overdue, held, or deferred queues. The LISTSCH command does not display the names or submission times for individual jobs within Events. To display the schedule for jobs, see “Reporting on scheduled activity” on page 298.

Example

For example, to display all entries on the current schedule cycle, type:

LISTSCH

Note: If an Event is scheduled more than once during the current schedule cycle, ESP Workload Manager only displays the time of the first execution. ESP Workload Manager stores only one instance of the Event and does not calculate the next execution time until it has executed the Event.


ESP-5.4-UG-05 99

Expected execution

The LISTSCH command can only display scheduled Events. If you want to display Events that do not have SCHEDULE commands, such as Events triggered by data-set activity you can use the EXPECT command.

The EXPECT command uses the same format as the SCHEDULE command, but it does not cause an Event to execute.

Example: Expected time of an Event

If your Event is usually triggered by the creation of a data set every morning at approximately 11 am, you could insert an EXPECT command in your Event definition to tell ESP Workload Manager when to expect the Event, like this:

EVENT ID(USER01.MY_EVENT)SUBMIT 'USER01.JCL.CNTL(MYJOB)'EXPECT 11AM DAILYDSTRIG MY.DATA.SET ANYCLOSEENDDEF

Triggering expected Events

The EXPECT command normally does not affect the schedule. If the data set that triggers the Event, in the above example, has not been created by the expected time, the Event continues to wait. However, if you trigger an Event that has an EXPECT command and you keep the REPLACE option, ESP Workload Manager treats the EXPECT command the same as a SCHEDULE command. ESP Workload Manager selects jobs and substitutes variables based on the expected time and date.

Displaying when an Event will execute

Using the NEXT command, you can display the next scheduled executions of an Event. The NEXT command lets you specify the number of execution times you want to test, up to a maximum of 99. As long as your Event contains at least one SCHEDULE command, ESP Workload Manager computes the execution times and dates for the number of executions you specify.

Example: Displaying the next execution times of an Event

If you want to know the next five execution dates and times for the Event PROD.LWD, you could use the NEXT command. The following shows the NEXT command and sample output from the command. ESP Workload Manager displays the next five scheduled times and dates:

NEXT 5 PROD.LWDSCHED AT 19.00.00 ON SATURDAY JANUARY 31ST, 2000

Section–Working with defined Events

100 ESP-5.4-UG-05

SCHED AT 19.00.00 ON SATURDAY FEBRUARY 28TH, 2000SCHED AT 19.00.00 ON TUESDAY MARCH 31ST, 2000SCHED AT 19.00.00 ON THURSDAY APRIL 30TH, 2000SCHED AT 19.00.00 ON SUNDAY MAY 31ST, 2000

Working with defined Events

The section “Controlling Event scheduling” on page 79 describes five commands for controlling an Event during definition. You can use ESP Workload Manager commands in Line mode, Page mode, batch, and through the ISPF interface, to control an Event after you define it.

Commands and their function

The following table summarizes the available commands and their function:

For ISPF users

To access the ISPF panels:

1. Select Option E on the Main Menu.

2. Select Option 3 on the Event Management Menu.

3. Type the appropriate code letter for the action you want to take and the Event’s name (prefix and descriptive name).

OR, you can:

1. Select Option E on the Main Menu.

2. Select Option 3 on the Event Management Menu.

Command Function

ALTER Alters the characteristics of an Event.

CLASS Controls the classes of Events (requires OPER authority; not available through panels).

DELETE Deletes an Event.

HOLD Holds an Event from processing.

LIST Lists an Event name or definition.

RELEASE Releases a held Event for processing.

RESUME Resumes processing of a suspended Event.

SIMULATE Simulates the functions of an Event.

SUSPEND Suspends an Event from processing.

TRIGGER Triggers execution of an Event.


ESP-5.4-UG-05 101

3. Type the prefix of the Event in the PREFIX field for multiple Events.

4. Press Enter. A list of Events appears.

5. Type the code letter for the action you want to take beside the Event name.

Note: The ISPF interface also provides BROWSE and EDIT options.

Listing Event names or definitions

ESP Workload Manager contains a LIST command that you can use to display:

• Event names• Next execution times• System IDs for Events• Complete Event definitions

For example, to see the names and next execution times of the defined Events starting with the prefix PROD, type the command below. The LEVEL operand identifies the Event prefix.

LIST LEVEL(PROD)

Note: In ISPF, you must abbreviate the LIST command to simply the letter L.

Simulating an Event

You can simulate the functions of any defined Event using the SIMULATE command. For the Event you select, the SIMULATE command tells you which jobs ESP Workload Manager submits, any messages it sends, how it substitutes symbolic variables, and so on. This command is particularly useful with ESP Procedures because you can use it to see how the complex and conditional components of your Procedure will run at a particular date and time. ESP Workload Manager also displays error messages if it encounters problems, such as syntax errors or successor loops in an ESP Procedure. You can simulate an Event for a day on which it is not normally scheduled; ESP Workload Manager simulates what would happen if the Event was triggered on that particular day.


102 ESP-5.4-UG-05

Options

There are a number of other options available with the SIMULATE command. For example, you can:

• Suppress the printing of the ESP Procedure listing.• Simulate data-set triggers, signal processing and job monitor Events.• Simulate Procedures invoked by the simulated Procedure as well as monitor

Events and other directly invoked Events.• Invoke a JCL scan exit during simulation. An indicator will be passed to this exit

indicating that this is a simulation rather than real Event execution.• Perform full syntax checking on all ESP Workload Manager commands invoked.• Direct the JCL output to a data set.• Suppress the execution of REXX code within an ESP Procedure.• Display all successors that were inherited because a job was not selected for some

reason on the job selection report.• Display jobs that were not selected for any reason on the job selection report.

Specifying the options

You specify these options using the SIMULATE command or on the Simulate Event Execution panel.

On the SIMULATE command, specify the Event name and any schedule operands. If you do not enter any operands, ESP Workload Manager either simulates the next occurrence of the Event, or, if the Event has no schedule execution, it assumes an execution time NOW.

Example: Simulating an Event

You can simulate the results of executing an Event named CYBER.TEST1 on the last workday of the current month. Enter the following command in Page mode:

SIMULATE EVENT(CYBER.TEST1) SCHED('LAST WORKDAY OF MONTH')

Triggering an Event manually

Triggering an Event

You can manually trigger an Event at any time through the TRIGGER command. Enter the command TRIGGER, followed by the Event’s name and the time at which you want it to execute. The default time is now.

If you specify a time in the past, ESP Workload Manager triggers the Event immediately and processes the Event as if it was this prior date. ESP Workload Manager selects jobs and resolves symbolic variables as if it were this date in the past. DELAYSUB/EARLYSUB statements are ignored unless they use the term REALNOW that reflects the actual time of Event trigger.


ESP-5.4-UG-05 103

The Event execution either replaces the next scheduled execution, or it can be a temporary addition to the schedule.

Adding executions

You can use the ADD option to schedule executions of the Event that you want to add to the Event’s normal schedule. ESP Workload Manager processes the ADD operand in the same way it processes a SCHEDULE command. A TRIGGER ADD always causes the Event to execute. If there is a HOLD or SUSPEND, ESP Workload Manager does not execute the Event and produces an error message.

For example, if you need to run an Event now in addition to its scheduled time of 7 pm, trigger the Event with the ADD option.

TRIGGER USER01.FIRST_EVENT ADD

Note: An installation can set the default on the TRIGGER command to ADD or REPLACE.

Replacing scheduled executions

When you want to process an Event at a time different than its next scheduled time, you can use the REPLACE option. REPLACE advances the execution time for an Event. For example, if you need to run an Event now instead of at 7 pm, trigger the Event with the REPLACE option.

When you use the REPLACE option, ESP Workload Manager selects jobs and resolves symbolic variables based on the replaced time and date. For example, if you have an Event that runs every Saturday and this week you want to run the Event on Friday instead, you can trigger the Event with the REPLACE option. ESP Workload Manager selects the jobs and resolves symbolic variables based on Saturday’s date.

The following example uses REPLACE to replace the next scheduled execution of an Event called PROD.PAYROLL.

TRIGGER PROD.PAYROLL REPLACE

Bypassing a scheduled Event

If you want to bypass the next execution of a scheduled Event, you can trigger the Event and specify NOXEQ. This can be used when you trigger an Event in error, and you need to undo this operation, or when you want to cancel one execution of an Event.

The following example bypasses the next scheduled execution of the Event called PROD.BAD_EVENT.

TRIGGER PROD.BAD_EVENT NOXEQ


104 ESP-5.4-UG-05

Postponing execution of an Event

When you use the HOLD command outside the Event definition process, ESP Workload Manager increments the Event’s hold count immediately. When you use the HOLD command within a definition (explained in “Controlling Event scheduling” on page 79), ESP Workload Manager does not increment the count until the scheduled date and time.

Holding and releasing an Event

By issuing the HOLD command followed by an Event name, you postpone execution of that Event until its hold count is reduced to zero. Every HOLD increases the count by one; every RELEASE command reduces it by one.

When a held Event is released and it has missed a scheduled execution, ESP Workload Manager executes the Event once for each scheduled execution that the Event missed, up to the number of times in the overdue count. This count is specified by the OVERDUE operand on a SCHEDULE command and defaults to one.

Example: Holding an Event

If you have an Event with the name PROD.MYEVENT, you can place it on hold (increasing its hold count by one) by typing the following:

HOLD PROD.MYEVENT

Bypassing execution of an Event

Outside of an Event definition, the SUSPEND command immediately increases the suspend count by one, telling ESP Workload Manager to bypass the Event you name. A suspended Event remains in that state until it is resumed. All scheduled executions and manual triggers of the Event are bypassed.

Suspending and resuming an Event

By issuing the SUSPEND command followed by an Event name, you bypass the execution of that Event until its suspend count is reduced to zero. Every SUSPEND increases the count by one; every RESUME command decreases it by one. When the suspend count reaches zero, the Event is eligible for execution. If the Event misses any execution times while suspended, ESP Workload Manager ignores them and does not consider the Event overdue.

Example: Suspending an Event

If you have an Event with the name PROD.MYEVENT, you can suspend it by typing the following:

SUSPEND PROD.MYEVENT


ESP-5.4-UG-05 105

Note: If the Event is both held and suspended at a scheduled execution time, ESP Workload Manager treats the Event as suspended and therefore does not consider it overdue.

Overdue Events

Event classes

After a long system outage, ESP Workload Manager makes it easy for you to manipulate classes of Events so that the system can process high priority work first. For more information on manipulating classes of Events see the ESP Workload Manager Operator’s Guide.

Overdue Events

Add OVERDUE to the end of your SCHEDULE command, and then a number in brackets indicating how often the Event should execute if it misses its scheduled time. The default is 1.

Example: Overdue Events

If you do not want an Event to run, even if it misses its 10 am scheduled execution time, type the command below. Because you do not want it to execute, type the number zero in the brackets:

SCHEDULE 10AM WORKDAYS OVERDUE(0)

Altering Events

To change certain characteristics of one or more Events:

Use the ALTEVENT command.

Specify any number of operands to cause multiple changes to a single Event or group of Events. When the name contains asterisks or a hyphen, ESP Workload Manager alters all matching entries. If you are unsure of which Events a particular command will affect, use a LIST command to display the Events.

Use the ALTEVENT command to change calendars, classes, symbol libraries, and system identifiers, in addition to adding or subtracting hours or minutes to compute a new set of time and date schedules.

Example: Altering system identifier

The example below alters all Events prefixed by MYGROUP, with SYSTEM identifiers beginning with OLDA, to execute on the system NEWA. The SYSTEM


106 ESP-5.4-UG-05

identifier corresponds to the ESP Workload Manager system identifier, defined by ESP Workload Manager SYSID initialization parameter.

ALTEVENT MYGROUP.- SYSTEM(NEWA OLDA)

Deleting Events

To delete an existing Event:

Use the DELETE command.

This removes the Event from the Event data set.

Important: If you delete an Event corresponding to an active Application, ESP Workload Manager is unable to continue processing that Application.

Example: Deleting an Event

The following example deletes the Event called TEST.FIRST_EVENT.

DELETE TEST.FIRST_EVENT

Important: If you delete an Event corresponding to an active Application, ESP Workload Manager is unable to continue processing that Application.

ESP-5.4-UG-05 107

Working with ESP Procedures

An ESP Procedure is a set of stored instructions that ESP Workload Manager invokes. When you create an ESP Procedure using CLANG, a high-level programming language. You can also use the IBM REXX language in ESP Procedures.

The main use of an ESP Procedure is to provide a framework for an ESP Application. You control an Application from one Event definition, regardless of the Application’s complexity or number of conditional requirements. You can use a single ESP Procedure to control a complete batch run or even multiple batch runs. The Procedure automatically accounts for any daily changes or month-end processing. For more information on using ESP Procedures to define Applications, see “Using Applications” on page 137.


• Overview of ESP Procedures• Invoking an ESP Procedure• ESP Procedure syntax• Using ESP Workload Manager control language in Procedures• Using symbolic variables in Procedures• Using expressions and strings in Procedures• Built-in functions• Using calendaring functions• Using functions for job selection• Using functions for symbolic variables• Using system activity functions

Section–Overview of ESP Procedures

108 ESP-5.4-UG-05

• Combining functions• Re-executing an ESP Procedure• Using templates• Using Event definition commands in Procedures• CLANG examples• Caching an ESP Workload Manager Procedure

Overview of ESP Procedures

You can code an ESP Procedure:

• In a stored Procedure that you store in a member of a PDS or PDSE, or in a sequential data set

• In an Instream Procedure that you include in an Event, starting with the PROC command and ending with the ENDPROC command

When you create an ESP Procedure, you can:

• Use as many statements as you need

• Add to or edit the Procedure

• Specify the Procedure line by line using the syntax described later in this chapter

• Invoke a stored Procedure from an Event

• Issue commands

• Set or test symbolic variables, whether built-in or user-defined

• Cache (store) the procedure in memory to improve performance

Note: You must create stored Procedures prior to creating the Event that invokes the Procedure.

Invoking an ESP Procedure

To invoke an ESP Procedure:

• Use the INVOKE command in an Event or in another ESP Procedure.

Chapter 5–Working with ESP Procedures

ESP-5.4-UG-05 109

The trigger for the Event can be:

• A scheduled date and time • A data set trigger• A job monitor trigger• A signal with a scheduled date and time• A manual trigger

Example: An Event invokes an ESP Procedure

The following example demonstrates how to use an Event to invoke an ESP Procedure.

The Event appearing below runs each weekday at 4 pm and invokes an ESP Procedure. The Event looks like this:

EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE 'CYBER.ESP.PROC(PAYDAILY)'ENDDEF

ESP Procedure syntax

ESP Procedures have a specific syntax that you must follow for each of the components listed below:

Syntax Rules Explanation

Name Use up to 8 alphanumeric characters for the name of an ESP Procedure. The first character must be a letter. Optionally you can use the format MYJOBS:ESPPROC.In this case, you must type a colon after the last character followed by the keyword ESPPROC.

Continuation Type either a hyphen (-) or a plus (+) sign as the last non-blank character on a line to continue a line of input. The + sign strips leading blanks from a continuation line.

Comments Enclose comments between /* and */. You can omit the last */ because a line end automatically ends the comment. Comments can be written anywhere in an ESP Procedure.

Data sets Enclose all data-set names in single quotation marks, otherwise ESP Workload Manager adds your TSO data set prefix to the name. Use LIB- or PAN- prefixes to identify Librarian and Panvalet data sets.

Delimiters Use single quotation marks when you want to denote character strings and literal data in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks.

Section–Using ESP Workload Manager control language in Procedures

110 ESP-5.4-UG-05

Examples of using the above syntax rules are presented throughout this chapter.

Using ESP Workload Manager control language in Procedures

CLANG is an integral component of ESP Procedures and provides great power and flexibility. Its several language elements listed below allow you to specify conditional processing requirements.

IF

Use IF to conditionally process an instruction or group of instructions depending on the evaluation of an expression. When you use an IF statement, the expression that follows it must return a true or false value. You can use any number of nested IF statements.

Example:

IF logical-expression THEN ...

THEN

Use THEN to indicate the Procedure processed only if the expression that follows the IF statement returns a true value. If a THEN statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP Workload Manager ignores the THEN statement. You must begin and end a set of instructions with DO and ENDDO language elements.

Example:

THEN statement

ELSE

Use an ELSE statement only in conjunction with an IF statement when the expression that follows the IF statement returns a false value. If you do not include an ELSE

Indentation Use indentation to improve readability (optional).

Variables Precede all symbolic variables with a symbol introducer character (the default character is the % sign), except when you use them in an expression or as the left-hand side of an assignment statement.

Labels Use labels in a Procedure to denote different sections. Labels can have up to 18 characters. The first character must be a letter, and you must type a colon after the last character. In addition to identifying sections for editing purposes, labels can also act as targets in JUMPTO statements, where they control logical flow.

Syntax Rules Explanation


ESP-5.4-UG-05 111

statement after an expression returning a false value, ESP Workload Manager passes control on to the next line. You must begin and end a group of instructions with DO and ENDDO language elements. If an ELSE statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP Workload Manager ignores the ELSE statement.

Example:

ELSE statement

DO

Use the DO statement in conjunction with THEN and ELSE statements to indicate the start of a set of statements. Use this statement to group a number of instructions together. You do not require a DO statement if you only have one instruction. DO must follow immediately after THEN or ELSE, or begin the continuation line. Do not use a continuation character (- or +) on a DO statement.

Example:

DO statement statement

ENDDO

Use the ENDDO statement in conjunction with the DO statement to indicate the end of a set of statements. The following example shows how you should use DO and ENDDO.

Example:

DO statement statementENDDO

EXIT

Use EXIT to quit from your current point in a Procedure. ESP Workload Manager continues to process pending requests up to the point at which you use EXIT. ESP Workload Manager also processes any action statements in the calling Event, or other ESP Procedures invoked in the same Event. ESP Workload Manager ignores EXIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, EXIT within the scope of a JOB statement causes ESP Workload Manager to process all statements up to the EXIT and submit the job.

Example:

EXIT

Section–Using ESP Workload Manager control language in Procedures

112 ESP-5.4-UG-05

QUIT

Use QUIT to quit an entire process and the Event that invoked it. If you use QUIT, ESP Workload Manager does not process any pending requests from this or any other Procedure invoked by the same Event. ESP Workload Manager ignores QUIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, QUIT within the scope of a JOB statement causes ESP Workload Manager not to process any statements for that job and does not submit the job, causing the job to fail with a SUBERROR. Therefore, any of the jobs dependencies are not released.

Example:

QUIT

JUMPTO

Use JUMPTO to search forward through the existing Procedure to find the next label of the name given in the JUMPTO statement. Use JUMPTO to skip over whole sections of a Procedure. You can use JUMPTO with or without an IF statement.

Example:

JUMPTO labelerr_handler

Note: After you specify DO, ENDDO, EXIT, or QUIT you must specify your next statement on the next line. You cannot continue these statements.

Example: Using IF-THEN-ELSE

This example uses the IF-THEN-ELSE construct.

IF A=B THEN SEND 'A AND B ARE EQUAL' U(*)ELSE SEND 'A AND B ARE NOT EQUAL' U(*)

If you use continuation characters and indentation, the above example looks like this:

IF A=B THEN - SEND 'A AND B ARE EQUAL' U(*)ELSE - SEND 'A AND B ARE NOT EQUAL' U(*)

Example: Grouping with DO-ENDDO

This example groups instructions together using DO and ENDDO:

DO SUBMIT 'CYB.ESP.JCL(PAYJOB1)' SEND 'PAYROLL IS RUNNING' CN(01)ENDDO


ESP-5.4-UG-05 113

Example: Using QUIT and EXIT

This example uses the QUIT and EXIT instructions, as follows:

• If today is CHRISTMAS, ESP Workload Manager quits the ESP Procedure and no instructions are processed.

• If today is not CHRISTMAS but it is a holiday, ESP Workload Manager sends a message and exits the Procedure at that point.

• If none of the above conditions are true, ESP Workload Manager sends a message indicating it will continue processing.

IF TODAY('CHRISTMAS') THEN QUITIF TODAY('HOLIDAY') THEN DO SEND 'NO WORK TODAY' U(BOSS) EXITENDDOSEND 'LET US CONTINUE PROCESSING' U(USER01)


For more examples of using CLANG, see “” on page 131.

Using symbolic variables in Procedures

You can use symbolic variables in an ESP Procedure. The different types of variables are:

Type of Variable Explanation

Built-in variables ESP Workload Manager provides a set of built-in variables for such information as the current date, time, and Event name. You can use these variables in an ESP Procedure, but their values cannot be changed. See the ESP Workload Manager Advanced User’s Guide for a complete list of these variables.

User-defined variables These are alphanumeric strings or integers that you can use in an ESP Procedure to represent character strings, literal data, and numbers. When using an integer variable, you must first define the variable with an INTEGER statement before you use it.If the variable is stored in a global variable table, you can retrieve it using a VGET statement.

Note: regardless of the type of variable stored in a global variable table, you will obtain a character string when you retrieve the variable unless you insert an INTEGER statement before retrieving it.

Section–Using expressions and strings in Procedures

114 ESP-5.4-UG-05

When you want to use the value of a symbolic variable, you use the symbol-introducer character (default is the per cent sign (%)) followed by the symbol name. For example: %NAME.

Note: Your installation can use a different symbol-introducer character. Check with your administrator to find out what symbol-introducer character is used at your site.

Example: Using symbolic variables

INTEGER NUMBERNUMBER=52NAME='FRED'SEND '%NAME IS %NUMBER YEARS OLD TODAY' U(USER01)

This example:

• Defines an integer variable called NUMBER and assigns it a value of 52.• Assigns the value FRED to the variable called NAME.• Sends a message to USER01 using these variables.

The message ESP Workload Manager sends to USER01 looks like this:

FRED IS 52 YEARS OLD TODAY

Example: Retrieving a variable from a global variable table

This example assumes that a variable containing the number of runs and named NUMOFRUN has been previously stored in a global variable table named MYTABLE.

INTEGER NUMOFRUNVGET NUMOFRUN TABLE(MYTABLE)SEND 'THE NUMBER OF RUNS IS %NUMOFRUN' U(USER01)


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.


ESP-5.4-UG-05 115

When you want to enter text and have it appear exactly as you typed it, type it enclosed in single quotes:

'THIS IS A CHARACTER STRING'

When you want to enter a text statement containing a changing variable, such as the time (%ESPATIME), you could type:

'THE TIME IS %ESPATIME'

ESP Workload Manager substitutes the actual system time in place of the symbolic-variable name %ESPATIME.

Using expressions

An expression is a variable, number, or character string connected by operators. Expression evaluation is from left to right; this is modified overridden by parentheses and by operator precedence. You can modify this order using parentheses.

A logical expression resolves to the value one if true, or zero if false. If an arithmetic expression resolves to zero, it is false. For any other value, the expression is true. If you do not enclose a logical expression in parentheses when you use an IF statement, ESP Workload Manager understands the THEN statement to be the terminator.

Examples:

• In the first statement, ESP Workload Manager processes the THEN statement if NUM=100.

• In the second statement, ESP Workload Manager processes the THEN statement if VAR1 is less than VAR2 and NUM is equal to 100.

IF NUM=100 THEN ...IF (VAR1 LT VAR2 AND NUM EQ 100) THEN ...

Using operators

You can use arithmetic operators, comparison operators, and logical operators in an expression.

Arithmetic operators

Numbers can be combined using the following arithmetic operators:

+ Add- Subtract* Multiply/ Divide// Integer Divide** PowerPrefix - Negate the following term. Same as '0-term'Prefix + Take following term as if it was '0+term'

If you use / for division, ESP Workload Manager performs the division internally using floating-point arithmetic but the resulting value is an integer. If you use // for

Section–Using expressions and strings in Procedures

116 ESP-5.4-UG-05

division, ESP Workload Manager disregards any remainder. For example, if A is an integer, then A = A/2*2 is always true, but A = A//2*2 is true only if A is even.

Comparison operators

The comparison operators return the value one if the result of the comparison is true, or zero otherwise. You can use the following operators, in either their symbol or letter form, in an expression.

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

Logical operators

You can use the following logical operators in an expression:

& AND| OR

Order of precedence

The order of precedence of the operators is (highest at the top):

¬ (not), prefix + (prefix plus), prefix - (prefix minus)**(power)/(divide), // (integer divide), * (multiply)+(plus), -(minus)>= (GE), <= (LE), < (LT), > (GT),= (EQ), ¬= (NE)ANDOR

In the statement below (A = B or C > D) is a valid expression, and GO is a valid character string that ESP Workload Manager assigns to the variable E. ESP Workload Manager assigns the value GO to the variable E if either A = B or C > D.

IF (A=B OR C > D) THEN E = 'GO'

Note: If the expression A = B is true, the entire logical expression is also true. This means that ESP Workload Manager does not have to evaluate C > D. This order of precedence is useful for expressions such as IF I = 0 AND J/I > 4. This expression does not cause an error since J is divided by I only if I is non-zero.


ESP-5.4-UG-05 117

Built-in functions

A function is a sequence of instructions that can receive data, process that data, and return a value. ESP Workload Manager provides a set of built-in functions. To use a function, type the function name directly followed by one or more arguments within parentheses, like this:

function(arguments)

Note: There can be no space between the function name and the left parenthesis.

Built-in functions

The built-in functions fall into the following categories:

Summary by function

The following table summarizes the functions by category:

Category Explanation

Calendaring Tests schedule criteria and calculate time periods.

Job selection Checks if a job has already been selected for submission.

Symbolics Performs operations on symbolic variables.

System activity Checks the status of activity on the system, including jobs and tape drives.

Category Function Description

Calendaring DAYS_FROM Calculates the number of days from a date.

Calendaring DAYS_TO Calculates the number of days away from a date in the future.

Calendaring DAYS_BETWEEN Calculates the number of units (days, weekdays, workdays) between two dates.

Calendaring TODAY Tests to see if today matches a specified schedule expression.

Calendaring TOMORROW Tests to see if tomorrow matches a specified schedule expression.

Calendaring YESTERDAY Tests to see if yesterday matches a specified schedule expression.

Job selection SELECTED Checks to see if a job has been selected.

Symbolics DEFINED Checks to see if a symbolic variable has been defined.

Section–Using calendaring functions

118 ESP-5.4-UG-05

Testing for a true condition

Each one of the SELECTED, TODAY, TOMORROW, and YESTERDAY built-in functions returns a true value (1) or a false value (0). To test for a true condition, you do not have to specify the true value, since this is the default. If you want to test for a false value, you must specify either =0, EQ 0, or use the word NOT.

In the following example, both statements have the same effect. Each checks to see if today is not Monday.

IF TODAY('MONDAY') EQ 0 THEN ...IF TODAY('NOT MONDAY') THEN ...


The following sections describe ESP Workload Manager built-in functions in detail and contain some examples of using these functions. For more examples, see “” on page 131.

Using calendaring functions

DAYS_TO

The DAYS_TO function returns a positive number representing the number of days from a specified special day, holiday, or any defined schedule criteria. If you do not use a year and the day you specified has passed, DAYS_TO assumes the next year and returns a positive number. If the date is in the past, ESP Workload Manager returns a negative number.

Symbolics LENGTH Returns the length of a symbolic variable.

Symbolics SUBSTR Returns a partial string of a symbolic variable.

System activity ACTIVE Checks to see if a job or address space is active on the current system.

System activity JOBONQ Checks to see if a job or address space is active on any system in the shared spool environment.

System activity TAPES Checks the status of tape drives.

Category Function Description


ESP-5.4-UG-05 119

Example: DAYS_TO

If you want to determine the number of days to December 25 from the current day, and assign that number to an integer variable called X, type:

INTEGER XX=DAYS_TO('DEC 25')

DAYS_FROM

The DAYS_FROM function returns a positive number representing the number of days from a date in the past. DAYS_FROM assumes the current year if you do not specify one. If the date is in the future, ESP Workload Manager returns a negative number.

Example: DAYS_FROM

The following is an example of an expression containing the DAYS_FROM built-in function:

IF DAYS_FROM('AUGUST 1ST') GT 0 THEN

DAYS_BETWEEN

The DAYS_BETWEEN function returns a whole number representing the number of a specified unit of time (days, months, workdays, fiscal_months, and so on) between two given dates. You do not have to specify the dates explicitly; you can use a schedule expression instead.

DAYS_BETWEEN('first date','second date','restrictor')

The restrictor is an optional qualifier that defaults to DAYS. Examples of the following are other possible restrictors; HOURLY, DAILY, are WORKDAYS, and WEEKDAYS, WEEKLY, SATURDAYS, WEEKENDS, MONTHLY, YEARLYPLUS SAT. Your restrictor cannot be any unit of time less than hourly. The value that this function returns is the number of occurrences of the restrictor between the first date and the second date. If the first date is not prior to the second date, the function returns a value of zero negative number. The maximum value the function returns is 50000 for any restrictor other than DAYS.

Example: Days_Between to calculate workdays

If you want to know the number of workdays there are from January 30, 2001, up to but not including June 30, 2001, you would type:

DAYS_BETWEEN('JAN 30 2001','JUNE 30 2001','WORKDAYS')

Section–Using calendaring functions

120 ESP-5.4-UG-05

Example: Days_Between to calculate weeks

You could also determine the number of Saturdays from the 6th workday of the current month, up to but not including tomorrow, by typing:

DAYS_BETWEEN('6TH WORKDAY OF MONTH STARTING + TODAY','TOMORROW','SAT')

TODAY

The TODAY function compares the schedule expression that you specify to today’s schedule date. It returns a true or a false value, depending on whether the expression matches today. ESP Workload Manager returns a number code indicating the result:

1 = true0 = false

In the following example, ESP Workload Manager only processes the instructions following the THEN statement if today is a Friday.

IF TODAY('FRIDAY') THEN ...

When the statement is false, ESP Workload Manager skips to the next ELSE statement or to the following line.

You can check if today is not Friday like this:

IF TODAY('NOT FRIDAY') THEN ...

Example: TODAY

The following are examples of the TODAY function:

IF TODAY('MON WED FRI') THEN ...IF TODAY ('FIRST-LAST DAY OF JUNE JULY') THEN ...IF TODAY('LAST WORKDAY OF MONTH LESS 1 WORKDAY') THEN ...• The first statement checks if today is Monday, Wednesday, or Friday.• The second statement checks if today is any day in June or July.• The last statement checks if today is the second last workday of the month.

TOMORROW

The TOMORROW function compares the expression following the TOMORROW keyword to tomorrow’s date (for example, the day after the schedule date). ESP Workload Manager returns a true or false value, depending on whether the expression matches tomorrow. ESP Workload Manager returns a number code indicating the result:

1 = true0 = false


ESP-5.4-UG-05 121

Examples: TOMORROW

The following are two examples using the TOMORROW function:

IF TOMORROW('LAST WORKDAY OF MONTH') THEN ...IF TOMORROW('HOLIDAY') THEN ...

• In the first example, ESP Workload Manager only processes the instructions following the THEN statement if tomorrow is the last workday of the month.

• In the second example, ESP Workload Manager only processes the instructions following the THEN statement if tomorrow is a holiday.

When the statement is false, ESP Workload Manager skips to the ELSE statement or the following line.

YESTERDAY

The YESTERDAY function compares the schedule expression that you specify to yesterday’s date (for example, the day before the schedule date). ESP Workload Manager returns a true or false value, depending on whether the expression matches yesterday. ESP Workload Manager returns a number code indicating the result:

1 = true0 = false

Example: YESTERDAY

In the following example, ESP Workload Manager only processes the instructions following the THEN statement when yesterday is the first workday of the month:

IF YESTERDAY('FIRST WORKDAY OF MONTH') THEN ...

When the statement is false, ESP Workload Manager skips to the ELSE statement or to the following line.

Example: YESTERDAY

In the following example, ESP Workload Manager only processes the instructions following the THEN statement when yesterday is a holiday:

IF YESTERDAY('HOLIDAY') THEN ...

When the statement is false, ESP Workload Manager skips to the ELSE statement or to the following line.

Section–Using functions for job selection

122 ESP-5.4-UG-05

Using functions for job selection

SELECTED

The SELECTED function returns a true or false value that indicates whether a job name has been selected as a result of a previously processed SELECT or RUN statement. To return a true value, ESP Workload Manager must have selected the job in this ESP Procedure or in another ESP Procedure invoked by the same Event, prior to evaluating the function. This function does not return a true value for a job selected via a POSTREQ, PREREQ, or COREQ statement.

ESP Workload Manager returns a number code for the value:

1 = true, the job name has been selected.0 = false, the job name has not been selected.

The syntax is:

SELECTED('JOBNAME')

If the job you are checking for selection is a qualified job, you will need to include the qualifier, like this:

SELECTED('jobname.qualifier')

This function is useful for scheduling jobs with the same frequency because it can eliminate the need to specify complicated criteria multiple times. The function is also useful when you want to schedule a job whenever another job is not scheduled.

Example: Selecting one job based on another

You can use the SELECTED function to select job B whenever ESP Workload Manager selects another job such as job A.

IF SELECTED('A') THEN SELECT B

Example: Selecting a job when another is not selected

In this example, ESP Workload Manager selects job Z whenever it does not select job X. ESP Workload Manager selects Z on all days except for the 3rd, 13th, and 23rd day of the month.

JOB X RUN 3RD 13TH 23RD DAY OF MONTHENDJOBJOB Z IF NOT SELECTED('X') THEN RUN TODAYENDJOB

The above results are valid only at Application generation time and not at Application process time.


ESP-5.4-UG-05 123

Using functions for symbolic variables

DEFINED

The DEFINED function checks to see if a symbolic variable has been defined and returns the following values:

1 = true0 = false

The syntax is:

DEFINED(variable)

Example: Defining an undefined variable

This example defines an integer variable called COUNT if it has not been defined.

IF NOT DEFINED(COUNT) THEN - INTEGER COUNT

LENGTH

The LENGTH function returns a number equal to the length of the variable following the LENGTH keyword in parentheses. The syntax is:

LENGTH(variable)

This function does not return a true or false value. Instead, it resolves to a whole number equal to the length of the named variable’s value.

Example: Calculating the length of a symbol

In this example, the LENGTH function assigns the length of a user-defined variable called LETTER to the integer variable SIZE. As a result, SIZE has a value of seven.

INTEGER SIZELETTER='OMICRON'SIZE=LENGTH(LETTER)

SUBSTR

The SUBSTR function resolves to a partial string from the variable string that follows the SUBSTR keyword in parentheses. The syntax is:

SUBSTR(start,length,variable_name)

Section–Using system activity functions

124 ESP-5.4-UG-05

Example: Using a substring of a time variable

The ESPATIME built-in variable represents the actual time, 19.35.42, for example. This example assigns the number of minutes in the ESPATIME symbolic variable to the symbol MIN.

MIN=SUBSTR(4,2,ESPATIME)

Example: Extracting the last character of a variable length symbol

This example uses the LENGTH and SUBSTR functions to extract the last character of the scheduled month name. The LENGTH function calculates the length of the month name. The SUBSTR function extracts the last character.

INTEGER X X=LENGTH(ESPSMONTH)LAST_CHAR=SUBSTR(%X,1,ESPSMONTH)

For example, if the scheduled month is December:

• X=8, because there are eight characters in the word December• LAST_CHAR=SUBSTR(8,1,'DECEMBER'), which resolves to R, the last

character in the word December

Using system activity functions

ACTIVE

The ACTIVE function tests to see if a job or any address space is active on the current system and returns a value based on that test. ESP Workload Manager returns a number representing the result:

address space identifier = true0 = false.

Note: If you want to verify that a job or any address space is active on any system (within the same JES node), use the JOBONQ built-in function.

Example: Checking if CICSPROD is active

This example sends a message to console identifier 01 if CICSPROD is active on the current system.

IF ACTIVE('CICSPROD') THEN + SEND 'CICSPROD IS STILL ACTIVE' CN(01)


ESP-5.4-UG-05 125

JOBONQ

Use the JOBONQ function to determine, by checking JES, whether a job or group of jobs is currently on any JES queue. To use the JOBONQ function, use the following syntax:

JOBONQ('jobname','prefix','criteria')

This function requires three operands: a job name, a prefix, and a search criteria.

Returning values

The following list contains all the acceptable search criteria codes:

JOBONQ variables

The JOBONQ function returns the count of jobs that meet the criteria. For each job, it generates a series of four variables beginning with the specified prefix (the second operand). The variables represent the job identifier (JOBID), job number (JOBNO), whether or not the job is on hold (JOBH), and the queue the job is in (JOBQ). The suffix increments from one to the number of jobs found.

Operand Explanation

jobname Specifies the name of the job or job name prefix. You can only use a job name prefix with the U criterion.

prefix Specifies the prefix of the variables you want to generate. This operand is optional. For example, you can specify:IF JOBONQ('MYJOB', '', 'E') THEN -SEND 'MYJOB IS EXECUTING' U(*)

criteria Specifies the search criteria consists of any combination of the letter codes below. If this operand is omitted, ESP Workload Manager looks in all queues.

Search Criteria Code Explanation

I Examine the input queue.

E Examine the execution queue.

O Examine the output queue.

H Examine held jobs only.

U Treat the job name as a user ID. The search includes any job with a name consisting of the job name plus one character.

Section–Using system activity functions

126 ESP-5.4-UG-05

Example: JOBONQ

The JOBONQ function in the following example verifies the existence of any job in the input queue (I) in hold status (H). ESP Workload Manager assigns the number of jobs that meet this criteria to the integer variable JOBCOUNT.

INTEGER JOBCOUNTJOBCOUNT = JOBONQ('PAYROLL','Z','IH')

If JOBCOUNT is not equal to zero, meaning that at least one job called PAYROLL is in the input queue in hold status, ESP Workload Manager generates a set of variables for each job it finds. These variables all begin with the prefix Z.

Example

For example, for the first job it finds the variables are:

When ESP Workload Manager finds more than one job, the variables it generates for the second job are: ZJOBID2, ZJOBNO2, ZJOBH2, and ZJOBQ2. ESP Workload Manager repeats this series with the last digit incrementing by one for additional jobs it finds.

If you use the U criterion, the JOBONQ function also returns the JOBN variable, with the appropriate prefix and suffix.

Using JOBONQ with REEXEC

You can also use the JOBONQ function in conjunction with the REEXEC statement to allow you to re-execute an ESP Procedure at a specified time or after a certain time interval. In the following example, ESP Workload Manager re-executes the ESP Procedure if MYJOB is found on any queue.

IF JOBONQ('MYJOB') THEN REEXEC IN(5)

TAPES

ESP Workload Manager evaluates the TAPES function to check the status of tape drives on the system and compares the status to the resources required by the job. When you use the TAPES function at the job level for a job in an Application, you can verify the status of the tape drives before you submit a job.

Variable Explanation

ZJOBID1 JES job identifier in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary.

ZJOBNO1 JES job number (for example 123456).

ZJOBH1 Equal to zero if JES is not holding the job, or equal to one if JES is holding the job.

ZJOBQ1 Equal to I, E, or O depending on whether the job is on the input, execution, or output queue respectively.


ESP-5.4-UG-05 127

Note: To check the status of tape drives, Cybermation recommends you use resources. Resources provide you with easier, more efficient ways of defining tape requirements. For more information, see “Using Resources” on page 325.

Example: TAPES

To use this function, enter TAPES followed by two operands from the lists below:

TAPES('xy')

ESP Workload Manager evaluates both operands (x and y) of the function and returns a whole number.You can choose one of the following three options as the first operand:

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

The default is CA.

Example: Checking available cartridge drives

If a job in an Application requires two cartridge drives, you can use the TAPES function to check that two cartridge drives are available before you submit the job. If they are not, ESP Workload Manager can check again after two minutes:

JOB TAPEJOB1IF TAPES('CA') < 2 THEN REEXEC IN(2)

Combining functions

You can combine built-in functions using the AND and OR logical operators. Specify the built-in function name each time you need to use it.

Option Explanation

C Cartridge drives.

R Reel-to-reel drives.

T Total drives.

Option Explanation

A Available.

O Online.

D Defined.

Section–Re-executing an ESP Procedure

128 ESP-5.4-UG-05

Examples

Some examples are shown below:

• Today is Friday, and today is not the last workday of the year:IF TODAY('FRIDAY' AND TODAY('NOT LAST WORKDAY OF YEAR') THEN

• Today is the last workday of the month, and CICS is active on the current system:IF TODAY('LAST WORKDAY OF MONTH') AND ACTIVE('CICS') THEN

• Yesterday was a holiday, tomorrow is Friday, and today is a workday:IF YESTERDAY('HOLIDAY') AND TOMORROW('FRIDAY') AND + TODAY('WORKDAY') THEN

• Today is Monday, Wednesday, or Friday, and either yesterday was a holiday or tomorrow is a holiday:IF TODAY('MON WED FRI') AND (YESTERDAY('HOLIDAY') OR + TOMORROW('HOLIDAY')) THEN

Re-executing an ESP Procedure

Use the REEXEC statement to request re-execution of an ESP Procedure at a specific time or after a certain time interval. ESP Workload Manager stores the number of re-executions in a symbolic variable called ESPREEXEC#. If you use REEXEC within the scope of a JOB statement in an Application, ESP Workload Manager re-executes only the code associated with that job, and maintains a separate ESPREEXEC# for each job.

Example: Checking if CICS is active

This ESP Procedure checks to see if a job or address space called CICS is active on the current system.

IF ACTIVE('CICS') THEN DO SEND 'CICS IS DUE TO COME DOWN' CN(01) NONDEL REEXEC IN(5)ENDDOELSE SUBMIT 'PROD.JCL.CNTL(CICSBKUP)'

• If CICS is active, ESP Workload Manager sends a non-deletable message to console id 01 and re-executes the Procedure in five minutes.

• If CICS is not active, ESP Workload Manager submits the member CICSBKUP from the library PROD.JCL.CNTL.

Note: If you want to set up a dependency with an online region, such as CICS, for a job in an ESP Application, the preferred method is to use ESP Workload Manager resource feature. For information on using resources, see “Using Resources” on page 325.


ESP-5.4-UG-05 129

Example: Waiting for a job

This ESP Procedure checks to see if a job called RMTJOB is on the input queue.

INTEGER COUNTCOUNT=JOBONQ('RMTJOB','X','IH')IF COUNT=1 THEN VS '$AJ%XJOBNO1'ELSE DO IF ESPREEXEC#<5 THEN REEXEC IN(30) ELSE SEND 'I GIVE UP ON RMTJOB' U(USER01)ENDDO

• If RMTJOB is on the input queue on hold, ESP Workload Manager releases the job.

• If RMTJOB is not on the input queue on hold, ESP Workload Manager checks the number of re-executions. If the number of re-executions is less than five, ESP Workload Manager re-executes the Procedure in 30 minutes. Otherwise, ESP Workload Manager sends a message.

Using templates

A template is an element of CLANG that allows you to specify repetitious commands or statements once, such as those you use to define holidays or jobs.

This section contains a brief introduction to templates. For more information on using templates, see the ESP Workload Manager Advanced User’s Guide.

Defining a template

To define a template:

1. Use a TEMPLATE statement to give your template a name and identify operands you want to pass through the template.

2. Define the statements that make up your template.

3. End the template definition with the ENDTEMPL statement.

To use a template you have defined:

• Specify the name of the template followed by any operands you want to pass through the template.

Example - Defining a static holiday

This example uses a template to define a static holiday called CHRISTMAS, for six years. The DEFHOL command defines a holiday for a particular date.

Section–Using templates

130 ESP-5.4-UG-05

Use a template in an ESP Procedure to specify the DEFHOL command and supply the template with different years. In this example:

• The name of the template is XMAS, and it accepts one positional operand represented by the variable YEAR.

• The body of the template consists of one statement that defines CHRISTMAS as a 24 hour holiday, on December 25 each year, in the SYSTEM calendar. The year is represented by the variable YEAR.

• The ENDTEMPL statement ends the template definition.• The template XMAS is then used with the years 2001 through 2006. Each of

these years is passed to the template and substituted for the variable YEAR within the template.

TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START('DEC 25, %YEAR') + FOR(24) CAL(SYSTEM)ENDTEMPLXMAS 2001XMAS 2002XMAS 2003XMAS 2004XMAS 2005XMAS 2006

Set up an Event to invoke this ESP Procedure and trigger it manually to define your holidays.

Example - Defining similar jobs

In this example, an Application contains a number of print jobs. These jobs:

• Run daily• Belong to a subApplication called PRTJOBS• Run independently

The following is a sample definition of this Application:

APPL PAYROLLJCLLIB 'CYB.JOBS.CNTL'JOB USERA SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERB SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERC SUBAPPL PRTJOBS RUN DAILYENDJOBJOB USERD SUBAPPL PRTJOBS


ESP-5.4-UG-05 131

RUN DAILYENDJOB

Because of the similarity of the jobs, you can define a print job template and pass one operand for the name of each job. The template contains details for the print job, such as SUBAPPL PRTJOBS and RUN DAILY.

Example - Defining similar jobs

APPL PAYROLLJCLLIB 'CYB.JOBS.CNTL'TEMPLATE PRTJOBS (1,NAME) JOB %NAME SUBAPPL PRTJOBS RUN DAILY ENDJOBENDTEMPLPRTJOBS USERAPRTJOBS USERBPRTJOBS USERCPRTJOBS USERD

The template is used for jobs USERA, USERB, USERC, and USERD. ESP Workload Manager substitutes the job name for the %NAME variable within the template.

Using Event definition commands in Procedures

You can use the following commands in an ESP Procedure:

Command Explanation

INVOKE Invokes another ESP Procedure.

LIBSUB Submits JCL from a Librarian data set.

PANSUB Submits JCL from a Panvalet data set.

SEND Sends messages to a TSO user or console.

SIGPOST Posts a complete signal.

SIGCYCLE Cycles a new generation of a signal.

SUBMIT Submits JCL from a PO, PS, or VSAM ESDS data set.

VS Issues an operator command (restricted use).

Section–CLANG examples

132 ESP-5.4-UG-05

CLANG examples

This section contains some additional examples of using CLANG.

Example: Scheduling a job on the last day of the month

In this example, ESP Workload Manager selects a job if it is the last day of the month and the month has 31 days in it. The Procedure uses the ESPSDD built-in symbolic variable that represents the number of the scheduled day of the month.

The ESP Procedure looks like this:

IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN SELECT MONTHEND

Alternatively, if you normally use RUN statements for your jobs, the ESP Procedure looks like this:

JOB MONTHEND IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN RUN TODAYENDJOB

Example: Taking different action on a weekday

In this example, ESP Workload Manager takes different actions based on whether or not the scheduled day is a weekday.

• If the scheduled day is a weekday, ESP Workload Manager sends a message and submits JOB1.

• If the scheduled day is not a weekday, ESP Workload Manager sends a different message and submits JOB2.


IF TODAY('WEEKDAY') THEN DO SEND 'TODAY IS A WEEKDAY' U(*) SUBMIT 'CYB.ESP.JCL(JOB1)'ENDDOELSE DO SEND 'TODAY IS A WEEKEND' U(*) SUBMIT 'CYB.ESP.JCL(JOB2)'ENDDO


ESP-5.4-UG-05 133

Example: Taking different actions based on the status of CICS

In this example, ESP Workload Manager takes different actions based on whether or not CICS is active.

• If CICS is active on the current system, ESP Workload Manager jumps to a label called STOP. ESP Workload Manager issues an operator command, schedules a re-execution in five minutes, and exits this Procedure.

• If CICS is not active on the current system, ESP Workload Manager jumps to a label called GO and issues a command to trigger an Event.


IF ACTIVE('CICS') THEN JUMPTO STOPELSE JUMPTO GOSTOP:VS 'F CICS SHUTDOWN'REEXEC IN(5)EXITGO:VS 'F ESP,TRIGGER PROD.NIGHTLY'

Example: Using calendaring functions

This example uses different CLANG functions. It accomplishes the following:

• Assigns the number of days to December 25 to the integer variable X• Assigns the number of workdays between today and December 25 to the integer

variable Y• Assigns the number of days since July 20, 1969 to the integer variable Z• Sends the above values back to your terminal• Sends another message back to your terminal if today is a workday


INTEGER X,Y,ZX=DAYS_TO('DEC25')Y=DAYS_BETWEEN('TODAY','DEC25','WORKDAYS')Z=DAYS_FROM('JUL20,1969')SEND 'THERE ARE %X DAYS TO CHRISTMAS' U(*)SEND 'THERE ARE %Y WORKDAYS TO CHRISTMAS' U(*)SEND 'THERE HAVE BEEN %Z DAYS SINCE THE FIRST MOON WALK' U(*)IF TODAY('WORKDAY') THEN - SEND 'ANOTHER DAY OF HARD LABOR' U(*)

Example: Calculating time periods

This example calculates the number of days, from a specific time and date in the past. ESP Workload Manager sends the results back to your terminal.

Section–CLANG examples

134 ESP-5.4-UG-05


INTEGER X,YX=DAYS_BETWEEN('1PM JAN1,1994','NOW','HOURLY')Y=DAYS_BETWEEN('JAN1,1994','TODAY','DAILY')SEND 'ITS BEEN %X HOURS SINCE STOP HOUR' U(*)SEND 'ITS BEEN %Y DAYS SINCE STOP DAY' U(*)

Example: Overriding an ESP Procedure on a particular date

There can be occasions where you need to use an alternate ESP Procedure for a specific date. One method is illustrated below:

DAILY:ESPPROCIF TODAY('specific date') THEN - DO INVOKE 'PROD.ALT.ESPPROC(DAILYEX)' EXIT ENDDO/*REGULAR PROCEDURE*/...

The first statement checks to see if today is a specific date. If so, ESP Workload Manager invokes an alternate ESP Procedure. Otherwise, ESP Workload Manager processes the statements in the regular Procedure.

Example: Taking different action based on time

In this example, ESP Workload Manager takes different actions based on when a job becomes eligible for submission. The criteria are:

• If job THISJOB becomes ready for submission between 3 am and 3:59 am, ESP Workload Manager submits the job and sends a message indicating it is almost too late to run the job.

• If THISJOB becomes ready for submission at 4 am or later, ESP Workload Manager does not submit the job.

• Otherwise, if THISJOB becomes ready between midnight and 2:59 am, ESP Workload Manager sends a message indicating the job is on time.

The ESP Procedure is shown below. The ESPAHH symbolic variable represents the actual two-digit hour.

JOB THISJOB RUN DAILY IF ESPAHH EQ '03' THEN DO SEND 'IT IS ALMOST TOO LATE TO RUN THISJOB' U(OP1) EXIT ENDDO IF ESPAHH GE'04' THEN QUIT


ESP-5.4-UG-05 135

SEND 'THISJOB IS ON TIME' U(OP1)ENDJOB

Caching an ESP Workload Manager Procedure

By caching (storing) an ESP Workload Manager Procedure in memory, you can improve CPU usage and processing speed for ESP Procedures that include a large number of jobs. You can create, display and delete cache entries by using the PCACHE and CPROC commands (for details, see the ESP Workload Manager Reference Guide).

Important: If you change the contents of a Procedure, delete the cached version of the Procedure so the new version is read automatically by an active Application.

To cache an ESP Workload Manager Procedure:

• Use the PCACHE command.

To display and delete cache entries:

• Use the CPROC command.

Note: To delete a Procedure cache, you need UPDATE access to security profile APPL.applname, where applname is the name of the Application generated by your Procedure. See your ESP Workload Manager security administrator to set up access. For details, see the ESP Workload Manager Security Guide.

Section–Caching an ESP Workload Manager Procedure

136 ESP-5.4-UG-05

ESP-5.4-UG-05 137

Using Applications

An Application consists of one or more jobs, or other workload objects. A workload object can be a job, a manual task, a command you want processed, or a distributed object, such as a Unix script. For example, an Application can consist of all of your payroll jobs. You can define an Application using the Application Definition panels, ESP Workstation, or by editing a member of a PDS. All Application definitions are stored in ESP Procedures.


• Introducing Applications• Identifying the Application• Identifying JCL libraries• Identifying jobs• Defining job requirements• Specifying time dependencies• Specifying job relationships• Using Implicit Resources• Selecting jobs for submission• Using different job types• Defining external jobs• Defining manual jobs• Using links• Using tasks• Using APPLEND workload object

Section–Introducing Applications

138 ESP-5.4-UG-05

• Changing job attributes• Using data-set-trigger workload objects• Using FTP data-set-trigger workload objects• Using explicit-data-set-trigger workload objects• Tagging jobs• Providing notification on Job status• Using critical-path analysis• Issuing ESP Workload Manager commands• Using subApplications• Working with Applications• Displaying an Application• Controlling an Application• Changing an Application definition• Invoking an ESP Application

Introducing Applications

This section describes the generating and processing of Applications:

• How ESP Workload Manager manages jobs in an Application• Generating and processing an Application• Application generations

Processing an Application

ESP Workload Manager performs the following processing steps for jobs in an Application:

1. When a job’s submission time arrives, ESP Workload Manager checks for any remaining dependencies.

2. Each job has a hold count. The hold count is a number corresponding to the number of immediate predecessors for the job. A job in an Application is not eligible for submission if the hold count exceeds zero.

3. When a predecessor job terminates successfully, ESP Workload Manager subtracts one from the successor job’s hold count. For instance, if the hold count for a job is three and a predecessor job terminates successfully, the hold count decreases to two.

4. When the hold count reduces to zero, ESP Workload Manager readies the job for submission, unless the job is in another type of hold status such as Manual hold or Resource Wait.

5. ESP Workload Manager submits the job when all required resources are available.

Chapter 6–Using Applications

ESP-5.4-UG-05 139

Application phases

An Application passes through the following two phases:

• Generation• Process

Generation phase

When an Event is triggered that invokes an ESP Application definition, ESP Workload Manager must first generate the Application. ESP Workload Manager reads the definition and creates a record in a file known as the APPLFILE. This record includes the information ESP Workload Manager needs to process the jobs in the Application. The record describes the Application and all the jobs within it.

Process phase

Once ESP Workload Manager generates an Application, it then begins to process that Application as follows:

• A component of ESP Workload Manager called the Application Manager has a queue of jobs awaiting submission. Jobs can be in a waiting state because of such things as time, predecessors, and resources.

• The Application Manager looks at the jobs and assesses whether any time dependencies have been met. If so, the job goes into a job dependency state and waits until the last predecessor dependency has been met.

• The job then enters a resource wait state, which allows ESP Workload Manager resource manager to verify that the job’s resource dependencies are met.

• ESP Workload Manager re-drives the Event to submit the job when the required resources are available.

• The Application manager uses real-time SMF data to update the execution status of each job.

Phase status

You can find out the phase status of an Application by using the ESP_APPL_PROC and ESP_APPL_GEN symbolic variables in an Application definition.

ESP Workload Manager sets these symbolic variables as follows:

ESP_APPL_GEN equals:

• 1 during generation phase• 0 otherwise

ESP_APPL_PROC equals:

• 1 during process phase• 0 otherwise

Section–Introducing Applications

140 ESP-5.4-UG-05

In the following example, ESP Workload Manager sends a message to a user only during the generation phase of an Application.

IF ESP_APPL_GEN=1 THEN - SE 'ESP IS GENERATING THE PAYROLL APPLICATION' U(TAXMAN)

Application generations

Each Application has a generation number assigned by ESP Workload Manager when the Application is generated. This number increments with each generation of an Application. Using the generation number, ESP Workload Manager can identify the particular generation of an Application to which a job belongs.

A generation of an Application does not have to complete within any 24 hour period. An Application can span many days or weeks, or you can schedule an Application many times in one day. Different generations of an Application can process at the same time.

Defining an Application

You must use an ESP Procedure to describe an Application to ESP Workload Manager. See “Working with ESP Procedures” on page 107 for detailed information on ESP Procedures.

ESP Procedure statements

An ESP Procedure that defines an Application consists of a series of statements that:

• Identifies the Application• Tells ESP Workload Manager where the appropriate JCL is located• Identifies the jobs• Describes the job relationships• Describes when ESP Workload Manager should select the jobs to run • Describes other job dependencies, such as time


ESP-5.4-UG-05 141

In addition, an ESP Procedure can also indicate which job documentation library is used, or specify what condition codes cause a job to fail.Visually, an Application looks like this:

Application definition

The corresponding Application definition looks like this:

APPL PAYROLLJCLLIB 'CYBER.ESP.JCL'JOB A RUN DAILY RELEASE (B,C)ENDJOBJOB B RUN DAILY RELEASE DENDJOBJOB C RUN DAILY RELEASE DENDJOBJOB D RUN DAILY RELEASE EENDJOBJOB E RUN FRIDAY RELEASE FENDJOBJOB F RUN LAST WORKDAY OF MONTHENDJOB

The following sections discuss how to define an Application.

A

B C

E

F

D

Daily

Friday

Last workday of month

Section–Identifying the Application

142 ESP-5.4-UG-05

Identifying the Application

Each Application must have a name. To identify the name of an Application, use the APPL statement in an ESP Procedure like this:

APPL applname

The Application name can contain up to 8 characters. Characters must be either alphanumeric, a national character ($ # @), or an underscore (_). The first character cannot be numeric. Your security administrator can require you to code other information on the APPL statement, such as the SAF_PROF_APPL keyword, to provide more granular security for the Application.

Controlling concurrent processing

Normally, if two generations of an Application are active on the system at the same time, they execute at the same time. You can control concurrent processing at different levels, as follows:

Operand Explanation Example

WAIT operand on APPL statement Specifies that a generation of an Application must wait until its previous generation is complete.

APPL PAYROLL WAIT

WAIT operand on the SUBAPPL statement

Specifies that the subApplication must wait until the same subApplication in the previous generation is complete.

SUBAPPL PAYREQ WAIT

JOB_ANCESTOR_WAIT(ANY) operand on the APPL statement

Indicates that a job is not eligible for submission if the same job in any previous generation of the Application has not completed successfully.

APPL PAYROLL + JOB_ANCESTOR_WAIT(ANY)

JOB_ANCESTOR_WAIT(LAST) operand on the APPL statement

Indicates that a job is not eligible for submission if the same job in the previous generation of the Application has not completed successfully. ESP Workload Manager only looks at the -1 generation.

APPL PAYROLL - JOB_ANCESTOR_WAIT(LAST)

None of the above operands Specifies that the Applications can process at the same time.

APPL PAYROLL


ESP-5.4-UG-05 143

Identifying JCL libraries

You can use global statements in your Application to specify the default JCL libraries you want to use throughout an Application. This saves you the task of repeatedly specifying the same information as part of each job definition. The scope of a global statement extends from the point at which you specify it to either the end of the Application, or to the point at which you specify another global statement. This way you can change or override job defaults several times during an Application, if necessary.

You can specify any of the following: a JCL library, a temporary JCL library, and a COPYJCL library at a global level. You can override the JCL library, member name, or COPYJCL library at a job level.

Note: The rules for the JCL library differ when resubmitting or inserting a job from CSF.

Example

The following example identifies three libraries in the BILLJOBS Application. These global statements are specified prior to any JOB statements.

APPL BILLJOBSJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL'COPYJCL 'CYBER.JCL.COPY' GEN(0)

Each of these statements is described in the sections following.

Specifying a JCL library

Use the JCLLIB statement to specify the JCL library you want to use for all jobs following this statement.

For example:

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYSENDJOBJOB PAYJOB2 RUN WORKDAYSENDJOB

The JCLLIB statement cannot be used at the job level. If you code a JCLLIB statement within the scope of a JOB statement, it affects all jobs after it, or until another JCLLIB statement is specified. To override the JCL library for a particular job, use the DATASET statement. For details, see ““Specifying a JCL library for a single job” on page 145”.

Section–Identifying JCL libraries

144 ESP-5.4-UG-05

The MEMBER statement can be used to override the JCL name searched for in the JCLLIB library. For details, see “Specifying a member name for a JCL library search” on page 145.

Specifying a temporary JCL library

Use the TEMPLIB statement to specify the temporary or override JCL library you want to use as the default for all jobs following this statement. For jobs following the TEMPLIB statement, if the JCL is found in the temporary library, then that JCL is used. Otherwise, JCL from the library in the most recent JCLLIB statement is used.

For example:

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL'JOB PAYJOB1 RUN WORKDAYSENDJOB

The preceding statement instructs ESP Workload Manager to look for JCL in the temporary library first. As long as the JCL is in the temporary library specified in TEMPLIB and is not date excluded, ESP Workload Manager submits the regularly scheduled job from the temporary library. ESP Workload Manager does not automatically delete the member from the TEMPLIB data set when a job completes.

You can code TEMPLIB anywhere in a procedure and all subsequent jobs will use JCL from the temporary library. In the following example, jobs PAYJOB2 and PAYJOB3 use JCL from temporary library PROD.OVERRIDE.JCL.

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN WORKDAYSENDJOBTEMPLIB 'PROD.OVERRIDE.JCL'JOB PAYJOB2 RUN WORKDAYSENDJOBJOB PAYJOB3 RUN WORKDAYSENDJOB

The MEMBER statement and the JOBNAME keyword in the TEMPLIB statement affect the JCL name searched for in the TEMPLIB library. For details, see “Specifying a member name for a JCL library search”, following.


ESP-5.4-UG-05 145

Specifying a member name for a JCL library search

By default, when ESP Workload Manager searches a library for JCL, it looks for a member name that is the same as the job name. You can use the MEMBER statement to specify a different member name from the job name. This is useful if you want to run the same JCL for different jobs. In the following example, the search is for member PJOB.

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 MEMBER PJOBJOB PAYJOB2 MEMBER PJOBENDJOB

You can have ESP Workload Manager disregard the MEMBER statement when it searches a temporary library by including the JOBNAME keyword on the TEMPLIB statement. This is useful if you want to override one job in a group of jobs that use the same JCL member, such as the jobs in the preceding example.

If you want to override PAYJOB1, you start by adding a TEMPLIB statement to the Procedure and placing the override JCL in the temporary library. However, both jobs in the preceding example run JCL from PJOB, whether it is in the JCLLIB or TEMPLIB libraries. You need to call your temporary JCL something else so it is not picked up by PAYJOB2. You do this by adding JOBNAME to the TEMPLIB statement and calling your override JCL PAYJOB1:

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'TEMPLIB 'PROD.OVERRIDE.JCL' JOBNAMEJOB PAYJOB1 MEMBER PJOBJOB PAYJOB2 MEMBER PJOBENDJOB

In the preceding example, ESP Workload Manager first searches the temporary JCL for member PAYJOB1 and runs that JCL. Next, it searches the temporary JCL for member PAYJOB2, which it does not find. It then searches the regular library for member PJOB and runs that JCL.

Specifying a JCL library for a single job

The JCLLIB and TEMPLIB statements allow you to specify the JCL library for multiple jobs. To specify the JCL library and (optionally) the member name for a single job, you use the DATASET statement. DATASET overrides the library in the JCLLIB statement (but not the library in the TEMPLIB statement) for the job it is coded under.


146 ESP-5.4-UG-05

Example: Using a different JCL library for a job

In the following example, the JCL for PAYJOB1 and PAYJOB3 is read from PROD.JCL.CNTL, the library from the JCLLIB statement. PAYJOB02 is read from PROD.OVERRIDE.JCL, the override library from the DATASET statement.

APPL PAYROLLJCLLIB 'PROD.JCL.CNTL'JOB PAYJOB1 RUN DAILY RELEASE PAYJOB2ENDJOBJOB PAYJOB2 DATASET 'PROD.OVERRIDE.JCL' RUN DAILY RELEASE PAYJOB3ENDJOBJOB PAYJOB3 RUN DAILYENDJOB

If you want to use the JCL from PROD.OVERRIDE.JCL only on February 14, 2000, you can code the following for the PAYJOB2 in the preceding example:

JOB PAYJOB2 IF TODAY('FEB 14,2000') THEN - DATASET 'PROD.OVERRIDE.JCL' RUN DAILY RELEASE PAYJOB3ENDJOB

Controlling the use of temporary JCL

Use the following options to control the use of temporary JCL:

• Use ESP Workload Manager control statements in JCL to limit the time period for usage. This technique is described later in this section.

• Use ESP Workload Manager automatic variable insertion facility (AUTOVARS) to insert a trailer step that deletes the TEMPLIB member. For information on using AUTOVARS, see the ESP Workload Manager Advanced User's Guide.

• Use another method for cleaning out the TEMPLIB members. For example, on a daily basis, delete the members.

• Instead of using TEMPLIB, use IF logic with the DATASET statement to override the JCL library for a particular job. This technique is described later in this section.

• Instead of using TEMPLIB, use %INCLUDE and %EXCLUDE statements within the JCL. This can be practical if the differences in JCL are minimal. For information on using these statements, see the ESP Workload Manager Advanced User's Guide.


ESP-5.4-UG-05 147

• Use different data sets. For example, you could use a different data set each day.

Example: Using a different TEMPLIB based on year and day

In the following example, ESP Workload Manager symbolic variables are used as part of the TEMPLIB data set name. %ESPSYEAR resolves to the four-digit year; %ESPSDDD resolves to the Julian day. For example, on February 28, 2001 this:

TEMPLIB 'ESP.OVERRIDE.D%ESPSYEAR%ESPSDDD'

resolves to:

ESP.OVERRIDE.D2001059

Limiting the use of temporary JCL

A job can run from a temporary JCL library (TEMPLIB) for a period of time. If you want to limit the time period in which temporary JCL is to be used for a job, you can:

Use a //* FROM statement in the job JCL to identify the beginning date and time. The default is NOW.

Use a //* UNTIL statement in the job JCL to identify the ending date and time. There is no default. ESP Workload Manager uses the TEMPLIB JCL up to, but not including, the date and time specified.

You can use either one of these statements or you can use both. Place these statements before the job card in a JCL member of the temporary library (TEMPLIB). You can use any ESP Workload Manager scheduling term that resolves to a single date and time.

Example

In the following example, ESP Workload Manager uses the temporary JCL from midnight on February 1, 2001 up to, but not including, February 14, 2001. At any time after February 13, ESP Workload Manager uses the default JCL library. Note these dates are based on the scheduled date of the Event, which may not be the actual date of job submission.

//* FROM FEB 1,2001//* UNTIL FEB 14,2001//BILLJOBA JOB . . .

To specify a COPYJCL library:

• Use the COPYJCL statement to generate a copy of the JCL for every job, as ESP Workload Manager submits it.

This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved. This JCL can be used for job re-submission. ESP Workload Manager keeps track of where the job was submitted from and the JCL that was used. ESP Workload Manager can store the copy of the


148 ESP-5.4-UG-05

JCL either by job name (JOBNAME operand) or by JES job number (JOBID operand).

Using the JOBNAME operand of the COPYJCL statement

The JOBNAME operand requests the member name used for storing the JCL for a job to be the same as the job name. This is the default. Each submission of a particular job overwrites the previous copy of that job JCL.

Using the JOBID operand

Use the JOBID keyword when you want ESP Workload Manager to store the copy of the JCL by job number. ESP Workload Manager creates a member name in the form JOBnnnnn or Jnnnnnnn, where nnnnn or nnnnnnn is the job number. See the job ID entry in the glossary. The system assigns this number sequentially. A member is not overwritten until the corresponding job ID reoccurs.

Writing the JCL to a GDG

With either the JOBID or the JOBNAME operand, you can write the JCL to a Generation Data Group (GDG). A new generation can be created each day to maintain several generations of JCL. Schedule an Event each day to submit a job that creates the next generation.

Example: Using COPYJCL

This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by job name (by default).

COPYJCL 'CYBER.JCL.COPY' GEN(0)

Suppressing COPYJCL

If you do not want to create COPYJCL for a particular job, you can specify the following:

JOB MISCCOPYJCL NONE

Compressing COPYJCL

If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You can use a data-set-triggered Event to submit the compress job automatically after a number of closures.


ESP-5.4-UG-05 149

Identifying jobs

An ESP Application is made up of a group of related jobs and other tasks. The jobs and tasks have job names assigned to them.

Before identifying job requirements, you must use a JOB statement to identify the name of the job in an Application. You can define jobs in any order. ESP Workload Manager submits the jobs based on how you define the job relationships.

JOB statement

Once the JOB statement has been used to introduce a job to an Application, use other related job statements to:

• Define a job’s processing requirements• Override any default specifications• Specify the relationships between the named job and others included in this

Application or outside this Application

The JOB statement defines the beginning of the job definition. The ENDJOB statement or another JOB statement signifies the end of a job definition. You must use an ENDJOB statement after defining all of your jobs. Although optional, it is recommended you use an ENDJOB for each job definition.

The following is a sample job definition:

JOB PATJOB1 RUN DAILY RELEASE PATJOB2ENDJOB

Qualifying jobs

ESP Workload Manager lets you qualify job names with a qualifier consisting of up to 8 alphanumeric characters, and separated from the job name by a period,‘.’ You can qualify jobs, links, and tasks, but you cannot qualify Manual jobs. Use qualification of job names in an Application to:

• Define duplicate jobs• Give a meaningful name to other job types, such as links and tasks• Give a more descriptive name to a job• Pass a built-in symbolic variable (ESPAPQUAL), representing the qualifier, to a

job’s JCL

Symbolic variables as qualifiers

You should not use %ESPA (actual) variables as time qualifiers for jobs because the actual time differs from Application generation to the time ESP Workload Manager submits a job as part of the Application. You can use %ESPS (scheduled) variables as time qualifiers as these refer to the scheduled time of the Event.

Section–Identifying jobs

150 ESP-5.4-UG-05

Examples: Qualified jobs

The following are some examples of qualified jobs. The last example uses a qualifier that consists of the first three characters of the symbolic variable %ESPSDAY. This is the scheduled day name. For example, on Monday this resolves to MON.

JOB MYJOB.RUN1JOB STILL.RUNNINGJOB BACKUP.SYSRESJOB PAYJOB.%ESPSDAY(1:3)

Duplicate job names

Duplicate job names are not allowed in an Application. If you want to invoke the same job more than once, you must use a qualifier.

When a JOB statement is repeated with an identical name in an Application, ESP Workload Manager considers that the second and following instances continue the first instance. You can spread a job definition over many fragments in a procedure. You cannot change the workload object type (for example from a TASK to a LINK.)

When there are multiple statements of the same kind:

• The latest statement instance overrides the previous ones if only one instance is allowed. For example, the DUEOUT statement.

• All the statements are combined if more than one statement is allowed. For example the RUN statement.

Examples

Multiple runs of a job

This example shows how you can define a job more than once in an Application using a job qualifier. Job A appears twice in the Application. The qualifier of the first run is THIS; the qualifier of the second run is THAT.

APPL TESTQUALJCLLIB 'CYB.TESTJOBS.CNTL'JOB A.THIS RUN ANY RELEASE A.THATENDJOBJOB A.THAT RUN ANYENDJOB

Combined statement

The following procedure segment:

JOB A DUEOUT EXEC 23:59 RUN WEEKDAYS


ESP-5.4-UG-05 151

NOTIFY OVERDUE ALERT(TRDY) RELEASE BENDJOB... (other job definitions)JOB A DUEOUT EXEC 13:00 RUN SUN RELEASE CENDJOB

is equivalent to:

JOB A DUEOUT EXEC 13:00 RUN WEEKDAYS AND SUN NOTIFY OVERDUE ALERT(TRDY) RELEASE B RELEASE CENDJOB

The RUN and RELEASE statements have been combined but the last instance of the DUEOUT statement has overridden the previous one. If you want to use the different DUEOUT requirements for weekdays and Sunday, you must use IF-THEN-ELSE logic.

Identifying a job as on-request

With Applications, you can identify certain jobs as on-request and define their relationships to other jobs. The on-request jobs take their place in the schedule when they are selected. From the time you generate the Application up to the time of job submission, you can use CSF or the APPLJOB command to request the job. If you have not explicitly requested the job, ESP Workload Manager bypasses it and treats it as a normal completion, releasing its successor jobs. To mark a job as on-request, use the REQUEST operand of the JOB statement.

REQUEST job

By selecting a REQUEST job, you are not requesting the job, you are only making it eligible for explicit request via CSF or the APPLJOB command. You must first generate the Application before you can request any of the Application’s jobs. To allow users to request jobs, you can generate the Application containing these jobs early in the morning and use submit time dependencies (for example, DELAYSUB statements) on the jobs with no predecessors so they are not submitted at the time ESP Workload Manager generates the Application.


152 ESP-5.4-UG-05

Other methods

Other methods exist for handling on-request work. For example you can:

• Insert a job into an Application from CSF• Use a separate on-request Application with a link that keeps it active• Trigger an Event and pass it a user symbolic variable representing the job name

For information on CSF, see “Consolidated Status Facility (CSF)” on page 221.For information on using links, see “Using links” on page 184. For information on using symbolic variables, see ESP Workload Manager Advanced User’s Guide.

Example

In the following example, if job J2 is not requested at the time it is scheduled for submission, ESP Workload Manager bypasses it and submits job J3.

The Application looks like this:

APPL APPL1JCLLIB...JOB J1 RUN DAILY RELEASE J2ENDJOBJOB J2 REQUEST RELEASE J3 RUN DAILYENDJOBJOB J3 RUN DAILYENDJOB

J1 Daily

J3 Daily

J2 REQUEST


ESP-5.4-UG-05 153

To request the job:

Use the RQ command from the Consolidated Status Facility, or use the APPLJOB (abbreviated AJ) Command.

The following example shows requesting job J2 in the current generation of APPL1, with the abbreviated APPLJOB command:

AJ J2 REQUEST APPL(APPL1.0)

To define critical jobs:

Use the CRITICAL operand on the JOB statement to identify a critical job in your Application.

If critical path analysis is turned on for the Application, ESP Workload Manager calculates the longest path to this job, based on historical execution time, and identifies this as the critical path. You can display critical path jobs using CSF or the LISTAPPL command.

The following statement defines job XYZ as critical.

JOB XYZ CRITICAL

For information on critical path analysis, see “Using critical-path analysis” on page 208.

To define held jobs:

Use the HOLD operand on the JOB statement to identify a job that you want to hold from submission until you release it.

This places the job on manual hold when ESP Workload Manager generates the Application. You can display jobs that are on manual hold using CSF or the LISTAPPL command.

The following statement defines job ABC on hold.

JOB ABC HOLD

It is not a common practice to define jobs on hold. If a job needs to wait for a manual process, it is better to use a task in the Application as a predecessor.

For information on using tasks, see “Using tasks” on page 188.

Defining conditional jobs

Normally, all jobs in an Application must complete, or be bypassed, for the Application to complete. In some situations, you could have some optional jobs (other than on-request jobs) that may or may not run as part of the Application. These jobs are referred to as conditional jobs. ESP Workload Manager completes an Application when all non-conditional jobs are complete and bypasses any incomplete conditional jobs.


154 ESP-5.4-UG-05

For example, you can have a recovery job that only runs when another job in the Application abends. In this case, the recovery job is a conditional job. The recovery job may or may not run. If all other jobs in the Application are complete then you want ESP Workload Manager to complete the Application.

To define conditional jobs:

Use the CONDITIONAL operand on the JOB statement to identify a job that may or may not run as part of an Application.

The following statement defines job RECOVER as a conditional job.

JOB RECOVER CONDITIONAL

For examples of using conditional jobs, see ESP Workload Manager Advanced User’s Guide.

Scope of a JOB statement

The scope of a JOB statement includes all statements up to an ENDJOB statement or the next JOB statement. ESP Workload Manager processes commands based on where they are placed, as follows:

• ESP Workload Manager processes commands outside the scope of JOB statements when the Application is generated and every time a job becomes eligible (for example, all dependencies met).

• ESP Workload Manager processes commands within the scope of a JOB statement only when the job becomes eligible (for example, all dependencies met).

Example: Sending messages at different stages

The following Application contains three SEND commands. ESP Workload Manager sends the following messages at the following points:

• MESSAGE1, when ESP Workload Manager generates the Application and each time it submits a job in the Application.

• MESSAGE2, when ESP Workload Manager submits job A.• MESSAGE3, when ESP Workload Manager submits job B.


APPL ABCJCLLIB . . .SEND 'MESSAGE1' U(*)JOB A SEND 'MESSAGE2' U(*) RUN DAILY RELEASE BENDJOBJOB B SEND 'MESSAGE3' U(*)


ESP-5.4-UG-05 155

RUN DAILYENDJOB

Defining job requirements

Once you name a job, you can use different statements to define the job’s requirements. These requirements generally fall into the following three areas:

Specifying time dependencies

A job can have different types of time dependencies. These include the following:

• Delayed, or early, submission time• Late submission time• Due-out times for different stages in processing• Cut-off time for submission• Cut-off time for job dependencies• Cut-off time for resources• Minimum and maximum run times

You can refer to different times to compensate for varying conditions using CLANG.

To delay submission of a job:

• Use the EARLYSUB (early submit time) or DELAYSUB (delayed submit time) statements to mark a job for delayed submission relative to the scheduled time of the Event.

Both statements achieve the same results. Since you can specify any valid schedule criteria that resolves to a single date and time when the Application builds, you can use the EARLYSUB (or DELAYSUB) statement to allow an Application to span many days or weeks.

Dependency

SelectionTiming

Section–Specifying time dependencies

156 ESP-5.4-UG-05

Example: Identifying a delayed submission time

This example specifies that job J2 should not be submitted prior to 9 pm:

JOB J2DELAYSUB 9PM

Example: Using different submission times

This example uses CLANG to specify different DELAYSUB times for a job. The second DELAYSUB statement overrides the first on weekends only. The different times are:

• 9 pm on weekdays• 5 pm on weekends

JOB J2 RUN DAILY DELAYSUB 9PM IF TODAY('WEEKEND') THEN DELAYSUB 5PMENDJOB

To delay the release of a job using the RELDELAY statement:

• Use the RELDELAY statement to delay job submission at the time a job becomes eligible (for example, ready). This statement uses minutes as its unit of measure. You can delay submission up to 255 minutes.

Example: Delaying submission of a job from ready time

This example delays submission of job J2 by 5 minutes when it becomes ready for submission.

JOB J2 RELDELAY 5ENDJOB

Introducing anticipated end times

When ESP Workload Manager generates an Application, it calculates anticipated end times for all jobs in the Application. ESP Workload Manager adjusts anticipated end times automatically as the Application processes; for example, when a job is submitted or a job ends. You can review the Application, at any stage, and determine when any job is expected to finish. This information is displayed to you whenever you list the Application (for example LISTAPPL command).


ESP-5.4-UG-05 157

Introducing dueout times

If a job is not complete by its anticipated end time, ESP Workload Manager continues to adjust this time. There is no indication that a job has missed its original anticipated end time. If you need to provide some awareness when jobs are late, you can identify any of the following:

• A late submission time• A late start time• A late end time

If the job has not completed the specified stage in processing by the due-out time, the status field shows OVERDUE in the Consolidated Status Facility (CSF) display of the job.

ESP Workload Manager can also send a message or trigger an Event when a job becomes overdue by using a NOTIFY statement. For more information, see “Providing notification on Job status” on page 206.

ESP Workload Manager also provides critical path analysis. For information on using critical path, see “Using critical-path analysis” on page 208.

Specifying due-out times

You can use any of the following statements to identify due-out times for a job:

Statement Explanation

LATESUB Specifies a late submission for a job. This identifies a time by which ESP Workload Manager should submit a job. The LATESUB time for a link, task, or data-set-trigger object represents the time by which all of its predecessor and time dependencies should be met (for example, the READY time).LATESUB does not force, or bypass, submission of the job. Use the ABANDON DEPENDENCIES statement to force submission of the job, regardless of dependencies; use the ABANDON SUBMISSION statement to bypass submission of the job.

DUEOUT INPUT Specifies a due-out time from the INPUT processing node. This refers to the start time.

DUEOUT EXEC Specifies a due-out time from the EXEC processing node. This refers to the successful end time. For a link, task, or data-set-trigger object, this represents the time by which it should complete.


158 ESP-5.4-UG-05

Statements for different job types

The following table indicates the statements you can use for different job types. For more information on job types, see “Using different job types” on page 177.

Example: Specifying a late submission time for a job

In the following example, job X has a late submission time of 9 pm.

JOB X LATESUB 9PM RUN DAILYENDJOB

Example: Specifying a due-out time for a job

This example specifies that job Z is due out of the execution queue by 3 am.

JOB Z DUEOUT EXEC 3AM RUN DAILYENDJOB

Example: Specifying a due-out time for a task.

This example specifies that the task called WAIT4.TAPE should be marked complete no later than two hours after the trigger time of the corresponding Event.

JOB WAIT4.TAPE TASK DUEOUT EXEC REALNOW PLUS 2 HOURS RUN DAILYENDJOB

Propagating dueout times

ESP Workload Manager propagates dueout times, up-stream, to all predecessors of a selected job where you specified a LATESUB or DUEOUT statement. This reduces the need for you to code a lot of LATESUB or DUEOUT statements in an Application. ESP Workload Manager sets these dueout times based on historical average elapsed times.

When ESP Workload Manager propagates a time to a predecessor, it sets the DUEOUT EXEC time and adjusts this time if it is already specified. ESP Workload

Job Type LATESUB DUEOUT INPUT DUEOUT EXEC

Job X X X

External job X X X

Manual job X X X

Link X X

Task X X

Data set Trigger Object X X


ESP-5.4-UG-05 159

Manager provides notification when this time is not met, just as it does when you specifically code a DUEOUT time. If you need to reset the time, you can use CSF or the APPLJOB command.

Note: Your administrator can have turned this propagation feature off.

Example: Propagating dueout times

In the following example, PAYJOB6 should be submitted by 7 am.

By specifying a LATESUB time for PAYJOB6, ESP Workload Manager automatically sets dueout execution times for all predecessors to this job. If any job in the PAYROLL Application is late, ESP Workload Manager highlights it on CSF. Further notification can take place using the NOTIFY statement.

A sample Application follows:

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'JOB PAYJOB1 RELEASE PAYJOB2ENDJOBJOB PAYJOB2 RELEASE (PAYJOB3,PAYJOB4,PAYJOB5)ENDJOBJOB PAYJOB3 RELEASE PAYJOB6ENDJOBJOB PAYJOB4 RELEASE PAYJOB6ENDJOBJOB PAYJOB5 RELEASE PAYJOB6ENDJOB

PAYJOB1

PAYJOB6

PAYJOB5PAYJOB4PAYJOB3

PAYJOB2


160 ESP-5.4-UG-05

JOB PAYJOB6 LATESUB 7AMENDJOBSELECT (PAYJOB1,PAYJOB2,PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)

Bypassing job dependencies

Use the ABANDON DEPENDENCIES job statement to drop a job’s predecessor dependencies once it meets a specified time. This does not override a manual hold, a time dependency, or a resource dependency for a job.

An example of this statement is:

ABANDON DEPENDENCIES 10PM

Bypassing jobs

Use the ABANDON SUBMISSION job statement to bypass a job after a specified time.

An example of this statement is:

ABANDON SUBMISSION 11PM

Example: Bypassing jobs and dependencies

The following example submits job J2 when job J1 completes successfully, or at 10 pm, whichever comes first. When J2 completes successfully, ESP Workload Manager checks that the time is before 11 pm. If it is, ESP Workload Manager submits job J3; otherwise, it bypasses J3 and submits job J4.

APPL APPL3JCLLIB...JOB J1 RUN DAILY RELEASE J2ENDJOBJOB J2 RUN DAILY ABANDON DEPENDENCIES 10PM RELEASE J3ENDJOBJOB J3 RUN DAILY ABANDON SUBMISSION 11PM RELEASE J4ENDJOBJOB J4 RUN DAILYENDJOB


ESP-5.4-UG-05 161

Example: Bypassing a job and wait for predecessor

Jobs A, B, and C are three sequential, daily jobs. Job B has a submission time of 9 am if job B is not submitted within an hour (10 am). Then job B should not run but job C should wait for job A to complete.

The following part of an Application identifies a delayed submission time of 9 am and an abandon submission time of 10 am for job B. Job B’s execution is abandoned if it is not submitted by 10 am. Job B is not actually bypassed until job A completes successfully, and job C waits until this happens.

JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AMENDJOBJOB C RUN DAILYENDJOB

Example: Bypassing a job without waiting for predecessor

Jobs A, B, and C are three sequential, daily jobs. Job B has a submission time of 9 am if job B has not been submitted within an hour (10 am), job C should start (even if job A is running), and job B should not run.

The following part of an Application identifies a delayed submission time of 9 am and an abandon submission time of 10AM for job B. Job B waits for job A to complete successfully prior to being bypassed. When you code an abandon dependencies time of just after 10 am, job B does not wait for job A to complete before it is bypassed and job C starts.

JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AM ABANDON DEPENDENCIES 10:01AMENDJOBJOB C RUN DAILYENDJOB


162 ESP-5.4-UG-05

Removing resource dependencies

Use the ABANDON RESOURCES job statement to submit a job without its resource dependencies, once it meets a specified time. An example of this statement is:

ABANDON RESOURCES 8AM

This example indicates ESP Workload Manager should not wait for resources for the job after 6 pm.

JOB PREPJOB RESOURCE (1,NITESHFT) ABANDON RESOURCES 6PMENDJOB

Specifying minimum or maximum run times

You can use the MINRUNTIME and MAXRUNTIME built-in symbolic variables to specify a minimum or maximum run time for a workload object. MINRUNTIME and MAXRUNTIME are integer variables representing an elapsed run time in minutes. You can set a run time to a fixed value or code a calculation to determine the value.

If you want to include the average run time of prior runs in your calculation, you can use the AVGRUNTIME built-in symbolic variable. The value of this integer variable is derived from the most recent elapsed times, which are stored in the Jobindex data set. The number of sample times used in the average depends on the number of index entries kept, as defined in the job tracking model. The average includes only successful runs; unsuccessful runs are ignored. The average is rounded to the nearest minute.

MINRUNTIME, MAXRUNTIME, and AVGRUNTIME are available at Application processing time only, not at generation time.

If a value is specified for MAXRUNTIME, this value is added to the start time for the run to obtain an expected end time. This time is then used as the DUEOUT EXEC time for the run, unless there is an existing DUEOUT EXEC for an earlier time, in which case the earlier DUEOUT EXEC time takes precedence. If the DUEOUT time calculated from the MAXRUNTIME value is exceeded, normal notification and alerting processes are activated.

If a value is specified for MINRUNTIME, this value is added to the start time for the run to obtain an expected earliest end time. When the run terminates, the actual end time is compared to this anticipated time. If the actual end time is earlier than the anticipated time, the run is considered to have ended prematurely. When this occurs, standard notification and alerting processes are invoked if you have coded a NOTIFY statement with the PREMEND (Premature end) operand.

Example: Specifying application level minimum and maximum run times, with


ESP-5.4-UG-05 163

global notification

APPL PAYROLLJCLLIB 'CYBER.JCL.CNTL'

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

NOTIFY OVERDUE USER(CYBER02)NOTIFY PREMEND USER(CYBER02)

JOB PAY1 RUN NOWENDJOB

JOB PAY2 RUN NOWENDJOB

In the preceding example, Application PAYROLL has two jobs, PAY1 and PAY2. The minimum run time for each job is set to 25% of its current average runtime; the maximum run time for each job is set to 175% of its current average run time. If either job runs over the maximum time or ends before having run for the specified minimum time, a notification message is sent to user CYBER02.

Example: CSF

In the following CSF display, job WAIT5, AGen 47 ended before the minimum time and job WAIT3, AGen 47 exceeded its maximum run time:

TT54 Consolidated Status: View 1 ------------ Row 1 of 6, Col 1COMMAND ===> SCR ===> CSR

Job Name Appl AGen Jobno MinRT MaxRT AvgRT Status___ WAIT3#5S TSTRFES 31 31755 7 12 16 FAILED, S222 AT 13.19 23 D___ WAIT5 TSTRFES 31 31754 7 12 5 COMPLETED AT 13.14 23 DEC___ WAIT3#5S TSTRFES 34 34969 - - 16 FAILED, S222 AT 08.47 24 D___ WAIT5 TSTRFES 34 34968 - - 5 FAILED, S222 AT 08.47 24 D___ WAIT3#5S TSTRFES 47 12220 7 12 16 EXECUTING STEP4 OVERDUE___ WAIT5 TSTRFES 47 12218 7 12 5 COMPLETED AT 14.06 09 JAN

Here are the notification messages corresponding to the preceding CSF display:

TT54_1194I Job WAIT5(JOB12218) ENDED PREMATURELY, CMPC=0 AT 14.06.02 ON 09 JAN2004, APPL TSTRFES.47

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


164 ESP-5.4-UG-05

Issuing the LJE command on job WAIT5, AGen 47 in the preceding CSF screen provides the following output. Note that the minimum, maximum, and average run times are displayed:

ESP ----------------------------------------------- Row 1 of 16, Col 1 -COMMAND ===>---------------------------------- TOP OF DATA---------------------------------AJ WAIT5(12218) APPL(TSTRFES.47)Job=WAIT5(12218), Completed->CC 0 Submitted ................ 2004/01/09 14:00 Started .................. 2004/01/09 14:00 Completed ................ 2004/01/09 14:06 MinimumRunTime=7, MaximumRunTime=12, AverageRunTime=5 Class=A, Priority=7, Step=STEP1, SrvClass=JES, SysName=SYSA, Sysplex=SYSAPLEX, Asid=0082, SmfId=SYSA, JesNode=CYBJES, EspProc=CYBTT01.TEST.ESPPROC(TSTRFES)

Appl=TSTRFES.47, Completed Scheduled ................ 2004/01/09 14:00 Built .................... 2004/01/09 14:00 Completed ................ 2004/01/09 14:17 DueOutPropagation, Event=CYBTT04.TSTRFES, TrigUser=CYBTT04

Example: History Report with sample output

The following history report includes “Min Run”, “Max Run”, and “Avg Run” columns:

REPORTINPUT DATASET('CYB1.TONYT540.HISTFILE')CRITERIA JOBNAME EQ WAIT- OR JOBNAME EQ CALCFROM DEC 1 2003DISPLAY JOBNAME,JOBNO,APPLSYS,MINRUNT,MAXRUNT,AVGRUNT,EXECQT,OVDEND,EXECSDATE 12,EXECST 10SORT EXECSDATE EXECST JOBNAME EXECQTENDRCYBERMATION ESP VER 5.4.0 BATCH INTERFACE 10.47.35 FRIDAY JANUARY 9TH,

JOBNAME JOB APPLSYS Min Max Avg EXEC OVERDUE START EXEC NO Run Run Run QTIME END DATE STARTWAIT3 42148 - - - 3M01 - THU 4DEC03 14.41.38WAIT5 42299 - - - 4M59 - THU 4DEC03 17.16.56WAIT5 42305 - - - 5M00 - THU 4DEC03 17.26.23WAIT5 42326 - - - 4M59 - THU 4DEC03 17.33.01WAIT5 42370 - - - 5M01 - THU 4DEC03 17.35.18WAIT5 54085 TSTRFES 7M00 12M00 5M00 5M09 0 TUE 9DEC03 08.17.13WAIT3#5S 54086 TSTRFES 7M00 12M00 16M00 16M10 4M12 TUE 9DEC03 08.17.23WAIT5 54541 TSTRFES 7M00 12M00 5M00 5M01 0 TUE 9DEC03 08.45.55WAIT3#5S 54542 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 08.45.56WAIT5 54615 TSTRFES 7M00 12M00 5M00 5M00 0 TUE 9DEC03 09.21.50WAIT3#5S 54616 TSTRFES 7M00 12M00 16M00 16M01 4M02 TUE 9DEC03 09.21.51WAIT3 55327 - - - 3M00 - TUE 9DEC03 15.04.20WAIT3#5S 55329 - - - 16M01 - TUE 9DEC03 15.04.28


ESP-5.4-UG-05 165

Specifying job relationships

To specify predecessor and successor job relationships:

Include the appropriate job-dependency statements.

A list of job-dependency statements appears below:

Specifying multiple jobs

If you need to specify more than one job name, enclose the job names in parentheses. For example:

RELEASE (PAYJOB2,PAYJOB3,PAYJOB4)

If you need to continue to another line, use either a + or a - as a line continuation character. For example:

RELEASE (PAYJOB2,PAYJOB3,PAYJOB4,-PAYJOB5,PAYJOB6)

Job-Dependency Statement

Explanation

AFTER Specifies any job that is a predecessor to this job and indicates a release to this job upon its completion. (The default is successful completion.)

RELEASE Specifies successors to a job that are released upon its completion. (The default is successful completion.)

PREREQ Specifies the names of any other jobs that must be complete before this job can be allowed to execute. These are prerequisite jobs. ESP Workload Manager automatically selects the prerequisite jobs for submission whenever this job is selected for processing.

COREQ Specifies the names of any other jobs which must be selected automatically whenever this job is selected for processing. The named job and all of its co-requisites are allowed to execute simultaneously; there is no relationship between a job and its co-requisites.

POSTREQ Specifies the names of any other jobs which must run after this job has executed. These are post-requisite jobs. ESP Workload Manager automatically selects the post-requisite jobs for submission whenever this job is selected for processing.

Section–Using Implicit Resources

166 ESP-5.4-UG-05

Two methods of coding a job-dependency relationship

The following are two ways of coding a job-dependency relationship. With either method, there is no difference in the way ESP Workload Manager generates or processes the Application.

Using Implicit Resources

ESP Workload Manager can specify mutually exclusive run requirements through Application and job-level statements. These statements provide an alternative to defining ESP Workload Manager resources explicitly and the corresponding coding of ESP Workload Manager resource statements to handle mutually exclusive run requirements.

ESP ENQUEUE provides the capability for a job to request exclusive or shared use of a resource without the need to define the resource explicitly in advance. ESP Workload Manager will prevent jobs with mutually exclusive requests from executing concurrently. ESP ENQUEUE behaves like the z/OS enqueues.

The NOTWITH feature uses ESP ENQUEUE to request that certain explicitly specified jobs not execute concurrently.

Consider the following guidelines before using the ENQUEUE and NOTWITH statements:

• Use ENQUEUE when you know which resource the jobs require.

• Use NOTWITH when you know that jobs cannot run together, but you do not know why.

Note: The NOTWITH and ENQUEUE statements use resources. Therefore, a resource file (RESFILE) and the topology must be defined before you can use them.

There are four statements with the ESP ENQUEUE and NOTWITH features. All four statements are valid within and outside the scope of a job definition. When coded within a job definition, they affect that job only. When coded outside the scope of a job definition, they affect the building of a default list that applies to all subsequent jobs.

Note: The statements described in this section use resources implicitly. Therefore, a resource file (RESFILE) and the network topology must be defined before you can use these statements.

Method Code

1 JOB ARELEASE B

2 JOB BAFTER A


ESP-5.4-UG-05 167

ENQUEUE

To specify mutually exclusive jobs (A and B) with the ENQUEUE statement:

1. Insert an ENQUEUE statement in the job workload object (job A).

2. Specify in that statement the name of a resource.

3. Specify the EXCLUSIVE operand.

4. Insert an ENQUEUE statement in the job workload object (job B).

5. Specify in that statement the name of the same resource as for job A.

6. You can specify either the SHARED (default) or the EXCLUSIVE operand.

Note: You can insert the ENQUEUE statement in an Application, outside a job workload object. In that case the statement applies to every job following it in the Application.

Examples

The following example shows job NWN001 specifying an enqueue on a resource named FRED:

APPL NWN00AJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY ENQUEUE NAME(FRED) SHAREDENDJOB

JOB NWN002 RUN DAILYENDJOB

The following example shows job NWN001 and job NWN002 specifying an enqueue on a resource named FRED. Because the operand EXCLUSIVE is specified in job NWN002, jobs NWN001 and NWN002 cannot run at the same time:



JOB NWN002 RUN DAILY ENQUEUE NAME(FRED) EXCLUSIVEENDJOB


168 ESP-5.4-UG-05

The following example shows job NWN001, job NWN002, and job NWN003 specifying an enqueue on a resource named FRED. Because the operand EXCLUSIVE is specified in job NWN002, job NWN002 cannot run at the same time as the other two jobs. Jobs NWN001 and NWN003 can run at the same time:



JOB NWN002 RUN DAILY ENQUEUE NAME(FRED) EXCLUSIVEENDJOB


To remove mutual exclusivity:

• Replace the ENQUEUE statement changing the status from EXCLUSIVE to SHARED, or

• Remove all ENQUEUE statements corresponding to a resource name.

To exclude jobs from an ENQUEUE statement at the Application level:

• Insert a DEQUEUE statement with a resource name matching exactly the resource name specified in the ENQUEUE statement.

You can insert the DEQUEUE statement in an Application, outside a job workload object. In that case, every job following it in the Application will be excluded from the ENQUEUE statement. To exclude only a specific job, you must place the DEQUEUE statement in the scope of that job.

Usage notes

The following example shows job NWN002 excluded from a specified enqueue of the resource named FRED.

APPL NWN00BJCLLIB 'CYBER.JCL.CNTL'ENQUEUE NAME(FRED) SHAREDJOB NWN001 RUN DAILYENDJOB

JOB NWN002


ESP-5.4-UG-05 169

RUN DAILY DEQUEUE NAME(FRED)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 NWN00GJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY ENQUEUE NAME(B-C) SHAREDENDJOB

JOB NWN002 RUN DAILY ENQUEUE NAME(BBC) EXCLUSIVEENDJOB

The ENQUEUE B- command produces the following:

BBC

(Gen) Held Shr NWN001, Appl NWN00G.1 Required Excl NWN002, Appl NWN00G.1


170 ESP-5.4-UG-05

B-C Held Shr NWN001, Appl NWN00G.1

The display shows job NWN002 waiting behind a satisfied request of NWN001. That request was generated by the ESP Resource Manager to reflect the match between NWN001’s enqueue on B-C and NWN002’s enqueue on BBC. Generated requests are shown with (Gen).

Manipulating the enqueue list in a generated Application

To manipulate the enqueue list of a specified job in a generated Application:

• Issue JOBENQ commands in page mode specifying the job and using the appropriate operands.

The JOBENQ command is a page mode command that does not require OPER authority.

Note: You can also use the ME command in CSF.

Example

Considering the following Application:

APPL NWN00GJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY ENQUEUE NAME(B-C) SHAREDENDJOB

JOB NWN002 RUN DAILY ENQUEUE NAME(BBC) EXCLUSIVEENDJOB

The ENQUEUE B- command produces the following:

BBC (Gen) Held Shr NWN001, Appl NWN00G.1 Required Excl NWN002, Appl NWN00G.1

B-C Held Shr NWN001, Appl NWN00G.1

The display shows job NWN002 waiting behind a satisfied request of NWN001.

To release job NWN002, you can issue the following command:

JOBENQ JOB(NWN002) APPL(NWN00G) DEQUEUE BBC


ESP-5.4-UG-05 171

ENQSELF

Before coding mutual exclusive run requirements with NOTWITH statements, you must know the ENQSELF status because ESP Workload Manager behaves differently depending on that status being ALWAYS or NOTALWAYS.

The ENQSELF command provides the option of specifying whether or not every job will have an enqueue on itself.

ENQSELF can be coded as an initialization parameter.

To display the status of ENQSELF:

• Issue the ENQSELF command without any operand.

Note: The ENQSELF command requires OPER authority.

To modify the status of ENQSELF:

• Issue the ENQSELF command with the operand corresponding to the desired status.

Note: The ENQSELF command requires OPER authority.

Example

The following is the response from issuing the ENQSELF ALWAYS command in ESP Workload Manager page mode:

OPER ENQSELF ALWAYSESP1573I ENQSELF MODE IS ALWAYS

NOTWITH

The NOTWITH statement provides a way to prevent mutually incompatible jobs to run at the same time as nothing other than the name of the other job is required.

A choice between the two following methods must be made:

• Set ENQSELF to ALWAYS. In this case every job will enqueue over itself and you will not need a matching NOTWITH statement in the other job, or

• Leave ENQSELF to NOTALWAYS. In this case you will need a matching NOTWITH statement in the other job.

The disadvantage of setting ENQSELF to ALWAYS is the overhead due to the automatic enqueuing of every job.

An alternative is the use of the ENQUEUE statement. See “ENQUEUE” on page 167.

For details about ENQSELF, see “ENQSELF” on page 171.


172 ESP-5.4-UG-05

To specify mutually exclusive jobs (A and B) with the NOTWITH statement:

1. Insert a NOTWITH statement in the job workload object (job A).

2. Specify the name of the job (job B) that you want to prevent running concurrently with job A.

3. If the ENQSELF status is NOTALWAYS, insert an equivalent NOTWITH statement in the workload object of job B. The statement must specify job A.

Note: You can insert the NOTWITH statement in an Application, outside a job workload object. In that case the statement applies to every job following the statement in the Application.

Automatic generation of ENQUEUE commands by the NOTWITH statement

The NOTWITH statement is used to inform ESP Workload Manager the job currently being defined is mutually exclusive with job1.qual1 in appl1 (or with a list of such jobs).

NOTWITH uses ESP ENQUEUEs for each specified job. NOTWITH will build a shared enqueue request in the following form:

ESPENQ_JOB(job1.qual1)_APPL(appl.-)

The NOTWITH statement will set a flag informing ESP Workload Manager to generate an enqueue itself (the job that has the NOTWITH statement). For example:

APPL TESTJOB MYJOB NOTWITH BILLSJOB.-; RUN DAILYENDJOB

The above Application results in the JOB MYJOB having the two following enqueues:

ESPENQ_JOB(MYJOB.)_APPL(TEST.21)ExclusiveESPENQ_JOB(BILLSJOB.-)_APPL(-.-)Shared

If job BILLSJOB.qual has a NOTWITH statement or ENQSELF is set to ALWAYS, BILLSJOB.qual in BILLSAPPL.10 enqueues on itself and it will have at least the following enqueue:

ESPENQ_JOB(BILLSJOB.qual)_APPL(BILLSAPPL.10)Exclusive

This enqueue, together with the job MYJOB shared enqueue, prevents the two jobs from running together.


ESP-5.4-UG-05 173

Examples of ESP ENQUEUES with NOTWITH

APPL NWN00CJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002 RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYS NOTWITH NWN001ENDJOB

The above ESP Application produced the following display from the ENQUEUE command. The ENQUEUE command displays the current enqueue status in the resource file. For more information, see the ENQUEUE command in ESP Workload Manager Reference Guide.

ESPENQ_JOB(NWN001.)_APPL(-.-) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN001.)_APPL(NWN00C.1) Held Excl NWN001, Appl NWN00C.1 (Gen) Required Shr NWN003, Appl NWN00C.1ESPENQ_JOB(NWN003.)_APPL(NWN00C.1) (Gen) Held Shr NWN001, Appl NWN00C.1 Required Excl NWN003, Appl NWN00C.1

In the display above, job NWN001 has an exclusive enqueue on itself and has a shared enqueue on job NWN003. Job NWN003 requests an exclusive enqueue on itself and a shared enqueue on job NWN001. This prevents the jobs from running together.

In the following example, job NWN003 has no NOTWITH statement so it will execute at the same time as job NWN001. Job NWN003 must have a NOTWITH NWN001 statement to be mutually exclusive with job NWN001.

APPL NWN00DJCLLIB 'CYBER.JCL.CNTL'JOB NWN001 RUN WEEKDAYS NOTWITH NWN003ENDJOBJOB NWN002 RUN WEEKDAYSENDJOBJOB NWN003 RUN WEEKDAYSENDJOB

You can use unmatched NOTWITH statements in combination with the ENQSELF command. For more information, see “ENQSELF” on page 171.


174 ESP-5.4-UG-05

To remove mutual exclusivity:

• Remove the NOTWITH statements for all the jobs that are no longer mutually exclusive.

To exclude jobs from an NOTWITH statement at the Application level:

• Insert a DROPNOTW statement matching, character for character, the NOTWITH statement that created the mutual exclusivity.

You can insert the DROPNOTW statement in an Application, outside a job workload object. In that case the statement applies to every job following it in the Application.

Example

When you specify the NOTWITH statement outside the scope of a job, there can be one job in the Application that can run concurrently with the other jobs. You can use the DROPNOTW statement in the scope of the job that can run concurrently to allow it to run.

APPL NWN00EJCLLIB 'CYBER.JCL.CNTL'

JOB NWN001 RUN DAILY NOTWITH (NWN002,NWN003)ENDJOB

NOTWITH NWN001



JOB NWN004 RUN DAILY DROPNOTW NWN001ENDJOB


ESP-5.4-UG-05 175

Selecting jobs for submission

To select a job for submission:

Do one of the following:

• Specify the name of the job in a SELECT statement.• Specify a RUN statement for the job to identify its schedule frequency.• Name the job in a POSTREQ, PREREQ or COREQ statement.

You can choose to use different methods to select jobs as part of the same Application. This Guide contains more information on the schedule frequencies you can use.

Example: Method 1

The following example shows two ways of selecting jobs for submission.The first method uses a RUN statement for each job. ESP Workload Manager selects job A each time the Procedure is invoked; ESP Workload Manager selects job B if the scheduled day is Friday.

JOB A RUN DAILY RELEASE BENDJOBJOB B RUN FRIDAYENDJOB

Example: Method 2

This method uses SELECT statements after identifying specific job requirements. ESP Workload Manager selects job A each time the Procedure is invoked; ESP Workload Manager selects job B if the scheduled day is Friday.

JOB A RELEASE BENDJOBJOB BENDJOBSELECT AIF TODAY('FRIDAY') THEN SELECT B

Submit time

If a job has a time dependency for submission, you must use either an EARLYSUB or a DELAYSUB statement. The statement RUN 5PM DAILY is not valid.

Section–Selecting jobs for submission

176 ESP-5.4-UG-05

Using SELECT vs. RUN statements

Some users prefer to use RUN statements; other users prefer SELECT statements. The following are some reasons for choosing either method:

• RUN statements are used within the scope of a JOB statement. You can look at a job definition and see the schedule frequency for the job. Many criteria can be handled with RUN statements without the need for using IF TODAY type logic.

• SELECT statements allow you to easily see all the jobs with the same criteria. Changing the criteria for these jobs requires a change to a single SELECT statement. You can also select a subApplication.

To deselect jobs:

• Use the NORUN and DESELECT statements to handle exceptions to a job’s regular schedule criteria.

These statements tell ESP Workload Manager when not to select a job.

ESP Workload Manager allows multiple RUN and NORUN statements for the same job. You should normally code your NORUN statements after your RUN statements. If you specify a job with a NORUN statement and without a RUN statement, ESP Workload Manager schedules the job each time the Event executes except when it manages to satisfy the NORUN schedule criteria.

Example 1

In the following example, job X runs daily except on the first Monday of the month.

JOB X RUN DAILY NORUN FIRST MONDAY OF MONTHENDJOB

Example 2

This example uses a DESELECT statement to achieve the same results.

SELECT XIF TODAY('FIRST MONDAY OF MONTH') THEN DESELECT X

Inheriting job relationships

Jobs in an Application can not require the same run frequency. When ESP Workload Manager selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited.


ESP-5.4-UG-05 177

Example

Consider the following three jobs and their schedule frequencies.

On Fridays all three jobs execute in order, but on any other day of the week, job J2 does not run. On these days, ESP Workload Manager selects jobs J1 and J3 and inherits their relationships with job J2. When job J1 completes successfully, it releases job J3.


For information on overriding the inheritance of job relationships, see the ESP Workload Manager Advanced User’s Guide.

Using different job types

An Application can consist of different types of jobs. You can define the following job types in an Application by using different operands on a JOB statement or different job-like statements.

J2

J3

J1 Daily

Friday

Daily

Type Description Identification

Job JCL submitted by ESP Workload Manager (default).

Blank

External job JCL submitted by another Application. EXTERNAL operand

Manual job JCL submitted outside an ESP Application. MANUAL operand

Link Task that does not require manual completion.

LINK operand

Section–Defining external jobs

178 ESP-5.4-UG-05

The next few sections describe the job types other than job. You can also define distributed workload, such as UNIX scripts, in your ESP Application. For information on defining this type of workload, see the JOB statement in ESP Workload Manager Reference Guide.

Defining external jobs

To identify to ESP Workload Manager that the job is part of another Application:

Use the EXTERNAL operand as part of a JOB statement.

You can establish relationships between jobs in different Applications. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied.

The Application that submits the job is known as the home Application. The Application where the job is defined as external is known as the distant Application.

When you define an external job:

• You can use different frequencies in the home and distant Application.• You must use the same qualifier in each Application.• You can use the LAX command in Page mode to display external jobs in active

Applications.

Example: Inter-Application dependency

In this example, ESP Workload Manager submits job X on Fridays, as part of Application APPL1. Job Z in the Application APPL2 waits for job X. The home Application for job X is APPL1; the distant Application for job X is APPL2.

Task Task that requires manual completion. TASK operand

Data-set trigger object

Object that completes based on data set trigger activity.

DSTRIG statement

APPLEND Self completing task that runs automatically at the end of an Application.

APPLEND statement

Type Description Identification


ESP-5.4-UG-05 179

Visually, the dependencies look like this:

The Application definition for APPL1 looks like this:

APPL APPL1JCLLIB....JOB A RUN DAILY RELEASE XENDJOBJOB X RUN FRIDAYENDJOB

The Application definition for APPL2 looks like this:

APPL APPL2JCLLIB....JOB X EXTERNAL RUN FRIDAY RELEASE ZENDJOBJOB Z RUN DAILYENDJOB

When ESP Workload Manager generates APPL2 on Fridays, job Z waits until job X completes in its home Application, APPL1.

Controlling external jobs

Under different situations, ESP Workload Manager must decide whether or not it should mark an EXTERNAL job complete. The following are some general rules ESP Workload Manager uses:

• If more than one generation of an Application is active when an external job ends, ESP Workload Manager posts the job as complete in all active and waiting Applications by default. See the APPL statement in the ESP Workload Manager Reference Guide for overriding that default.

• A job defined as EXTERNAL in an Application is normally not marked complete by ESP Workload Manager if the job is run manually.

APPL1 APPL2

X(External job)

Z(job)

X(job)

A(job)

Section–Defining external jobs

180 ESP-5.4-UG-05

Some of the ways you can control how to post external jobs complete are described below.

Specifying an Application

When you define an external job, you can use the APPLID operand to specify the name of the Application that submits the job. ESP Workload Manager does not mark the external job complete unless it was submitted by the Application specified. For example, ESP Workload Manager only marks the following job as complete when the job is submitted from the Application called ANOTHER.

JOB ABC EXTERNAL APPLID(ANOTHER)

SCHEDULED operand

You can specify a SCHEDULED operand on a JOB statement to reflect when an external job is scheduled. The Application containing the external does not have to be active when the job in the home Application ends. ESP Workload Manager automatically looks back or waits to see if the dependency has been satisfied.

The job in the example below only gets marked complete when run from another Application with the same scheduled date. This provides synchronization of Applications. See the ESP Workload Manager Advanced User’s Guide for more information.

JOB ABC EXTERNAL SCHEDULED('TODAY')

The following example shows specifying a range:

JOB ABX EXTERNAL SCHEDULED ('NOW LESS 2 HOURS ENDING NOW PLUS 2 HOURS')

SCOPE operand

You can specify a SCOPE operand on a JOB statement to control how far back ESP Workload Manager searches the Job Index data set and to limit the forward search for a job in the SADGEN data set (as a result of a RESOLVE statement in an ESP Workload Manager Procedure). See the ESP Workload Manager Advanced User’s Guide for more information.

When you select an external job, the SCOPE operand instructs ESP Workload Manager to look back in the Job Index data for the required external job with a status of COMPLETED. ESP Workload Manager does not use a look forward time unless you use a RESOLVE statement. If the job is not found, ESP Workload Manager waits for the dependency to be satisfied.

In this example, ESP Workload Manager runs job ABC on Sundays and looks back 24 hours to Saturday for its successful completion.

job abc external scope(-24:00) run sundayENDJOB


ESP-5.4-UG-05 181

Job qualifiers

For ESP Workload Manager to mark an external job complete, the job qualifier must match what was defined in the home Application. You can use job qualifiers to ensure that an external job does not get marked complete when it is run manually. You can qualify external jobs with the home Application name. For example:

JOB ABC.BILLING EXTERNAL

Authorization string

You can specify that ESP Workload Manager checks an authorization string for external jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a user ID or an account field. For example, ESP Workload Manager only marks the following job as complete when the job is run with an authorization string of CYBER.

JOB ABC EXTERNAL AUTHSTR(CYBER)

Posting options

Different posting options are available on the APPL statement. For example, you can select different options to control the posting of external jobs when multiple generations of an Application are active. See the ESP Workload Manager Advanced User’s Guide for more information.

Forced complete

When an external job is forced complete in a distant Application, it has no effect on the status of the same job in any other distant Application, or in the job’s home Application.

When an external job is forced complete in its home Application, this change will be transmitted to every existent Application in which the job is defined as external.

USERMOD 30

Prior to release 5.1.0, if a job defined as EXTERNAL in an Application is forced complete in the home Application, the job in the remote Application (where it is EXTERNAL) is marked complete only if the job in the home Application has actually been submitted. With release 5.1.0, 5.2.0, 5.3.0, and 5.4.0 the remote Application job is now marked complete even if the home Application job was forced complete prior to submission. This USERMOD disables this new functionality for those users who rely on the previous behavior.

Section–Defining manual jobs

182 ESP-5.4-UG-05

Defining manual jobs

To identify to ESP Workload Manager that a job is submitted outside of an ESP Application:

• Use the MANUAL operand as part of a JOB statement.

As a result, ESP Workload Manager does not look for JCL, nor does it try to submit the job. The job can be submitted by a person, an operator command, an Event, or another scheduling product.

You can use manual jobs as predecessor or successor jobs within an Application. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied.

Note: When defining a MANUAL job in an Application, keep the following in mind:

• You must define a manual job as a tracked job if you want to use it in an Application. Check with your administrator to find out about tracked jobs.

• You cannot use a job qualifier for a manual job.

Example 1

In the example below, job ZZ runs after the manually submitted job YY on Mondays, Wednesdays, and Fridays. On other days job ZZ does not wait for job YY.

JCLLIB...APPL SMALLJOB ZZ AFTER YY RUN DAILYENDJOBJOB YY MANUAL RUN MON WED FRIENDJOB

Example 2

In this example, job B is a manual job that should not complete until job A runs successfully. After job A is submitted, ESP Workload Manager has no control over the submission time for job B, because job B is a manual job. However, ESP Workload Manager can remind someone to submit the job at the time it should be submitted.


ESP-5.4-UG-05 183

Visually, the flow of jobs looks like this:

The Application is shown below. The PROCESS operand on the manual job causes ESP Workload Manager to process the SEND command when job B is eligible for submission.

JCLLIB...APPL ABCJOB A RELEASE B RUN DAILYENDJOBJOB B MANUAL PROCESS SEND 'TIME TO SUBMIT JOB B' USER(SW) RUN DAILY RELEASE CENDJOBJOB C RUN DAILYENDJOB

Controlling manual jobs

Under different situations, ESP Workload Manager must decide whether or not it should mark a MANUAL job complete. The following are some general rules ESP Workload Manager uses:

• If more than one generation of an Application is active when an manual job ends, ESP Workload Manager posts the job as complete in all active and waiting Applications by default. See the APPL statement in the ESP Workload Manager Reference Guide for overriding that default.

• A job defined as MANUAL in an Application is normally not marked complete if the job is run as part of another Application.

Some of the ways you can control the posting complete of manual jobs are described below.

A

B

C

MANUALLYSUBMITTED

Section–Using links

184 ESP-5.4-UG-05

Authorization string

You can specify that ESP Workload Manager checks an authorization string for manual jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a user ID or an account field. For example, ESP Workload Manager only marks the following job as complete when the job is run with an authorization string of CYBER.

JOB ABC MANUAL AUTHSTR(CYBER)

Posting options

Different posting options are available on the APPL statement. For example, you can select different options to control the posting of manual jobs when multiple generations of an Application are active. See the ESP Workload Manager Advanced User’s Guide for more information.

Forced complete

When a manual job is forced complete in one Application, it has no effect on manual jobs in other Applications that just happen to refer to the same physical job instance.

If you want to modify the status of a specific manually submitted job in multiple Applications that define this job as manual, the modification will have to be performed explicitly in each of the dependent Applications.

Using links

A link is a task that does not require manual completion. Use a link when you need to take an action (for example, issuing a command or sending a message), but the Application does not need to wait for you to notify ESP Workload Manager that the action has been completed. A link can also be used as a dependency node to simplify complex dependencies.

LINK operand

The LINK operand on the JOB statement identifies a link. ESP Workload Manager does not try to submit JCL for it. You define relationships and other dependencies for a link the same way you do for a job that ESP Workload Manager would submit. A link usually has a schedule frequency, and it can have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application. If you want to use a link to process commands, you must specify LINK PROCESS, as shown in the next example.


ESP-5.4-UG-05 185

Example

In the following example, a link is used to send a message to user BP01 after MYJOB1 and MYJOB2 complete successfully.

JOB LETME.KNOW LINK PROCESS AFTER (MYJOB1,MYJOB2) RUN DAILY SEND 'MYJOBS ARE DONE' USER(BP01)ENDJOB

Link vs. task

A link is the same as a task, except that ESP Workload Manager automatically marks a link as complete as soon as its dependencies are met, while a task requires an action.

Note: A link cannot have a resource dependency. If this is a requirement, you need to use a self-completing task.

Example: Simplifying job relationships

You have an Application that contains two groups of three jobs. The second group of jobs cannot run until all jobs in the first group have completed.

To create this dependency configuration without using a link means that dependencies must be created from all three jobs in the first group to all three jobs in the second group. While ESP Workload Manager can create an Application that includes many inter-linked dependencies like this, the Application can be hard to read and maintain.

Visually, you need to define the dependencies like this:

Solution

A better approach is to create a link that represents the completion of the first three jobs, and releases the second group of three jobs. This simplifies the definition of job relationships and makes it easier to add or delete jobs in each group.

B CA

E FD

Section–Using links

186 ESP-5.4-UG-05


One way of coding LINKJOB is shown below:

JOB LINKJOB LINK RUN DAILY PREREQ (A,B,C) POSTREQ (D,E,F)ENDJOB

Uses for links

Common uses of links include:

• Issuing commands• Keeping an Application active• Notifying when something happens• Notifying when something does not happen

The following examples illustrate some typical uses of links.

Example: Issuing a command

This example uses a link to start some initiators.

JOB OPEN.INITS LINK PROCESS VS '$SI1-10' RUN DAILYENDJOB

Example: Keeping an Application active

This example uses a link called KEEPOPEN to keep an Application active until 23:59. This technique is useful when you need an Application active to insert on-request jobs.

JOB KEEPOPEN LINK DELAYSUB 23:59 RUN DAILYENDJOB

B CA

E FD

LINKJOB


ESP-5.4-UG-05 187

Example: Notifying when an Application completes

This example sends a message at the end of an Application. The message includes the following symbolic variables:

%ESPAPPL - Represents the name of the Application

%ESPATIME - Represents the actual time the Application completes

JOB ENDAPPL LINK PROCESS AFTER LASTJOB RUN DAILY SEND '%ESPAPPL HAS COMPLETED at %ESPATIME' USER(BP01)ENDJOB

For detailed information on symbolic variables, see the ESP Workload Manager Advanced User’s Guide.

Example: Starting a task, taking action after completion

You want ESP Workload Manager to monitor a manually started task, and run a job when the started task ends. This example shows how you can set up these dependencies.

Visually the dependencies look like this:

To set up this Application:

1. Use a link to start the started task.

2. Identify the started task as a Manual job (because the task is started by an operator command).

3. Run a job when the Manual job ends successfully.

START.STC1(Link)

STC1(Manual)

BATCHJOB(Job)

Section–Using tasks

188 ESP-5.4-UG-05

Application


APPL MYAPPLJCLLIB 'SYS1.JCL'JOB START.STC1 LINK PROCESS RUN DAILY VS 'S STC1'ENDJOBJOB STC1 MANUAL RUN DAILY RELEASE BATCHJOBENDJOBJOB BATCHJOB RUN DAILYENDJOB

Using tasks

You can define tasks in an Application and establish dependencies between them and other tasks and jobs. A task can represent a manual process such as balancing a report, or an automated process such as a step in a job completing.

You identify a task using the TASK operand on a JOB statement. ESP Workload Manager does not try and submit JCL for it. You define relationships and other dependencies for a task the same way you do for a job that ESP Workload Manager would submit. A task usually has a schedule frequency and can have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application.

When you mark a job as a TASK and select it for execution, ESP Workload Manager builds it as part of the Application. The AJ command, or the C command from CSF, can be used to mark a task complete.

Example: Checking a report

In this example, a report needs to be checked on workdays after job J1 completes successfully.


ESP-5.4-UG-05 189


Identifying CHECKRPT.J1 as a TASK

The following Application identifies CHECKRPT.J1 as a TASK. When J1 completes successfully on a workday, ESP Workload Manager issues the SEND command to user BP01, indicating the actions to be taken. ESP Workload Manager submits job J2 only when CHECKRPT.J1 is marked complete. On non-workdays, J2 inherits the relationship with J1, and ESP Workload Manager submits J2 after J1 completes successfully.

JCLLIB 'CYBB.JOBS.CNTL'APPL ABC WAITJOB J1 RUN DAILY RELEASE CHECKRPT.J1ENDJOBJOB CHECKRPT.J1 TASK RUN WORKDAYS SEND 'JOB J1 HAS COMPLETED SUCCESSFULLY ' USER(BP01) SEND 'COMPLETE THE CHECKRPT.J1 TASK' USER(BP01) RELEASE J2ENDJOBJOB J2 RUN DAILYENDJOB

Uses for tasks

You can choose to use tasks for:

• Balancing reports• Input tapes• Step-level dependencies• Any other special handling jobs

J1(Job)

CHECKRPT.J(Task)

J2(Job)

Section–Using APPLEND workload object

190 ESP-5.4-UG-05


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.


ESP-5.4-UG-05 191

Example

In the following example, the APPLEND workload object named FRED will be made a successor of JOB2, because JOB2 has no other successors. However, job AFTERAE2 and AFTRAELA, which also do not have successors, are successors to the APPLEND workload object, so are not also made predecessors to it.

APPL TESTAE1JCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 LINK RUN DAILY REL JOB2ENDJOB

JOB JOB2 LINK RUN DAILYENDJOB

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

JOB AFTERAE1 LINK RUN DAILY REL AFTRAELAENDJOB

JOB AFTERAE2 LINK RUN DAILYENDJOB

JOB AFTRAELA TASK RUN DAILYENDJOB

Additional considerations

There is an additional consideration when using the APPLEND workload object:

The APPLEND object does not generate any SMF by itself. If it has no successors, then the ESP1159I message will be the only external indication that an Application has ended.

Section–Changing job attributes

192 ESP-5.4-UG-05

To generate SMF, a S/390 job will need to be run as a successor to the APPLEND object. For example:

APPL EXAMPLEJCLLIB 'CYBER.JCL.CNTL'

JOB JOB1 RUN DAILYENDJOB

APPLEND TERMIN8 POSTREQ TERMIN8RENDJOB

JOB TERMIN8R MEMBER IEFBR14ENDJOB

Changing job attributes

In ESP Workload Manager, you can define a job with a number of different attributes using different operands on the JOB statement. Some examples of attributes are CRITICAL, HOLD, REQUEST, CONDITIONAL, LINK, and MANUAL.

A job can have different attributes based on different criteria. For example, you can define a job on hold but only for a particular date. This job has different attributes based on schedule criteria.

To define a job with different attributes:

• Use the JOBATTR statement.

This statement lets you change any attributes of a job within the scope of the JOB statement or in job documentation. Attributes include the operands you can use on the JOB statement.

Example: Changing a job attribute

In the following example, job ABC runs daily. On December 9, 2000, it needs to be defined on hold.

JOB ABC RUN DAILY IF TODAY('DEC9,2000') THEN JOBATTR HOLD ENDJOB


ESP-5.4-UG-05 193


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.


The next sections describe how to set up data-set-trigger objects. For more examples using these objects, and for other techniques on handling data set dependencies, see the ESP Workload Manager Advanced User’s Guide.

Preparing to use data set trigger objects

To use a data-set-trigger object, the Systems Programmer responsible for ESP Workload Manager must add a Workload Object Module (WOBDEF) statement to the ESP Workload Manager initialization parameters (for example, WOBDEF LOAD CYBESODT).

To set up a data-set-trigger object in an Application:

1. Use the DSTRIG statement to assign a name to the data-set-trigger workload object. You can use some of the same operands you use on a JOB statement. These include REQUEST, HOLD, and CONDITIONAL.

2. Use the DSNAME statement to identify the name of the data set. Quotation marks are optional. You can use a wildcard character hyphen (see “About this guide” on page 1), and you can use operands such as COUNT, ANYCLOSE,

Section–Using data-set-trigger workload objects

194 ESP-5.4-UG-05

JOBNAME, and RENAME to handle different requirements. Only one DSNAME statement is supported per workload object.

3. Use a RUN or SELECT statement to identify when you want this object to build as part of the Application.

4. Use other statements, such as DELAYSUB, DUEOUT, RELEASE to identify other requirements.

Example: Waiting for a data set creation

In this example:

• The DSTRIG statement identifies a data-set-trigger object called BIGFILE.• The DSNAME statement identifies PROD.CICS.FILE1602 as the data set.

Because no other operands are specified, ESP Workload Manager waits for this data set to be created.

• The frequency is DAILY.• The successor job is ABCJOB.

DSTRIG BIGFILE DSNAME PROD.FILE.CICS1602 RUN DAILY RELEASE ABCJOBENDJOB

Once the Application containing this object is active, ESP Workload Manager watches for the PROD.CICS.FILE1602 data set to be created. When it is created, the BIGFILE object completes and releases the successor job ABCJOB.

Visual perspective

Visually, the flow looks like this:

Waiting for any closure of a data set

You can use the ANYCLOSE operand to indicate any closure of a data set. This includes the creation of a new data set and the updating of an existing data set. If you do not specify ANYCLOSE, ESP Workload Manager waits for the data set to be created.

ABCJOB(Job)

PROD.CICS.FILE1602(data set)


ESP-5.4-UG-05 195

Example

The following example uses a data-set-trigger workload object (WAIT4.DS) to build a dependency between any closure of a data set (PROD.WEEKLY.ACCNTS) and a job (PAYJOB1).

APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG WAIT4.DS DSNAME PROD.WEEKLY.ACCNTS ANYCLOSE RUN DAILY RELEASE PAYJOB1ENDJOBJOB PAYJOB1 RUN DAILYENDJOB

Limiting data set activity to a job

You can restrict the trigger to only specific data sets created by a particular job. Use the JOB operand followed by the full name or job name prefix of the job.

Example: Job specific creation

The following example indicates a data-set-trigger occurs when job ABC creates a generation of the data set USER1.PAYROLL.

DSTRIG USERDATA DSNAME USER1.PAYROLL.G- JOB(ABCENDJOB

Waiting on multiple data sets

To set up a dependency on multiple data sets, you need to use a separate data-set-trigger object for each.

Section–Using data-set-trigger workload objects

196 ESP-5.4-UG-05

Example: Waiting on more than one data set

In this example, job XYZ waits for two data-set-trigger objects: FILEA and FILEB.

• FILEA completes when CYBER.DATA111.CNTL closes.• FILEB completes when CYBER.DATA999.CNTL closes.

APPL PAYROLLJCLLIB 'CYB.JCL.CNTL'DSTRIG FILEA DSNAME CYBER.DATA111.CNTL ANYCLOSE RUN DAILY RELEASE XYZENDJOBDSTRIG FILEB DSNAME CYBER.DATA999.CNTL ANYCLOSE RUN DAILY RELEASE XYZENDJOBJOB XYZ RUN DAILYENDJOB

Waiting on multiple closures of the same data set

It is possible for a data set to be closed several times. You can use the COUNT operand to specify how often this closure is required before the data-set-trigger object completes. The count begins when the data-set-trigger object becomes ready (for example, any time and predecessor dependencies have been met). The CSF STATUS field displays the counter and its current value once the data-set-trigger object becomes ready.

With each closure, ESP Workload Manager increases its internal counter by one. When the counter reaches the number you set in your COUNT operand, ESP Workload Manager completes the data-set-trigger object. The next time the Application gets generated, the count is set to zero.

Example: Waiting on multiple closures of a data set

In the following example, the data-set-trigger object completes after two creations of a data set:

DSTRIG DOUBLE.INPUT DSNAME SITE1.BILLING.FILE COUNT(2)ENDJOB

Limiting data set activity to a user

You can restrict the trigger to only specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the job task closing or renaming the data set


ESP-5.4-UG-05 197

Example: User specific creation

The following Event triggers when user CYBER1 creates a generation of the data set USER1.PAYROLL.

DSTRIG PROD.PAY_DATA DSNAME USER1.PAYROLL.G- USER(CYBER1) INVOKE 'PROD.ESP.PROCS(PAYJOBS)'ENDDEF

Controlling data-set-trigger objects

A data-set-trigger object must be ready before ESP Workload Manager looks for the activity specified on the DSNAME statement. A data-set-trigger object can have a predecessor or a time dependency or be defined on hold. Each of these conditions prevents the data-set-trigger object from completing. Once a data-set-trigger object becomes ready, the only action you can take against it is complete it.

Example: Data-set-trigger has a dependency

In the following example, the data-set-trigger object INPUT.DATA has a delayed submission time of 6 pm. If the CYBER.BILLING data set is created prior to this time, the data-set-trigger object does not complete. At 6 pm, ESP Workload Manager sends a message to BOB indicating it is waiting for some data.

DSTRIG INPUT.DATA DSNAME CYBER.BILLING RUN DAILY DELAYSUB 6PM SEND 'WAITING FOR INPUT DATA NOW' U(BOB) RELEASE BILLJOB1ENDJOB

Displaying data-set-triggering information

While DSTRIG workload objects are active, you can use the LDXE command to display them. The LDXE command differentiates between Event-level and Application-level data-set triggers.

The following is an example of the output produced by the LDXE command, where:

• Application PAYROLL.1 contains a job-level data-set trigger called WAIT4.DS. It is waiting for a data set closure on a data set called CYBER.PAYROLL.DATA1.

• Event CYBER.CYCLES is waiting for data set USER.INPUT.CYCLE to be created.

LDXEEVENT/APPL (WOB)-------DATASETPAYROLL.1 (WAIT4.DS) CYBER.PAYROLL.DATA1, ANYCLOSECYBER.CYCLES USER.INPUT.CYCLE2 ENTRIES DISPLAYED

Section–Using FTP data-set-trigger workload objects

198 ESP-5.4-UG-05

Using FTP data-set-trigger workload objects

FTP data-set-trigger workload objects are a particular kind of data set trigger workload object, where an Event can be triggered when a successful FTP file transfer or FTP rename completes.

When setting up an FTP data-set workload object, the file transfer causing the Event to be triggered can be closely defined by:

• Specifying the direction of the transfer• Limiting data-set activity to a host• Limiting data-set activity to a user ID• Limiting data set activity to a logon ID

Specifying the direction of the transfer

You can specify that the data file transfer direction is from the remote FTP partner to the local mainframe FTP partner or vice versa. Use the FTP operand followed by RECEIVE or RECV if the transfer is from the remote FTP partner to the local mainframe FTP partner. Use the FTP operand followed by SEND if the transfer is from the local mainframe FTP partner to the remote FTP partner.

Examples: FTP RECEIVE and SEND

The following Event triggers when a file is successfully received from a remote FTP partner, creating a generation of the data set USER1.PAYROLL.

DSTRIG PROD.PAY_DATA RUN DAILY DSNAME USER1.PAYROLL.G- FTP(RECEIVE) RELEASE PROD.ESP.PROCS(PAYJOBS)ENDJOB

The following Event triggers when the data set CYBER.XFER.001 is successfully sent from the local mainframe FTP partner to a remote FTP partner.

DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(SEND) RELEASE PURGE.XFER(001)ENDJOB

Limiting data-set activity to a host

You can restrict the trigger to FTP transfer from only a specific host. Use the HOST operand followed by the DNS host name or the IP address of the specified host.


ESP-5.4-UG-05 199

Example: Host specific creation

The following Event triggers when a remote FTP partner with the IP address 10.1.3.1 successfully transfers a file creating the data set CYBER.XFER.001.

DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) HOST(10.1.3.1) RELEASE PROCESS.XFER(001)ENDJOB

Limiting data-set activity to a user ID

You can restrict the trigger to specific data sets created or renamed by a particular user. Use the USER operand followed by the user ID of the user. The user ID refers to the host security user ID of the local FTP partner’s job task regardless of whether the local FTP partner is the client or the server.

Note: Because user ID always refers to a local mainframe host security user ID, lowercase characters are translated to uppercase.

Example: User-specific creation

The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the user ID prefix of the local FTP partner is CYB.

DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) USER(CYB-) RELEASE PROCESS.XFER(001)ENDJOB

Limiting data set activity to a logon ID

You can restrict the trigger to specific data sets created or renamed by a particular user. Use the LOGON operand followed by the logon ID of the user.

The logon ID refers to the user ID that the FTP client uses to logon to the FTP server.

If the FTP client is the remote partner, then logon ID is the user ID of the local FTP partner. In this case, specifying LOGON(logonid) has the same effect as specifying USER(userid).

If the FTP client is the local partner, then logon ID is the user ID of the remote FTP partner.

Note: When logon ID is a remote user ID, it can be case sensitive, as for example on UNIX hosts. Therefore, logon ID lowercase characters are not translated to uppercase.

Section–Using FTP data-set-trigger workload objects

200 ESP-5.4-UG-05

Example: Logon specific creation

The following Event triggers when a remote FTP partner successfully transfers a file creating the data set CYBER.XFER.001 assuming that the remote FTP partner did logon to the FTP server with the CYBER005 user ID.

DSTRIG CYBER.XFER RUN DAILY DSNAME CYBER.XFER.001 FTP(RECEIVE) LOGON(CYBER005) RELEASE PROCESS.XFER(001)ENDJOB

Notes on FTP trigger operands

dsname

The data set name specified in the DSNAME Application statement always refers to the local mainframe data set for both FTP(RECEIVE) and FTP(SEND).

ANYCLOSE

FTP triggers cannot to distinguish between data-set creation and data-set updates. Therefore, ANYCLOSE is assumed if not explicitly specified in an FTP trigger definition.

RENAME

When RENAME is specified for an FTP trigger, the trigger is activated on completion of an FTP rename command issued by the client to rename a data set to a specified data set name. Because data set name always refers to a local host data set, the remote FTP partner must be the client for an FTP trigger where RENAME is specified. Therefore the RENAME and FTP(SEND) operands are mutually exclusive.

Example

The following is an example of an FTP transfer-triggered Event. This Event sends a message to a user each time an FTP transfer to data set CYBER.DATA.SET completes from logged-on user aixuser on host AIXHOST to any local user with host security user ID prefix CYB. Because both the USER and the LOGON operands are specified and because they specify different user IDs, the FTP trigger criteria can only be satisfied if the local FTP partner is the client.

DSTRIG USER.APPL_RECEIVE RUN DAILY DSNAME CYBER.DATA.SET USER(CYB-) FTP(RECEIVE)- HOST(AIXHOST) LOGON(aixuser) SEND 'APPLICATION RECEIVED FROM CLIENT' USER(BP)ENDJOB


ESP-5.4-UG-05 201

Using explicit-data-set-trigger workload objects



• The explicit data-set trigger notification utility program (CYBESDT1).• The operand EXPLICIT in the DSNAME statement.

You invoke CYBESDT1 in a job, as an additional step, conditionally to the successful execution of the step manipulating a specified data set. This program writes an SMF record type 132 subtype 1.

An explicit data-set trigger is defined to ESP Workload Manager via the EXPLICIT operand in the DSNAME statement.

Explicit data-set trigger SMF record requirement

An installation must cut SMF type 132 subtype 1 SMF record for explicit data-set triggering to function.

Explicit data-set trigger notification utility program(CYBESDT1)

ESP Workload Manager receives notification of an explicit data-set trigger when CYBESDT1 is executed. CYBESDT1 must, at least, use the following input parameters:

• The dsname of the data set causing the activation of the data-set trigger (DSNAME)

• The volume serial number where the data set resides, if the data set is uncataloged

CYBESDT1 writes a user SMF type 132 subtype 1 record containing information required for the explicit data-set trigger.

The target ESP Workload Manager subsystem examines the SMF record, and if a matching explicit data-set trigger definition is found, satisfies the data-set trigger.

Program CYBESDT1 can execute in a batch, TSO, started task, or run task environment (for example, Connect:Direct (NDM)). It must also be APF-authorized or the attempt to write the explicit data-set-trigger SMF record fails with an ABEND047.

Program CYBESDT1 is reentrant.

Note: If you execute CYBESDT1 specifying a relative generation of a GDG in a job that creates new generations, the position of the CYBESDT1 step in the job determines the generation being selected. CYBESDT1 considers that the current generation (relative generation (0)) is the latest generation created when it executes.

Section–Using explicit-data-set-trigger workload objects

202 ESP-5.4-UG-05

CYBESDT1 input parameters

The input parameters of CYBESDT1 are specified in the JCL EXEC PARM for a batch job, and as operands when running as a TSO command.

The syntax is as follows:

DSNAME|DATASET(dsname[(member)|(relgen)]) {VOLSER|VOLUME(volser)} [SUBSYSTEM|SSID(subsystem)] [VERIFY|NOVERIFY]


DSNAME(dsname) or DATASET(dsname)

Specifies the data-set name.

member Specifies a member name of a PDS.

relgen Specifies the relative generation of a generation data group (GDG). For example you can code:• (0) for the current generation• (+1) for the next generation• (-1) for the previous generationYou must code relgen in CYBESDT1 and in the corresponding DSTRIG command or DSNAME statement exactly the same way, including leading zeros.

Note: Alternatively, you can include the absolute generation in dsname. For example:


VOLSER(volser) or VOLUME(volser)

Specifies the volume serial number that the data set resides on. It is required for uncataloged data sets and optional for cataloged data sets.

SUBSYSTEM(subsystem) or SSID(subsystem)

Is the ESP Workload Manager subsystem identifier keyword. This parameter is optional, if omitted, all tracking ESP Workload Manager subsystems will receive the explicit data-set trigger SMF record that program CYBESDT1 writes. A tracking ESP Workload Manager subsystem is one whose ESPPARM initialization file does not contain the following statement:SMFINT OFF

VERIFY Specifies that CYBESDT1 will set the explicit data-set trigger only if the following criteria are met:• The specified data set is catalogued if the VOLSER or

VOLUME parameter is omitted.• The specified data set resides on the specified volume.

(From the volser parameter if specified, from the catalog if not.)

• The owner of the job executing CYBESDT1 has update access to the data set specified.


ESP-5.4-UG-05 203

CYBESDT1 return codes

CYBESDT1 issues a zero return code if the explicit data-set trigger SMF record was successfully written, and a non-zero return code if any error condition occurs that causes the explicit data-set trigger SMF record not to be written.

%ESPTRGDG symbolic variable

The built-in symbolic variable, %ESPTRGDG, is generated when an event level explicit-data-set trigger is activated with a relative generation specified (relgen).

The value of %ESPTRGDG is set to the corresponding GDG base name. For example, if the data set activating the explicit data-set trigger is:


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


If the fully qualified data-set name cannot be determined, %ESPTRDSN is set to blanks. This can happen in the following two situations:

• The specified relative generation does not exist in the GDG index• NOVERIFY was specified as an operand of CYBESDT1

Examples

Invoking CYBESDT1 from page mode or line mode

To run CYBESDT1 from page or line mode, you must prefix the command with TSO because CYBESDT1 is external to ESP Workload Manager.

TSO command example:

TSO CYBESDT1 D(PDS.DATA.SET(MEMBER1))

TSO call example:

CALL 'CYBER.SSCPLINK(CYBESDT1)' 'D(PDS.DATA.SET(MEMBER1))'

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


Section–Using explicit-data-set-trigger workload objects

204 ESP-5.4-UG-05

Explicit data-set trigger notification batch example

In the following example, STEP1 creates or updates member MEMBER1 in the data set PDS.DATA.SET.

If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set PDS.DATA.SET(MEMBER1) has been created or updated.

//DSTRIG01 JOB ...//*//STEP1 EXEC PGM=IEBGENER//SYSPRINT DD SYSOUT=*//SYSIN DD DUMMY//SYSUT1 DD DISP=SHR,DSN=SEQ.DATA.SET//SYSUT2 DD DISP=OLD,DSN=PDS.DATA.SET(MEMBER1)//*//STEP2 EXEC PGM=CYBESDT1,COND=(0,LT),// PARM='DSNAME(PDS.DATA.SET(MEMBER1)) SUBSYSTEM(ESPS)'//STEPLIB DD DISP=SHR,DSN=CYBER.SSCPLINK

The following example triggers MYEVENT when the data set PDS.DATA.SET(MEMBER1) is created or updated:

EVENT ID(MYEVENT)DSTRIG PDS.DATA.SET(MEMBER1) EXPLICITENDDEF

Note: The data-set trigger, whether an Event or a workload object, must exist before you execute CYBESDT1.

Explicit data-set trigger notification Connect:Direct (NDM) run task example

In the following example, STEP1 copies the data set OLD.DATA.SET from Connect:Direct node NODE1 to the local Connect:Direct node as data set NEW.DATA.SET.

If STEP1 completes successfully, STEP2 notifies ESP Workload Manager subsystem ESPS through an explicit data-set trigger that data set NEW.DATA.SET has been created by the Connect:Direct copy operation.

PROCESS1 PROCESS SNODE=NODE1STEP1 COPY FROM(PNODE DSN=OLD.DATA.SET - TO(SNODE DSN=NEW.DATA.SET - DISP=(NEW,CATLG,DELETE)) IF (STEP1 EQ 0) THENSTEP2 RUN TASK (PGM=CYBESDT1 - PARM=(C'DSNAME(NEW.DATA.SET) SUBSYSTEM(ESPS)')) - SNODE EIF


ESP-5.4-UG-05 205

Tagging jobs

TAG statement

You can use the TAG statement to tag jobs in an Application with a character string up to 16 characters. The tag can apply to all jobs in an Application or to individual jobs depending on where you place it. You can use a tag to:

• Allow the filtering of jobs with a common characteristic using CSF• Pass information to JCL. The %ESPAPTAG symbolic variable contains the data

in the TAG statement.

Example: Tagging jobs with the scheduled day of week

The following example uses a symbolic variable to tag all jobs in an Application with the three-character day of the week:

TAG '%ESPSDAY(1:3)'APPL BILLING

Example: Tagging high priority jobs

This example tags PAYJOB as a high priority job:

JOB PAYJOB TAG 'HIGH_PRIORITY'ENDJOB

Example: Tagging jobs with Application name

This example uses the TAG statement to specify the name of the Application that submits the job. This is useful when you have an Application containing external jobs.

Construct the Application like this:

• Use a global TAG statement to identify the name of the Application.• Use a job-specific TAG statement for each external job to specify the name of the

Application submitting each external job.

Section–Providing notification on Job status

206 ESP-5.4-UG-05

Sample Application

A sample Application looks like this:

APPL PAYROLLJCLLIB . . .TAG 'PAYROLL'JOB A RUN DAILY RELEASE BENDJOBJOB B RUN DAILY RELEASE CENDJOBJOB C RUN DAILY AFTER XENDJOBJOB X EXTERNAL TAG 'BILLING' RUN DAILYENDJOB

Providing notification on Job status

You can use the NOTIFY statement within an Application to keep yourself or other users informed about the progress of jobs in an ESP Application. The NOTIFY statement can inform you when:

• A job is submitted.• A job starts.• A job becomes overdue from different processing points.• A job execution is faster than expected.• A job ends abnormally (ABENDs).• A job fails (for example, condition code failures).• A job ends (successfully or unsuccessfully).• ESP Workload Manager resubmits a job.

Using this statement, the only type of notification you can receive for external jobs, manual jobs, data-set-trigger objects, links, and tasks is overdue. This notification is based on the LATESUB and DUEOUT statements.

Notification list (MAILLIST)

You can direct notification messages to a notification list instead of specifying the user ID directly in the NOTIFY statement.


ESP-5.4-UG-05 207

The notification lists are included in the MAILLIST data set. The MAILLIST data set contains any number of MAILBOX initialization parameters, each of them containing any number of TSO user IDs and email addresses. You select where the NOTIFY statement sends messages by coding a mailbox name in the MAILBOX operand. Messages will be sent to all TSO user IDs and email addresses specified in the mailbox. See the “MAILLIST data set” section in the ESP Workload Manager Installation and Configuration Guide for information on how to set up the MAILLIST data set and the mailboxes.

Example: Using the notification list

In the following example, a notification that the job ending is overdue is directed to all TSO user IDs and email addresses contained in the CYBERBOX mailbox.

NOTIFY OVERDUE JOBEND MAILBOX(CYBERBOX)

Example: Notification on submit and abend

For example, suppose that you know that a programmer has modified the JCL for job D and you want to find out:

• When ESP Workload Manager submits the job• If the job ABENDs

In this example, the NOTIFY statement tells ESP Workload Manager to notify user USER01 when ESP Workload Manager submits job D and if job D ABENDs.

JOB D NOTIFY SUBMIT ABEND USERS(USER01) RELEASE E RUN DAILYENDJOB

Example: Overdue notification

This example notifies user USER02 when job LONGJOB becomes overdue. ESP Workload Manager sends a message to USER02 if LONGJOB does not complete execution successfully by 5 am.

JOB LONGJOB NOTIFY OVERDUE USER(USER02) DUEOUT EXEC 5AM RUN DAILYENDJOB


The NOTIFY statement can notify users and trigger an Event.

For information on triggering an Event, see Chapter 3, “Job Monitoring and Alert Processing”, in the ESP Workload Manager Advanced User’s Guide.

Section–Using critical-path analysis

208 ESP-5.4-UG-05

Using critical-path analysis

Critical-path analysis, combined with the ability to set time dependencies and trigger Events automatically, provides the framework for advanced due out notification when mission critical workload does not complete within the designated time frame or window.

ESP Workload Manager allows you to identify a job within an Application that represents a critical point of that Application. The longest path to that job, based on historical execution time, is a critical path.

Example of a critical path

In the following diagram, job Z is identified as the critical point in an Application. The longest path to job Z, based on historical execution time, represents the critical path. If all jobs are selected, the critical path consists of jobs A, B, X, Y, and Z.

ESP Workload Manager determines the critical path when it generates an Application. The critical path for an Application can vary depending on which jobs are selected. Based on the previous example, the critical path can vary as follows:

Jobs Not Selected Critical Path

X, Y A, B, C, D, Z

X, Z A, B, C, D

X, Y, D A, B, E, F, Z and A, B, C, Z

Z A, B, X, Y - defaults to longest path

A

Z

D

C

Y

X

F

E

B

15 Mins

15 Mins

15 Mins

30 Mins

CRITICAL

30 Mins

10 Mins

20 Mins

60 Mins

10 Mins


ESP-5.4-UG-05 209

Preparing to use critical path

Prior to using critical path, check with your administrator to ensure the critical-path feature is enabled. Through the CRITPATH ESP Workload Manager initialization parameter or command, an installation can disable critical path analysis for all Applications, enable critical-path analysis for selected Applications, or turn on critical-path analysis for all Applications.

To use the critical-path feature:

1. Turn on critical-path analysis for an Application.

2. Identify one or more critical jobs.

To turn on critical-path analysis for an Application:

• Use the CRITPATH ON statement as a global statement before your job definitions. For example:

APPL BILLINGJCLLIB 'CYBER.JCL'CRITPATH ONJOB A...

Critical-path analysis for all Applications

Some installations can turn on critical-path analysis for all Applications using an ESP Workload Manager initialization parameter or command. If critical-path analysis is on for all Applications:

• You do not need the CRITPATH ON statement to use critical-path analysis for an Application.

• You must use the CRITPATH OFF statement as a global statement, to turn off critical-path analysis for an Application.

To identify critical jobs:

• Use the CRITICAL operand on a job that represents a critical point in the Application, as follows:

JOB Z CRITICAL

If critical-path analysis is turned on for an Application, but no selected jobs are coded with the CRITICAL operand, ESP Workload Manager calculates the path to the job that will finish last and identifies that path as the critical path.

Section–Using critical-path analysis

210 ESP-5.4-UG-05

External jobs on critical path

Jobs defined as external jobs in an Application can be part of the critical path. However, if those external jobs have predecessors, the predecessors in the home Application are not defined as part of the critical path.

Multiple critical paths

An Application can have more than one critical path. In the following diagram, four jobs (represented by grayed boxes) are critical jobs. The longest paths to each of these jobs, based on historical execution time, are identified as critical paths.

Overriding elapsed times

There can be situations where you want to override historical elapsed times. For example, on the last day of the month, a job on the critical path can run longer than normal. Or there can be no historical information for a job on the critical path because this is the first run of the job. In these situations, you can override historical elapsed-time defaults using the DURATION statement to specify an estimated duration for the job.

The following example sets the elapsed-time estimate for job A to 120 (minutes) on the last day of the month:

JOB A RUN WORKDAYS IF TODAY('LAST DAY OF MONTH') THEN DURATION 120ENDJOB

A

L

PO

K

F

G IH

EB C D

V

TS

U

R

N Q

M

J


ESP-5.4-UG-05 211

Displaying the critical path

After ESP Workload Manager generates an Application, you can display the critical path using CSF freeform filtering or the List Application (LAP) command.

Using the consolidated status facility (CSF)

You can use the CSF freeform filtering feature to filter jobs in an Application that are on the critical path or not on the critical path.

The following freeform filter results in a display of all critical-path jobs in the PAYROLL Application.

CRITICAL_PATH AND APPL EQ 'PAYROLL'


For more information on freeform filtering, see “Consolidated Status Facility (CSF)” on page 221.

Using the list Application command

The LISTAPPL (LAP) command displays information about your Application. All jobs on the critical path are identified with a label of CRITICAL PATH. Any job in the Application coded with the CRITICAL operand is identified with a label of CRITICAL. You can limit your display to jobs on the critical path or jobs not on the critical path.

The following LAP command uses the CRITPATH operand to display only those jobs on the critical path for the current generation of the PAYROLL Application:

LAP PAYROLL.0 ALL CRITPATH

Issuing ESP Workload Manager commands

As part of an Application you can issue ESP Workload Manager commands. This is useful, for example, when you want to issue commands to manipulate jobs, trigger Events, and perform displays. Use the ESP or ESPNOMSG statement in an Application to issue an ESP Workload Manager command. ESPNOMSG suppresses responses from the command.

Section–Using subApplications

212 ESP-5.4-UG-05

Example: Triggering an Event

This example uses a link called MORE.WORK. It issues an ESP Workload Manager command to trigger an Event called CYB.OTHER in addition to its regular schedule. ESP Workload Manager suppresses the response (for example, EVENT TRIGGERED) from the trigger command.

JOB MORE.WORK LINK PROCESS RUN ANY ESPNOMSG TRIGGER CYB.OTHER ADDENDJOB

Example: Creating an Event, triggering an Event

This example issues a series of ESP Workload Manager commands to:

• Define a new Event called CYB.NEW_EVENT

• Trigger the new Event

JOB CREATE.EVENT LINK PROCESS RUN ANY ESP EVENT ID(CYB.NEW_EVENT) SYSTEM(ESPA) REPLACE ESP SEND 'THIS IS A NEW EVENT' USER(CYB01) ESP ENDDEF ESP TRIGGER CYB.NEW_EVENTENDJOB

Using subApplications

An Application can consist of one or more subApplications. This is useful, for example, when you have a large Application you would like to break up into smaller, easier to manage, groups of jobs. You can display, manipulate, and report on subApplications. You can control a group of jobs belonging to the same subApplication by using a single command. Use CSF or the LISTAPPL (LAP) and APPLJOB (AJ) commands to display and control subApplications respectively.

To identify a subApplication:

Use the SUBAPPL statement in an Application to identify a subApplication and choose a name different from any job name in the Application.

You can use the SUBAPPL statement within the scope of a JOB statement to associate a job with a subApplication, or outside the scope of a JOB statement to apply to multiple jobs. Use the WAIT operand if you have not used it on the APPL statement and you want a subApplication to wait on the previous generation of the subApplication.


ESP-5.4-UG-05 213

Example

The following example shows two subApplications defined within the Application called ACJOBS. The criteria are:

• Jobs in CYB1 and CYB2 belong to the subApplication called PREPJOBS.

• Jobs CYB3 and CYB4 belong to the subApplication called NIGHTLY.

• The PREPJOBS subApplication can process even if the previous PREPJOBS subApplication is not complete; the NIGHTLY subApplication must wait until the previous generation of the corresponding subApplication completes execution.

APPL ACJOBSSUBAPPL PREPJOBSJOB CYB1 RELEASE CYB3ENDJOBJOB CYB2 RELEASE CYB3ENDJOBSUBAPPL NIGHTLY WAITJOB CYB3 RELEASE CYB4ENDJOBJOB CYB4ENDJOBSELECT (CYB1,CYB2,CYB3,CYB4)

Selecting a subApplication

If your jobs within a subApplication have the same frequency, you can choose to use a SELECT statement to select all jobs within a subApplication. This eliminates the need to use a RUN statement for each job or a SELECT statement that specifies the name of each job.

To select a subApplication:

Use the SELECT statement to specify one or more subApplication names, followed by the operand SUBAPPL.

Section–Using subApplications

214 ESP-5.4-UG-05

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

APPL ACJOBSSUBAPPL PREPJOBSJOB CYB1 RELEASE CYB3ENDJOBJOB CYB2 RELEASE CYB3ENDJOBSUBAPPL NIGHTLY WAITJOB CYB3 RELEASE CYB4ENDJOBJOB CYB4ENDJOBSELECT (PREPJOBS,NIGHTLY) SUBAPPL

Similarly, you can use the DESELECT statement to deselect all jobs within a subApplication.

To display a subApplication:

Use the LS command from CSF or use the LISTAPPL (LAP) command with the SUBAPPL operand to display subApplications.

For example, the following results in a structured view of the subApplication PREPJOBS within the Application called ACJOBS.

LAP ACJOBS SUBAPPL(PREPJOBS) ALL

To control a subApplication:

Use either CSF or different operands command to control subApplications similar to the way in which you control jobs.

You can:

• Bypass a subApplication or cancel the bypass • Ready a subApplication• Request a subApplication or cancel the request• Hold or release a subApplication • Complete a subApplication • Remove a subApplication from wait status

Example: Requesting a subApplication

In the example below, ESP Workload Manager requests the subApplication called REQJOBS in the Application MYAPPL. The system requests each selected job marked as REQUEST in this subApplication. This eliminates the need to request each job individually.

AJ REQJOBS REQUEST APPL(MYAPPL.0)


ESP-5.4-UG-05 215

Note: Requesting a subApplication is not the same as selecting each job in the subApplication.

Working with Applications

Once ESP Workload Manager generates an Application, you can display and control jobs, subApplications, and the Application itself. You can perform any of these tasks using:

• Commands in page mode, a batch job, or an ESP Procedure • The Consolidated Status Facility (CSF) • ESP Workstation

This section describes some available common commands.


For more information on CSF, see “Consolidated Status Facility (CSF)” on page 221. For more information on ESP Workstation, see the ESP Workstation User’s Guide.

Displaying an Application

After ESP Workload Manager generates an Application, use the LISTAPPL command to display it. The short form of the command is LAP. Use the command with the ALL operand to give a structured view of an active Application or with other operands to give a summary of active or completed Applications. You can limit the display to specific generations of an Application and to specific jobs within an Application.

Section–Controlling an Application

216 ESP-5.4-UG-05

Sample output

Sample output from an LAP command looks like this:

LAP PAYROLL.23 ALLAPPL PAYROLL GEN 23 CREATED AT 09.54 ON MONDAY MAY 14TH, 2001 BY EVENT CYBBP01.PAY PAYD001A J6281, COMPLETED, CC 0 AT 10.01 ON MONDAY MAY 14TH, 2001 PAYD002A J6282, COMPLETED, CC 8 AT 10.04 ON MONDAY MAY 14TH, 2001 PAYD003A J6283, STARTED, STEP 3 PAYD004A, HC=1 SUBMISSION AT 10.15 ON MONDAY MAY 14TH, 2001 ANTICIPATED END TIME: 10.20 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD003A SUCCESSORS: PAYD100A

PAYD100A, HC=1 ANTICIPATED END TIME: 10.29 ON MONDAY MAY 14TH, 2001 DUE OUT BY 10.30 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD004A SUCCESSORS: PAYD006A

ABCJOB, HC=0 ANTICIPATED END TIME: 10.59 ON MONDAY MAY 14TH, 2001 EXTERNAL PREDECESSORS: NONE SUCCESSORS: PAYD006A

PAYD006A, HC=2 ANTICIPATED END TIME: 11.12 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD100A, ABCJOB SUCCESSORS: ENDAPPL RESOURCES: 1,CICSUP

ENDAPPL, HC=1 ANTICIPATED END TIME: 11.29 ON MONDAY MAY 14TH, 2001 PREDECESSORS: PAYD006A SUCCESSORS: (NONE)

----- 1 ENTRY DISPLAYED

Other options are available on the LISTAPPL command. For example, you can display particular jobs, a previous generation of an Application, or a subApplication.

Controlling an Application

APPLJOB command

The APPLJOB command controls jobs, subApplications, and Applications. The short form of this command name is AJ.


ESP-5.4-UG-05 217

Options on APPLJOB command

Many different options are available on this command. Some of these options allow you to:

• Insert a job• Add or reset dependencies for a job• Drop dependencies for a job• Bypass a job• Complete a job, subApplication, or Application• Request a job.

Examples

Here are some examples of using the APPLJOB command with the current generation (.0) of an Application called PAYROLL.

Example: Requesting a job

This example requests MYJOB.

AJ MYJOB REQUEST APPL(PAYROLL.0)

Example: Bypassing a job

This example bypasses PAYJOB3. ESP Workload Manager bypasses the job at the time it would normally submit it.

AJ PAYJOB3 BYPASS APPL(PAYROLL.0)

Example: Inserting a link to add a job relationship

This example inserts a link called LINKME. It has a predecessor of PAYJOB1 and a successor of PAYJOB2, which means that PAYJOB1 must complete successfully prior to submitting PAYJOB2.

AJ LINKME INSERT PRED(PAYJOB1) SUCC(PAYJOB2) -ATTRIBUTES(LINK) APPL(PAYROLL.0)

Example: Completing an Application

This example completes the entire Application.

AJ ALL COMPLETE APPL(PAYROLL.0)

You will likely use the Consolidated Status Facility to perform many of these tasks. For more information on controlling jobs, subApplications, and Applications, see “Consolidated Status Facility (CSF)” on page 221.

Section–Changing an Application definition

218 ESP-5.4-UG-05

Changing an Application definition

ESP Workload Manager does not submit a job to JES until all of its dependencies have been met. You can make changes to the ESP Procedure where the Application definition resides while the Application is processing. Some changes you make take effect immediately (next job submission); others do not take effect until the next time the Application is created.

Important: If you cache a Procedure and then you update it, use the CPROC command to delete the cached version so the new version is read automatically by an active Application. For details, see “Caching an ESP Workload Manager Procedure” on page 135.

Changes that take effect immediately

You can make changes to any of the following commands and statements listed below. Global changes, outside the scope of any JOB statements, apply to all subsequent submissions. Job specific changes, within the scope of a JOB statement, apply to the next submission of that job.

CCCHK, CCFAIL, COPYJCL, DATASET, DOCLIB, DOCMEM, ESP, INVOKE, JCLLIB, MEMBER, MODEL, MONITOR, NOTIFY, PNODES, SEND, SUBMIT, TEMPLIB, VS commands and statements.

Statements related to distributed workload, for example, ARGS, CMDNAME, ENVAR, or USER, take effect immediately.

Changes that do not take effect until next generation

You can drop dependencies and change time dependencies for an active Application through CSF. However, any of the changes listed below to the coded Application definition do not take effect until the next generation.

• Job relationships: AFTER, COREQ, DEQUEUE, DROPNOTW, ENQUEUE, NOTWITH, POSTREQ, PREREQ, RELEASE

• Time dependencies: ABANDON DEPENDENCIES, ABANDON RESOURCES, ABANDON SUBMISSION, DELAYSUB/EARLYSUB, DUEOUT, LATESUB, RELCOUNT, RELDELAY

• Schedule criteria: for example, RUN/NORUN, SELECT/DESELECT statements

• APPL, CRITPATH, DURATION, JOBATTR, RESOURCE, SUBAPPL, TAG

• JOB statement operands: for example, CONDITIONAL, CRITICAL, EXTERNAL, LINK, MANUAL, REQUEST, TASK


ESP-5.4-UG-05 219

If you need to make temporary, one-time changes, such as inserting or bypassing a job, use the Consolidated Status Facility or the AJ command.

Invoking an ESP Application

To invoke an ESP Application via an ESP Event:

• Use an ESP Event to invoke an ESP Application.

The trigger for the Event can be:

• A scheduled date and time• A data-set trigger• A job-monitor trigger• A signal with a scheduled date and time• A manual trigger

An Event can invoke more than one ESP Procedure, but it can only process one Application per Event.

Normally, you should not change an Event to invoke another Application while it is still processing an active Application.

Example: An Event invokes an ESP Procedure to create an Application

The following example demonstrates how to use an Event to invoke an ESP Application.

The Event below runs each weekday at 4 pm. It invokes an ESP Procedure that defines the Application and job relationships. The Event looks like this:

EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE 'CYBER.ESP.PROC(PAYDAILY)'ENDDEF

Section–Invoking an ESP Application

220 ESP-5.4-UG-05

ESP-5.4-UG-05 221

Consolidated Status Facility (CSF)

The Consolidated Status Facility provides a focal point for monitoring and controlling the workload. You will see which jobs have recently executed, are currently running, and are scheduled to execute. You can zoom in on any job to get greater detail, edit JCL, and restart jobs.

Note: You can use CSF for jobs in an Application, but not for jobs submitted directly from an Event.


• Setting up CSF views• CSF fields• Defining a view• Customizing a view• Updating a view• Deleting a view• Selecting views• Commands• Inserting a job• Resubmitting a job• Rerunning multiple jobs• Removing job dependencies• Resetting a time dependency• Bypassing and completing jobs• Adding job dependencies

Section–Setting up CSF views

222 ESP-5.4-UG-05

• Adding a job with a time dependency• Adding a job relationship in an Application• Adding a LINK process• Setting and resetting the user status field• Modifying a Job Resources or Enqueues• Using other commands• Extensions to CSF• Freeform filtering

Setting up CSF views

ESP Workload Manager can handle a large workload at your installation. Different people are interested in different aspects of this workload. One person can be interested in a particular Application, whereas someone else can only be interested in jobs that have failed regardless of the Application to which they belong.

Displaying data

Using the Consolidated Status Facility, you can display only relevant data in the format you want by using views. A view is a customized way of looking at ESP Workload Manager workload. Think of CSF as a kind of scoreboard where:

• Each row represents a workload object, such as a job, link, or task.• Each column represents an attribute of a workload object, such as job number and

status.

Example

For example, one row can represent a job. Each column represents some attribute of the job, such as the job name, Application generation number, Pnode (processing node), job number, and status. An example of what the CSF looks like is shown below. Here the CSF presents the current status of an Application:

Chapter 7–Consolidated Status Facility (CSF)

ESP-5.4-UG-05 223

CSF fields

This section describes some special fields that CSF uses.

Pnode fields

A job in an Application goes through different stages in processing. These stages are known as Pnodes. Using CSF you can filter and sort your view by Pnode and display Pnode information.

The following table describes the Pnode fields:

Note: The term Pnode is also used to describe the phases through which ESP Workload Manager tracks a job. The Pnodes described here apply only to jobs in an ESP Application and do not include post-execution phases.

Pnode Description

APPLHOLD Application hold.

APPLWAIT Application waiting on previous generation.

BYPASSED Bypassed.

COMPLETE Completed successfully.

EXEC Executing.

EXTERNAL External job submitted by another Application.

FAIL Completed unsuccessfully.

INPUT Input queue - JES number assigned.

JANCWAIT Job ancestor wait.

MANHOLD Manual hold.

MANSUB Manual submission.

PREDWAIT Predecessor wait.

READY Eligible.

RESWAIT Resource wait.

SANCWAIT SubApplication ancestor wait.

SUBDELAY Submission delayed.

SUBERROR Submission error.

SYSERROR System error.

TASK Task requiring completion.

WAITING Delayed submission time.

Section–CSF fields

224 ESP-5.4-UG-05

SUBDELAY Pnode

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

SUBERROR Pnode

This table provides more information on what you see in the Status field if a job is in the SUBERROR Pnode.

Pnode Status Description

SUBDELAY Submit delayed by REEXEC n

The submission of the job has been delayed.

SUBDELAY Submit delayed, eventset closed

The eventset in which the Event is stored is currently closed. As soon as it is opened, the Event will be scheduled.

SUBDELAY Submit delayed, DS contention

The execution of the Event was delayed because data-set contention. It will be retried at five minute intervals.

SUBDELAY Submit delayed, DS offline The execution of the Event was delayed because a data set is offline. It will be retried at five minute intervals.

SUBDELAY Submit delayed, DS recalled The execution of the Event was delayed because a data set was in a migrated state. A recall has been requested, and the Event will be retried at five minute intervals.

Pnode Status DescriptionSUBERROR Submit eventset I/O error An I/O error has occurred in the

eventset. The Event cannot be processed.

SUBERROR Submit error, Event not found The Event needed by the Application has been deleted. It will need to be redefined.

SUBERROR Submit error, group not defined

The ESP Workload Manager Group definition for the Event has been deleted. It will need to be redefined.

SUBERROR Submit error, applfile not found

The APPLFILE in which the APPL resides could not be found.

SUBERROR Submit error, applfile I/O An I/O error occurred while reading the ATR (Application Tracking Record) from the APPLFILE.


ESP-5.4-UG-05 225

Status fields

You can display the following status fields on CSF:

Setting the User Status field

You can set the user status field when you use either of the following:

• HR command—holds a job with a reason.• SUS command—resets user status for a job.

For example, if you bypass a job you can use the user status field to notify others of the reason for this action. The user status field for a job looks like this:

JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY

ESP Workload Manager does not reset the User Status field.

SUBERROR Submit failed, Event error An error occurred processing the Event. Usually due to a syntax error in the ESP Procedure. An error message has been sent to the Event’s owner. This can also occur when the master ESP Workload Manager ends while trying to submit a job.

SUBERROR Submit error, invalid job name ESP Workload Manager encountered an invalid job name

SUBERROR Submit error, JCL missing The JCL for the job to be submitted was not found in the specified data set, or a data set was not specified for the job.

SUBERROR Submit error, member missing The PDS member in which a JOB’s JCL resides was not found.

SUBERROR Re-execution count exhausted The maximum re-execution count has been reached

SUBERROR Submit error, quit QUIT statement encountered

Pnode Status Description

Status Field Description

User status Displays information set by the user.

System status Displays the system state of a workload object. This is the system state that ESP Workload Manager continues to change during job processing. You cannot change the values in this field.

Status Displays the user status, if set. If the user status is set to null, it displays the system status.

Section–Defining a view

226 ESP-5.4-UG-05

To reset the User Status field to null:

• Issue the SUS command, and enter a period (.) in the field.

Defining a view

The process of defining a view involves replicating an existing view and customizing the new view to your requirements.

To define a view:

1. Select option C from the ESP Workload Manager Main Menu to access CSF.

2. Type V at the Command Line. ESP Workload Manager takes you to the View Definitions panel, which lists any existing views, as shown below.

3. Enter R to the left of a view name to copy an existing view under a new name. ESP Workload Manager takes you to the Replicate View panel.

4. Type the name, an applicable description, and the message you want displayed when there are no items matching the view criteria. The view you selected appears, showing all the jobs that fall within that view definition.

5. Customize the view as described in the next section.

Storing views

ESP Workload Manager stores your view definitions in the ESPCSFA member of your ISPF profile data set. This allows you to use the same view on different systems.


ESP-5.4-UG-05 227

Customizing a view

Once you select a view, you can customize the information presented. Some examples of types of views are:

• Application specific.

• Exception monitoring. For example, you can define a view called TROUBLE to display workload objects requiring intervention.

• Incomplete jobs.

• Overdue jobs.

Commands

You can enter the following commands on the COMMAND line to define the characteristics of a view:

The following sections describe each of these areas.

Filtering information

When you filter information, you are describing the criteria for displaying a job as part of a view. For example, you can filter by Application name to select only those jobs in a particular Application. This information defines the rows in your display.

To filter information:

• Type FI on the CSF Command Line.

This takes you to the Filter Specification panel where you can specify characteristics of the jobs ESP Workload Manager filters into the display. You can filter based on different conditions (for example failed jobs) and based on other criteria such as job name, Application name, and tag.

Command Characteristic

FI Filter information.PR Presentation information.PT Presentation titles.PL Presentation column length.SO Sort the information presented.CO Define color options based on job status.

You can use colors to distinguish workload states.

Section–Customizing a view

228 ESP-5.4-UG-05

Logic applied to multiple conditions

When you select two or more conditions, the resulting selection is controlled based on a logic dependent of:

• The position of the condition. for example, in the same column.• The kind of testing: positive or negative.

The following logic rules apply:

• When the conditions are in the same column:

• With positive testing (Y), ESP Workload Manager uses OR logic• With any negative testing (N), ESP Workload Manager uses AND logic

• When the condition are in different columns, ESP Workload Manager uses AND logic

Examples

To see all incomplete jobs:

• Type N in the Completed field.

To see all incomplete jobs in Application Payroll:

• Type N in the Completed field and PAYROLL in the Appl field.

ESP Consolidated Status: Filter Specification for View,REP COMMAND ===> Enter conditions in this section (N, blank or Y).

Failed ===> Manual ===> Intervention ===> Overdue ===> Links ===> On-request ===> Completed ===> Tasks ===> Requested ===> Res wait ===> External ===> Bypassed ===>

Enter filter criteria in this section, wildcards allowed.

Jobname ===> ===> ===> ===> ===> ===> ===> ===> P-Node ===> ===> ===> ===> Appl ===> ===> ===> ===> Subappl ===> ===> ===> ===> Account ===> ===> ===> ===> Tag ===> ===>

Active after ===> Scheduled before ===> Freeform filter ===> (blank, N or Y)

Column 3Column 2Column 1


ESP-5.4-UG-05 229

To see all jobs that are incomplete AND not failed:

1. Type N in the Completed field.

2. Type N in the Failed field.

To see all jobs that are complete OR failed:

1. Type Y in the Completed field.

2. Type Y in the Failed field.

Note: Extensive help facilities are available with pop-up menus and hypertext links. Use your HELP key for additional information.

Freeform filtering

Freeform filtering is an extension to the CSF filtering capabilities that allows you a more versatile and customizable method of filtering your ESP Applications. If you cannot use the standard filter panel for your requirements, see “Freeform filtering” on page 247 for information on using this feature.

Presenting information

Once you have filtered the information you want, you can specify the attributes of the filtered jobs you want presented. For example, you can see the job number, Pnode (processing node), and status information for each job. This information defines the columns in your display.

Note: Option O.5 (Set CSF Options) allows you to set different options for CSF. This determines the types of entries displayed when you enter any Presentation command from CSF.

To present information:

1. Type PR on the CSF Command Line. The Presentation Fields panel appears.

2. On this panel, indicate the fields you want displayed by entering a number or letter beside each desired field. The numbers and letters also represent the order you want them to appear across the screen. You can alter the presentation order easily by using numeric and alphabetic characters.

Example

The following example positions the Appl Generation column between the Application and Completion Code columns.

Appl Generation 2AApplication 2Completion Code 3

Section–Customizing a view

230 ESP-5.4-UG-05

Note: ESP Workload Manager always lists the job name in the first column; you cannot change this.

To further define the presentation information, you can change the presentation column lengths and titles.

Presentation titles

The PT command takes you to the Presentation Fields panel. On this panel, you can define the titles that ESP Workload Manager presents for each of the fields listed. This is useful for long titles you want to abbreviate. For example, you can shorten the field title Account number. You can type an abbreviation such as ACCT in the area to the right of the field name Account number. Or you could change the TAG title to reflect how you are using tags in an Application.

Presentation column length

The PL command takes you to the Presentation Fields panel. On this panel ESP Workload Manager lists all the columns used in the CSF view. You can override the default display length of these columns by entering the number of characters you want in the display.

Sorting information

Sorting information defines the order in which ESP Workload Manager presents the rows of information.

To define your sorting requirements:

• Type SO on the CSF Command Line.

The Presentation Fields panel lets you identify the fields by which you want to sort your view, and the order in which you want ESP Workload Manager to sort them. You can select one or more fields to sort on by typing a one or two character string next to the field. The strings are sorted in normal collating sequence (for example, blank before letters before numbers) to determine the sort order of the displayed data.

Note: If a field contains multiple words (for example, STATUS field), the sort occurs only on the first word.

Sort sequence

A Sort sequence field allows you to specify an ascending or descending sort sequence for a field. Type A, or leave the field blank, for ascending order; Type D for descending order.


ESP-5.4-UG-05 231

The following logic rules apply:

• When the conditions are in the same column:

• With positive testing (Y), ESP Workload Manager uses OR logic• With any negative testing (N), ESP Workload Manager uses AND logic

• When the condition are in different columns, ESP Workload Manager uses AND logic

Color options

Color screens allow you to use different colors and highlighting options to indicate job status. You can choose different colored and highlighted options to represent different job status conditions, including:

• Submitted• Overdue• Task awaiting post• Executing• Failed

To select color options:

1. Type CO on the COMMAND line.

2. Complete the fields as required.

Updating a view

You can update a view at any time by selecting the different options for customization, such as FI, PR, and SO.

To update a view:

1. Enter U to the left of the view name you want to update.

2. Type the name, an applicable description, and the message you want displayed when there are no items matching your view criteria in the respective fields.

3. Press Enter. ESP Workload Manager returns you to the View Definitions panel.

Section–Deleting a view

232 ESP-5.4-UG-05

Deleting a view

You can delete an existing view at any time.

To delete an existing view:

1. Enter D to the left of the view name you want to delete.

2. Press Enter. ESP Workload Manager removes the view from the View Definitions panel.

Selecting views

There are two methods for selecting a view.

To delete a view, if you do not know the name of the view you want to select:

1. Type V on the COMMAND line of the Consolidated Status View pane. ESP Workload Manager presents you with a list of views.

2. From the list of views, type S beside the view you wish to select.

To delete a view if you know the name of the view you want to select:

• Type V viewname on the COMMAND line.

Commands

When ESP Workload Manager displays a view, it precedes each job name with an entry field. The codes below represent commands that are valid in CSF. To use one of these commands, type the letter code in the entry field preceding the job name you want to manipulate. ESP Workload Manager issues the appropriate command (for example, LISTAPPL, APPLJOB) in the background.

The next sections list the available commands in different categories.


ESP-5.4-UG-05 233

Working with Applications

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

Working with subApplications

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

Working with jobs

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

Command Description

AA Releases an Application held by ESP Workload Manager.

CA Completes all workload objects in an Application.

Note: If the Application is not held or waiting, the Application is now complete. Otherwise, the Application is still active.

HA Places Application into ESP Workload Manager hold status.

LA Lists Application.

LAD Dumps Application data.

UWA Removes Application from wait status.

Command Description

AS Releases a subApplication held by ESP Workload Manager.

BYS Bypasses a subApplication.

CS Completes an entire subApplication.

HS Places subApplication into ESP Workload Manager hold status.

LS Lists subApplication.

RDS Readies a subApplication.

RQS Requests a subApplication.

UBS Cancels the bypass of a subApplication.

URS Cancel the requests of a subApplication.

UWS Removes subApplication from wait status.

Command Description

A Releases a job.

$A Issues a JES release command on a z/OS job.

BC Browses COPYJCL.

BJ Browses the last executed JCL.

BY Bypasses a job.

C Completes a job.

$C Cancels a z/OS job in JES.

Section–Commands

234 ESP-5.4-UG-05

$CD Cancels a z/OS job with a dump in JES.

$CP Cancels and purges a z/OS job in JES.

$D Displays the JES status of a job.

DD Drops all predecessor dependencies.

DIN Displays an info record.

DR Drops all resource dependencies.

EC Edits COPYJCL.

EJ Edits the last executed JCL.

H Places a job into ESP hold status.

$H Issues a JES HOLD command on a z/OS job.

HR Places a job into ESP hold status with a reason.

IJ Inserts a job.

IJA Inserts a job after a selected job.

IJB Inserts a job before a selected job.

IW Inserts additional workload definitions into an active Application.

L Displays all dependencies.

L, then D Drops individual dependencies.

LI Displays index entries.

LJ Displays step-level statistics.

LJE Lists detailed information about the specified job.

LR Displays the job resources.

ME Modifies enqueues.

MR Modifies resources.

P Issues a system STOP command on an executing z/OS job, if it is programmed to do so.

QS Quiesces a z/OS job executing on a goal mode system. Requires ESP Workload Manager High Performance Option (HPO).

R Resubmits or restarts a job.

RD Readies a job, removing all predecessors, and submits time dependencies.

RM Reruns multiple jobs.

RP Replies to an AS/400 message.

RQ Requests a job.

RR Views the ESP Encore panels.

Note: Use RX if you want to exclude specifics steps from the range of steps you want to rerun.

RS Resumes the original service class of a z/OS job executing on a goal mode system. Requires ESP Workload Manager High Performance Option (HPO).

Command Description


ESP-5.4-UG-05 235

Working with other ESP Workload Manager definitions

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

Inserting a job

Using CSF, you can insert different job types into an active Application. The inserted job runs immediately unless you define a predecessor or insert the job on hold.

You can use two options to insert a job in CSF: IW or IJ.

RT Resets one or more time dependencies.

RX Views the ESP Encore panels

SUS Resets the user status field for a job.

UB Un-bypasses a bypassed job.

UIN Updates an info record.

UR Un-requests a requested job.

UW Un-waits a job from job-ancestor wait (JANCWAIT).

W Selects distributed job options.

WC Cancels a PeopleSoft job.

WSF Retrieve a distributed job spool file.

XP Manually expedites a job with an associated expedite policy, waiting for execution or executing. Requires ESP Workload Manager High Performance Option (HPO).

Command Description

Command Description

BD Browses job documentation.

BE Browses Event.

BP Browses ESP Procedure.

ED Edits job documentation.

EE Edits Event.

EP Edits ESP Procedure.

Section–Inserting a job

236 ESP-5.4-UG-05

IW option

Use IW for inserting:

• Jobs requiring different ESP Encore options• Jobs requiring resources• Distributed jobs with Agent-related statements• Multiple workload objects

This option takes you to the ISPF edit mode where you type the job definitions in the same free-format text used to define workload in an ESP Procedure.

Note: You must specify AFTER and RELEASE statements to define predecessor or successor relationship with other jobs in the Application. If you do not specify AFTER and RELEASE statements, the inserted jobs run immediately.

Example

To add job NEWJOB to an Application with a predecessor of job PAYD006A and a successor of job PAYD008A:

1. Type IW beside any job in the Application; you are taken to the ISPF edit mode.

2. Enter the following:

N_JOB NEWJOB AGENT HPBOX#11 SCRIPTNAME W:\PROD\SCRIPTS\NEWJOB.BAT AFTER PAYD006A RELEASE PAYD008AENDJOB

3. Exit the edit panel (PF3). ESP Workload Manager simulates the job you have inserted.

4. Exit the panel (PF3). A confirmation screen appears. You can proceed with the insertion, edit it, or cancel it. Type 1 to proceed and press Enter.

Your job, NEWJOB, should now appear as part of your CSF display.

IJ option

Use IJ for single jobs with basic requirements. This option present an ISPF panel where the user fills the appropriate fields

Example

To add job NEWJOB to an Application with a predecessor of job PAYD006A and a successor of job PAYD008A:

1. Type IJ beside any job in the Application.

2. Type NEWJOB as the object name on the Insert an Object panel.


ESP-5.4-UG-05 237

3. Type Y for predecessors, Y for successors, and press Enter.

4. Enter PAYD006A as the predecessor job name, and press Enter.

5. Enter PAYD008A as the successor job name, and press Enter.

Your job, NEWJOB, should now appear as part of your CSF display.

Resubmitting a job

Using CSF, you can resubmit a job that has terminated abnormally.

The following rules apply when you resubmit a job from the CSF panel shown below:

• If an override member name is specified (in the Member field), but no override JCL library name is specified (in the Dsname field), then the specified member name is used together with the original JCL library.

• If the JCL library name is specified but the member name is blank, then the specified JCL library is used with the original member name.

• If both fields are blank, the original library name and original member name are used.

• If both fields are filled in, then the specified library name and specified member name are used.

• On a resubmit, the original JCL library is forced into use, even if the same member has been placed in TEMPLIB. However, if an override of the data set is entered on the resubmit panel, this override is explicitly used.

Note: If the job is an INSERTED job, and a JCL Library is supplied on the resubmit, the supplied JCL library will be used and continue to be used on future resubmits. If an asterisk is placed in the JCL library name field, the previously supplied JCL library name will no longer be used for the current and future resubmits.

Section–Rerunning multiple jobs

238 ESP-5.4-UG-05

Note: Once an override library name has been specified on this panel, the Dsname field displays the latest override library name used for the remainder of the CSF session. Once you exit from CSF, this default value is lost.

Rerunning multiple jobs

You can rerun multiple jobs using the RERUNM (RM) command. The command resets specified jobs to the state before they ran. Application Manager schedules a rerun for them as their dependencies are satisfied. By default, the command requests a rerun of the root job and all of its successors. In the resulting CSF screen, you can modify the list of jobs run. You can also request an ESP Encore restart, and enter USER variables and ESP Encore commands.

To rerun multiple jobs from CSF:

1. In CSF, type RM next to the root job of the group of jobs you want to rerun.

2. Press Enter. The Rerun jobs in application screen appears. The root job name has a plus sign (+) appended to it, indicating that all successors will be included. From the screen, you can specify multiple root jobs, request ESP Encore restart, and enter USER variables and ESP Encore commands.


ESP-5.4-UG-05 239

3. Press Enter to update the list of selected jobs.

4. Enter SUB to submit your request.

Removing job dependencies

You can use CSF to remove different dependencies from a job in an Application.

Example

You can:

• Use the RT command to remove time dependencies• Use the DD command to drop all predecessor dependencies• Use the L and then D command to drop individual predecessor dependencies, like

this:

ESP Rerun jobs in application JEFF.17 Command ===>

Review and modify the settings as needed. Press ENTER to see the updated list of selected jobs. When ready, enter SUB to submit the request, CAN or END to abort.

Root jobs ===> A+

Job list data set ==> USER1 ===> USER2 ===> USER3 ===> USER4 ===> Case-sensitive ===> ( Y to preserve the case of USER variables) Encore restart ===> ( Y to select) Encore statements: ===> ( Y to go to the statements panel)

5 jobs will be selected for rerun: A, B, C, D, E

Section–Resetting a time dependency

240 ESP-5.4-UG-05

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

JOB PAYD008A

PREDECESSORSD PAY006A NEWJOB

SUCCESSORS PAYR009A

• Use the RD command to ready a job—remove all dependencies except resources

• Use the DR command to remove all resource dependencies

Resetting a time dependency

A job in an Application can have different types of time dependencies. Using CSF, you can reset any of these dependencies.

To change a time dependency for a job:

• Type RT beside the job. The Reset Object Times panel appears.

The following table associates each field on the Reset Object Times panel with the corresponding Application statement.

Example

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

Field ESP Procedure Statement

Earliest submit time DELAYSUB or EARLYSUB

Late submit time LATESUB

Overdue time for job start DUEOUT INPUT

Overdue time for job end DUEOUT EXEC

Abandon execution at ABANDON SUBMISSION

Abandon dependencies at ABANDON DEPENDENCIES

Abandon resources at ABANDON RESOURCES


ESP-5.4-UG-05 241

To remove this time dependency:

• Type RT beside the job and reset the early submit time with one of the following actions:• Type NOW in the earliest submit time field, and press ENTER• Type RESET in the earliest submit time field, and press ENTER• Blank out the data in the earliest submit time field, and press ENTER

Time at which an ESP Workload Manager object becomes overdue

The time at which an object becomes overdue for submission, start of execution, and end of execution can be displayed on CSF. They are also stored on the ESP Workload Manager history file for inclusion in history reports.

Overdue display in CSF

The following table shows the selection fields in the presentation screen (CSF PR command) and the sort screen (CSF SO command) and the resulting heading in the main CSF screen. You cannot use them as selection criteria in Freeform filters.

The values shown in CSF are in the same format as the Scheduled field, for example, “08.51 TODAY” or “16.30 MON”.

At the time an object becomes overdue for submission, start, or end, the object is marked as overdue, and the value of the appropriate overdue field is set to this time.

If an object's due time for submission, start, or end, is changed (for example, by means of a CSF RT line command), the new time value is compared to the current time. For the due time that was changed:

• If the object is currently marked as overdue and the new due time is in the future, the overdue status is revoked and the corresponding “overdue at” time is cleared.

• If the new due time is in the past, the object is marked as overdue, and the corresponding “overdue at” time is set to this new time.

Overdue for... Field description(Presentation or Sort screen)

CSF screen heading

Submission Became O/D Sub O/D Sub at

Start of execution Became O/D Strt O/D Strt at

End of execution Became O/D End O/D End at

Section–Bypassing and completing jobs

242 ESP-5.4-UG-05

Sample CSF display of an overdue job

ESP4 Consolidated Status: View 1 ------------ Row 1 of 8, Col 1COMMAND ===> SCR ===> CSR

Job Name Scheduled PNode CCode O/D Sub at O/D Strt at O/D End at ___ WAIT3 16.30 MON COMPLETE 0___ WAIT3#5 16.30 MON COMPLETE 0___ WAIT3#5S 16.30 MON COMPLETE 0___ WAIT5 16.30 MON COMPLETE 0___ WAIT5 08.51 TODAY COMPLETE 0 08.52 TODAY 08.53 TODAY 08.56 TODAY___ WAIT5 09.00 TODAY COMPLETE 0 09.01 TODAY 09.02 TODAY 09.05 TODAY___ WAIT5 10.17 TODAY COMPLETE 0 10.19 TODAY___ WAIT5 10.28 TODAY EXEC - 10.30 TODAY

Sample LCSF output of an overdue job

Note: For this sample, the overdue job information is shown in bold.

20040513 103802+0400 . . /MAIN/RFE1214A.7/WAIT5 STATE COMPLETE Conditions(COMPLETE) Status(COMPLETED AT 08.59 13 MAY) SystemStatus(COMPLETED AT 08.59 13 MAY)Jobno(19974) Account(?) ASeq(0005) Scheduled(08.51.00 THU 13 MAY 2004) UpdatedOn(08.59.03 THU 13 MAY 2004) ReaderTime(200405130854) StartTime(08.54.02 THU 13MAY 2004) EndTime(08.59.05 THU 13 MAY 2004) Cmpc(CC 0) OrigJno(19974) ExecJno(19974) Jes(2) Class(A) Priority(7) ASID(0022) SID(SYSA) SrvClass(JES) Sysname(SYSA) Sysplex(SYSAPLEX) OrigNode(CYBJES) ExecNode(CYBJES) AvgRT(5) OvdSubmitAt(08.52.02 THU 13 MAY 2004) OvdStartAt(08.53.02 THU 13 MAY 2004) OvdEndAt(08.56.02THU 13 MAY 2004)

Overdue history reporting

You can use the OVDSUBAT, OVDBEGAT, and OVENDAT fields to report overdue time history. For details see “History reporting fields” on page 277.

Bypassing and completing jobs

Using CSF, you can bypass and complete jobs.

Bypassing a job

You can bypass a job up to the time it becomes ready for submission by typing BY next to it. ESP Workload Manager updates the status field to BYPREQ indicating that a bypass has been requested. When the job’s predecessors are complete, the job is bypassed, and the successor jobs released. You can unbypass a job by typing UB next to the job anytime before the job actually becomes bypassed.

Completing a job

When you complete a job, you are telling ESP Workload Manager to consider the job complete. Successors are immediately released, including those in other Applications. You can complete a job by typing C next to the job, at any time.


ESP-5.4-UG-05 243

You cannot reverse the completion of a job. If you mistakenly complete a job, you can insert another occurrence of the job (qualified for uniqueness) with the required dependencies, but successor jobs can have already been released.

Adding job dependencies

Using CSF, you can add different dependencies to a job in an Application.

Example

For example, you can:

• Use the RT command to add time dependencies• Insert a task as a predecessor or successor• Insert a link with predecessor A and successor B to add a relationship between jobs

A and B

Adding a job with a time dependency

To add a job with a delayed submission time:

1. Insert the job on hold (IJ command, job on HOLD? ==> Y).

2. Reset the submission time for the job (RT command, earliest submit time ==> time).

3. Release the job from hold (A command).

Adding a job relationship in an Application

To add a relationship between two unrelated jobs in an Application:

1. Type the IJ command beside any job in the Application.

2. Enter the name of the link in the job name field.

3. Type A in the predecessor field.

4. Type B in the successor field.

5. Specify the job type as L (link).

When job A completes successfully, ESP Workload Manager completes the link and submits job B.

Section–Adding a LINK process

244 ESP-5.4-UG-05

Example

For example, you can add a link to an Application to cause job B to wait for job A to complete successfully. Visually, the dependencies look like this:

Adding a LINK process

Note: If the Application contains an APPLEND workload object, the hold count of the APPLEND workload object is incremented when a LINK process is inserted and becomes a predecessor to the APPLEND workload object. However, the HC data in the scoreboard is not immediately updated.

To add a link that processes commands:

1. Edit the Application definition to define the link and specify the commands you want processed. For example:

JOB EXTRA LINK PROCESS SEND 'THIS IS AN INSERTED LINK PROCESS' U(*)ENDJOB

2. Insert a link with the same name into the Application—specify job name, job type, and dependencies.

When the link becomes ready, ESP Workload Manager processes the commands.

Setting and resetting the user status field

To set the user status field:

Use either of the following:

• HR command to hold a job with a reason• SUS command

A B

LINKME


ESP-5.4-UG-05 245

Example

For example, if you bypass a job, you can use the user status field to notify others of the reason for this action. The user status field for a job looks like this:

JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY

ESP Workload Manager does not reset the user status field. To reset the user status field to null, issue the SUS command and enter a period (.) in the field.

Modifying a Job Resources or Enqueues

You can use the LR command to display the resources and enqueues associated with a job. You can also use the MR and ME commands to modify the resources and enqueues associated with a job.

LR command

The LR command displays the resources and enqueues associated with a job.

For each resource, the following are displayed:

• The resource name

• The resource quantity

• The resource availability indicator:

• ? means that the resource is not defined.• Y means that the resource is available; in the case of local resource Y is only

displayed if the resource has gravity or if the requested quantity of the resource is available on a CPU of the current node.

• N means that the resource is not available on any CPU.• X means that the requested quantity of the resource is available on a CPU of a

node other than the current node and that the resource does not have gravity.

For each enqueue, the following are displayed:

• The enqueue name• Whether the enqueue is shared or exclusive

You can use two subcommands with the LR command for resources:

• L displays more information about a specific resource. You can also press Enter.• X displays more information about all resources

Section–Modifying a Job Resources or Enqueues

246 ESP-5.4-UG-05

ME command

The ME command allows you to change one or more enqueues and to add new enqueues. The ME command is equivalent to the JOBENQ command and provides the same operands.

For each enqueue, the following are displayed and updated automatically if you make changes:

• The enqueue name• Whether the enqueue is shared or exclusive

MR command

Using the MR command

The MR command allows you to change the quantity of a resource and to add new resources for a job. The MR command is equivalent to the JOBRES command.

For each resource, the following are displayed and updated automatically if you make changes:

• The resource name

• The resource quantity

• The resource availability indicator:

• ? means that the resource is not defined.• Y means that the resource is available; in the case of local resource Y is only

displayed if the resource has gravity or if the requested quantity of the resource is available on a CPU of the current node.

• N means that the resource is not available on any CPU.• X means that the requested quantity of the resource is available on a CPU of a

node other than the current node and that the resource does not have gravity.

You can use two subcommands with the MR command:

• L displays more information about a specific resource.• X displays more information about all resources


ESP-5.4-UG-05 247

Using other commands

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

Another way of processing ESP Workload Manager commands is to type ESP followed by the command you want processed. The following example issues a TRIGGER command from the command line.

ESP TRIGGER PROD.MORE_WORK ADD


For more information on using these modes, see “Getting Started” on page 31.

Extensions to CSF

The Consolidated Status Facility can have extensions written in REXX. Your installation can add its own commands and enhance or replace the standard commands.

Example

For example, your installation can write commands to:

• Trigger an Event• Edit JCL prior to job submission• Provide confirmation panels• Force user status information• Access SDSF

Check with your administrator to see if any customized commands are available to you.

Freeform filtering

Freeform filtering is an extension to the CSF filtering that allows you a more versatile and customizable method of filtering your ESP Applications. You have the option to

Command Invokes ESP Workload Manager in ...

ESP Line mode.

ESPPM Page mode.

Section–Freeform filtering

248 ESP-5.4-UG-05

filter your Applications using the standard filter panel or to use the Freeform filter for scenarios that cannot be handled using the standard panel.

Example

For example, you can filter based on the following criteria:

• Jobs that have started and ended between specific times• Jobs on a critical path• Completion codes for jobs within a subApplication• Jobs within an Application that have a restart step

Entering a freeform filter

To enter a freeform filter:

1. Type FI on the CSF command line. The Filter Specification panel appears.

2. Type Y in the Freeform filter ===> field. This places you in ISPF Edit, where you can enter a Freeform filter, as shown below.

(COMPLETE OR INCOMPLETE)

Filter criteria syntax

term [[{AND|OR} term] ...]

Note: The AND operator takes precedence over the OR operator. You can nest expressions within parentheses to force precedence or to make your filter easier to understand.

Term syntax

(keyword[(v1[,v2])] reloperator value)|condition

Operand Description

term See “Term syntax” on page 248.

AND Connects two terms when both terms must be true.

OR Connects two terms when at least one term must be true.


ESP-5.4-UG-05 249

Examples of substring notation

For example, assume that JOBNAME contains the string PRODJOB. The following table demonstrates the outcome that results when you specify certain substring notations:

Operand Description

keyword Identifies the kind of workload objects on which you want to filter, such as Applications or workload object names. See “Keywords:” on page 250 for the list of valid keywords.

v1 Refers to the starting position if you want to use portions of a value, rather than its full contents. (Substring notation.)

Character positions start at one.

If v1 is negative, the starting position is relative to the last non-blank character of the variable. For example, -1 refers to the last character.

v2 Refers to the number of characters if you want to use portions of a value, rather than its full contents. (Substring notation.)• If v2 is omitted, it defaults to the remaining length of the variable.• If v2 is positive, it specifies the number of characters required.• If v2 is negative, it represents the remaining length less v2.

reloperator Specifies the operation, such as EQ for equal to. See “Relational operators” on page 253 for the list of relational operators.

value Specifies what you want Application name to be equal to, such as PAYROLL.

condition Specifies the condition. For example, if you want to see all Applications that are incomplete, the condition INCOMPLETE. See “Conditions” on page 254 for the list of available conditions.

Specification Result

JOBNAME PRODJOB

JOBNAME(1,4) PROD

JOBNAME(5) JOB

JOBNAME(5,1) J

JOBNAME(-1,1) B

JOBNAME(1,7) PRODJOB

JOBNAME(1,-3) PROD


250 ESP-5.4-UG-05

Examples of freeform filter

Keywords:

Enter the following filter To see...

CRITICAL_PATH Workload objects on the critical-path.ON_REQUEST AND REQUESTED On-request workload objects that have

been requested.APPL EQ 'PAYROLL' AND RESTART_STEP_PRESENT

Workload objects in the PAYROLL Application that have a restart step.

JOBNAME(1,1) EQ 'P' AND JSBYTE EQ 'F'

Failed workload objects that start with P.

CMPC EQ 'S222' AND SUBAPPL EQ 'PAYJOBS'

Workload objects with a completion code of S222 in the PAYJOBS subApplication.

(JOBNAME(1,3) EQ 'PAY' OR JOBNAME(1,3) EQ 'ACC')AND APPL EQ 'FINANCE'

Workload Objects that start with PAY or ACC and belong to an Application called FINANCE.

JOBNAME(1,4) EQ 'TEST' AND APPL EQ 'TESTAPPL' AND INCOMPLETE

Workload Objects in Application TESTAPPL that start with TEST and are not complete.

APPL EQ 'CYBER' AND OVERDUE_START AND REQUEST

Workload Objects in Application CYBER whose execution start time is overdue and that are requestable.

JOBNAME(1,3) EQ 'CYB' AND STIME> TIME(11AM TODAY)

Workload Objects whose names start with CYB that started later than 11 am today.

WOBTYPE EQ 'HP' AND APPL EQ 'BILLING'

All HP workload objects in the BILLING Application.

JOBNAME(1,1) EQ 'X' AND APPL EQ 'MYAPPL' AND NOT_REQUESTED

Workload Objects that start with X in Application MYAPPL that have not been requested.

(JOBNAME EQ 'TESTJOB' OR JOBNAME(1,1) EQ 'A' OR JOBNAME(1,2) EQ 'BC') AND (APPL EQ 'MYAPPL' OR APPL (1,2) EQ 'PA') AND OVERDUE_START

Workload Objects called TESTJOB or whose names start with the characters A or BC and are contained within Application MYAPPL or any Application whose name starts with PA and whose execution start time is overdue.

EVENT EQ 'CYBER MYJOB' Workload Objects in Applications that have been generated by the Event CYBER.MYJOB.

Keyword Description

ACCOUNT Account number

AGENT Agent name

APPL Application name


ESP-5.4-UG-05 251

APPLFILE Application file

APPLGEN Application generation

APPLSEQ Application definition sequence

APSLOT Application file slot number

ASFLAG Application status flag

ASID Execution address space identifier of the job

AUTH Authorization string

AVGRUNTIME Average execution time

CLASS Job class

CMPC Completion code

DMANAGER Distributed manager name

ETIME Job end time

EVENT Event name. The Event name consists of a prefix and a descriptive name. You must includes spaces so the prefix is eight characters long and the descriptive name starts in the ninth character position. The descriptive name can be 16 characters maximum. Specifying EVENT displays all jobs in Applications that have been generated by the Event.

EXECJNO Execution job number. It may be different from the submission job number if the job executes on a different JES node from the node where the job was submitted.

EXECNODE Execution JES node of the job

HC Hold count

HWRM High water reel mounts

HWCM High water cart mounts

JAFLAG Job attribute flag

JOBNAME Job name

JOBNO Job number

JSBYTE Job status byte as followValue Description

C Completed.

D Dependency.

E Executing.

F Failed.

I Input.

P Post-process.

R Resources.

JSFLAG Job status flag

LONGNAME Long name of the job

Keyword Description


252 ESP-5.4-UG-05

MAXRUNTIME Maximum allowable execution time

MINRUNTIME Minimum allowable execution time

NETID DJC/JES3 network ID

NSCM Non-specific cart mounts

NSRM Non-specific reel mounts

ORIGJNO Submission job number. It may be different from the execution job number if the job executes on a different JES node from the node where the job was submitted.

ORIGNODE JES node where the job was submitted.

PGN Performance group number of the job if the execution system is in WLM compatibility mode

PNODE Processing node

PRIORITY Job priority

QUAL Qualifier

RDRTIME Time the job was submitted to a JES reader

SADFLAG SAD flags

SCBCYCLE Scoreboard cycle

SCBENTRY Scoreboard entry number

SCBTOKEN Scoreboard token

SCHED Scheduled time

SMFID Execution SMF identifier of the job

SRVCLASS Service class of the job if the execution system is in WLM goal mode

STATUS System status

STIME Job start time

SUBAPPL SubApplication name

SYSNAME Execution system name of the job

SYSPLEX Execution sysplex name of the job

TAG Tag

TRSLOT Trakfile slot number

USTATUS User status

WOBTYPE 2-character workload object type:Value Description

AE ApplEnd

AM AGENT_MONITOR

AX Aix_Job

A4 AS400_Job

CM CPU_Mon

DM DB_Job

Keyword Description


ESP-5.4-UG-05 253

Note: For any of the time fields, (for example, ETIME, SCHED, and STIME), you need to use the TIME function in a comparison. For example, STIME > TIME(11AM TODAY). You can compare against any time in a format that ESP Workload Manager recognizes.

Relational operators

Relational operators include the following standard operators:

DT DSTRIG

EX EXTMON

FM File_Trigger

FT FTP_JOB

HM DISK_Mon

HP HPUX_Job

IM IP_Mon

LJ Linux_Job

LM EVENTLOG_Mon

NC NCR_Job

NT NT_Job

OV OpenVMS_Job

PM PROCESS_Mon

PS PS_Job

SJ Sun_Job

SM SERVICE_Mon

SP SAP_Job

SQ Sequent_Job

TA Tandem_Job

TM TEXT_Mon

UJ Unix_Job

Keyword Description

>= GE greater than or equal

<= LE less than or equal

> GT greater than

< LT less than

= EQ equal

¬= NE not equal to


254 ESP-5.4-UG-05

Conditions

Condition Description

ALL All workload objects.

APPL_COMPLETE Application execution is complete.

BYPASSED Workload object execution has been bypassed.

COMPLETE Workload object execution is complete.

CRITICAL_PATH Workload object is on a critical path.

EXTERNAL Workload object is external to an Application.

INCOMPLETE Workload object execution is not complete.

INTERVENTION_REQUIRED Workload object execution requires manual intervention.

INTVRQ Workload object execution requires manual intervention.

LINK Workload object is a LINK.

MANUAL_TASK Workload object is a manual task.

NOT_APPL_COMPLETE Application execution is not complete.

NOT_BYPASSED Workload object execution has not been bypassed.

NOT_CRITICAL_PATH Workload object is not on a critical path.

NOT_EXTERNAL Workload object is not an external.

NOT_INTERVENTION_REQUIRED Workload object execution does not require manual intervention.

NOT_INTVRQ Workload object execution does not require manual intervention.

NOT_LINK Workload object is not a LINK.

NOT_ON_REQUEST Workload object is not defined as REQUEST.

NOT_OVERDUE_END Workload object execution end time has not been exceeded.

NOT_OVERDUE_START Workload object execution start time has not been exceeded.

NOT_REQUESTED Workload object has not been specifically requested.

NOT_RESTART_STEP_PRESENT Workload object does not have a restart step.

NOT_TASK Workload object is not a TASK.

ON_REQUEST Workload object is defined as REQUEST.


ESP-5.4-UG-05 255

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

OVERDUE_END Workload object execution end time has been exceeded.

OVERDUE_START Workload object execution start time has been exceeded.

REQUESTED Workload object has been specifically requested.

RESTART_STEP_PRESENT Workload object has a restart step.

TASK Workload object is a TASK.

Condition Description


256 ESP-5.4-UG-05

ESP-5.4-UG-05 257

Job Documentation

The ESP Workload Manager job-documentation facility lets you create a complete and centralized definition of each one of your jobs. You can document a job’s entire requirements, including its predecessors and successors, its schedule frequency, all the resources it requires, and so on. Users and operators can retrieve this information easily using the JOBINFO command or through the Consolidated Status Facility.

Job documentation can also be used for informational purposes.


• Contents of job documentation• Control information• User description• Creating job documentation• Using the jobs option• Updating job documentation• Using job documentation• Using the control information• Referencing job-documentation members• Overriding job documentation• Using job documentation for qualified jobs• Using job documentation for links and tasks• Retrieving information• Converting existing job documentation• Other uses of job documentation

Section–Contents of job documentation

258 ESP-5.4-UG-05

Contents of job documentation

A job-documentation entry is a member of a partitioned data set (PDS). Each entry consists of the following information in two parts, either of which is optional:

Comment

Either section can include comments within /* */ pairs.

Control information

The control information comes first in your job-documentation entry and follows a very specific format, as shown below:

job name: JOBDOC

Example

For example, to specify the start of job documentation for the job PAYJOB1, enter the job name followed by a colon, a space, and the JOBDOC keyword like this:

PAYJOB1: JOBDOC

Using CLANG and REXX

Control information uses the same job-statement information you use in an ESP Procedure. You can also use CLANG and REXX within job documentation to handle conditional or complex requirements.

Job documentation entry Explanation

Control information Information that ESP Workload Manager will use directly when processing a job, such as the JCL library, job dependencies, and schedule frequency.

User description Other information you want to store about a job. This can include ABEND codes, messages, restart instructions, job severity, and so on.

Chapter 8–Job Documentation

ESP-5.4-UG-05 259

Example control information

Control information is specified as shown below:

PAYJOB: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP,GT,4)RUN WORKDAYSIF MONDAY('MONDAY') THEN DELAYSUB 7PMELSE DELAYSUB 6PM

Storing requirements

You can store all requirements for a job in a job-documentation library. Alternatively, you can also store some requirements in ESP Procedures and others in job documentation members. For example, you can use job documentation to store only the resource requirements for a job and use ESP Procedures to store scheduled frequency, job relationships, and time dependencies.

User description

The user-description section of your job documentation must begin with the keyword USERDESC as a heading. After that, the rest of the data can be formatted as you choose. You can divide the user description section into paragraphs and identify each paragraph with a label. You can then retrieve selected information by label name. ESP Workload Manager supplies the following standard labels:

ESP Workload Manager Label

Use this Label to…

Function Describe what the job does.

Programmer Identify the programmer of the job.

Abends Identify ABEND codes and recovery activity. A number sign (#) can precede each ABEND code. This lets you request display information about a specific ABEND code when retrieving information with the JOBINFO command.

Messages Identify message codes and recovery activity. A number sign (#) can precede each message ID code. This lets you request display information about a specific message ID when retrieving information with the JOBINFO command.

Section–Creating job documentation

260 ESP-5.4-UG-05

Customized labels

You can use any of your own labels as long you observe the following guidelines:

• A label consists of a word, 1 to 16 characters long, followed by a colon and at least one blank.

• A label must be the first entry on a line.• A label can precede any type of information, such as report distribution

information, severity codes, and escalation Procedures.• Each paragraph ends with the next label or the end of the PDS member.• You can specify as many labels as you wish.

Example

In the example below, the USERDESC keyword identifies this as the user-description area of job documentation. Each of the five user description paragraphs begins with a label (for example, FUNCTION, PROGRAMMER, ABENDS, MESSAGES, SEVERITY) followed by a colon (:).

USERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 – warning#Z001 - user not authorizedSEVERITY: 3

Creating job documentation

Create one entry for each job you want to document. Use a member name equal to the job name; otherwise, you will need to override this in an ESP Procedure. To create job documentation, use either ISPF edit or the jobs option of the ESP Workload Manager Main Menu.


ESP-5.4-UG-05 261

Using the jobs option

The jobs option (option J on the Main Menu) provides panels for creating job documentation members. These panels do not provide fields for all possible data, but they can assist you in specifying some of your requirements. You can then add to these requirements using ISPF edit.

To create a job documentation member for a job:

1. Select option J.

Note: The first time you select this panel, you must specify the name of the pre-allocated PDS file to store job documentation. This PDS then becomes your default.

2. Complete the job name and other control information on the Job Specifications screen, as shown below.

3. Enter 1 on the command line to access the Job User Description panel.

4. Complete any user description information, as shown below.

Section–Updating job documentation

262 ESP-5.4-UG-05

5. If you have DJC or JES3 installed, you can enter 2 on the command line to define DJC/JES3 specifications. See the ESP Workload Manager Advanced User’s Guide for more information.

6. Press PF3 twice to return to the Main Menu.

Result

You have now created and stored job documentation. ESP Workload Manager stores the information in a member of the job documentation PDS with the same name as the job name. The information is stored as shown below.

PAYJOB1: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP1 GT 4)USERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 - warning#Z001 - user not authorized

Points to note about the example shown

In this example, notice the following:

• The first line identifies the job name using a label and specifies JOBDOC.• The first descriptive section contains control information.• The user description section is headed by the keyword USERDESC. It is defined

in free format, using indentations to improve readability only.

Updating job documentation

You can return to the PDS member where your job documentation entry resides and update the information using either ISPF edit or the ED command from the Consolidated Status Facility.


ESP-5.4-UG-05 263

Note: Do not use the Job Specifications panel (Option J) to update existing job documentation. This option is only for initially setting up your documentation. When you try to use this panel to update an existing entry, you will receive an error message indicating the member already exists.

Updating the previous example

For example, you could update the previous example to:

• Insert IF-THEN-ELSE statements to allow for different delayed submission times• Insert a RUN statement to identify the job’s frequency• Add a user field to identify the job’s severity

Resulting job documentation

The job documentation now looks like this:

PAYJOB1: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP1 GT 4)RUN WORKDAYSIF TODAY('MONDAY') THEN DELAYSUB 7PM ELSE DELAYSUB 6PMUSERDESCFUNCTION: sort and merge payroll filesPROGRAMMER: joan smithABENDS: #SB37 - space problem - double space requirements and restart job from failing stepMESSAGES:#AC101 - number of available accounts <50 - warning#Z001 - user not authorizedSEVERITY: 3

Using job documentation

You can use job documentation in the following ways:

• To control processing using the control information directly• To retrieve information

Section–Using the control information

264 ESP-5.4-UG-05

Using the control information

To use the control information directly, you must use the DOCLIB statement in an ESP Procedure. This statement identifies the name of your job documentation library.

ESP Procedure

The ESP Procedure below shows a DOCLIB statement pointing to the library CYBER.JOBS.DOC that contains documentation on jobs specified in this Procedure.

APPL PAYJOBSJCLLIB 'CYB.JCL.CNTL'DOCLIB 'CYBER.JOBS.DOC'JOB PAYJOB1ENDJOBJOB PAYJOB2ENDJOBJOB PAYJOB3ENDJOB

ESP Workload Manager then uses the job-documentation information to establish dependencies and any other requirements. To invoke this Procedure, use an INVOKE command in an Event.

Relationship with Event and Procedure

The following diagram shows the relationship between an Event, an ESP Procedure, and a job documentation library. When ESP Workload Manager executes the Event, the INVOKE command invokes the ESP Procedure. The DOCLIB statement in the ESP Procedure identifies the name of the job documentation library. ESP Workload Manager retrieves the job documentation (if it exists) for each job identified by a JOB statement. This includes jobs submitted as part of the ESP Procedure, links, tasks, qualified jobs, external jobs, and manual jobs.

A: JOBDOCRUN DAILYRELEASE B

Job DocumentationLibrary

DOCLIB . . .JOB AINVOKE . . .

ESP ProcedureEvent


ESP-5.4-UG-05 265

Referencing job-documentation members

DOCMEM operand

ESP Workload Manager retrieves job documentation by job name. If you want to reference a job-documentation member with a name other than the job name, use the DOCMEM operand when you identify the job in an ESP Procedure.

In this example, job A uses a job documentation member called SPECIAL.

JOB A DOCMEM(SPECIAL)

Overriding job documentation

Job information can be specified in different places. These include ESP Procedures, job documentation, and tracking models. As a result, it is possible to have conflicting information specified for a job. Therefore, you must ensure ESP Workload Manager knows which information to use.

Rules

ESP Workload Manager uses the following rules:

Example

For example, if you specify a HISTFILE as below, it overrides the HISTFILE specified in a tracking model for the job.

APPL PAYJOBSDOCLIB 'CYBER.JOBS.DOC'JCLLIB 'CYBER.JOBS.JCL'JOB PAYJOB1 HISTFILE HIST2 RUN DAILYENDJOB

Type of information …overrides corresponding

ESP Procedure information… … job documentation information.

Job documentation information… …tracking model information.

Section–Using job documentation for qualified jobs

266 ESP-5.4-UG-05

Temporary override

You can temporarily override the control information specified in job documentation from within an ESP Procedure by specifying the new control information you want to use. In this example, the RELEASE statement for PAYJOB1 overrides any RELEASE statement specified in the job documentation for the job.

DOCLIB 'CYBER.JOBS.DOC'APPL PAYJOBSJOB PAYJOB1 RELEASE NEXTJOBENDJOB

Using job documentation for qualified jobs

Job qualifier

ESP Workload Manager uses the eight-character job name to access job documentation. If you want to use job documentation for jobs defined with a job qualifier, you can do one of the following:

• Use the DOCMEM operand when you define the job in the ESP Procedure, and specify the name of the member used for the job’s documentation.

• Use IF-THEN-ELSE logic in the job-documentation member to check the qualifier of a job and process different statements. Use the ESPAPQUAL symbolic variable for jobs in an Application. Use the ESPJQUAL variable for jobs in a DJC/JES3 network.

Each approach is illustrated below.

DOCMEM method

This method shows you how you use different job documentation members for different qualified versions of a job. Job A.RUN1 references member A1; job A.RUN2 references member A2.

JOB A.RUN1 DOCMEM(A1)JOB A.RUN2 DOCMEM(A2)

IF-THEN-ELSE method

This method uses a common job-documentation member for job A. ESP Workload Manager processes different statements based on the job qualifier.

If the qualifier is RUN1, the job runs daily and releases job Y.

If the qualifier is RUN2, the job runs on workdays and releases job Z.


ESP-5.4-UG-05 267


Job-documentation member

The job-documentation member looks like this:

A: JOBDOCIF ESPAPQUAL='RUN1' THEN DO RUN DAILY RELEASE YENDDOIF ESPAPQUAL='RUN2' THEN DO RUN WORKDAYS RELEASE ZENDDO

Using job documentation for links and tasks

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

A.RUN1

Y

A.RUN2

Z

Section–Using job documentation for links and tasks

268 ESP-5.4-UG-05

Example: Documenting links and tasks

In this example, the Application consists of a job, a task, and a link. The Application identifies their names, and the job documentation library contains the processing requirements, as shown below:

Example: Documenting a job and a link

This example uses job documentation to store resource requirements. In this Application, there are two jobs: MEMOBACK and MEMOBACK.MSG. The specifications are that:

• The first job requires one unit of a resource called DB2TAB.• The second job is a link that sends a message when job MEMOBACK completes

successfully.

IF statement

ESP Workload Manager uses the same job-documentation member for each job because it does not check the qualifier when accessing job documentation. To prevent the link from using the resource, the job-documentation member for MEMOBACK uses an IF statement to assign a resource requirement to the unqualified job only.

DOCLIB 'CYBER.JOBS.DOCJCLLIB 'CYBER.JOBS.DOCAPPL ABCJOB AJOB CHECK TASKJOB ENDAPPL LINK PROCESSENDJOB

A: JOBDOCRUN DAILYRELEASE CHECK

CHECK: JOBDOCRUN DAILYSEND 'CHECK REPORT FOR JOB A'

ENDAPPL: JOBDOCRUN DAILYRELEASE CHECK

ESP ProcedureJob Documentation Member


ESP-5.4-UG-05 269

The ESP Procedure and job documentation member look like this:

Retrieving information

You can retrieve job-documentation information using the Consolidated Status Facility (CSF) or the JOBINFO (JI) command from the operator console, the ESP Workload Manager command processor, or ISPF interface (Line mode or Page mode). You can display all information for a job or display selected information as identified by fields and labels.

Using CSF

You can access job documentation information directly from CSF with the following commands.

ESP Workload Manager retrieves the information from the data set identified by the DOCLIB statement in an ESP Procedure. Using this method, ESP Workload Manager retrieves all information on the job. You cannot select individual fields.

Using TSO

If a job is submitted by an ESP Procedure, ESP Workload Manager searches the job-documentation library identified by the DOCLIB statement. If a job-documentation library was not identified in the ESP Procedure, or the job was not scheduled from an ESP Procedure, the JOBINFO command looks for the file name JOBDOC. If the file is allocated, it is opened and searched for a member corresponding to the job name. The JOBDOC file can consist of a concatenation of several partitioned data sets.

DOCLIB 'CYBER.JOBS.DOC'JCLLIB 'CYBER.JOBS.JCL'APPL MEMOJOB MEMOBACK RUN WORKDAYS RELEASE MEMOBACK.MSGJOB MEMOBACK.MSG LINK PROCESS RUN WORKDAYS SE 'MEMOBACK IS DONE' U(*)ENDJOB

MEMOBACK: JOBDOCIF ESPAPQUAL=' ' THEN + RESOURCE (1,DB2TAB)

Job DocumentationMember

ESP Procedure

Command Explanation

BD Browses job documentation

ED Edits job documentation

Section–Retrieving information

270 ESP-5.4-UG-05

To use the JOBINFO command in TSO you must pre-allocate a file to your TSO session, either in LOGON Procedure or LOGON CLIST. You can dynamically allocate this file during a session by issuing the following TSO command:

ALLOC FI(JOBDOC) DA('data set name') SHR

Using an operator console

The console version of the JOBINFO command requires the JOBDOC file in the ESP Workload Manager started task Procedure. You can issue the following commands from an operator console, or from Page mode, respectively:

F ESP,JOBINFO jobname or OPER JOBINFO jobname

Examples: Retrieving job-documentation information

Some examples of retrieving job-documentation are shown below.

• To display all information about PAYJOB1, type:

JOBINFO PAYJOB1

• To display ABEND information for PAYJOB1 as well as the contents of the user defined field SEVERITY, type:

JI PAYJOB ABENDS FIELD(SEVERITY)

• To display PAYJOB1’s successor (RELEASE) and JCL data set (DATASET) information, type:

JI PAYJOB1 RELEASE DATASET

Retrieving job-documentation information

The following table summarizes where and how you can retrieve job-documentation information:

Origin Command Retrieved from

Consolidated Status Facility BD or ED Library specified in the ESP Procedure.

Page mode or line mode JOBINFO DOCLIB in ESP Procedure or JOBDOC DD allocated to your TSO session.

Page mode or line mode OPER JOBINFO JOBDOC DD allocated to the ESP Workload Manager started task.

Operator console F ESP,JOBINFO JOBDOC DD allocated to the ESP Workload Manager started task.


ESP-5.4-UG-05 271

Converting existing job documentation

Methods for converting documentation

You can already use some form of job documentation and want to convert it to ESP Workload Manager. There are two methods for converting documentation. The method you use depends on how you want to use your existing job documentation.

• If you want to use ESP Workload Manager to retrieve your existing job documentation in its present format, you can insert a USERDESC label in each job-documentation member.

• If you want ESP Workload Manager to modify the data to allow retrieval of information by label name, you can use the GENDOC command.

To retrieve your existing job documentation through ESP Workload Manager:

1. Update each member to include the USERDESC heading at the beginning of the information. An example is shown below:

Before:

THIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH.FREQUENCY: LAST WORKDAY OF THE MONTH

After:

USERDESCTHIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH.FREQUENCY: LAST WORKDAY OF THE MONTH

2. Allocate the job documentation files, with the DD name of JOBDOC, to your TSO session or to the ESP Workload Manager started task. You can then use the JOBINFO command to extract information.

To convert an existing PDS job documentation library into an ESP Workload Manager documentation library:

• Use the GENDOC command in Line mode, Page mode, or in batch.

The GENDOC command identifies the input data set, the members to be copied, and the output data set. You can also identify changes you want to make when the old documentation converts.

Section–Converting existing job documentation

272 ESP-5.4-UG-05

Commands

You can use the following commands:

New data set

For each selected member of the input data set, ESP Workload Manager generates a corresponding member in the output data set. ESP Workload Manager automatically adds the following two lines to each member of the new data set:

jobname: JOBDOCUSERDESC

GENDOC can insert appropriate paragraph labels in the converted user-description section to allow retrieval of information by label.

Example: Using GENDOC to convert job doc.

Below is a set of sample conversion instructions for ESP Workload Manager:

GENDOC JOBDOC.DATA ESP.JOBDOC.DATA LEV(A-,B-) SNUMREMOVE '**'LABEL 'SYSOUT REVIEW' 'SYSOUT_REVIEW' INLINELABEL 'RESTART PROCEDURES' 'RESTART:' BEFORE GO

The above example tells ESP Workload Manager to:

• Copy all members beginning with A and B from the data set JOBDOC.DATA to the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right-hand eight columns of each source member record.

• Not copy any lines containing **.

• Replace any lines starting with SYSOUT REVIEW with the character string SYSOUT_REVIEW.

• Overlay the semicolon on any line beginning with STEP. The semicolon is positioned after the third character following the string STEP.

• Place the label RESTART: on its own line before any line starting with the string RESTART PROCEDURES.

• Proceed with the copy process.

Command Explanation

REMOVE Identifies lines that are not to be copied to the output data set.

LABEL Alters or replaces lines in the output data set, or inserts lines at different locations.

GO Indicates that all specifications are complete and that the copy process should proceed


ESP-5.4-UG-05 273

Message at the end of the conversion

ESP Workload Manager issues the following message at the end of the conversion to indicate the number of members in the input and output data sets.

ESP000 nnn MEMBERS IN SOURCE DATASET, mmm MEMBERS PROCESSED

Other uses of job documentation

You can use ESP Workload Manager job-documentation facility for more than just jobs. You can also create documentation libraries for documenting such items as:

• Startup and shutdown Procedures• Telephone numbers• Trouble-shooting Procedures

Remember to allocate the JOBDOC file and use proper labels.

Example: Storing phone numbers

This example shows you how to use a job-documentation member to list phone numbers for software support. A label identifies the name of each product so that you can retrieve the information easily.

USERDESC/* LISTS PHONE NUMBERS FOR SOFTWARE SUPPORT */ESP: REGULAR (905) 479-4611 AFTER HOURS (416) 287-5021CICS:(905) 123-4567...

If you call the above member SUPPORT, you can retrieve support phone numbers for ESP Workload Manager by typing the following:

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

OutputInput

Section–Other uses of job documentation

274 ESP-5.4-UG-05

ESP-5.4-UG-05 275

Creating Reports

You can get information about your jobs in several ways. You can generate a report, flowchart a jobstream, view CSF, or use tracking commands to give you the job information you require.


• History reporting• Structuring the report• Reporting fields• Field formats• Invoking the report function• Specifying input criteria• Specifying output criteria• Ending the report definition• ESP Workload Manager history reporting fields• Accumulating reporting fields• Reporting on scheduled activity• Generating data• Extracting data• Generating scheduled versus actual report• Generating projected versus actual data• Extracting tape information• Using job mapping• Job-mapping data set

Section–History reporting

276 ESP-5.4-UG-05

• Generating data for the report• Producing a job-activity report• Producing a job-descendent report• Putting it all together• ESP Workload Manager FLOWDOC• Flowcharting• Generating flowcharts using MS Project• Generating flow charts with ESP Workload Manager and Timeline

Reporting in batch

When reporting in batch, a hyphen at the end of a line indicates a continuation. If you are using a hyphen as a mask, follow it with a semi-colon (for example, PAY-;).

History reporting

ESP Workload Manager has a powerful and versatile reporting facility that you can use at any time to generate details about the progress of jobs. Information in the job history files, defined by the administrator or installer, provide the basis for the reports. You can generate reports online or in batch

Note: You can report only on jobs, started tasks, and TSO users that the ESP Workload Manager administrator requests ESP Workload Manager to track.


For more information on how to specify which of these ESP Workload Manager will track, see the ESP Workload Manager Installation and Configuration Guide.

Structuring the report

You can structure a report definition in several sections, some of which are optional. Start each section of a report definition by a command, and then code each section in free format and in any sequence.

Chapter 9–Creating Reports

ESP-5.4-UG-05 277

Sections of a report

The sections that make up a report are:

• Input source selection• Selection criteria• Display format• Sort options• Titles and footings• Section break definitions• Subtotals

Content of the report

For most reports, you usually specify input source selection, selection criteria, and display format. You can make reports as detailed as you want, describing such aspects as:

• Job name• Completion date• Application name• CPU time• Number of print lines

Reporting fields

You can select, sort, and display as many as 70 fields using the CRITERIA, SORT, and DISPLAY commands. With these commands, you can create a report containing as much detail as you want.

History reporting fields

You can find the list of ESP Workload Manager history reporting fields and their definitions in “ESP Workload Manager history reporting fields” on page 289.

Section–Field formats

278 ESP-5.4-UG-05

Field formats

Field categories

Using ESP Workload Manager, you can display or base selection criteria on the following field categories:

• Character• Numeral• Time• Elapsed time• CPU times• Dates.

Character fields

These include JOBNAME, ACCOUNT, CLASSID, and PGMR. These fields are always left justified. In the CRITERIA section, you can select character fields by specifying the full field value or part of it. If you specify a part of the field, you must include wildcard characters asterisk or hyphen (see “About this guide” on page 1.)

Example

The following example selects any jobs that begin with ZA and have a B in the fourth character position of the name. In this example, ESP Workload Manager would also select any occurrences of the job ABC.

CRITERIA JOBNAME EQ ZA*B OR JOBNAME EQ ABC

Numeric fields

These fields include APPLGEN, EXCP, EXEC#, JOBNO, RC, RRJOBNO, STEPS, SUBJOBNO, TRANSACT, and TRANSRES. ESP Workload Manager displays them right justified with leading zeros translated into blanks. You can increase the default length for these fields by specifying whatever length you want on the DISPLAY statement or by defining a longer title.

Example

The following example displays DASD EXCP counts to nine digits because the title length (DISK-EXCP) is nine characters. The title for the tape EXCP counts is TAPE I/O but ESP Workload Manager displays the counts to a length of nine, as specified. Blanks on the left fill the field. ESP Workload Manager justifies title and numeric fields on the right.

DISPLAY DEXCP 'DISK_EXCP' TEXCP 9 'TAPE I/O'


ESP-5.4-UG-05 279

Comparisons

You can also make comparisons against numeric fields in the CRITERIA section. ESP Workload Manager supports the following comparison operators: AND and OR.

Example

This example selects all jobs that perform I/O to tape, but use less than 1000 tape EXCPs.

CRITERIA TEXCP>0 AND TEXCP<1000

Time fields

Time appears in the 24-hour clock format. The default is hh.mm.ss, but you can omit the seconds by specifying a display size of five. The RDRON, EXECST, ENDT, and COMPT fields fall into this category. You can use any date and time format valid on a SCHEDULE command when you want to select these fields.

Example

The following example selects all jobs submitted since March 3rd, 2001.

CRITERIA RDRON GT MARCH 3RD 2001

Elapsed time fields

OVDSTART, INPUT, TOTALQT, and OVDCOMPT are examples of elapsed times. ESP Workload Manager displays them in the following forms:

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

ESP Workload Manager Form

Explanation

ss Seconds, where ss is the number of seconds when the elapsed time is less than 1 minute.

mmMss Minutes and seconds, when the elapsed time is less than 1 hour. For example: 10M53 (10 minutes and 53 seconds).

hhHmm Hours and minutes, when the elapsed time is less than 99 hours. For example: 16H14 (16 hours and 14 minutes).

hhhHm Hours and first digit of minutes, when the elapsed time is greater than 99 hours but less than 999 hours.

hhhH Hours, when the elapsed time is more than 999 hours.

Section–Field formats

280 ESP-5.4-UG-05

Example

The following example selects jobs that were in execution for one or more minutes, yet completed execution within five hours.

CRITERIA EXECQT GE 1M00 AND EXECQT LT 5H00

CPU time fields

This includes CPUTIME, SRBTIME, and TCBTIME. They appear in the form mm:ss.th, where mm is the number of minutes, ss is the number of seconds, and th are the tenths of a second.

Example

The following example selects all jobs that consumed between 10 seconds and 5 minutes of CPU time.

CRITERIA CPUTIME>10 AND CPUTIME<5:00

Date fields

These fields include RDRONDATE, EXECSDATE, ENDDATE, PURGDATE, SCHEDDATE, and COMPDATE. By default, they appear in the form xxxddmmmyy, where:

You can change the way date fields are displayed in a report using the DATEFORM command within the report. See “Specifying output criteria” on page 284.

You can use any date and time format valid on a SCHEDULE command when you want to select these fields as input criteria to your report.

Example

The following example selects all jobs that were submitted since 9 am on

March 29th, 2000.

CRITERIA RDRONDATE GT 9AM MARCH 29TH 2000

The date fields also allow for some sorting by storing time information. When you request sorting by a date field, ESP Workload Manager sorts by date and time. If you specify the following, ESP Workload Manager reports only on those jobs with a reader-on time and date of midnight, August 23, 2000.

CRITERIA RDRONDATE EQ AUGUST 23RD 2000

Field Symbol Explanation

xxx first three characters of the day of the week.

dd day of month number.

mmm first three characters of the month name.

yy last two digits of the year.


ESP-5.4-UG-05 281

Invoking the report function

To invoke the reporting function:

Use any of the following methods:

• Type the REPORT command from Page mode or Line mode.• Execute PGM=ESP in batch and specify the REPORT command.• Use the LOAD command to load a report definition from a data set.• Use the REPORT command of the ESP Workload Manager command processor.

When you enter the REPORT command, you are in report mode and can now structure your report.

Specifying input criteria

The input for a report consists of:

• A history file• A time range• Selection criteria

This section describes each of these areas.

To identify the history file:

• Use the HISTFILE command to specify the history files you want to use as the input source.

If you omit the history file you want to use, ESP Workload Manager scans all the history files you can access. Your ESP Workload Manager Administrator determines history-file access.

The following specifies a history file called HIST1:

HISTFILE HIST1

To use a history file other than current:

• Use the INPUT command to request that ESP Workload Manager read in other records from a data set other than an active history file.

You can use any VSAM KSDS, ESDS, or non-VSAM sequential data set as input. The data records must have the exact format of the ESP Workload Manager history file records. You will find this option most useful with files you create using the COPY statement.

Section–Specifying input criteria

282 ESP-5.4-UG-05

If the ESP Workload Manager subsystem is not functioning when the system generates a report, use the INPUT statement rather than the HISTFILE statement. The sub-system does not have to be active to use the INPUT statement.

To specify the time range:

• Use the FROM and TO commands to specify a time range for the history-file search.

In this way, you can limit your search based on the job submission time in the history file. If you do not specify an end time, ESP Workload Manager uses the current time. You can use any valid schedule command that resolves to a date and time, for example:

FROM 10AM TODAYFROM 8AM YESTERDAY TO 8AM TODAYFROM 9AM TODAY LESS 1 WEEK TO 9AM YESTERDAY

To specify the selection criteria:

• Use the CRITERIA command to specify selection criteria.

The syntax is:

CRITERIA field operator value

To view all the values possible for field, see “ESP Workload Manager history reporting fields” on page 289.

You can specify several field, operator, and value groups. To be selected, all criteria elements must be matched. Use the OR connective to provide alternatives. If you do not specify a CRITERIA command, ESP Workload Manager reports on all records that meet the time-range criteria.

You can use the following operators in either their symbol or letter form in a CRITERIA command. You cannot use the equal sign (=).

If you want to compare a field to a null string, use a blank enclosed in single quotes, as in ' '.

Note: You can specify several criteria sections in a single report, using multiple CRITERIA commands; ESP Workload Manager selects a job if it satisfies any criteria section.

Symbol Form Letter Form Explanation

>= GE Greater than or equal.

<= LE Less than or equal.

< LT Less than.

> GT Greater than.

¬= NE Not equal to.

EQ Equal.


ESP-5.4-UG-05 283

Example 1

The following example selects only those jobs that belong to the PAYROLL Application:

CRITERIA APPLSYS EQ PAYROLL

Example 2

The following example selects only those jobs that have been restarted:

CRITERIA RRJOBNO NE 0

Example 3

The following example selects a job if it belongs to the PAYROLL Application and the job name starts with P.

CRITERIA APPLSYS EQ PAYROLL JOBNAME EQ P-

Example 4

The following example selects a job if it belongs to the PAYROLL Application or the job name starts with P.

CRITERIA APPLSYS EQ PAYROLLCRITERIA JOBNAME EQ P-

Or you could use OR to separate the requirements:

CRITERIA APPLSYS EQ PAYROLL OR JOBNAME EQ P-

Example 5

The following example selects all jobs that ended between 8 am and 4 pm on May 17, 2001:

CRITERIA ENDDATE GE 8:00 MAY17,2001 -ENDDATE LE 16:00 MAY17,2001

Example 6

The following example selects all jobs that were submitted by ESP Workload Manager outside of an ESP Application:

CRITERIA ESPSUB EQ YES AND APPLSYS NE ' '

Section–Specifying output criteria

284 ESP-5.4-UG-05

Example 7

The following example selects only those jobs for reporting that either:

• Have names beginning with ABC

• Have two character names that begin with A

• Perform tape I/O

• Have no more than 10000 EXCPs to DASD devices

CRITERIA TEXCP GT 0 OR DEXCP LT 10000CRITERIA JOBNAME EQ ABC- OR JOBNAME EQ A*

Example 8

The next example selects only those jobs that:

• Have more than 10000 EXCPs

• Or have more than 1 minute of CPU time

The commands look like this:

CRITERIA EXCP GT 10000CRITERIA CPUTIME GT 1:00

Specifying output criteria

To specify an output data set:

• Use the COPY command if you want to specify an output data set or file to receive all or subsets of the job history records read in from the input source.

ESP Workload Manager writes to any format sequential data set. If a data set is new and you have not yet specified a record format for it, ESP Workload Manager uses the following default: LRECL=4096, RECFM=VBS, BLKSIZE=6144.

To separate data into different files:

• Use the COPY option when you want to separate data in a history file into one or more files.

The example below sends records to tape after they are 12 weeks old:

REPORTHISTFILE HIST1CRITERIA RDRON GT TODAY LESS 12 WEEKSCOPY SELECT FILE(DISK1)COPY REJECT FILE(TAPE1)


ESP-5.4-UG-05 285

To specify the date format:

• Change the default using the DATEFORM command.

History reporting displays date fields in DDMMMYY format by default.

The options are as follows:

Note: This setting only affects the date format you use to display fields in a history report; it does not affect the date format you use on a CRITERIA command, and it does not affect the date format used in schedule criteria.

Example: DATEFORM

In the following example, the date format is set to YMD. Any date fields, such as EXECSDATE (start date), displayed in the report will be in YYYYMMMDD format.

DATEFORM YMD

To specify fields to display:

Use the DISPLAY command to specify the fields you want to display. Then you have the option to define titles.

Entering field names

Once you start the DISPLAY section, you can enter several field names one after the other. Separate each by a blank or a comma, along with optional lengths and titles. ESP Workload Manager places the fields you specify on the report detail line in the order you specified them. To view all the values possible for field, see “ESP Workload Manager history reporting fields” on page 289.

DATEFORM Results Example

DMY This is the default.

Day DDMMMYY MON14MAY01

JULIAN Day DDDYY MON13401

YM Day YYYYMMM MON200105

YMD Day YYYYMMMDD MON20010514

MDY Day MMMDDYY MON051401

Section–Specifying output criteria

286 ESP-5.4-UG-05

Example

In the following example, ESP Workload Manager:

• Displays both job name and the reader-on time and date, along with their default titles

• Restricts the reader-on date to five characters

• Displays the tape and disk EXCP count to five and six digits respectively

• Includes special title segments for the last two fields

DISPLAY JOBNAME, RDRON, RDRONDATE 5, TEXCP 'TAPE' -'EXCPS' DEXCP 6 'DISK' 'EXCPS'

To specify the sort criteria:

• Use the SORT option to specify the fields you want to sort and whether you want the sort sequence to be ascending or descending.

The default is ascending. The following example sorts data by decreasing use of CPU time. ESP Workload Manager displays the data in sequence of ascending DASD EXCP counts.

SORT CPUTIME D DEXCP

To specify other formats:

• Use the BREAK command to define the points in the report where you want to:• Force a new page• Print any number of blank lines• Produce a subtotal

You can specify several break elements in a break section. ESP Workload Manager subtotals only meaningful fields such as CPUTIME and DEXCP, but not JOBNO. The subtotal detail line has the same format as the normal detail line, except that it always has the word subtotal starting in column one. The next column displays the number of items ESP Workload Manager sub-totaled. The preceding information occupies the first 14 character positions on the line. When you create a detail line, do not place any fields you want ESP Workload Manager to subtotal in the first two columns.


ESP-5.4-UG-05 287

Example: Specifying a format

In the following example:

• When the first three characters of the first account number change, ESP Workload Manager prints a subtotal and starts a new page.

• When the first two characters of the job name change, ESP Workload Manager leaves one blank line.

DISPLAY JOBNAME JOBNO ACCOUNT RDRON DEXCP TEXCPSORT ACCOUNT JOBNAMEBREAK ACCOUNT 3 EJECT SUBTOTALBREAK JOBNAME 2 SPACE 1

Ending the report definition

To end the report definition:

• Use the ENDR command to mark the end of a report definition and initiate the report generation.

Example: Reporting on an Application

This example reports on all jobs in an ESP Application called PAYROLL that have changed status since 8 am today. The SETWIDTH command sets the width of the report to 80 characters.

REPORT SETWIDTH 80 FROM 8:00AM TODAY CRITERIA APPLSYS EQ PAYROLL DISPLAY JOBNAME CMPC EXECST EXECSDATE ENDT ENDDATE CPUTIMEENDR

Sample output from the above commands is shown below.

JOBNAME JOBNO COMP CODE

EXEC START

START DATE

EXEC END END DATE

CPU TIME

PAYD001A 2221 0 11.56 MON 14MAY01 12.02 MON 14MAY01 0:01






PAYD008A 2234 SOC1 12.08 MON 14MAY01 12.08 MON 14MAY01 0:00





Section–Ending the report definition

288 ESP-5.4-UG-05

Example: Reporting in batch

In the example below, the first four lines represent JCL statements, and the remaining lines define a report. The report includes information on jobs whose first account number begins with PAY that ESP Workload Manager has tracked from 6 pm yesterday until 8 am today.

//REPORT JOB ...//EXEC PGM=ESP,REGION=4000K//SYSPRINT DD SYSOUT=X//SYSIN DD *REPORTHISTFILE HIST1FROM 6PM YESTERDAY TO 8AM TODAYCRITERIA ACCOUNT EQ PAY-;DISPLAY JOBNAME, JOBNO, ACCOUNT, DEXCP, TEXCPSORT ACCOUNT BREAK ACCOUNT 4 EJECT SUBTOTALENDR

Note: When the reporting job is executed in batch, a hyphen at the end of a line indicates a continuation. If you are using a hyphen as a mask, follow it with a semi-colon (for example PAY-;).



SUBTOTAL (13) 0:06

TOTAL (13) 0:06

JOBNAME JOBNO COMP CODE

EXEC START

START DATE

EXEC END END DATE

CPU TIME


ESP-5.4-UG-05 289

Example: Writing report output to a data set

The following example writes a history report to a new data set. The report includes information on jobs with names beginning with CYB that ESP Workload Manager has tracked since 4 pm on the current day.

//HISTRPT JOB (CYB1000),'HIST.REPORT',CLASS=A,MSGCLASS=O,//NOTIFY=CYB01//STEP1 EXEC PGM=ESP,REGION=4000K,PARM='SUBSYS(ES51)'//STEPLIB DD DSN=CYB8.SCP5100.SSCPLINK,DISP=SHR//SYSPRINT DD DSN=CYB2.NF.HISRPT,DISP=(NEW,CATLG,DELETE),// DCB=(RECFM=FB,LRECL=133,BLKSIZE=13300),// UNIT=SYSDA,SPACE=(CYL,(1,1),RLSE),VOL=SER=WORK01//SYSIN DD *REPORTHISTFILE HIST1CRITERIA JOBNAME EQ CYB-;FROM 4PM TODAYDISPLAY JOBNAME JOBNO CMPC MXCMPC EXECST EXECQT CPUTIMESORT JOBNAME DBREAK JOBNAME 4 EJECT SUBTOTALENDR

ESP Workload Manager history reporting fields

The following are history reporting fields.

Field Explanation

ACCOUNT Specifies the job first account operand, can also be specified as ACCOUNT1.

ACCOUNT2 Specifies the job second account operand.

ACCOUNT3 Specifies the job third account operand.

ACCOUNT4 Specifies the job fourth account operand

AGENT Specifies the Agent name as stated in the AGENT statement.

ALLOCQT Specifies the allocation queue time. This is the total time the job spends in the allocation process (for example waiting for tape mount).

APPLGEN Specifies the Application generation number (absolute).

APPLSYS Specifies the Application name for jobs defined to an Application; can also be specified as APPL.

APPLTAG Specifies the tag associated with a job in an Application.

ASID Specifies the address-space identifier of an executing z/OS job.

AUTHSTR Indicates job authority string that you can use to verify ownership of the job.

AVGRUNT Specifies the job average execution time.

Section–ESP Workload Manager history reporting fields

290 ESP-5.4-UG-05

CCFAIL Indicates whether or not the job failed because of condition codes. The field has a value of YES if the job failed because of a condition code, and the value is NO otherwise.

CLASSID Specifies the ESP Workload Manager class to which you defined the Event.

CMPC Specifies the job completion code, including return code, user abend code, or system abend code. For more information on the different completion codes, go to the last page of the History Reporting Field topic.

COMPDATE Specifies the job completion date: it is the date on which the job completed its last post-processing phase. If the job has no post-processing phases, the completion date is the same as the purge date. (See note at the end of the table.)

COMPT Specifies the job completion time: it is the time at which the job completed its last post-processing phase. If the job has no post-processing phases, it is the same as the purge time. (See note at the end of the table.) COMPT is set equal to the ENDT field for distributed workload.

CPUTIME Specifies the total CPU time, including both SRBTIME and TCBTIME.

DEXCP Specifies the total EXCP count to DASD devices.

ENDDATE Specifies the date at the end of execution.

ENDT Specifies the time at the end of execution.

ESPSUB Indicates whether or not the job was submitted by ESP Workload Manager. It has a value of YES if the job was submitted by ESP Workload Manager (either through an Event or as part of an Application); otherwise, it has a value of NO.

EXCP Specifies the total EXCP count for the job during the execution phase.

EXEC# Specifies the number of times the job has executed as part of a particular generation of an Application.

EXECNODE Specifies the JES node name where a z/OS job is executing or waiting for execution (for example, LOCAPPL operand).

EXECQT Specifies the elapsed time for the job during the execution.

EXECSDATE Specifies the date at the start of the execution.

EXECST Specifies the execution start time. For example, 08:26.

EXECSYS Specifies the system where the job executed. This is not set until the job is purged regardless of your tracking options.

EXEJOBNO Specifies the JES job number where the job executed. This value is different from the SUBJOBNO value when the job executes on a node different from the node it was submitted to.

Field Explanation


ESP-5.4-UG-05 291

GROUP Specifies the prefix of the Event associated with the job, if ESP Workload Manager submitted it.

INFOREC Specifies the Info/System record number.

INPUTQT Specifies the length of time the job was in the input queue.

INSYS Specifies the system the job was submitted on. This is not set until the job is purged regardless of your tracking options.

JOBCLASS Specifies the JES execution class.

JOBNAME Specifies the name of the job.

JOBNO Specifies the job number. This value is the submit job number before and after the job executes and the execution job number during the time the job executes.

JOBQUAL Specifies the ESP Workload Manager job qualifier.

LINES Specifies the number of print lines.

LONGNAME Specifies the long name of a job.

MAXRUNT Specifies the job longest expected execution time.

MINRUNT Specifies the job shortest expected execution time.

MSGFAIL Indicates whether or not the job failed because of an ESP Workload Manager SYSMSGS command. The field has a value of YES if the job terminated because of the ESP Workload Manager SYSMSGS facility, and the value is NO otherwise.

MXCMPC Specifies the maximum completion code for the job.

MXRC Specifies the highest return code from any step in the job. This is a numeric field. For more information, see “Numeric fields” on page 296.

NCI Specifies the number of card images submitted to the internal reader.

NETID Specifies the network identifier for a job belonging to a DJC/JES3 job network.

NSTM Specifies the number of nonspecific tape mounts (scratch tapes) for the job.

ORIGNODE Specifies the job original or submission JES node.

OUTSYS Specifies the system the job was purged on. This is not set until the job is purged regardless of your tracking options.

OVDBEGAT Specifies the time at which the job last became overdue for start.

OVDCOMP Specifies the amount by which the job was overdue at the time of completion. The criteria for being late are defined by the DUEOUT OUTPUT statement in an ESP Procedure or in a job tracking model.

OVDEND Specifies the amount of time by which the job was late in ending execution. The criteria for being late are defined by the DUEOUT EXEC statement in an ESP Procedure or in a job tracking model.

Field Explanation


292 ESP-5.4-UG-05

OVDENDAT Specifies the time at which the job last became late in ending execution.

OVDSTART Specifies the amount of time by which the job was late in starting execution. The criteria for being late are defined by the DUEOUT INPUT statement in an ESP Procedure or in a job tracking model.

OVDSUBAT Specifies the time at which the job last became overdue for submission.

PGMR Specifies the contents of the programmer name field for the job.

PGN Specifies the performance group number of an executing z/OS job. This applies only to jobs running in a compatibility mode system.

POSTQT Specifies the elapsed time spent in post-output processing phases.

PRINTQT Specifies the length of time the job remained in the print queue.

PRIORITY Specifies the job JES execution priority. It has a value between 0 and 15.

PURGDATE Specifies the date of job purge.

PURGT Specifies the purge time. PURGT is set equal to the ENDT field for distributed workload.

RC Specifies the return code from the last step executed in the job. This is a numeric field. For more information, see “Numeric fields” on page 296.

RDRON Specifies the time at which ESP Workload Manager read the job into the system. RDRON is set equal to the EXECST field for distributed workload.

RDRONDATE Specifies the date at job submit time. This field also includes the time for sorting purposes but not for display purposes.

RRJOB Specifies the name of job being rerun or null.

RRJOBNO Specifies the job number of the most recent execution of a resubmitted job. This field only has a value for a job that is being rerun by ESP Workload Manager (for example, a job that has been resubmitted via an explicit AJ command or the R line command in CSF). If the job is not a rerun, this field is set to zero.

RTYPE Specifies the run type as follows:Value Explanation

P A primary run—set for a normally scheduled execution or by a TRIGGER REPLACE command.

T An extra run—set by a TRIGGER ADD command.

D An execution caused by data-set activity.

R A rerun.

SCHEDDATE Specifies the scheduled date.

SCHEDT Specifies the scheduled time.

Field Explanation


ESP-5.4-UG-05 293

SID Specifies the SMF identifier of system that z/OS job is executing on.

SPTM Specifies the number of specific (for example, non-scratch) tape mounts for the job.

SRBTIME Specifies the CPU time consumed while in SRB mode.

SRVCLASS Specifies the service class of an executing z/OS job. This applies only to jobs running in a goal mode system.

STATUS Specifies the job status. There are four possible values:Value Explanation

INPUT Defines submitted jobs not yet started.

STARTED Defines jobs currently in execution.

COMPLETE Defines jobs that completed all phases of processing.

ENDED Defines jobs that completed execution but did not finish all phases of processing.

STEPS Specifies the number of job steps.

SUB# Specifies the submission number for a job in an Application.

SUBAPPL Specifies the subApplication identifier.

SUBJOBNO Specifies the JES job number where job was submitted. This is useful when a job is submitted on one system and routed to another system where a different JES job number is assigned.

SUNITS Specifies the job service units, as defined by the SRM.

SYSABD Specifies the system abend code or null.

SYSNAME Specifies the name of the system in the sysplex that z/OS job is executing on.

SYSPLEX Specifies the name of the sysplex that z/OS job is executing on.

TAPEM Specifies the number of tape mounts for the job.

TAPEW Specifies the maximum number of tape drives allocated to a job at one time. Note that SPTM and NSTM may not add up to TAPEW. SPTM and NSTM represent numbers of tape mounts. TAPEW counts the number of different tape drives that were used at one time. For example, if a job-step calls for three specific tapes, one at a time, on the same drive, then TAPEW will be one, but SPTM will be three.

TCBTIME Specifies the CPU time consumed while in TCB mode.

TEXCP Specifies the total EXCP count to tape drives.

TMODEL Specifies the name of the ESP Workload Manager tracking model that was used to track the job.

TOTALQT Specifies the total elapsed time for the job.

Field Explanation


294 ESP-5.4-UG-05

TRANSACT Specifies the total time for which a transaction is active. In the case of a batch job, this is approximately equal to the total execution times for the programs contained in the job. It is measured in units of 1024 microseconds.

TRANSRES Specifies the total time during which a transaction was resident in real memory. This is often identical to the transaction active time (TRANSACT), but can differ since it does not include any time during which the task was swapped out of real memory. It is measured in units of approximately one millisecond, or more precisely, units of 1024 microseconds.

TRUSER Specifies the user ID that triggered the Event. It resolves to the user ID that manually triggered an Event, and is blank otherwise.

UABEND Specifies the user abend code or null.

WDFAIL Indicates whether or not there was a WTO-detected JCL error. The field has a value of YES if the job terminated prior to starting execution, and the value NO otherwise. These errors are caused by such activities as an early (pre-execution) JCL error, certain security-system verification errors, and a cancellation of a job while it is on the JES input queue.

Field Explanation


ESP-5.4-UG-05 295

ESP Workload Manager may not track jobs through to the output stage at your installation. For such jobs:

• The times specified in the COMPDATE and COMPT fields refer to when the jobs complete successfully.

• The LINES, POSTQT, PRINTQT, PURGDATE, and PURGT fields are not applicable.

WOBTYPE Specifies the short name of workload object types:.Value Description

AE ApplEnd

AM AGENT_MONITOR

AX Aix_Job

A4 AS400_Job

CM CPU_Mon

DM DB_Job

DT DSTRIG

EX EXTMON

FM File_Trigger

FT FTP_JOB

HM DISK_Mon

HP HPUX_Job

IM IP_Mon

LJ Linux_Job

LM EVENTLOG_Mon

NC NCR_Job

NT NT_Job

OV OpenVMS_Job

PM PROCESS_Mon

PS PS_Job

SJ Sun_Job

SM SERVICE_Mon

SP SAP_Job

SQ Sequent_Job

TA Tandem_Job

TM TEXT_Mon

UJ UNIX_Job

Field Explanation


296 ESP-5.4-UG-05

Numeric fields

The RC and MXRC fields contain strictly numeric values. For cases where a completion code is non-numeric (for example JCL errors, system or user abends, CCFAIL), special values are inserted in these fields as an indication of the actual completion status.

The following table lists the completion codes:

Field length change

All fields that represent Time previously displayed minutes and hours. As of ESP Workload Manager 5.1, these displays now include seconds. This causes an increase in the field length for coding purposes. Knowing this is important if you produce a history report and use another program (for example SAS) to pull data out of the report.

Type of Error Value

System ABEND Abend code + 10000 (abend code converted to decimal first)

User ABEND Abend code + 20000

SYSERROR 30000 (actual completion status unavailable)

CCFAIL 30001 (terminated by CCFAIL or CCCHK logic)

JCLERROR 30002

RUNNING 32767 (job still executing)


ESP-5.4-UG-05 297

Example: History report showing overdue jobsREPORTINPUT DATASET('CYB1.TONYT540.HISTFILE')CRITERIA JOBNAME EQ WAIT5 OR JOBNAME EQ CALCFROM MAY 1 2004DISPLAY JOBNAME,JOBNO,APPLSYS,OVDSUBAT,OVDBEGAT,OVDENDAT,OVDENDSORT EXECSDATE EXECST JOBNAMEENDRCYBERMATION ESP VER 5.4.0 BATCH INTERFACE 10.06.25 THURSDAY MAY 13TH,

JOBNAME JOB APPLSYS OVERDUE OVERDUE OVERDUE OVERDUE NO SUBMIT SINCE START SINCE END SINCE END FORWAIT5 52329 - - - -WAIT5 52701 TESTSAD - - - -WAIT5 57042 TESTSAD - - - -WAIT5 57780 RFE1214A 5MAY04 13.00 5MAY04 13.01 5MAY04 13.04 3M02WAIT5 57998 RFE1214 - - 5MAY04 14.56 3M01WAIT5 58016 RFE1214 - - 5MAY04 15.06 1M13WAIT5 58178 TESTSAD - - - -WAIT5 60836 RFE1214 - - 6MAY04 10.39 3M01WAIT5 60846 RFE1214A 6MAY04 10.38 6MAY04 10.39 6MAY04 10.42 3M03WAIT5 60894 RFE1214 - - 6MAY04 11.01 3M01WAIT5 60961 RFE1214 - - 6MAY04 11.10 3M01WAIT5 60997 TSTRFES - - 6MAY04 11.19 1M02WAIT5 61218 RFE1214 - - 6MAY04 12.40 3M02WAIT5 61231 RFE1214A 6MAY04 12.48 6MAY04 12.49 6MAY04 12.52 3M01WAIT5 61270 - - - -WAIT5 61291 - - - -WAIT5 61404 - - - -WAIT5 61683 TESTSAD - - - -WAIT5 63421 TESTSAD - - - -WAIT5 11567 TESTSAD - - - -WAIT5 19967 TESTSAD - - - -WAIT5 19974 RFE1214A 13MAY04 08.52 13MAY04 08.53 13MAY04 08.56 3M00WAIT5 20007 RFE1214A 13MAY04 09.01 13MAY04 09.02 13MAY04 09.05 3M01

Accumulating reporting fields

Totals are produced for the following reporting fields:

• ALLOCQT • NSTM • STEPS

• CPUTIME • OVDCOMP • SUNITS

• DEXCP • OVDEND • TAPEM

• EXCP • OVDSTART • TCBTIME

• EXECQT • POSTQT • TEXCP

• INPUTQT • PRINTQT • TOTALQT

• LINES • SPTM • TRANSACT

• NCI • SRBTIME • TRANSRES

Section–Reporting on scheduled activity

298 ESP-5.4-UG-05

Reporting on scheduled activity

The scheduled-activity facility reports on the scheduled workload for a time period in the future. You can generate online and hardcopy reports about scheduled jobs, links, tasks, and manual jobs. The reports provide a variety of job statistics that indicate processing requirements. The data the report generates uses average execution results from tracked jobs to provide a true picture of what you can expect during the next scheduled occurrence of the jobs.

Note: This facility reports on job workload that is not yet active. Jobs in an active Application are excluded, for example.

To set up schedule forecasting:

1. Allocate a sequential data set to store scheduled activity data. See the SADGEN command in the ESP Workload Manager Reference Guide.

2. Generate data on scheduled jobs.

3. Extract data to create a report.

4. Update data to obtain a scheduled versus actual report. (This is an optional Procedure.)

Generating data

To generate data that you can use for scheduled-activity reporting, ESP Workload Manager must simulate all the Events and ESP Procedures it would execute in a specified period. ESP Workload Manager does this by executing the ESP Workload Manager subsystem started task Procedure in batch with a special parameter (PARM='SAR' or PARM='SAD'). The output generated by this simulation forms a scheduled activity data set.

You can also create multiple schedule-activity data sets. You can generate separate data sets on scheduled activity for the next day or for the next week, or you want different activity data sets for different production groups.

Note: ESP Workload Manager does not reflect an Event in the scheduled activity data set unless it contains either a SCHEDULE or EXPECT command.

SADGEN command

When creating a job to generate a scheduled-activity data set, you can limit the simulation to specific Event data sets, prefixes, and classes using the different operands of the SADGEN command.


ESP-5.4-UG-05 299

You can also use the ESPSADG symbolic variable in an ESP Procedure to affect the simulation. This variable is set equal to 1 during SADGEN processing; otherwise, it is set to zero. For example, the following statement at the beginning of an ESP Procedure causes ESP Workload Manager not to simulate the Procedure during SADGEN processing:

IF ESPSADG=1 THEN QUIT

When ESP Workload Manager creates a scheduled activity data set, it contains a record for each job you want to submit, within the time range you have specified on a schedule command. If you specify neither the FROM nor TO time range, ESP Workload Manager provides the following default:

'NOW' TO '6AM TOMORROW'

You can use the EXTERNALS operand to add an extra entry on the SADGEN data set for each external job found within the specified scheduling criteria.

Example

The example below is a batch job, SADGEN, that generates a scheduled activity data set called CYBER.SAD. The name of the started task Procedure for ESP Workload Manager is ESP.

//SADGEN JOB...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD *//SYSIN DD *SADGEN DATASET('CYBER.SAD') -FROM('8AM TODAY')TO('8AM TOMORROW')

Extracting data

After ESP Workload Manager generates the data, you can extract data to produce a standard-format scheduled-activity report. You can create the report either in batch or online using the LSAR command, or using option S on the Main Menu.

Section–Extracting data

300 ESP-5.4-UG-05

LSAR command

The LSAR command generates a standard scheduled activity report that includes the following data:

• Job name. A character following the job name identifies a specific job type:• T = Task• M = Manual• R = Request• L = Link• E = External• blank = other job type

• Scheduled submit date and time. These reflect the Event schedule time unless you use the modeling feature to provide estimated submit times.

• Number of samples used for average.

• Average values for previous job executions:

• Elapsed execution time• CPU time• Number of print lines• Number of specific and non-specific (scratch) tape mounts• Number of tape drives required• DJC network and/or Application• Fully qualified Event identifier

• Total values for previous job executions:

• Number of jobs• Number of jobs without statistics• Initiator time• CPU time• Number of print lines• Number of specific tape mounts• Number of non-specific (scratch) tape mounts

Note: If you do not use the FROM keyword, the starting time for this report defaults to now.

Example: Displaying scheduled activity data

The following example requests a report on activity scheduled in an 8 hour period starting at 5 am using the data set CYBER.SAR. ESP Workload Manager presents the data in scheduled time sequence.

LSAR DSN('CYBER.SAR') FROM('5AM TODAY')-TO('1PM TODAY') TIMESEQ


ESP-5.4-UG-05 301

Generating scheduled versus actual report

You can update a scheduled activity data set with current job status, creating a scheduled versus actual report. ESP Workload Manager calculates the completion status of a schedule, so that you can see how much work has been completed and how much remains.

If you use CSF to monitor the workload, you receive more up-to-date information because ESP Workload Manager automatically updates the CSF. However, to generate a hardcopy report on the current status from CSF, you can code your own extensions. For more information on CSF, see “Consolidated Status Facility (CSF)” on page 221.

SADUPD command

You perform the schedule update in a similar way to the schedule activity generation. Instead of the SADGEN command, use the SADUPD command. ESP Workload Manager can run a job at frequent intervals during a day to update the scheduled activity data base. The job executes in a fraction of the time of the original schedule generation.

After ESP Workload Manager has run the scheduled update, use the STATUS operand on the LSAR command, or specified on the Option S panel, to request a status display instead of the regular schedule display. This provides the status of all jobs in the schedule, as well as the time and percent of the schedule still remaining. ESP Workload Manager displays actual start and end times, completion codes, and rerun indicators.

Example 1: Creating a scheduled activity data set

This example uses JCL to create the scheduled activity data set:

//SADGEN JOB CYB1000,CLASS=A//S1 EXEC ESP,PARM='SAR'//SYSIN DD *SADGEN DATASET('CYBER.ESP.SAD') -FROM('5AM TODAY')TO('5AM TOMORROW')

Example 2: Updating a scheduled activity data set

This example shows the JCL which can be used to provide an update on this scheduled activity:

//SADUPD JOB CYB1000,CLASS=A//S1 EXEC ESP,PARM='SAR'//SYSIN DD *SADUPD DATASET('CYBER.ESP.SAD')

Section–Generating projected versus actual data

302 ESP-5.4-UG-05

Generating projected versus actual data

The scheduled activity update feature provides you with actual start and end times for jobs. ESP Workload Manager modeling feature can project these times in advance. As a result, ESP Workload Manager can generate a Projected versus Actual report that shows each job’s projected and actual start and end times. For detailed information on modeling, see the ESP Workload Manager Advanced User’s Guide.

To generate a projected versus actual report:

1. Before ESP Workload Manager starts the workload you are interested in, generate a scheduled activity data set using the SADGEN command in a batch job.

2. When the SADGEN completes, run a model in batch. The model processor updates each job’s projected start and end times in the SADGEN data set. Ensure that the model processing covers the appropriate period.

3. After all jobs in the SADGEN data set are complete, update the scheduled activity data set using the SADUPD command in a batch job.

4. Use the LSAR command with the PROJECTED operand to generate a Projected versus Actual report.

LSAR DSN('CYBER.SADFILE') PROJECTED

Extracting tape information

You can request the ESP Workload Manager extract tape volume serial information during a scheduled-activity data-set generation run. ESP Workload Manager references the tape management catalog when it generates the scheduled activity data set.

ESP Workload Manager can then generate a data set using this extracted information and feed the data set into the TMS or CA1 tape pull program.


ESP-5.4-UG-05 303

To extract tape information:

1. Use the INPUTDS statement in the job documentation data set or ESP Procedure identifying the tape data sets associated with each job. For example:

JCLLIB PROD.JCLAPPL PAYROLLJOB JOB1 RELEASE JOB2ENDJOBJOB JOB2 INPUTDS PROD.GDG(-1)ENDJOBSELECT (JOB1,JOB2)

2. Generate a scheduled activity using the SADGEN command in a batch job.

3. Use the LSAR command specifying TAPEPULL(dsname), where dsname is the pre-allocated PDS to store tape data set information. An example is shown below:

LSAR DSN('CYBER.ESP.SAD') TAPEPULL('PROD.TAPE.PULL')

4. ESP Workload Manager creates a member for each job. You should re-initialize the TAPEPULL data set before you generate the scheduled activity data set.

5. Use this PDS as input to the TMS or CA1 tape pull program.

Using job mapping

Job mapping is a reporting facility you use produce detailed job information. You can generate the following reports:

Unlike the scheduled-activity report, which is based on time, the job mapping feature generates data based on Event names. These Events can be scheduled or can require data set or manual triggers. There is no need for these Events to have executed because history data is not required for the jobs. If history data is available, this historical information is incorporated into the reports.

Type of Report Content of Report

Job activity This report contains detailed information on jobs including job name, Application name, job type, Event name, ESP Procedure name, JCL library, execution time, CPU time, and predecessor and successor jobs.

Job descendent This report shows a job and its successors.

Section–Using job mapping

304 ESP-5.4-UG-05

To set up job mapping:

1. Allocate a sequential data set to store the job mapping data. See below.

2. Generate data for the report using the MAPGEN command. See “Generating data for the report” on page 304.

3. Use the JOBMAP command to display a job activity report or use the JOBTREE command to display a job descendent report. See “Producing a job-activity report” on page 305.

Job-mapping data set

Allocate a sequential data set to store the data. This is referred to as the job-mapping data set.

Generating data for the report

Before performing this step, you must allocate a sequential data set to store the data. See “Job-mapping data set” on page 304.

Use the MAPGEN command to generate data for the job-mapping data set that can be used by the JOBMAP and JOBTREE commands to produce reports. To use the MAPGEN command, use a batch job that executes the ESP Workload Manager started task with the special parameter, PARM='SAR' or PARM='SAD'.

The MAPGEN command takes the information for an Event, or set of Events, and stores it in your job mapping data set. To use this command, specify the name of your job mapping data set and an Event descriptive name (for example, without the prefix), which can include wildcards.

Note: You must use the MAPGEN command in batch.

Example 1

In the following example, ESP Workload Manager generates data for all Events and stores the output in the ESP.MAPGEN data set. The name of the started task for ESP Workload Manager is ESP.

//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(-)

Explanation Attributes for 3390 DASD Otherwise use

Organization PS PS

Record format VBS VBS

Record length 32756 32756

Block size 27998 16384


ESP-5.4-UG-05 305

Example 2

In the following example, the MAPGEN command causes ESP Workload Manager to generate data for all Events with descriptive names that start with PAY and store the output in the ESP.MAPGEN data set.

//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(PAY-)

Producing a job-activity report

Before performing this step, you must generate data for the report. See “Generating data for the report” on page 304.

JOBMAP command

Use the JOBMAP command to produce a job-activity report. This report contains detailed job information. For each job, regardless of its frequency, the job-activity report lists the following information:

• Job name (An M or a T can follow the job name, indicating that the job is a manual job or a task)

• Application name• Job type (for example, job, request, manual, external)• Scheduled frequency• Job qualifier• Event name• Calendar names• JCL data set and member name• Indication if the JCL data set is a JCLLIB or TEMPLIB• Scope for external and manual jobs• Job class• Programmer name• Tape drive and mounts (both cartridge and reel)• Elapsed execution time• CPU time• Hold count• List of predecessor jobs• List of successor jobs• List of resources• ESP Procedure data set and member names• Tag

To use the JOBMAP command:

• Specify the name of your job-mapping data set.


306 ESP-5.4-UG-05

Because this command uses the job-mapping data set as input, you can report only on jobs contained in that data set. You can use the JOBMAP command in batch, by executing PGM=ESP with the correct SUBSYS parameter, or in Page mode.

Example - Using JOBMAP in batch

The following example creates a job-activity report for all jobs. The subsystem name for ESP Workload Manager in this example is ESPM.

//MYJOB JOB ...//S1 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD *JOBMAP DSN('ESP.MAPGEN')

Example: Using JOBMAP in Page mode

The following example creates a job-activity report, for all jobs, in Page mode.

JOBMAP DSN('ESP.MAPGEN')


ESP-5.4-UG-05 307

Reviewing the output

For each job, ESP Workload Manager produces output similar to the following:

Customizing your job-activity report

Because of the amount of data generated for each job, you can limit the report to a specific Application, produce an index, or suppress certain fields in your report.

Generating a report for a specific Application

You can use the APPL operand to restrict the data to a specific Application. The following example lists a job activity report for all jobs in the PAYROLL Application.

JOBMAP DSN('ESP.MAPGEN') APPL(PAYROLL)

Generating an index

You can use the JOBINDEX, APPLINDEX, and RESINDEX operands to produce an index by job name, Application name, or resource name, respectively.

The following example creates a job activity report with an index by job name and an index by Application name.

JOBMAP DSN('ESP.MAPGEN') JOBINDEX APPLINDEX

JOB NAME APPL NAME TYPE SCHEDULING

PAYJOB01 PAYROLL JOB SCHEDULED: DAILY

QUALIFIER:

EVENT: CYBER.PAYJOB01 SYSTEM

CALENDAR (S):

JCL: MY.JCLLIB (PAYJOB01)

SCOPE:

CLASS: A

PROGRAMMER: J. DOE

TAPES: REEL DRIVES: 0

REEL MOUNTS: 0

CART DRIVES: 0

CART MOUNTS: 0

ELAPSED: 0H 0M 0S

CPU: 0H 0M 0S

HOLD COUNT: 0

AFTER: –NONE–

BEFORE: PAYJOB02

PAYJOB03

RESOURCES: –NONE–

PROC: MY.ESPPROC (PAYJOB01)

TAG:


308 ESP-5.4-UG-05

The following is a sample index of jobs that will appear at the end of your job-activity report:

JOB INDEX

JOB NAME APPL NAME PAGE-------- --------- ----PAYJOB01 PAYROLL 1PAYJOB02 PAYROLL 2PAYJOB03 PAYROLL 2END OF LIST

The following is a sample index of Applications that will appear at the end of your job-activity report:

APPLICATION INDEX PAGEAPPL NAME JOB NAME PAGE--------- -------- ----PAYROLL PAYJOB01 1 PAYJOB02 2 PAYJOB03 2END OF LIST

Suppressing fields

To suppress certain fields:

• Use the NODISPLAY operand.

You can suppress the following fields:

Field Description

CALENDAR Calendar names.

CLASS Job class.

CPU CPU time.

ELAPSED Elapsed execution time.

EVENT Event name.

HOLDCOUNT Hold count.

JCLDS JCL data set and member name.

PGMER Programmer name.

PRED List of predecessor jobs.

PROC ESP Procedure data set and member name.

RESOURCE List of resources.

SCOPE Scope (externals and manuals only).

SUCC List of successor jobs.

TAG Tag.

TAPES Tape drives and mounts (both cartridge and reel).


ESP-5.4-UG-05 309

The following example suppresses the display of CPU time, elapsed execution time, tape drives, and mounts.

JOBMAP DSN('ESP.MAPGEN') NODISPLAY(CPU,ELAPSED,TAPES)

Producing a job-descendent report

To produce a job-descendent report:

• Use the JOBTREE command.

This report lists a job and all successor, or descendent, jobs.

Because the JOBTREE command uses the job-mapping data set as input, you can report only on jobs contained in that data set. You can use the JOBTREE command in batch, by executing PGM=ESP with the correct SUBSYS operand, or in page mode.

To use the JOBTREE command:

Specify:

• The name of the job-mapping data set• The specific name of a job• Optionally, the name of an Application to which the job belongs

If you do not specify the name of an Application, ESP Workload Manager examines all Applications in the job-mapping data set for a match and uses the first one that it finds.

Example: Using JOBTREE in batch

In the following example, a job-descendent report is produced for job PAYJOBA. The subsystem name for ESP Workload Manager, in this example, is ESPM.

//MYJOB JOB...//S1 EXEC PGM=ESP, PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD*JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)

Example: Using JOBTREE in page mode

The following example creates a job-descendent report, for job PAYJOBA, in page mode.

JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)

Section–Producing a job-descendent report

310 ESP-5.4-UG-05

Example

In the following example, a job-descendent report is produced for job START.APPL in the PAYROLL Application.

JOBTREE DSN('ESP.MAPGEN') JOB(START.APPL) APPL(PAYROLL)

Reviewing the output

The report uses indentation to indicate successor relationships. A job that is indented farther than the job on the previous line indicates a successor relationship.

Consider the following flow of jobs:

A job descendent tree for PAYJOBA looks like the following. PAYJOBA releases PAYJOBB and PAYJOBC, PAYJOBB and PAYJOBC release PAYJOBD, and PAYJOBD releases PAYJOBE.

JOB DESCENDENT TREEPAYJOBA JOB PAYROLLPAYJOBB JOB PAYROLLPAYJOBD JOB PAYROLLPAYJOBE JOB PAYROLLPAYJOBC JOB PAYROLLPAYJOBD JOB PAYROLLPAYJOBE JOB PAYROLL

PAYJOBA

PAYJOBB PAYJOBC

PAYJOBD

PAYJOBE


ESP-5.4-UG-05 311

Putting it all together

Sample batch job

The following is a sample batch job to:

• Allocate a job-mapping data set (STEP1)

• Generate data for the job-mapping data set for all Events with descriptive names that start with P (STEP2)

• Generate a job-activity report, with an index by job name, for all jobs in the PAYROLL Application (STEP3)

• Generate a job-descendent report for START.APPL in the PAYROLL Application job name (STEP3)

//MYJOB JOB ...//STEP1 EXEC PGM=IEFBR14//ALLOC DD DSN=MY.MAPGEN,// DISP=(,CATLG),// UNIT=SYSDA,SPACE=(TRK,(40,20)),// DCB=(DSORG=PS,RECFM=VBS,LRECL=32756,BLKSIZE=16384)//STEP2 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=A//SYSIN DD *MAPGEN DATASET('MY.MAPGEN') EVENT(P-)//STEP3 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=A//SYSIN DD *JOBMAP DSN('MY.MAPGEN') APPL(PAYROLL) JOBINDEXJOBTREE DSN('MY.MAPGEN') JOB(START.APPL) APPL(PAYROLL)/*

Section–ESP Workload Manager FLOWDOC

312 ESP-5.4-UG-05

ESP Workload Manager FLOWDOC

ESP Workload Manager FLOWDOC generates reports detailing information about workload scheduled by ESP Workload Manager. The following outlines the information that is produced:

• Application/subApplication names

• Run dates

• Calendars referenced

• Job-level information:

• Whether the job is held or not• Tag field• Job type • Submission time (DELAYSUB/EARLYSUB if coded in the Application, else

Event submission time)• Job name• Hold count• Released jobs• Resource information• Scope information (look back/ahead times for manual or external jobs)• External job information (Application and job names)

Graphical representation

The entire process is represented as follows:

User InputUser Input ESPESP

CYBES091CYBES091

CYBES090CYBES090

SAD FileSAD File

FlowDocFlowDoc

VSAMVSAM


ESP-5.4-UG-05 313

ESP Workload Manager FLOWDOC components

ESP Workload Manager FLOWDOC consists of three components:

• ESP Workload Manager data generation• data base generation• Report generation

ESP Workload Manager data generation

An ESP Workload Manager SADGEN request is made to generate the ESP Workload Manager information. The following JCL provides an example of this job:

//STEP1 EXEC PGM=IEFBR14//SADGEN DD DSN=DAILY.SADGEN,DISP=(MOD,DELETE),// UNIT=SYSDA,SPACE=(TRK,0)//STEP2 EXEC PGM=IEFBR14//SADGEN DD DSN=DAILY.SADGEN,DISP=(,CATLG),// UNIT=SYSDA,SPACE=(CYL,(40,20)),// DCB=(DSORG=PS,RECFM=VB,LRECL=16380,BLKSIZE=16384)//STEP3 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *SADGEN DATASET('DAILY.SADGEN') - FROM ('TODAY') TO ('TODAY PLUS 30 DAYS') - EXTERNALS - EVENTSET(-) LEVEL(-) THRESH(0)/*

Data base generation

The data base generation step is used to create the VSAM data base. The following JCL would be used to execute this utility:

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=*//SYSIN DD * DELETE DAILY.FLOWDOC CLUSTER DEFINE CLUSTER(NAME(DAILY.FLOWDOC) - RECORDSIZE(64 32760) - KEYS(53 0) - INDEXED - SHR(3 3) - CYLINDERS(40 20) - VOLUMES(vol_ser))/*//STEP2 EXEC PGM=CYBES090//STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK//SYSPRINT DD SYSOUT=X//SYSUT1 DD DISP=SHR,DSN=DAILY.SADGEN//SYSUT2 DD DISP=SHR,DSN=DAILY.FLOWDOC


314 ESP-5.4-UG-05

Note: The space allocated for the VSAM data base should be approximately 25% greater than the space consumed by the SADGEN data set.

Report generation

ESP Workload Manager generates reports by Event or Application name along with a date range. Wild cards are permitted in the selection criteria. The following JCL would be used to generate a report:

//stepname EXEC PGM=CYBES091//STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK//SYSPRINT DD SYSOUT=*//SYSUT1 DD DISP=SHR,DSN=DAILY.FLOWDOC//SYSIN DD * FLOWDOC { PREFIX(event_prefix)EVENT(event_name)|APPL(appl_name)} { FROM('criteria') TO('criteria') | DATE('criteria') }/*

If selection by Events is desired, then you must specify PREFIX and NAME.

If selection by Applications is desired, specify the APPL operand. Applications and Events are mutually exclusive. The names specified can contain wildcards.

If a range of dates is desired, specify the FROM and TO. If only a single date is desired, then specify DATE. Single dates and date ranges are mutually exclusive.

Multiple FLOWDOC statements can be present in the input stream.

Report organization

The data is presented organized by subApplication with Application or Event. The jobs are shown in the order in which they will be executed.

If a job is referenced as a predecessor of a job in another Application as an EXTERNAL job, the referencing job name and Application name for that job is shown provided that the referencing job is part of an Application that is already on the data base.

Repeated executions of an Application or Event are grouped together to eliminate redundant reporting. These repeating Applications are shown by date. If there is any variation in the sequence of jobs executed, each variation will be shown separately. For example, if an Application has a series of jobs which run daily but some which only run on Monday, a thirty day report would display for example, 26 executions of the Application showing all of the non-Monday jobs and four executions of the Application showing all jobs.


ESP-5.4-UG-05 315

Report headings

The following shows the headings as they appear in the report, and what they mean:

Sample report generation jobs

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

Heading Description

HOLD This field is set to Y if the ESP Workload Manager JOB definition statement specified the HELD operand.

TAG This field is the first eight bytes of the job tag.

TYPE This field can be one of:• TASK a task• MAN a manual• LINK a link• EXT an external job• JOB a normal job

SUB TIME This field is the expected submission time of the job. If it is blank, then the ESP Workload Manager SADGEN process has determined no specific time. This time reflects ESP Workload Manager statements, which affect submission time such as DELAYSUB.

JOB NAME This is the job name as defined in the ESP Procedure.

HC This is the number of outstanding predecessors. If a job has no predecessors, the hold count field has a value of zero.

RELEASES This lists all of the jobs (two per line) which are released by this job. If a job does not have any successors, then (NONE) will be placed in the release field.

RESOURCE This lists all of the resources (one per line) which are used by this job.

SCOPE These fields are only present for external jobs. They represent the first and second scope times in the format hh:mm where hh is the hours and mm is the minutes.

SUCCESSOR This lists all of the downstream jobs, one per line, showing the Application name and the referencing job name. A downstream job is a job that references this job as an external. It can release this job or it can require this job as a predecessor.


316 ESP-5.4-UG-05

Example 1

The following report-generation JCL could be used to produce a report detailing information about the PAYROLL Application starting today ending tomorrow:

//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(PAYROLL) FROM('TODAY') TO('TOMORROW')

Example 2

The following report-generation JCL could be used to produce a report detailing information about an Application which is invoked by an Event called CYBER.PAYROLL on August 29th, 2000:

//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC PREFIX(CYBER) NAME(PAYROLL) DATE('AUGUST 29, 2000')

Example 3

The following report-generation JCL could be used to produce a report detailing information about the BILLING Application from 4 pm today until 4 pm two days from today:

//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(BILLING) FROM('4PM TODAY') TO('4PM TODAY PLUS 2 DAYS')


ESP-5.4-UG-05 317

Example 4

The following report-generation JCL could be used to produce a report detailing information about the CLAIMS Application from Monday to Friday. Jobs in the CLAIMS Application that have varying run frequencies will be displayed on their respective day, for example, jobs coded as RUN MONDAY will be displayed on Mondays run date.

//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(CLAIMS) DATE('MONDAY')FLOWDOC APPL(CLAIMS) DATE('TUESDAY')FLOWDOC APPL(CLAIMS) DATE('WEDNESDAY')FLOWDOC APPL(CLAIMS) DATE('THURSDAY')FLOWDOC APPL(CLAIMS) DATE('FRIDAY')

Sample JCL and report

The following example shows the report-generation JCL and the report produced by that JCL.

Report generation JCL

The following report-generation JCL could be used to produce a report detailing information about the PAYROLL and ACCTPAY Applications from September 15, 2000 until September 16, 2000:

//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A//STEP01 EXEC PGM=CYBES091//STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR//SYSPRINT DD SYSOUT=*//SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR//SYSIN DD *FLOWDOC APPL(PAYROLL) FROM('TODAY') TO('TOMORROW')

Section–Flowcharting

318 ESP-5.4-UG-05

Sample ESP Workload Manager FLOWDOC report

The following FLOWDOC report results from the previous JCL:

Flowcharting

Schedulers and operators sometimes find it helpful to have a representation of the workload. Graphic flow charts make it easier to see job dependencies and to monitor the progression of work.

Creating flowcharts

You can create flow charts of workloads using the following PC-based graphics software:

• MS Project• TIMELINE

ESP Workload Manager produces an input file for the PC software. This input file is then used in creating the graphic flow chart of the workload. You have the option of

APPLICATION: PAYROLL

RUN DATES: FRI 15 SEP 2000

***SUCCESSOR***

HOLD TAG TYPE SUBTIME JOBNAME HC RELEASES RESOURCE SCOPE APPL JOBNAME

N LINK 22.00 START PAY1 CPUABS

N PAYROLL JOB 20.00 PAY1 1 PAY2, PAY3

PAY4, PAY5

N PAYROLL JOB 20.00 PAY2 1 PAY6 IMS

N PAYROLL JOB 20.00 PAY3 1 PAY6 IMS

N PAYROLL JOB 20.00 PAY4 1 PAY6

N PAYROLL JOB 20.00 PAY5 1 PAY6 ACCTPAY ACCT1

N PAYROLL JOB 20.00 PAY6 4 PAY7, PAY8

PAY9


N PAYROLL JOB 20.00 PAY8 1 PAY10 ACCTPAY ACCT1


N PAYROLL JOB 20.00 PAY10 3 END CPUABS


ESP-5.4-UG-05 319

viewing the ESP Workload Manager workloads on the PC, or sending the output to the PC printer or plotter when you want a paper copy.

Generation of flow charts consists of some operations on the mainframe, a PC file transfer, and some additional operations on a PC.

For a real-time, graphical view of the workload, see the ESP Workstation User’s Guide.

Generating flowcharts using MS Project

ESP Workload Manager GENPROJ feature exports data that describe an existing ESP Application in a format that can be used by PC-based project-management software, Microsoft Project.

Exported fields

The exported fields include:

• Job Name• SubApplication name• Start date and end date• Duration• Late start time and late end time• Percent complete• Tag

To test and use the GENPROJ feature:

1. Create a data set to receive the GENPROJ data. The recommended DCB attributes are RECFM=FB, LRECL=80, and BLKSIZE=3120. However, you can use any sequential or partitioned data set with VB or FB format and an LRECL of at least 72.

2. Create an active ESP Application or use an Application you can display using the LISTAPPL command. If you need to create a dummy test Application, you can insert a built-in delay prior to the first job by using an EARLYSUB command. This ensures that the Application does not complete prior to the GENPROJ data extract. For example:

APPL TESTAPPLJOB JOB1 EARLYSUB NOW PLUS 24 HOURS RUN DAILY RELEASE JOB2ENDJOB

3. Use the GENPROJ command to extract data from the Application. For example:

GENPROJ TESTAPPL.0 DATASET('SYS1.TESTAPPL.GENPROJ')

Section–Generating flowcharts using MS Project

320 ESP-5.4-UG-05

4. Download the data set (SYS1.TESTAPPL.GENPROJ) to a DOS file, like TESTAPPL.TXT, using your installation’s file transfer Procedure. You should specify the ASCII and CRLF file transfer options.

5. Execute the Cybermation-supplied utility CONVERT.EXE on your PC. You can copy this program from a diskette supplied by Cybermation. If your installation did not receive this diskette, please contact Cybermation Technical Support. At the DOS prompt, or in Windows: File Run, switch to the appropriate directory and enter: CONVERT <input file> <output file>.For example:

CONVERT TESTAPPL.TXT TESTAPPL.MPX

The extension .MPX identifies the file as an Microsoft Project file. If you enter CONVERT without operands the command syntax is displayed.

6. Start Microsoft Project on your PC. Within Microsoft Project, open the .MPX file, for example TESTAPPL.MPX. Once the project has been opened within Microsoft Project, it can be manipulated and viewed in the same way any other project. A PERT chart displays the Application horizontally with each job shown as a box within the chart. Bold boxes identify critical path jobs. Boxes with a diagonal slash indicate that this job is complete. You should save the Application as a project file, for example TESTAPPL.MPP. Subsequent GENPROJ data extracts can be used to update the project status of an Application.

Illustration of steps 1 to 5

These steps are illustrated below:

APPL on APPLFILE mydsn

mydsn.txt mydsn.mpx

mydsn.mpp

GENPROJ

Convert

download

MS Project


ESP-5.4-UG-05 321

Generating flow charts with ESP Workload Manager and Timeline

ESP Workload Manager GENFLOW feature exports data that describes a scheduled ESP Application in a format used by the PC-based project-management software, Timeline. ESP Workload Manager uses information from a Scheduled Activity data set and exports the following fields:

• Job name• Start time and end time

To test and use the GENFLOW feature:

1. Access ESP Workload Manager in Page mode. Issue the GENFLOW command, specifying two positional operands:

• The name of a scheduled activity-data set (SADGEN file). ESP Workload Manager uses this data set as input.

• The name of a file to which GENFLOW will write the data. If you do not specify the DCB attributes, GENFLOW sets them to: LRECL=80, BLKSIZE=3120.

2. Issue a FLOW command for each separate flowchart you require. The FLOW command identifies a flow chart by a name of up to seven characters. The FLOW command also identifies jobs and/or Applications to be included.

3. After the flow commands have been entered (you can specify as many as required), type GO. ESP Workload Manager reads the SADGEN file and writes the output to the target file.

GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER'FLOW PAYROLL APPL(PAYROLL)FLOW BACKUPS JOBS(BACK-)GO

4. Use a PC file transfer program to send the data to a PC.

5. On the PC, use a file editor to edit the file, as described below.

Each flow command generates two sections in the file. Each section is preceded by a file identifier in the form:

--ffffx.CSV where ffff is the flow ID, and x is T for TASK or D for dependencies.

Section–Generating flow charts with ESP Workload Manager and Timeline

322 ESP-5.4-UG-05

For the preceding example, you will see the following:

--PAYROLLT.CSV–100–nnn–900....–PAYROLLD.CSV–100-....–BACKUPST.CSV-100...-...–BACKUPDS.CSV-100..-...

Each FLOW generates a TASK section, named ffffT.CSV, and a dependency section, ffffD.CSV, where ffff is the ID on the FLOW statement.

Split the file into two files for each flow. The file names should:

• Be called ffffT.CSV and ffffD.CSV• Contain the corresponding contents of the main file, excluding the file

identifier (--ffffx.CSV) line.

6. You can now access Timeline.

7. Use the File, Import, Tables menu. Specify that you are using tasks and dependencies, and specify the names of the files you created.

Note: You will have to do one flow at a time.

8. Once the data has been analyzed, you can view the data in GANTT (spreadsheet format) or PERT (Flowchart format). To print the flowchart, use the GRAPHIC, PERT function.


ESP-5.4-UG-05 323

Illustration of steps 1 to 8

These steps are illustrated below:

SADGEN file mydsn

mydsn.txt

mydsn.mlp

GENFLOWFLOWGO

Split file

download

Timeline

chart1t.csv

chart1d.csv

Section–Generating flow charts with ESP Workload Manager and Timeline

324 ESP-5.4-UG-05

ESP-5.4-UG-05 325

Using Resources

You can ensure that jobs in an ESP Application are submitted only when all of their resource requirements are met. Because you do this without manual intervention, there are no unnecessary delays before a job starts. With ESP Workload Manager resource feature, you can automate resource management.

Note: Before you start to use ESP Workload Manager resource features, your Systems Programmer needs to define a resource data set called the RESFILE, and specify the CPUs and nodes in your environment. If you want ESP Workload Manager to make default resource assignments, the RESDFLT initialization statement must also be specified.


• What is a resource?• Types of resources• Scope of resources• Using real devices• Routing jobs to other systems• Managing jobs• Requesting resources• Default resources• Working with resources• Defining resources• Setting resources• Modifying Resources

Section–What is a resource?

326 ESP-5.4-UG-05

• WLM Workload Balancing• Agent Workload Balancing• Deleting resources• Displaying resource information• Step-level resource release• Resource absorption• Example: Controlling mutually exclusive jobs• Example: Controlling access to an online system• Example: Time periods for low priority jobs• Example: Using a resource for a self-completing task• Example: Controlling access to a data base• Example: Running jobs on a particular system• Example: Controlling mutually exclusive groups of jobs• Example: Planning for a system shutdown - Part 1• Example: Planning for a system shutdown - Part 2• Example: Schedule dependency

What is a resource?

A resource is any type of real or abstract object that affects a job’s ability to run successfully and can be quantified. Resources are classified by resource type and by scope.

Examples of resources

Some examples of resources are:

• Tape drives• Scratch tapes• Online systems• data bases• Time periods• The completion of a job

Types of resources

ESP Workload Manager resources are classified into three types:

• Renewable• Depletable• Threshold

Chapter 10–Using Resources

ESP-5.4-UG-05 327

Renewable resource

A renewable resource is a borrowed resource. When a job is submitted by ESP Workload Manager, the job removes the resource from the resource pool. However, the resource is not permanently used up. Instead, it is returned to the resource pool at the end of execution, whether successful or not. In other words, the job temporarily borrows the resource to allow it to execute successfully.

For example:

A renewable resource can be used to control concurrent access to a data base.

Depletable resource

A depletable resource is a consumed resource. When a job is submitted by ESP Workload Manager, the job removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. The job needs to consume the resource to execute successfully.

For example:

A depletable resource can be a scratch tape, which is removed from the pool when a job writes a permanent data set onto it.

Threshold resource

A threshold resource is a sizing resource. A job does not actually remove the resource from the pool of resources while it executes. You can think of a threshold resource as a variable height doorway into the system. If the resource quantity is set to two, any number of jobs requiring two or fewer units are submitted. However, any job requiring three or more units is too high to pass through the door and so is not submitted. ESP Workload Manager sizes the job against the current level of the threshold resource.

For example:

A threshold resource can be used to represent elapsed time and limit the size of jobs entering the system. You can prevent long-running jobs from being submitted just before scheduled downtime.

Section–Scope of resources

328 ESP-5.4-UG-05

Scope of resources

You can classify the scope of the resources you define according to the following resource levels:

Using real devices

A real resource represents an actual hardware device. It is normally used for tape drive. The limitation is that they can work correctly only in a single z/OS image. The ESP Workload Manager master is only aware of the status of devices on the image it is running on.

Device counts

ESP Workload Manager determines the available count by first looking at the system control blocks for the resources. Then ESP Workload Manager counts how many of the UCBs (unit control blocks) within that device group are currently online and not allocated. If ESP Workload Manager schedules a job that requires a tape device, it could be several seconds or minutes before the job actually allocates the UCB. ESP Workload Manager ensures that it does not over-allocate a resource when scheduling jobs that require it. ESP Workload Manager uses an effective available count that is the lower of the following values: real value and the available count maintained by ESP Workload Manager.

Example

If a job requires three units of a real resource, and ESP Workload Manager available count is three, ESP Workload Manager waits for the resource if there are only two devices actually online and unallocated.

Type of resource Explanation

Local resource Each processor maintains an individual counter for the resource.

Global resource The resource availability counter is shared among all processors within a node.

Enterprise resource The resource availability counter is shared among all nodes. This type has a true meaning only when one ESP Workload Manager system submits the work for all nodes.


ESP-5.4-UG-05 329

Routing jobs to other systems

In a multiple CPU environment, a job can require a mix of resources that are not available on the ESP Workload Manager system submitting the job. However, these resources can be available on another processor, either on the current node or on a remote node. ESP Workload Manager tries to find all the resources a job requires on one system.

Routing JCL

ESP Workload Manager can automatically insert the appropriate JCL into a job to ensure the job is routed to the required node or processor. The JCL ESP Workload Manager uses to route jobs is specified as part of the NODE and CPU definitions in your ESP Workload Manager initialization parameters. These are normally a /* EXEC nodename card and a /*JOBPARM SYSAFF=xxxx card.

Example

If ESP Workload Manager builds an Application on SYSA but the resource a job needs is on SYSB, ESP Workload Manager routes the job to SYSB. If these systems are within the same JES node, ESP Workload Manager submits the job and inserts a /*JOBPARM SYSAFF=SYSB card to route the job to SYSB.

Gravity

ESP Workload Manager can cause a job to be routed to a remote node only if one of the resources required by the job has the GRAVITY attribute in its definition. ESP Workload Manager can cause a job to be routed to another CPU within the same node regardless of the GRAVITY setting.

Managing jobs

When the Application Manager readies a job for submission, it checks to see if the job has requested any resources. If so, the Application Manager passes the job to the Resource Manager component. The Resource Manager submits the job when the required resources become available. If all of a job’s resource requirements cannot be met, ESP Workload Manager does not submit the job.

Multiple resources

If a job requires multiple resources, or multiple units of a single resource, and all of these resources are not available when the job is readied for submission, ESP Workload Manager does not hold on to any resources. As soon as another job ends that is using a resource this job needs, or the resource status changes in any way—for

Section–Requesting resources

330 ESP-5.4-UG-05

example, by the RESDEF command being issued—the job is rechecked for submission.

Renewable resources

If a job is using a renewable resource, the resource is taken when the job is submitted and is freed up as soon as the job ends, whether it is successful or not. A failed job, by default, has the same resource requirements upon restart as at submission time.

Requesting resources

To identify the resources required by individual jobs or by an Application, you use the RESOURCE statement within an Application definition. This can be done at an Application level or at a job level. An individual job can request any number of different resources. You can use resources for jobs and tasks, but not for links.

Statements

When you specify resource requirements, there are two statements you can use:

• The RESOURCE statement• The PRIORITY statement

Using the RESOURCE statement

Use the RESOURCE statement to identify resource requirements. In parentheses, specify the number of units required, followed by the resource name. If you omit the number of units, ESP Workload Manager uses a default of 1.

For example, to specify one unit of a resource called CICS, use:

RESOURCE (1,CICS) or RESOURCE (CICS)

If you want to request more than one resource, string your resource specifications together. For example, if your requirements are one unit of the resource called CICS and two units of a resource called SCRATCH, specify:

RESOURCE (1,CICS,2,SCRATCH)

Placing the RESOURCE statement

When you use a RESOURCE statement within an Application to provide specific resource information for an individual job, you place the statement between the JOB ... ENDJOB pair. The RESOURCE statement then affects only that individual job. It also overrides any resources that occur before the JOB ... ENDJOB pair.

If the RESOURCE statement is specified outside the scope of a JOB ... ENDJOB pair, the RESOURCE statement applies to the jobs that follow until a new


ESP-5.4-UG-05 331

RESOURCE statement, outside the scope of a JOB statement, occurs. Jobs inserted into an Application after it has been generated do not inherit any resource requirements.

Example: Requesting resources

In the following example, all jobs in the Application require one unit of the NITESHFT resource except job A that requires one unit of the CICS resource.

APPL ABCJCLLIB 'CYB.ESP.JCL'RESOURCE (1,NITESHFT)JOB A RESOURCE (1,CICS) RUN DAILYENDJOBJOB B RUN DAILYENDJOBJOB C RUN DAILYENDJOB

Adding resource requirements

Use the ADD operand on the RESOURCE statement to specify resources in addition to the resource requirements already specified for a job or the Application. You use it by specifying RESOURCE ADD, the number of units, and then the resource name.

Example

In the following example, job A needs one unit of the CICS resource in addition to one unit of the NITESHFT resource:

RESOURCE (1,NITESHFT)JOB A RESOURCE ADD(1,CICS)ENDJOB

Dropping resource requirements

The DROP operand on the RESOURCE statement specifies that one or more resource requirements are dropped for the jobs that follow, until a new RESOURCE statement occurs either within a JOB ... ENDJOB pair, or outside the scope of a JOB... ENDJOB pair. You use it by specifying RESOURCE DROP and then the resource name, like this:

RESOURCE DROP(T3420)RESOURCE DROP(CICS,T3420)

Section–Requesting resources

332 ESP-5.4-UG-05

To free a job from any resource dependency (except default resources) you specify:

RESOURCE DROP

Example

In the following example, job ABC requires one unit of the LOWPRIO resource and two units of the IMS resource. If the scheduled day is Friday, the LOWPRIO requirement is removed.

JOB ABC RUN DAILY RESOURCE (1,LOWPRIO,2,IMS) IF TODAY('FRIDAY') THEN RESOURCE DROP(LOWPRIO)ENDJOB

Dropping default resources

You cannot drop default resources using the DROP operand. Instead, you must request zero units of the default resource to indicate you do not want to use the default resource for a job or group of jobs.

Example

In the following example, job ABC does not have the ELAPSED default resource assigned to it and has a requirement for one unit of CICS.

JOB ABC RESOURCE (0,ELAPSED,1,CICS)ENDJOB

Using the PRIORITY statement

You can use the PRIORITY statement in a job definition to specify the relative priority of the job within an ESP Workload Manager group. The maximum value is 99. Zero is the lowest priority value and the default.

You can prioritize jobs within one group without delaying jobs in another group. ESP Workload Manager uses the priority when one or more jobs, within the same ESP Workload Manager group, are competing for the same resource. In this case, ESP Workload Manager queues the higher priority job ahead of the lower priority job. The queuing sequence of jobs in other groups is not affected. PRIORITY only applies to renewable and depletable resources.

ESP Workload Manager groups

The ESP Workload Manager group name is determined by the Event prefix. For example:

• CYBER.nnn identifies a job belonging to the group CYBER.• PROD.nnn identifies jobs in the PROD group.


ESP-5.4-UG-05 333

For instance, a job that is assigned a priority in a group called CYBER is compared only to other jobs in the CYBER group and not to jobs in another group called PROD.

Example: Setting priority

The following example sets a priority of 99 for job BIGJOB. ESP Workload Manager queues this job ahead of other jobs from the same group when these jobs are waiting for the MSTRFILE resource.

JOB BIGJOB PRIORITY 99 RESOURCE (1,MSTRFILE)ENDJOB

Example: Setting priority

The following example sets a different priority for jobs B, C, and D. Each job requires one unit of a renewable resource called MSTRFILE. When job A completes, ESP Workload Manager queues the jobs in the order D, C, and B.

JOB A RUN DAILY RELEASE (B,C,D)ENDJOBJOB B RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 10ENDJOBJOB C RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 20ENDJOBJOB D RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 30ENDJOB

Default resources

ESP Workload Manager can determine some of the significant resource requirements that a job have by looking at the job’s run history. If required, ESP Workload Manager can then make default resource assignments automatically.

Section–Default resources

334 ESP-5.4-UG-05

Default assignments

The resources for which ESP Workload Manager can make default assignments are:

• Number of tape drives needed• Number of scratch tapes needed• Percentage CPU absorption• Total CPU time used• Total elapsed time used• Total print lines generated

Determining a default assignment

The information used to assign default resources is based on information contained in ESP Workload Manager Job Index file. ESP Workload Manager bases the default resource levels that it assigns on an average of the samples found in the job index. The number of samples depends on the index count specified when the job’s tracking model was defined. Only information from normal job completions, and not from abends, is used. The information is updated each time a new generation of an Application is created.

Default resources

To set up default resources:

1. Use the RESDFLT initialization statement in the ESP Workload Manager initialization parameters to identify the default resource you want to use.

2. Issue the RESDEF ADD command to define the default resource.

Example: Default scratch tape resource

The following ESP Workload Manager initialization statement causes ESP Workload Manager to use a default resource for scratch tapes. The name of the resource is SCRTAPES.

RESDFLT SCRATCH(SCRTAPES)

The following ESP Workload Manager command defines the SCRTAPES resource as a global, depletable resource, with a maximum quantity of 293.

RESDEF SCRTAPES ADD GLOBAL DEPLETABLE MAX(293)

ESP Workload Manager uses historical information to assign scratch-tape resource requirements to each job in an Application when it creates a generation of that Application.


ESP-5.4-UG-05 335

Excluding default resources for an Application

Each Application ESP Workload Manager creates uses default resources you have set up. In an Application, you can code RESOURCE (0, resname) if you do not want ESP Workload Manager to assign default resources for a job or for an Application.

Working with resources

RESDEF command

You define, display, set, and delete resources using the RESDEF command. In a multiple CPU environment, you must issue the RESDEF command from a master ESP Workload Manager system. This is normally the same system on which your Applications are built.

Note: Your ESP Workload Manager administrator needs to grant you the necessary access for these functions.

The following sections describe how to define and work with resources. See the Examples sections later in this chapter for more examples of using resources.

Defining resources

Once you define a resource, the definition is stored in an ESP Workload Manager file, called the RESFILE. This information is saved across restarts of ESP Workload Manager unless ESP Workload Manager is restarted with the RESFORM option. Resource definitions are normally stored in the ESP Workload Manager initialization parameter data set or another data set that ESP Workload Manager reads at startup time.

To define a resource using the RESDEF command:

1. Name the resource, using up to 44 alphanumeric characters, the first of which must be alphabetic or national.

Note: The resource’s name must not end with a period or use two consecutive periods.

2. Use the ADD operand to indicate you are adding a resource.

3. Indicate the scope as local, global, or enterprise.

4. Indicate the type as renewable, depletable, or threshold.

5. Indicate if the resource corresponds to a real device, and specify the IBM generic or esoteric Unit Name for the device.

Section–Defining resources

336 ESP-5.4-UG-05

6. Indicate the CPU to which the resource applies, if it is a local resource and you have more than one CPU.

7. Specify the maximum and available quantities associated with the resource. For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. Maximum is the total quantity of the resource that exists; available is the current quantity.

Indicate whether or not the resource has gravity. This allows a job to be routed to another node if the resource is not available on the node on which the job was submitted.

Example: Defining a renewable resource

This example defines a resource called DATABASE. It is a global, renewable resource with maximum and available quantities of one.

RESDEF DATABASE ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)

Example: Defining a threshold resource

This example defines a resource called CICSUP. It is a local, threshold resource on SYSA with an availability count of one.

RESDEF CICSUP ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)

Example: Long resource name with no restrictions:

RESDEF RED_CARTRIDGE_WITHOUT_LABELS_OR_NUMBERS +ADD LOCAL DEPLETABLE AVAIL(50)

Defining a real resource

A real resource is one that is associated with an actual hardware device. This is normally a tape transport. ESP Workload Manager looks at the number of online, unallocated devices to satisfy a job’s real resource requirement.

To define a real resource:

• Use the DEVICE operand, on the RESDEF command, to specify a valid z/OS device name (for example, legal value for the UNIT=keyword in JCL).

The unit name can be a generic, such as 3480, or an installation-defined esoteric such as TAPE. Real resources should be defined as local and renewable. Use the MAX operand to identify the number of devices available to ESP Workload Manager submitted jobs.


ESP-5.4-UG-05 337

RESREFR command

You can use the RESREFR command to refresh resource status. This can be required when you change the environment. For example, if a job is waiting for tape drive resources and you vary more tape drives online, ESP Workload Manager is not immediately aware of this. The RESREFR command causes ESP Workload Manager to look at the environment and refresh the status of real resources.

Example: Defining a real resource

This example defines a resource called T3480. It is a local, renewable, real resource that represents a device type of 3480. There is a maximum of 20 of these devices.

RESDEF T3480 ADD LOCAL RENEWABLE DEVICE(3480) MAX(20)

Setting resources

To change a resource:

• Use the SET operand on the RESDEF command to change the scope or the quantity of a resource.

You cannot change the type of a resource without deleting and redefining it.

For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. If you set the maximum, the available count changes. Setting the available count has no effect on the maximum count.

Example

This example sets the available quantity of the resource LOWPRIO to one.

RESDEF LOWPRIO SET AVAIL(1)

Setting quantities automatically

For some resources, you want ESP Workload Manager to set the quantity for you automatically. For example, you have a resource called CICSUP to represent that a started task called CICS is active. You can use ESP Workload Manager to automatically set the quantity of the resource to indicate the availability. See Job Monitoring and Alert Processing in the ESP Workload Manager Advanced User’s Guide for more information.

Section–Modifying Resources

338 ESP-5.4-UG-05

Modifying Resources

You can use the JOBRES command to add new resource requirements and change existing resource requirements for a job. This is done after the Application has been generated. Once the Application is generated, you can issue the JOBRES command at any time, including if the job is already waiting for resources (RESWAIT state).

You can also use the MR command in CSF.

WLM Workload Balancing

You can define real resources representing a number of CPU service units required by a job. They are used for WLM workload balancing within a sysplex. The use of those resources is based on the feedback from IBM WLM queries. CPU service unit resources are supported for systems in a sysplex running in goal mode. When ESP Resource manager determines that a number of CPU service unit resources requested by a job is available on more than one system in the sysplex, it uses the feedback from IBM WLM queries to route the job on the system with the most available service units. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.

Note: CPU service unit resources are available only if the ESP Workload Manager High Performance Option (HPO) is installed.

CPU service unit resources are controlled with the NODE command or initialization parameter and the RESDEF command. See the ESP Workload Manager Reference Guide for commands and the ESP Workload Manager Installation and Configuration Guide for initialization parameters. See the “ESP Workload Manager High Performance Option” in the ESP Workload Manager User’s Guide for information on how to use WLM workload balancing.

To use WLM workload balancing, you must:

• Code one or more NODE initialization parameters or commands. You must specify the SYSPLEX operand.

• Code CPU initialization parameters or commands for each CPU participating in the load balancing. You must use the SYSNAME value as the name.

• Define resources with the RESDEF command specifying the WLM operand.

• Specify the required resources in the ESP Procedures for the jobs you want to direct to the CPU with the most available service units using workload balancing.


ESP-5.4-UG-05 339

Agent Workload Balancing

You can define real resources representing the percentage of CPU availability required by a job. This is used for workload balancing within a system with multiple ESP Agents. The workload balancing is based on the feedback from the Agents. When ESP Resource manager determines that the percentage of CPU availability requested by a job is available on more than one system, it uses the feedback from the Agents to route the job to the Agent platform with the highest percentage of availability. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.

Note: Agent workload balancing is available only if the ESP Workload Manager High Performance Option (HPO) is installed.

Agent workload balancing is controlled with the CPU and NODE commands or initialization parameters and the RESDEF command. See the ESP Workload Manager Reference Guide for commands and the ESP Workload Manager Installation and Configuration Guide for initialization parameters. See the “ESP Workload Manager High Performance Option” in the ESP Workload Manager User’s Guide for information on how to use Agent workload balancing.

To use Agent workload balancing, you must:

• Code the NODE initialization parameter or command to define a common node to which all the Agent platform participating in load balancing belong.

• Code CPU commands or initialization parameters with the AGENT operand for each Agent platform participating in the load balancing.

• Define resources with the RESDEF command specifying the MONITOR(CPU) operand and a non-zero POLL operand.

• Specify the needed resources in the ESP Procedures of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.

• Code the ROUTING operand in the AGENT statement of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.

Deleting resources

To delete a resource:

• Use the DELETE operand on the RESDEF command.

Section–Displaying resource information

340 ESP-5.4-UG-05

This example deletes the resource LOWPRIO.

RESDEF LOWPRIO DELETE

Note: You cannot delete a resource while any job is using the resource.

Displaying resource information

To display information about a resource:

• Use the Consolidated Status Facility and ESP Workload Manager commands.

To display the resources associated with that job and determine what jobs have resources allocated:

• Use the LR command for a job using CSF.

If a job is awaiting resources, the status field in CSF states waiting for resources, and the PNODE field in CSF states RESWAIT.

In the following example, the LOCKOUT resource is displayed to determine what jobs are using the resource and what jobs are waiting for the resource.

Resource LOCKOUT List Own WaitResource LOCKOUT Global Renewable 1 needed by PAYJOBD, Appl PAYROLL.396TORONTO * Max=1 Avail=0 1 used by BILLJOBA, Appl BILLING.293

You can drop resource dependencies using the DR command.

To display one or more resources:

• Use the LIST operand on the RESDEF command.

The display shows the name of the resource, the type of resource, and the quantities associated with the resource. You can also display the jobs using the resource and the jobs needing the resource.

This example displays the CICSUP resource. It is a local, threshold resource with an available count of one on CPU1 and an available count of zero on CPU2.

RESDEF CICSUP LISTResource CICSUP Local ThresholdNODE1 CPU1 Avail=1NODE1 CPU2 Avail=0

The following command is used to display all resources.

RESDEF – LIST


ESP-5.4-UG-05 341

To display resource requirements for jobs not yet submitted in an active Application:

• Use the LISTAPPL (LAP) command.

Sample output looks like this:

LAP TURNOVER.14 ALLAPPL TURNOVER GEN 14 CREATED AT 13.43 ON TUESDAY MAY 15TH, 2001 BY EVENT CYBER.TURNOVER A J1169, STARTED, STEP 1 B, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1 C, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1, 1 LOWPRIO D, HC=1 PREDECESSORS: A SUCCESSORS: D RESOURCES: 1 DB2TAB1, 1 LOWPRIO

Step-level resource release

Step-level resource release allows you to return resources to the resource pool at job step-end. Previously, resources would remain allocated to a job for the duration of the job.

Step-level resource release is achieved by the use of a new STEPEND statement. STEPEND is coded within the scope of the job statement. You can release part or all of the resources to the resource pool. You can have more than one STEPEND statement in one job.

Step-level resource release is available for renewable resources only.

Syntax

The following is the syntax of the STEPEND statement:

STEPEND STEPNAME(stepname) PROCSTEP(procstep) –RELRES(n1,resname1,n2,resname2,…)

Operand Description

stepname Indicates the name of the job step.procstep Indicates the name of the proc step.n,resname Indicates the quantity and name of the resource to be released.

Section–Resource absorption

342 ESP-5.4-UG-05

Examples – Stepend statement

The following example shows releasing one unit of a resource after STEP1, PROCA finishes:

APPL ONEJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (6,T3480) STEPEND STEPNAME(STEP1) PROCSTEP(PROCA) - RELRES(1,T3480)ENDJOB

The following example shows releasing two more units of the same resource later in the same job:

APPL ONE JCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBA RUN DAILY RESOURCE (5,T3480) STEPEND STEPNAME(STEP3) PROCSTEP(PROCB) - RELRES(2,T3480)ENDJOB

Ensure the step names and procedure steps you specify match your JCL exactly. You can release resources by specifying just a procedure step and not a step name, if that is how your JCL is tailored.

Note: Step-level Resource Release only works if USERMOD 11 is off. When USERMOD 11 is on, the Application Manager does not get step-end notification.

Resource absorption

In ESP Workload Manager Version 5 Release 1, jobs that required a large resource count would encounter processing delays as jobs with low resource requirements would get the resource, thus keeping the overall available resource count low.

In ESP Workload Manager Version 5 Release 3, Resource Absorption reserves the resources that are available at the time the job is next in the queue and holds them while waiting to accumulate the remainder of resources required for that job. Jobs with smaller resource requirements cannot use the reserved resource.

The ABSORB statement will only ABSORB resources if the request is for less than or equal to the maximum resource defined. An ABSORB statement is coded within the scope of the job, above the RESOURCE statement, where Absorption is to occur. ABSORB can also be used at the Application level.


ESP-5.4-UG-05 343

A job with a higher priority and the same resource requirements will take the resources and run before the lower priority job with the ABSORB statement.

Once the higher priority job completes, or has the resources it needs, the process of gathering resources starts again.

Example: ABSORB statement

The following example shows coding an ABSORB statement within the scope of the job:

APPL ABSRESJCLLIB 'CYBER.JCLLIB.CNTL'JOB JOBX RUN DAILY ABSORB RESOURCE (4,T3480)ENDJOB

When JOBX is first in the queue, the Resource Manager begins the process of reserving the required resources, four units of T3480. Jobs that follow JOBX in the queue that require less than or equal to the same resource, and are the same job priority, will not be submitted before JOBX.

Types of resources

Absorption is available for the following types of resources:

• Renewable• Depletable

Section–Resource absorption

344 ESP-5.4-UG-05

Example 1: Application with absorption

The following example shows an Application with an Absorb statement:

APPL ABSRESJCLLIB 'CYBER.JCLLIB.CNTL'JOB A RESOURCE (1,T3480)ENDJOBJOB B RESOURCE (1,T3480)ENDJOBJOB C RESOURCE (1,T3480)ENDJOBJOB D ABSORB RESOURCE (3,T3480)ENDJOBJOB E RESOURCE (1,T3480)ENDJOBJOB F RESOURCE (1,T3480)ENDJOBSELECT (A,B,C,D,E,F)

Example 2: Application with absorption

The following example shows the CSF display of Application ABSRES:

Jobname APPL GEN Pnode StatusA ABSRES 10 EXEC EXECUTING STEP2B ABSRES 10 EXEC EXECUTING STEP1C ABSRES 10 EXEC EXECUTING STEP1D ABSRES 10 RESWAIT Waiting for ResourcesE ABSRES 10 RESWAIT Waiting for ResourcesF ABSRES 10 RESWAIT Waiting for Resources

The following example shows the current resource allocations:

Resource ABSRES List Own WaitResource ABSRES Global Renewable 3 needed by D, Appl ABSRES.11 1 needed by E, Appl ABSRES.11 1 needed by F, Appl ABSRES.11TOR1 * Max=3 Avail=-3 1 used by A, Appl ABSRES.11 1 used by B, Appl ABSRES.11 1 used by C, Appl ABSRES.11 3 absorbed by D, Appl ABSRES.11


ESP-5.4-UG-05 345

Example: Controlling mutually exclusive jobs

In this example, a renewable resource controls the execution of two jobs so they do not execute at the same time.

You can also use another method to control mutually exclusive jobs. See “Using Implicit Resources” on page 166.

The criteria for this example are:

• Job A and job B cannot execute at the same time.• Each job requires one unit of a resource called DB2TAB1.

To set-up mutually exclusive jobs:

1. Define a global, renewable resource with maximum and available quantities of one.

RESDEF DB2TAB1 ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)

2. Specify, in the Application in which each job is defined, a requirement of one unit of the resource. For example:

JOB A RESOURCE (1,DB2TAB1)ENDJOB

JOB B RESOURCE (1,DB2TAB1)ENDJOB

Result

At any time, either one unit of the resource is available, or no units of the resource are available. If, for example, job A is executing, the available count of the resource is zero, and ESP Workload Manager prevents job B from executing. ESP Workload Manager returns the resource to the system upon completion (successful or not) of job A.

Extending this example

You can extend this example to any number of jobs.

Resource DB2TAB1

Job A Job BWaiting for Resource

Section–Example: Controlling access to an online system

346 ESP-5.4-UG-05

If you need to control mutually exclusive groups of jobs, see “Example: Controlling mutually exclusive groups of jobs” on page 350.

Example: Controlling access to an online system

This example uses a renewable resource to control the maximum number of concurrent job executions.


• Access to an IMS region is limited to a small number of jobs at any one time.• Job A and either job B or job C can execute at the same time.• Jobs B and C cannot execute at the same time.

Visually, the requirements look like this:

To control access to an Online System:

1. Define a local, renewable resource with maximum and available quantities of three. The name of the resource is IMS.

RESDEF IMS ADD LOCAL RENEWABLE MAX(3) AVAIL(3)

2. In an Application, specify the number of units each job requires. For example:

Result

ESP Workload Manager processes the jobs as follows:

• Job A can run concurrently with either job B or job C.• Jobs B and C cannot execute at the same time because they require a total count of

four units of the IMS resource.

Job RESOURCE Statement

A RESOURCE (1,IMS)

B RESOURCE (2,IMS)

C RESOURCE (2,IMS)

IMS 31,IMS

2,IMS

2,IMS

A

B

C


ESP-5.4-UG-05 347

Example: Time periods for low priority jobs

This example uses a threshold resource to control when low priority jobs run.


• Low priority jobs can execute between 9 am and 4 pm on workdays.• At other times, ESP Workload Manager puts low priority jobs into a waiting for

resources status.

To set time periods for low priority jobs:

1. Define a threshold resource with an available quantity of one. The name of the resource is LOWPRIO.

RESDEF LOWPRIO ADD GLOBAL THRESHOLD AVAIL(1)

2. For each low priority job, identify a resource requirement of one unit of the resource, like this:

JOB ABC RESOURCE (1,LOWPRIO) RUN DAILYENDJOB

3. Set up two Events: one to set the quantity of the resource to zero and the other to set the quantity of the resource to one. The Events look like this:

EVENT ID(OPER.SET_LOWPRIO_ON) SCHEDULE 9AM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(1)'ENDDEF

EVENT ID(OPER.SET_LOWPRIO_OFF) SCHEDULE 4PM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(0)'ENDDEF

Section–Example: Using a resource for a self-completing task

348 ESP-5.4-UG-05

Result

ESP Workload Manager turns the LOWPRIO resource on and off automatically. Any job requiring one unit of the LOWPRIO resource can only execute between 9 am and 4 pm on workdays.

In a multiple CPU environment, you can have different time periods to run low priority jobs on different systems. You can define different local resources and set them independently.

Example: Using a resource for a self-completing task

A link cannot have a resource requirement because a link is marked complete as soon as it becomes ready. Instead, you can use a self-completing task that requires a resource.

Self-completing task

This example uses a task called WAIT4.LOWPRIO that requires one unit of a resource called LOWPRIO.

JOB WAIT4.LOWPRIO TASK PROCESS RUN ANY RELEASE NEXTJOB RESOURCE (1,LOWPRIO) ESP AJ WAIT4.LOWPRIO COMPLETE APPL(WAIT4.%ESPAPGEN)ENDJOB

Result

When the LOWPRIO resource becomes available, ESP Workload Manager readies the task and issues an ESP AJ command to complete itself. This command uses an ESP Workload Manager symbolic variable (%ESPAPGEN) for the Application generation number to ensure the task is marked complete in the correct generation.



Allow low priority

Disallow low priority

9 a.m. to 4 p.m.

4 p.m. to 9 a.m.


ESP-5.4-UG-05 349

Example: Controlling access to a data base

In this example, a renewable resource controls access to a data base.


• Any job that updates the data base requires exclusive use of the data base. In this example, jobs A and Z update the data base.

• Any number of jobs that read the data base can execute at the same time. In this example, jobs B and C read the data base.

To control access to a data base:

1. Define a global, renewable resource with maximum and available counts of 999. The name of the resource is DBASE1.

RESDEF DBASE1 ADD GLOBAL RENEWABLE MAX(999) AVAIL(999)

2. In the Applications for each job, specify the number of units required. A job that updates the data base requires 999 units; a job that reads the data base requires one unit. For example:

Result

ESP Workload Manager processes the jobs as follows:

• Neither job A or job Z can run concurrently with any of the other jobs, because each requires the maximum count for the resource.

• Jobs B and C can run together because they require a total count of two units of the DBASE1 resource.

Example: Running jobs on a particular system

This example uses threshold resources to control on which system a job runs.In a master-proxy environment, you may need jobs to run on a particular system. Instead of hard coding this requirement in JCL, ESP Workload Manager can add, at submit time, the JCL required to route a job to a system.

Job RESOURCE Statement

A RESOURCE (999,DBASE1)

B RESOURCE (1,DBASE1)

C RESOURCE (1,DBASE1)

Z RESOURCE (999,DBASE1)

Section–Example: Controlling mutually exclusive groups of jobs

350 ESP-5.4-UG-05

CPU definitions

Prior to using the resource feature, CPU definitions are added to the ESP Workload Manager initialization parameters that assign names to your master and proxy ESP Workload Manager systems and identify routing JCL for routing jobs to each system. These definitions must be in place for proper routing.

For example, the following are two CPU definitions that specify routing JCL:

CPU SYSA ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSA')-CURRENTCPU SYSB ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSB')

Defining the resources

You can represent each system by a local, threshold resource. The name of the CPU must be the same as that identified in your ESP Workload Manager initialization parameters. For example, the following defines two local, threshold resources called SYSA and SYSB, each with an available count of one.

RESDEF SYSA ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)RESDEF SYSB ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(1)

Requesting the resource

To specify a job must run on SYSB, request one unit of the SYSB resource. For example:

JOB XYZ RESOURCE (1,SYSB) RUN DAILYENDJOB

A job can request other resources, which can be either local or global. ESP Workload Manager tries to find all the resources a job needs on one system.

Result

When the SYSB resource is available, ESP Workload Manager submits the job and adds a system affinity card for SYSB. For example, ESP Workload Manager adds the following card:

/*JOBPARM SYSAFF=SYSB

Example: Controlling mutually exclusive groups of jobs

In this example, ESP Workload Manager controls resources such that one group of jobs does not execute while another group is running. The technique illustrated here can be used whether or not both groups of jobs are in the same Application.


ESP-5.4-UG-05 351

Criteria for this example


• 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


B

START.2(task)

(job)

A(job)

START.1(task)

C(job)

D(job)

E(job)

RESET.2(link)

RESET.1(link)

Section–Example: Controlling mutually exclusive groups of jobs

352 ESP-5.4-UG-05

Sample Application

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


ESP-5.4-UG-05 353

Result

ESP Workload Manager produces the following results:

• When job A ends successfully, ESP Workload Manager completes one of the tasks and starts processing one group of jobs.

• The predecessor task for the other group of jobs requires the MUTUAL resource, which is not available.

• When the first group of jobs is done, a link sets the available quantity of the MUTUAL resource to one. This allows the other group of jobs to process.

Example: Planning for a system shutdown - Part 1

You can use the ELAPSED default resource to prevent long-running jobs from starting prior to a system shutdown. ESP Workload Manager uses historical information to assign elapsed-time resource requirements to each job in an Application when it creates a generation of that Application.

To set up this example:

1. Define the ESP Workload Manager resource representing elapsed time. The name of the resource in this example is RUN_TIME.

2. Turn on the default resource called ELAPSED.

3. Optionally, set up a countdown Procedure that you can use prior to a system shutdown.

Defining the resource representing elapsed time

The following ESP Workload Manager command defines the RUN_TIME resource as a local, threshold resource, with an available quantity of 9999. If you are running a master-proxy environment, you should define a local resource for each CPU and use the same name for the resource.

RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(9999)

Turning on the ELAPSED resource

The following ESP Workload Manager initialization statement causes ESP Workload Manager to use a default resource for elapsed time.

RESDFLT ELAPSED(RUN_TIME)

When ESP Workload Manager creates an Application, each job is assigned a RUN_TIME requirement, unless you have specified RESOURCE (0,RUN_TIME) in your Application.

Section–Example: Planning for a system shutdown - Part 2

354 ESP-5.4-UG-05

Setting up a countdown Procedure

The following example uses an Event called OPER.SHUTDOWN that invokes an ESP Procedure. When you trigger this Event, specify the number of minutes until shutdown in the USER1 field.

Actions carried out by the ESP Procedure

The ESP Procedure:

• Assigns the USER1 variable to a variable called TIME.• Sends a message to CN(01) informing them of the number of minutes until

shutdown.• Sets the available quantity of an ESP Workload Manager threshold resource called

RUN_TIME to the number of minutes until shutdown.• Decrements the TIME variable by one.• If the amount of time now left until shutdown is greater than or equal to zero,

ESP Workload Manager re-triggers the Event in one minute (the amount of time left is passed as the USER1 variable).

• The process repeats until the amount of time left is less than zero.

/*/* PASS NUMBER OF MINUTES TO SHUTDOWN USING USER1/* PARAMETER WHEN TRIGGERING EVENT/*/*SEND MESSAGE, DECREMENT TIME AND RE-TRIGGER EVENT IN /*1 MINUTE IF TIME >=0/*INTEGER TIMETIME=USER1SEND 'SYSTEM COMING DOWN IN %TIME MINUTES' CN(01)RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)TIME=TIME-1IF TIME>=0 THEN ESP TRIGGER OPER.SHUTDOWN + USER1('%TIME') AT('REALNOW PLUS 1 MINUTE')

Example: Planning for a system shutdown - Part 2

In a master-proxy environment, a default resource representing elapsed time (for example RUN_TIME) can be used to prevent jobs from being submitted if there is not enough elapsed time available. If the RUN_TIME resource is defined as a local resource for each CPU, then each CPU can have its own counter. ESP Workload Manager only submits a job to JES if there is enough of the RUN_TIME resource available on any CPU. Even though JES controls where the job executes, ESP Workload Manager can automatically insert a system affinity card to control routing.


ESP-5.4-UG-05 355

Resource check

When a job’s predecessor and time requirements have been met, ESP Workload Manager checks to see if the required resources are available. For example, ESP Workload Manager checks to see if enough of the RUN_TIME resource is available for job XYZ on each of the CPUs. If no ORDER has been specified on the CPU definitions in the ESP Workload Manager initialization parameters for the master, ESP Workload Manager checks each CPU in the order in which each is defined.

Suppose ESP Workload Manager does not find enough of the resource on SYSA but does find enough of the resource available on SYSB; ESP Workload Manager submits the job and adds a system affinity card to route the job to SYSB. If no JCL has been specified for the ROUTEJCL operand in the CPU initialization parameter, ESP Workload Manager submits the job and JES determines where the job runs.

Multiple resource requirements

If a job needs the RUN_TIME resource and must execute on a particular system, on SYSA for example, you have two resource requirements. You should add a resource requirement of one unit of SYSA in your Applications. This is a local, threshold resource with quantity of one. ESP Workload Manager will not submit a job until enough of the RUN_TIME resource is available and the SYSA resource is available; each of these local resources needs to be available on the same system.

Defining the system resources

Define a local resource that represents the CPU. For example, the following defines two local, threshold resources called SYSA and SYSB, each with an available count of one.

RESDEF SYSA ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)RESDEF SYSB ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(1)

To specify a job must run on SYSA, request one unit of the SYSA resource. For example:

JOB XYZ RESOURCE (1,SYSA)ENDJOB

Defining the default resources

The following example defines two local RUN_TIME resources, one for SYSA and one for SYSB.

RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(99999999)RESDEF RUN_TIME ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(99999999)

Section–Example: Schedule dependency

356 ESP-5.4-UG-05

Setting the resources

You can set the available count of your RUN_TIME resources using the Procedure explained in Part 1 of this example. Use the CPU operand on the RESDEF command to specify the system on which you are setting the resource. For example:

RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)

The system resources, SYSA and SYSB, are always available. You can turn them off when the system ends and turn them on when the system starts using ESP Workload Manager or some other form of automation.

Result

When enough of the RUN_TIME resource is available and the system resource (for example, SYSA or SYSB) is available, ESP Workload Manager submits the job and adds a system affinity card for the appropriate system.

Example: Schedule dependency

This example uses a threshold resource to represent the completion of a job. For example, you can have a job that is dependent on an on-request job with an unpredictable frequency.

In this example, PAYJOB2 requires that the previous run of PAYJOB1 has completed successfully.

To set schedule dependency:

1. Define a threshold resource with an available quantity of zero. In this example, the name of the resource is the same as the name of the predecessor job, PAYJOB1.

RESDEF PAYJOB1 ADD GLOBAL THRESHOLD AVAIL(0)

2. For the successor job, define the first job as a resource requirement.

JOB PAYJOB2 RESOURCE (1,PAYJOB1)ENDJOB


ESP-5.4-UG-05 357

3. Use a link in each Application to set the quantity of the resource.

When PAYJOB1 completes successfully, use a link to set the available quantity of the PAYJOB1 resource to one.

JOB END.PAYJOB1 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(1)ENDJOB

When PAYJOB2 completes successfully, use a link to set the available quantity of the PAYJOB1 resource to zero. This prevents PAYJOB2 from running without its dependency the next time it is scheduled.

JOB END.PAYJOB2 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(0)ENDJOB


Result

ESP Workload Manager produces the following results:

• When PAYJOB1 ends successfully, ESP Workload Manager processes a link called END.PAYJOB1. The link sets the available count of the PAYJOB1 resource to one.

• ESP Workload Manager does not submit PAYJOB2 until the PAYJOB1 resource is available.

• When PAYJOB2 completes successfully, ESP Workload Manager processes a link called END.PAYJOB2. The link sets the available count of the PAYJOB1 resource to zero.

END.PAYJOB1(link)

PAYJOB1(job)

PAYJOB2(job)

END.PAYJOB2(link)

Section–Example: Schedule dependency

358 ESP-5.4-UG-05

ESP-5.4-UG-05 359

Optimizing ESP Applications to UseDistributed Manager

When your ESP Workload Manager network contains one or more Distributed Managers, you can create ESP Applications that run workload on one or more ESP Agents controlled by a Distributed Manager. You should consider certain guidelines when defining Applications that run workload managed by a Distributed Manager.

You can tailor the structure of the ESP Applications that require management by a Distributed Manager to make the most efficient use of the Distributed Manager's ability to manage previously scheduled workload when the mainframe is unavailable.

This chapter describes the guidelines to follow when defining distributed Applications and those ESP Workload Manager features that are not currently supported by the Distributed Manager.

If this is a new installation of ESP Workload Manager that does or will include one or more Distributed Managers, read this chapter before you begin coding ESP Applications.

Section–Planning Applications to optimize Distributed Manager

360 ESP-5.4-UG-05

This chapter contains the following topics

• Planning Applications to optimize Distributed Manager• Establishing ownership of a workload object• Creating distributed Applications• Defining ownership of an Application• Changing ownership of an Application• Changing ownership of an Application dynamically

Planning Applications to optimize Distributed Manager

Before you define a new distributed ESP Application or update an existing distributed Application, you should consider the features and limitations of the Distributed Manager. Creating Applications that optimize the abilities of the Distributed Manager ensure the completion of the Application when the mainframe is unavailable.

To plan optimal Applications:

1. Plan the proposed workflow for this Application.

2. Will this Application be required to run and complete when the mainframe is unavailable?

• Yes. The Distributed Manager must be specified as the owner on the APPL statement.

• No. The owning Manager can default to the central ESP Workload Manager.

3. Review the workflow to identify the following:

• The owning Manager of each workload object. See “Establishing ownership of a workload object” on page 364.

• The number of times the owning Manager changes from a Distributed Manager to the central ESP Workload Manager or vice versa.

See “Example 2: Non-recommended structure” on page 362.

4. Group the workload objects wherever possible, to minimize the number of changes in owning Manager:

• Group z/OS workload at the beginning or end of an Application.• If network integrity is a problem, group workload objects that run on Agents

controlled by one Distributed Manager together, reducing the communication required between Distributed Managers.

See “Example 1: Recommended structure” on page 361.

Chapter 11–Optimizing ESP Applications to Use Distributed Manager

ESP-5.4-UG-05 361

5. Review the list of ESP Workload Manager functions not supported by the current release of DM. Eliminate the use of the following functions in any ESP Application that runs workload managed by a Distributed Manager:

• Resolution of runtime symbolic variables.• Resolution of runtime CLANG or REXX statements.• Workload objects containing EXTERNAL or MANUAL operands.• ESP Workload Manager alerts.

For more detailed information, see “Unsupported functions” on page 364.

6. Create a set of rules for defining distributed Applications at your site.

Features and limitations

The primary purpose of a Distributed Manager is to track scheduled workload that is running on ESP Agents. As status is returned from an Agent, the Distributed Manager passes the status to the central ESP Workload Manager or any other Distributed Managers. If the mainframe is down or communication to the mainframe is unavailable, the Distributed Manager continues to track workload, releasing workload objects under its control as their dependencies are met. When the mainframe becomes available again, the Distributed Manager sends all status updates to the ESP Workload Manager.

The Distributed Manager can release workload under its control, or it can send status to another Distributed Manager. It cannot determine that a workload object has completed if information from the owning Manager (such as the central ESP Workload Manager) is unavailable. See the following examples that graphically describe the optimal way to design the interrelationships within an ESP Application.

Example 1: Recommended structure

The following example shows an ESP Application that runs z/OS, UNIX, and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Note that the workload is grouped to limit the number of owning Manager changes and the number of interdependencies between Managers.

In this example, the dependency on the availability of the mainframe is limited to the beginning of the Application: ESP Workload Manager schedules the Application and manages the first two workload objects. After they complete, if the connection to the mainframe is lost, or the mainframe is taken down for maintenance, the workload

Section–Planning Applications to optimize Distributed Manager

362 ESP-5.4-UG-05

continues to run because it does not rely on intervention from the mainframe. Ideally, remove all dependencies on the mainframe entirely, or limit them to the beginning or end of the Application.

Example 2: Non-recommended structure

The following example shows an ESP Application that runs z/OS, UNIX, and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Distributed Manager 1 controls the UNIX workload, and Distributed Manager 2 controls the Windows NT workload. Note that the workload objects have many interplatform dependencies, and the owning Manager changes six times within the Application. In this example, if the mainframe becomes unavailable after JOB A completes, workload cannot continue to run after UNIX_JOB F and NT_JOB S complete.

In the following example, each Distributed Manager has a dependency on the availability of the mainframe throughout the entire Application. If the mainframe or communication to it becomes unavailable at any point during the execution of the Application, the work cannot continue to run. A workload object can complete, but

JOB A

JOB B

NT_JOB S

NT_JOB T

NT_JOB V

Distributed Manager 1 Distributed Manager 2

Central ESP Workload Manager

UNIX_JOB F

UNIX_JOB G

UNIX_JOB H

Change

Change


ESP-5.4-UG-05 363

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

UNIX_JOB F

JOB A

UNIX_JOB G

JOB B

NT_JOB S

NT_JOB S

NT_JOB S

JOB C

Central ESP Manager

Distributed Manager 1 Distributed Manager 2

Central ESP Manager

Change

Change

Change

ChangeChange

ChangeChange

Section–Establishing ownership of a workload object

364 ESP-5.4-UG-05

Unsupported functions

Some ESP Workload Manager functions are not yet supported by ESP Distributed Managers. While your workload objects will not cause errors in the Distributed Manager if they contain statements the Distributed Manager does not recognize, your workload can not perform as expected. The following ESP Workload Manager functions are not supported by Distributed Managers:

• Resolution of runtime symbolic variables• Resolution of runtime CLANG or REXX statements• Workload objects containing EXTERNAL or MANUAL operands• ESP Workload Manager alerts

Support of these functions varies depending on the owning Manager of the Application or workload object. See the following table to determine when a function is unavailable:

Establishing ownership of a workload object

The owning Manager of a workload object controls the following:

• When the workload object is submitted• Status updates regarding the workload object• Reporting to other Managers about the status of the workload object

State of central ESP Workload Manager

Functions Unavailable if Owned by ESP Workload Manager

Functions Unavailable if Owned by a Distributed Manager

ESP Workload Manager available

• Runtime symbolic variables

• Runtime scripting of CLANG and REXX

• EXTERNAL• MANUAL• Alerts

ESP Workload Manager unavailable

• Runtime symbolic variables• Runtime scripting of

CLANG and REXX• EXTERNAL• MANUAL• Alerts

• Runtime symbolic variables

• Runtime scripting of CLANG and REXX

• EXTERNAL• MANUAL • Alerts


ESP-5.4-UG-05 365

Owner of an Application

The owning Manager of an Application is defined on the APPL statement or in the workload definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager. The owner specified at the Application level also applies to all links and tasks within the Application, unless the owner is specified in the link or task definition.

The owning Manager determines the status of the Application and is the only Manager that can complete the Application. Therefore, if you are running a distributed Application that must be able to complete when the mainframe is unavailable, a Distributed Manager must be the owner.

Owner of a link or task

The owner of a link or task is defined either at the Application level, with the OWNER operand on the APPL statement, or in the link or task definition with the OWNER operand. Specifying the OWNER operand in the link or task definition overrides any specified at the Application level.

Specifying a Distributed Manager as the owning Manager of a link or task allows you to define the link or task as distributed workload. The Distributed Manager determines if the conditions of the link or task are met.

Owner of a z/OS job

The owner of a z/OS job is always the central ESP Workload Manager.

Owner of a distributed workload object

The owner of a distributed workload object is not determined by an OWNER operand—it is determined by the network topology defined in the AGENTDEF file. A Manager—either a Distributed Manager or the central ESP Workload Manager—owns each Agent. The Manager that owns the Agent running the workload object owns the distributed workload object.

Creating distributed Applications

You can optimize your ESP Applications for use with a Distributed Manager by keeping some simple rules in mind when designing the Application. Also, consider if the Application will run most efficiently under the ownership of a Distributed Manager or the central ESP Workload Manager.

Section–Defining ownership of an Application

366 ESP-5.4-UG-05

To create an ESP Application that optimizes the Distributed Manager's capabilities:

1. Specify a Distributed Manager as the owner if this Application must be able to complete when ESP Workload Manager is unavailable. Specify an OWNER operand on the APPL statement or specify an owner in the Owner field in ESP Workstation.

2. Structure the Application to minimize embedded dependencies on z/OS workload. If dependencies on z/OS workload are required within the Application, try to place them at the beginning or end of the Application.

3. Ensure you do not include external or manual jobs within the Application.

4. Ensure any symbolic variables can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime symbolic variables.

5. Ensure any CLANG or REXX used within the Application can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime-scripting requirements.

6. Ensure you do not use ESP Workload Manager alerts in the Application.

7. Group workload by Distributed Manager where possible.

Defining ownership of an Application

The owning Manager of an Application is the only Manager that can start or complete an Application, change the status of an Application, or send notifications to the other Managers regarding the status of an Application. The owner of an Application is also the owner of all links and tasks within the Application, unless the owner is specified within the link or task definition.

The owning Manager of an Application is defined on the APPL statement or in the Application definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager.

If you are running a distributed Application that must be able to complete when the mainframe is unavailable, specify a Distributed Manager as the owner.


ESP-5.4-UG-05 367

To define the owner of an Application:

1. Create a new Application or edit an existing Application.

2. Proceed to step 4 if you are using ESP Workstation. Otherwise continue.

Proceed to step 3 if you want to specify an owner that changes based on a schedule. Otherwise continue.

Specify an OWNER operand on the APPL statement. Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character, as follows:

APPL PAYROLL OWNER(DMTOR)

Proceed to step 5.

3. Specify an OWNER operand on the APPL statement. Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character. Define the circumstances under which you want ownership of the Application determined. Specify the exceptions first. Specify the normal business-as-usual circumstances next. The following example defines a Distributed Manager as the owner of the Application on weekends:

IF TODAY('WEEKEND') THEN - APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL

Proceed to step 5.

4. Bring up Workload Definition Defaults in the Workload Editor.

Find the Owner field on the Application tab.

Enter a valid Distributed Manager name, up to 16 alphanumeric characters. The first character must be alphabetic or a national character.

5. Simulate the Event that runs this Application for each circumstance. Ensure the results are as expected.

6. Save the Application.

7. Upload the Procedure to the mainframe if you are using ESP Workstation.

Changing ownership of an Application

Depending on how ownership is specified in your Application, there can be times when you want to change the ownership, such as when you expect the mainframe to be shut down for maintenance.

You need to change the ownership in the Application, and trigger the Event prior to shutting down ESP Workload Manager.

Section–Changing ownership of an Application dynamically

368 ESP-5.4-UG-05

To change the ownership of an Application:

1. Edit the Application.

2. Change the owner to the new name if an owner is currently defined for the Application. Otherwise, add an owner name in the Owner field on ESP Workstation, or add an OWNER statement as follows:

APPL PAYROLL OWNER(DMTOR)

3. Simulate the Event that runs this Application to ensure expected results.


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.


5. If you are using ESP Workstation, upload the Procedure to the mainframe.

ESP-5.4-UG-05 369

Using XCF with ESP Workload Manager

ESP Workload Manager Version 5 Release 4 can use the Cross-System Coupling Facility (XCF) component of z/OS.


• Commands• XCF Services• State awareness• Trace

Chapter 12–Using XCF with ESP Workload Manager

ESP-5.4-UG-05 371

Enabling XCF Services

XCF Services are registered and started via the XCF START SERVICE xxxx command. This command must be coded in the initialization parameter data set. XCF Services must be coded in all the ESP Workload Manager subsystems in the XCF group.

When an XCF Service is coded and started on the ESP Workload Manager master, a listener is activated. When an XCF Service is started on the ESP Workload Manager proxies, it will connect to the ESP Workload Manager master’s listener for that Service.

Job tracking and data-set triggering

In ESP Workload Manager Version 5 Release 1, an ESP Workload Manager proxy subsystem writes job tracking and data-set-triggering records to a QUEUE file. The ESP Workload Manager master subsystem reads those records from the QUEUE file.

In ESP Workload Manager Version 5 Release 3, you have the option to use XCF for job tracking and data-set triggering. When XCF is used, the ESP Workload Manager proxy transmits job tracking and data-set-triggering records to the ESP Workload Manager master via XCF. You have a faster vehicle for communication, thus reducing contention on the QUEUE file.

If XCF Services are not enabled, ESP Workload Manager Version 5 Release 3 will continue to write job tracking and data-set-triggering records to the QUEUE file.

QUEUE file

The QUEUE file is still required in ESP Workload Manager Version 5 Release 3.

The QUEUE file has a record of abended job information (available via the DAB command) and information on jobs in the Input, Execute, and Output pnodes.

QUEUE file to XCF migration considerations

The ESP Workload Manager master will always check the QUEUE file for job tracking and data-set-triggering records written by ESP Workload Manager proxies. To migrate from the QUEUE file to an XCF connection, add the XCF START SERVICE xxxx commands in the ESP Workload Manager master and ESP Workload Manager proxy initialization parameter data set at the same time. If you are going to add the XCF START SERVICE xxxx commands separately, put them in the ESP Workload Manager master first.

If the ESP Workload Manager proxy has the XCF START SERVICE xxxx commands in the initialization parameters and the ESP Workload Manager master does not, job tracking and data set triggering records cannot be sent from the ESP Workload Manager proxy to the ESP Workload Manager master.

Section–XCF Services

372 ESP-5.4-UG-05

To start XCF Services:

Use the following is the syntax for the XCF START SERVICE commands in the initialization parameter data set:

XCF START SERVICE DSTRIGXCF START SERVICE TRACKING

Displaying XCF Services

The following is an example of a response to the XCF DISPLAY SERVICE command entered from the ESP Workload Manager master. This example includes XCF Services available with HAO and HPO:

Service Status Group Member SuspDSTRIG Active QS10 QS10M3 120ROUTING Active QS10 QS10M3 120SCOREBD Active QS10 QS10M3 120TRACKING Active QS10 QS10M3 120

This is an example of a response to the XCF DISPLAY SERVICE command entered from an ESP Workload Manager proxy. This example includes XCF Services available with HAO and HPO:

Service Status Group Member SuspDSTRIG Active QS10 QS10S 120ROUTING Active QS10 QS10S 100SCOREBD Active QS10 QS10S 120TRACKING Active QS10 QS10S 100

To display active XCF Service connections:

Enter the following command from an ESP Workload Manager master:

XCF DISPLAY ACTIVE

The following is an example of a response to the above command:

Group=P520, Member=P521Partner Service Status ConnectionListener DSTRIG ActiveListener TRACKING ActiveP522 DSTRIG Active 1,5P522 TRACKING Active 3,7

To stop an XCF Service:

• Enter the following command:

XCF STOP SERVICE DSTRIG

To restart an XCF Service on the fly after it has been stopped:

• Enter the following command:

XCF START SERVICE DSTRIG


ESP-5.4-UG-05 373

Purging XCF Services

When you purge a Service on an ESP Workload Manager master, the Service is purged and restarted. ESP Workload Manager stops and starts the listener. You should only use purging in situations when XCF STOP SERVICE does not appear to be working.

Example of Purging a Service

The following is an example of purging an XCF Service:

XCF PURGE SERVICE DSTRIG

Result:

ESP4221I Listener and 1 connection purged, Service=DSTRIG, Group=P520, Member=P521

Example of a restarted Service

To display the active XCF connections from an ESP Workload Manager master, enter:

XCF DISPLAY ACTIVE

The following example shows the Service DSTRIG connected on a new listener compared to the previous DISPLAY ACTIVE illustration:

Group=P520, Member=P521Partner Service Status ConnectionListener TRACKING ActiveListener DSTRIG ActiveP522 TRACKING Active 3,7P522 DSTRIG Active 4,8

State awareness

In an XCF group, state awareness exists between all the ESP Workload Manager subsystems in the group. Each ESP Workload Manager is a unique member of a common group, but they all know each other’s operating status.

Each ESP Workload Manager subsystem knows which other ESPs are active, quiesced, or failed in the XCF group. Each ESP Workload Manager member also knows the XCF Services that are available on the ESP Workload Manager master.

Section–Trace

374 ESP-5.4-UG-05

To display the members in the XCF group and their respective states:

• Use the XCF DISPLAY GROUP command.

XCF DISPLAY GROUPGroup=QS10 Member=QS10M3 Interval=60 TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusQS10 QS10M1 SYSC 0056 QS10 QS10 Shadow ActiveQS10 QS10M3 SYSA 009B QS10SHAD QS10 Master ActiveQS10 QS10M5 SYSC 0041 QS10SMC QS10 Shadow ActiveQS10 QS10S SYSA 009F QS10S QS1S Proxy ActiveQS10 QS10S2 SYSC 0046 QS10S2 QS12 Proxy Active

To stop an ESP Workload Manager XCF member:

• Use the XCF STOP MEMBER command.

XCF STOP MEMBER member

To stop all the ESP Workload Manager XCF members in the XCF group simultaneously:

• Use the XCF STOP GROUP command.

XCF STOP GROUP

Trace

The XCF Trace facility is a debug tool. XCF Trace captures data and spools the output to a preset sysout class. Only use the tool when instructed by Cybermation technical support.

To activate and capture data using XCF Trace:

1. Define a sysout class by entering:

XCF SET TRACE SYSOUT(x)

2. Activate the trace by entering:

XCF START TRACE

3. When you have captured the data, turn the trace off and spool the current XCF trace file to output by entering:

XCF STOP TRACE

SPIN TRACE

The XCF SPIN TRACE command spools the current XCF trace file to output and starts a new XCF trace file. It can be used when the trace file is started upon initialization of the ESP Workload Manager subsystem and kept running for the duration of the subsystem session.


ESP-5.4-UG-05 375

Usage notes

The XCF SET TRACE SYSOUT(x) and XCF START TRACE commands can be specified in the initialization parameter data set, but XCF STOP TRACE and XCF SPIN TRACE cannot. It is recommended to put XCF SET TRACE SYSOUT(x) in the initialization parameter data set because then only XCF START TRACE is required to start it.

Section–Trace

376 ESP-5.4-UG-05

ESP-5.4-UG-05 377

ESP Workload Manager High Performance Option

This chapter provides you with information on the ESP Workload Manager High Performance Option.


• Expedite• Resource Balancing• Workload Balancing• XCF Status Monitoring• XCF Routing Service• XCF Scoreboard Service

Section–Expedite

378 ESP-5.4-UG-05

Expedite

The Expedite feature in the ESP Workload Manager High Performance Option (HPO) provides a method of accelerating a job. With Expedite, you can define actions specifying how a job should be accelerated based on certain criteria.

If the command prefix of the first JES node is different from the command prefix on other JES nodes, you cannot use the EXPEDITE feature on them to:

• Change the class of a job• Change the priority of a job• Start a job immediately

Overview

Expedite Actions are defined in a policy. An Expedite Policy is associated with an ESP Application through the expedite statement. An Expedite Policy specifies how a job priority should be increased. The criteria are OVERDUE (the job start or end time is overdue) and CRITICAL_PATH (the job is on the critical path). OVERDUE and CRITICAL_PATH are EXPEDITE command operands.

Expedite Policies are defined in the initialization parameter data set or with the EXPEDITE command. The EXPEDITE command and expedite statement are documented on subsequent pages in this chapter and also in the ESP Workload Manager Reference Guide.

For information on the EXPEDITE initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.

The Expedite feature is documented in the following order in this chapter:

• Expedite actions• Examples of Expedite policy definitions• Expedite statement

Expedite actions

The methods of accelerating a job are known as Expedite actions.

The following Expedite actions are available for submitted jobs that are not yet executing. The objective of a job expedite is to initiate the job as soon as possible or to make it run as quickly as possible when it does start.

Option Action

1 Change the job JES execution class, specified by the EXPEDITE CLASS(class) operand.

2 Change (increase) the job priority on the JES execution queue, specified by the EXPEDITE PRIORITY(priority) operand.

3 Start the job immediately, specified by the EXPEDITE START operand.

Chapter 13–ESP Workload Manager High Performance Option

ESP-5.4-UG-05 379

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

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

Examples of Expedite policy definitions

The following command defines an Expedite policy, called POLICY_1. The Expedite policy specifies that a job in the ESP Application associated it is associated with, be expedited if its start or end time is overdue. If the job is expedited while it is waiting for execution, its execution queue priority will be set to 15. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.

EXPEDITE POLICY_1 ADD OVERDUE PRIORITY(15) SRVCLASS(JES_FAST)

If the following command is then issued after the previous one, a job in an ESP Application associated with Expedite policy POLICY_1 will be expedited if its start time or end time is overdue and it is on the critical path. If the job is expedited while it is waiting for execution, its job class will be set to F. It is started (initiated), provided F is an IBM WLM-managed job class queue. If the job is expedited while the job is executing, its service class will be changed to JES_FAST.

EXPEDITE POLICY_1 ALTER CRITICAL_PATH NOPRIORITY + CLASS(F) START

The following command has the same effect as issuing the previous two in succession:

EXPEDITE POLICY_1 ADD OVERDUE CRITICAL_PATH +CLASS(F) START SRVCLASS(JES_FAST)

Expedite statement

The expedite statement associates an ESP Workload Manager Expedite policy with an ESP Application. When EXPEDITE is specified within the scope of a job in the Application, it designates the Expedite policy for that job only. When EXPEDITE is specified outside the scope of any job in the Application, it designates the default Expedite policy for that Application.

Option Action

1 Change the job service class, specified by the EXPEDITE SRVCLASS(srvclass) operand. This requires the system be in IBM WLM goal mode.

2 Change the job performance group, specified by the EXPEDITE PERFORM(pgn) operand. This requires the system be in IBM WLM compatibility mode.

Option Action

1 Change the ESP Workload Manager priority of a job waiting for ESP Workload Manager resources dynamically. This is specified by the ESP_PRIORITY operand.

Section–Expedite

380 ESP-5.4-UG-05

Host security check

A user’s authority to specify an EXPEDITE statement in the ESP Application is governed by a host security check on the Expedite policy’s name.

The user the Application is running on behalf of must have read access to the specified Expedite policy host security resource name; otherwise, the Expedite action is ignored.

The host security resource name for an Expedite policy is:

prefix.EXPEDITE.name

Example

If an Application is invoked under user ID DEPT001 and contains the following statement:

EXPEDITE FAST_BAT

A host security check is made to ensure that user DEPT001 has read access to host security resource ESP.EXPEDITE.FAST_BAT before the Application can go ahead.

Related information

For more information, see the host security resource name EXPEDITE in the ESP Workload Manager Security Guide.

Example of using the expedite statement

For this example, the following Expedite policy definitions exist:

EXPEDITE FAST ADD OVERDUE PRIORITY(15) SRVCLASS(FAST)EXPEDITE SUPER ADD OVERDUE START SRVCLASS(SUPER)

Operand Description

prefix Indicates the ESP Workload Manager resource name prefix specified in the PREFIX operand of the SAFCLASS statement in the initialization parameters. This is usually PREFIX(ESP).

name Indicates the Expedite policy name.


ESP-5.4-UG-05 381

Example Application:

APPL DAILYRUNJCLLIB 'DEPT01.JCLLIB'EXPEDITE FAST

JOB JOB001 DUEOUT EXEC REAL PLUS 10 MINUTES RELEASE JOB002 RUN DAILYENDJOBJOB JOB002 EXPEDITE OFF RELEASE JOB003 RUN DAILYENDJOBJOB JOB003 EXPEDITE SUPER RUN DAILYENDJOBJOB JOB004 EXPEDITE OFF RUN DAILYENDJOB

How it works:

• Job JOB001 is associated with Expedite policy FAST and is expedited if it has not completed successfully 10 minutes after the trigger time of the corresponding Event.

• Job JOB002 is not associated with any Expedite policy and therefore cannot be expedited.

• Job JOB003 is associated with Expedite policy SUPER but can only be expedited manually (for example, by the XP CSF line command), as it has no due-out specification and Expedite policy SUPER does not specify CRITICAL_PATH as a criterion.

• Job JOB004 is not associated with any Expedite policy and therefore cannot be expedited.

Note: The above example is intended primarily to illustrate the capabilities of the expedite statement. Typically, most Applications will have a single, global-scope EXPEDITE statement to govern all jobs in the Application.

Section–Resource Balancing

382 ESP-5.4-UG-05

Resource Balancing

Resource balancing is an enhancement that enables ESP Workload Manager to monitor all the ESP Workload Manager resources in the ESP resource topology for availability and utilization.

When the ESP Workload Manager High Performance Option is not installed, if the first CPU in the ESP resource topology has a resource definition count of AVAIL=x, and x matches workload in the queue, ESP Workload Manager still sends workload to the first processor, regardless of whether or not the CPU was operating at ESP Workload Manager resource capacity.

When the ESP Workload Manager High Performance Option is installed, ESP Workload Manager checks all the CPUs and determines which machine has more available resources. ESP Workload Manager then selects the least loaded CPU and distributes the workload accordingly. ESP Workload Manager balances the workload across the ESP resource topology.

Usage note

There is no coding required to enable resource balancing. With the ESP Workload Manager High Performance Option installed, it is an automatic behavioral change

Workload Balancing

ESP Workload Manager uses workload balancing to select the where to run workload. For z/OS systems, ESP Workload manager uses WLM workload balancing, which is based on information from IBM WLM. For workload associated with ESP Agents, ESP Workload manager uses Agent workload balancing, which is based on polling the Agent platforms.

WLM workload balancing

To use WLM workload balancing, you must:

• Code one or more NODE initialization parameters or commands. You must specify the SYSPLEX operand.

• Code CPU initialization parameters or commands for each CPU participating in the load balancing. You must use the SYSNAME value as the name.

• Define resources with the RESDEF command specifying the WLM operand.

• Specify the required resources in the ESP Procedures for the jobs you want to direct to the CPU with the most available service units using workload balancing.


ESP-5.4-UG-05 383

Use of CPU service unit resources

You can define real resources representing a number of CPU service units required by a job. They are used for WLM workload balancing within a sysplex. The use of those resources is based on the feedback from IBM WLM queries. CPU service unit resources are supported for systems in a sysplex running in goal mode. When ESP Resource manager determines that a number of CPU service unit resources requested by a job is available on more than one system in the sysplex, it uses the feedback from IBM WLM queries to route the job on the system with the most available service units. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.

Coding RESDEF with WLM operand

You must define a WLM resource as LOCAL RENEWABLE. In a multi JES node sysplex environment, you must also specify GRAVITY in the resource definition.

To determine the MAX count, see the “CPU capacity table” in the MVS planning: Workload Management IBM manual. Choose a number of service units per second for your CPU model and multiply it by either 60, 180, or 600 for SUM60, SUM180, or SUM600 respectively. You can use the result or any higher number. If your installation has CPUs of different models, use the RESDEF SET command to adjust the counts on individual CPUs.

You can determine the quantity of the WLM resource required by jobs using either the CPU service units or the CPU time shares (percentage) of jobs in the entire workload. You can calculate these numbers based on ESP Workload Manager history reports with the SUNITS field selected. You can also use other performance and reporting tools. It is important that you understand that the resource represents the rate at which service units are consumed (over the last 60, 180, or 600 seconds), and not the total amount used by a job. Reports usually show the total amount.

ESP Workload Manager routes a job to one of the available systems based on the WLM resources requested by a job and other requested resources.

IBM WLM feedback is a measurement of recent but past activity; therefore, it is not a precise prediction of a CPU load by the time ESP Workload Manager submits a job. The real value of a WLM resource is the number of unused service units. This number can be different from the number of service units available for a job if that job service class is higher than the service class of the currently executing workload.

The workload is balanced between all the CPUs that belongs to the same NODE in the resource topology. The node is defined with the NODE initialization parameter or command (it must include the SYSPLEX operand).

Section–Workload Balancing

384 ESP-5.4-UG-05

Scenario using WLM workload balancing

Assumptions:

• 2 CPUs in node Toronto• 3 CPUs in node Chicago

Setting the topology:

NODE TORONTO ADD SYSPLEXNODE CHICAGO ADD SYSPLEXCPU T1 ADD NODE(TORONTO) CURRENTCPU T2 ADD NODE(TORONTO)CPU C1 ADD NODE(CHICAGO)CPU C2 ADD NODE(CHICAGO)CPU C3 ADD NODE(CHICAGO)

Setting the resources

RESDEF MAINRES ADD LOCAL RENEWABLE GRAVITY + MAX(100) WLM(SUM180)

ESP Workload Manager will receive the number of unused CPU service units over three minutes from IBM WLM. The number of unused CPU service units is obtained before a job using the resource is submitted.

Specifying a job:

JOB mytojob RUN DAILY RESOURCE(1,MAINRES)ENDJOB

The job runs on the CPU where maximum service units is available. The number 1 in RESOURCE(1,MAINRES) should be replaced by the number of service units used by the job. You can obtain this number with the LJE command and in the history report.


ESP-5.4-UG-05 385

Agent workload balancing

To use Agent workload balancing, you must:

• Code the NODE initialization parameter or command to define a common node to which all the Agent platform participating in load balancing belong.

• Code CPU commands or initialization parameters with the AGENT operand for each Agent platform participating in the load balancing.

• Define resources with the RESDEF command specifying the MONITOR(CPU) operand and a non-zero POLL operand.

• Specify the needed resources in the ESP Procedures of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.

• Code the ROUTING operand in the AGENT statement of the jobs you want to direct to the Agent platform with the highest percentage of availability using workload balancing.

Resource representing the percentage of CPU availability

You can define real resources representing the percentage of CPU availability required by a job. This is used for workload balancing within a system with multiple ESP Agents. The workload balancing is based on the feedback from the Agents. When ESP Resource manager determines that the percentage of CPU availability requested by a job is available on more than one system, it uses the feedback from the Agents to route the job to the Agent platform with the highest percentage of availability. The availability of other resources can affect how ESP Workload Manager selects the best system for the job.

Coding RESDEF with MONITOR(CPU) operand

You must define a MONITOR(CPU) resource as LOCAL RENEWABLE GRAVITY.

The system asks all Agents to provide the percentage of availability on the platforms they control. This is done at the frequency specified by the POLL operand for platforms where the corresponding CPU initialization parameter includes an AGENT operand. You can limit the scope of the resource you define by using the NODE and CPU operands.

ESP Workload Manager routes a job to one of the available systems based on the MONITOR(CPU) resources requested by a job and other requested resources.

The workload is balanced between all the Agent platform in the same NODE. The node is defined with the NODE initialization parameter or command.

Section–Workload Balancing

386 ESP-5.4-UG-05

Scenario using Agent workload balancing

Assumptions:

• 3 Windows NT CPUs associated with Agents called AGwin1, AGwin2, and AGwin3

• 4 UNIX CPUs associated with Agents called AGunix1, AGunix2, AGunix3, and AGunix4

Setting the topology:

NODE WIN ADDNODE UNIX ADDCPU WIN1 ADD NODE(WIN)AGENT(AGwin1)CPU WIN2 ADD NODE(WIN)AGENT(AGwin2)CPU WIN3 ADD NODE(WIN)AGENT(AGwin3)CPU UNIX1 ADD NODE(UNIX)AGENT(AGunix1)CPU UNIX2 ADD NODE(UNIX)AGENT(AGunix2)CPU UNIX3 ADD NODE(UNIX)AGENT(AGunix3)CPU UNIX4 ADD NODE(UNIX)AGENT(AGunix4)

All the CPUs that have the same NODE operand in the CPU initialization parameter are linked.

Setting the resources:

RESDEF RESWIN ADD NODE(WIN) LOCAL RENEWABLE GRAVITY MAX(100)+ MONITOR(CPU) POLL(5 MINUTES)RESDEF RESUNIX ADD NODE(UNIX) LOCAL RENEWABLE GRAVITY MAX(100)+ MONITOR(CPU) POLL(5 MINUTES)

ESP Workload Manager will receive the status of every CPU in both nodes every five minutes.

Specifying an NT job:

NT_JOB myntjob RUN DAILY RESOURCE(1,RESWIN) AGENT AGwin1 ROUTING CMDNAME C:\myjob.exeENDJOB

The ROUTING operand specifies that the job may run on any CPU in the same node as the CPU associated with Agent AGwin1.

Note: The value of 1 in the RESOURCE statement should be changed to a realistic value representing the actual load of the job on CPUs. If you do not adjust this value, the lag time due to the frequency of the polling may affect the CPU selection.


ESP-5.4-UG-05 387

Specifying a UNIX job:

UNIX_JOB myunjob RUN DAILY RESOURCE(1,RESUNIX) AGENT AGunix1 ROUTING SCRIPTNAME /SW/myjobENDJOB

The ROUTING operand specifies that the job may run on any CPU in the same node as the CPU associated with Agent AGwin1.

Note: The value of 1 in the RESOURCE statement should be changed to a realistic value representing the actual load of the job on CPUs. If you do not adjust this value, the lag time due to the frequency of the polling may affect the CPU selection.

XCF Status Monitoring

Note: XCF status monitoring is also available with the ESP Workload Manager High Availability Option (HAO).

XCF status monitoring is a feature that monitors ESP Workload Manager XCF members’ activity for any possible problems. An ESP Workload Manager XCF member requests XCF status monitoring when it joins the XCF group.

When XCF status monitoring is enabled, ESP Workload Manager notifies XCF of an interval period. The interval period is specified in seconds. ESP Workload Manager then updates its status with XCF according to the specified interval.

XCF status monitoring is enabled by coding the INTERVAL operand on the SYSPLEX initialization parameter.

How XCF status monitoring works

If an ESP Workload Manager subsystem has not updated its XCF status monitoring field for at least two intervals, XCF warns the other members in the XCF group of a possible problem with that ESP Workload Manager as there can be either a loop or hang in the ESP Workload Manager main task.

Message ESP4316I is issued:

ESP4316I XCF status update missing, possible main task loop or hang

Note: This message may not necessarily indicate a problem with the ESP Workload Manager. For example, the system that ESP Workload Manager is running under can be heavily loaded and z/OS is not dispatching ESP Workload Manager.

Section–XCF Routing Service

388 ESP-5.4-UG-05

Second warning message

When XCF does not receive a positive response from the failing ESP Workload Manager subsystem, XCF broadcasts to all the other ESP Workload Manager XCF members in the XCF group that a status update missing condition exists for that member.

Message ESP4331W is issued:

ESP4331W XCF status update missing

XCF member failure

If the failing ESP Workload Manager subsystem terminates, message ESP4317I is issued:

ESP4317I XCF member state change

Normal operating status resumed

If the failing ESP Workload Manager subsystem resumes its normal operating status, message ESP4318I is issued:

ESP4318I XCF status update resumed

For the full explanation of the ESP Workload Manager messages indicated above, see the ESP Workload Manager Messages manual.

XCF Routing Service

Note: XCF routing service is also available with the ESP Workload Manager High Availability Option (HAO).

XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services also apply to the XCF ROUTING and SCOREBD Services.

Note: Cybermation recommends that the default routing be changed from LOCAL to MASTER during installation. You can display your current routing status by using the ROUTING STATUS command.

Overview

The ROUTING Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and Workstation servers) connected to the ESP Workload Manager proxy the ability to route subsystem requests, usually ESP Workload Manager commands, to the ESP Workload Manager master. The ESP Workload Manager master processes the subsystem requests and routes command responses back


ESP-5.4-UG-05 389

to the ESP Workload Manager client through the ESP Workload Manager proxy. In this scenario, the ROUTING MASTER command must be specified.

Description

Without ESP Workload Manager High Availability Optionor High Performance Option

Typically installations run an ESP Workload Manager proxy on each system in the sysplex and the ESP Workload Manager master runs on one of the systems. To issue subsystem requests to the ESP Workload Manager master, an ESP Workload Manager client must connect directly to the ESP Workload Manager master. Therefore, the TSO/ISPF user and/or Workstation Server must be on the same system as the ESP Workload Manager master.

With ESP Workload Manager High Availability Optionor High Performance Option

By connecting an ESP Workload Manager client to the ESP Workload Manager proxy rather than to the ESP Workload Manager master, the client (TSO/ISPF users or Workstation Servers) can run on any system in the sysplex and issue subsystem requests to the ESP Workload Manager master through the XCF ROUTING Service.

Benefit

It does not matter which system in the sysplex the ESP Workload Manager master is running on. The ESP Workload Manager proxy always knows, through its XCF group member State Awareness capabilities, where the ESP Workload Manager master is and how to access it.

Enabling XCF ROUTING

XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if that data set is different than the ESP Workload Manager master. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.

The following is an example enabling XCF ROUTING:

XCF START SERVICE ROUTING

The ROUTING command

The ROUTING command is an ESP Workload Manager command that can be issued in ESP Workload Manager page mode or in a line mode interface. It can be issued by both TSO/ISPF users and ESP Workstation users.

Section–XCF Scoreboard Service

390 ESP-5.4-UG-05

Purpose of the ROUTING command

The ROUTING command is used to instruct the connected ESP Workload Manager subsystem to either process subsystem requests itself, or to route subsystem requests to the ESP Workload Manager master.

How it works

When an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to the ESP Workload Manager master, the ROUTING command is not useful, as the LOCAL and MASTER options mean the same thing.

However, when an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to an ESP Workload Manager proxy, entering ROUTING LOCAL instructs the ESP Workload Manager proxy to process subsystem requests itself. Subsystem requests are usually ESP Workload Manager commands. If you enter ROUTING MASTER, this instructs the ESP Workload Manager proxy to route subsystem requests to the ESP Workload Manager master.

When an ESP Workload Manager client is connected to the local ESP Workload Manager proxy, subsystem requests can only be forwarded to the ESP Workload Manager master if an active XCF ROUTING connection exists between the local ESP Workload Manager proxy and the ESP Workload Manager master.

Examples

The following example instructs the connected ESP Workload Manager subsystem to route subsystem requests to the ESP Workload Manager master:

ROUTING MASTER

The following example instructs the connected ESP Workload Manager subsystem to process subsystem requests itself:

ROUTING LOCAL

XCF Scoreboard Service

Note: XCF scoreboard service is also available with the ESP Workload Manager High Availability Option (HAO).

XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the new XCF ROUTING and SCOREBD Services.

The SCOREBD Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and/or Workstation Servers) connected to the ESP Workload Manager proxy to view the ESP Workload Manager scoreboard. When an ESP


ESP-5.4-UG-05 391

Workload Manager proxy’s XCF SCOREBD Service connects to the ESP Workload Manager master, the master transmits the contents of the scoreboard to the ESP Workload Manager proxy. Thereafter, the ESP Workload Manager master transmits every scoreboard update it makes to all ESP Workload Manager proxies connected to it via the XCF SCOREBD Service.

Benefit

The ESP Workload Manager proxies can maintain their own respective copies of the scoreboard.

The XCF SCOREBD Service makes it possible for an ESP Workload Manager TSO/ISPF client connected to an ESP Workload Manager proxy to view the scoreboard through CSF. It also makes scoreboard information accessible to Workstations connected to a Workstation Server that, in turn, is connected to an ESP Workload Manager proxy.

Enabling XCF SCOREBD

XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if that data set is different than the ESP Workload Manager master. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.

The following is the command syntax to enable XCF SCOREBD:

XCF START SERVICE SCOREBD


392 ESP-5.4-UG-05

ESP-5.4-UG-05 393

ESP Workload Manager High Availability Option

This chapter provides you with information on the ESP Workload Manager High Availability Option.


• Shadow Manager• ARM Registration• XCF Status Monitoring• XCF Routing Service• XCF Scoreboard Service

Section–Shadow Manager

394 ESP-5.4-UG-05

Shadow Manager

Shadow manager provides your environment with the ability to shift the workload to another ESP Workload Manager master, so processing can continue.

Shadow manager can eliminate the single point of failure by providing a hot backup and instant switch over should a system fail.

Shadow manager is an ESP Workload Manager subsystem that reads its initialization parameters, joins an ESP Workload Manager XCF group, then monitors the ESP Workload Manager master in that XCF group for its termination. When the ESP Workload Manager master terminates, the shadow manager takes action based on its shadow goal for that type of termination or takes action from a direct command to take over as the ESP Workload Manager master.

An ESP Workload Manager master may or may not be shadow-enabled.

Shadow-enabled ESP Workload Manager master

A shadow-enabled ESP Workload Manager master is an ESP Workload Manager subsystem that will become a shadow manager if, when it is started, it detects that an active ESP Workload Manager master already exists in its XCF group.

Shadow-disabled ESP Workload Manager master

A shadow-disabled ESP Workload Manager master is an ESP Workload Manager subsystem that will terminate if, when it is started, it detects that an active ESP Workload Manager master already exists in its XCF group.

Data-set usage

Cybermation strongly recommends that a shadow manager read the same initialization parameter data set as the ESP Workload Manager master.

Shadow manager must have the same checkpoint file as the ESP Workload Manager master.

Shadow manager START parameters

An ESP Workload Manager master is defined as shadow-enabled through either the PRIMARY or SHADOW parameters. These can be specified in the START command or in the started task JCL.

An ESP Workload Manager subsystem is defined as a shadow manager through either the SECONDARY or SHADOW parameters. These can be specified in the START command or in the started task JCL.

For information on using the START command, see the ESP Workload Manager Operator’s Guide.

Chapter 14–ESP Workload Manager High Availability Option

ESP-5.4-UG-05 395

Symbolic variable: %SHADOW

%SHADOW is a symbolic variable that can be used anywhere in the initialization parameters. The %SHADOW symbolic variable is created only if the SHADOW operand is used in the START parameters or JCL, for the ESP Workload Manager subsystem.

The ESP Workload Manager master and shadow managers must have different XCF member names.

Using the %SHADOW symbolic variable is one way to ensure the ESP Workload Manager master and shadow managers have different XCF member names when they read the same initialization parameter data set.

For example:

SYSPLEX GROUP(ESP) MEMBER(ESPM%SHADOW)

Shadow Goal

A shadow goal is a set of actions that a shadow manager is instructed to perform when the ESP Workload Manager master terminates.

How a shadow goal works

A shadow manager can have one shadow goal for each way the ESP Workload Manager master can terminate. That is, it can have a QUIESCE shadow goal, a LEAVE shadow goal and/or a FAIL shadow goal.

A shadow manager takes action automatically only if it has a shadow goal for the way in which the ESP Workload Manager master terminates. For example, if the ESP Workload Manager master terminates and enters an XCF quiesced state, the shadow manager must have a QUIESCE shadow goal to take any specified action.

In addition to specifying actions that a shadow manager must perform, a shadow goal also specifies how long the shadow manager must wait before performing the actions.

What actions a shadow goal can take

A shadow goal can specify one or more of the following actions to take when the ESP Workload Manager master terminates:

• Issue warning message #4397• Issue a system command• Take over as the ESP Workload Manager master• Take over as the ESP Workload Manager master and trigger an ESP Event

SHADGOAL command

A shadow goal is defined by the SHADGOAL command or defined in the initialization parameters. The SHADGOAL command is documented in the ESP

Section–Shadow Manager

396 ESP-5.4-UG-05

Workload Manager Reference Guide. For information on the SHADGOAL initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.

XCF member termination

The ESP Workload Manager master (or any XCF group member) can terminate in one of three possible ways:

• QUIESCE• LEAVE• FAIL

QUIESCE

The ESP Workload Manager master terminates normally but leaves a trace of its membership in the group behind. An XCF DISPLAY GROUP ESP Workload Manager command will show the XCF member in a quiesced state.

LEAVE

The ESP Workload Manager master terminates normally but leaves no trace of its membership in the group behind. The XCF member goes into an undefined state. An XCF DISPLAY GROUP ESP Workload Manager command will not show the XCF member, because it does not exist in any way.

FAIL

This happens when the ESP Workload Manager master terminates abnormally (ABENDs). An XCF DISPLAY GROUP ESP Workload Manager command will show the XCF member in a failed state.

SHADGOAL Command

You can specify SHADGOAL in the ESP Workload Manager initialization file of a shadow manager or a shadow-enabled ESP Workload Manager master, or dynamically in a shadow manager, via the z/OS MODIFY command. You can also use the SHADGOAL command to delete a shadow goal or to list the shadow goals.

The SHADGOAL syntax varies in the initialization parameter and the z/OS MODIFY command. For information on the SHADGOAL initialization parameter, see the ESP Workload Manager Installation and Configuration Guide. For information on the z/OS MODIFY SHADGOAL command, see the ESP Workload Manager Reference Guide.


ESP-5.4-UG-05 397

SHADGOAL examples

The following example specifies that 180 seconds (3 minutes) after the ESP Workload Manager master terminates and enters an XCF quiesced state, the shadow manager issues warning message #4397 and issues z/OS command S ESPM.

SHADGOAL MASTER(QUIESCE) AFTER(180) WARN +COMMAND('S ESPM')

The following example specifies that 300 seconds (5 minutes) after the ESP Workload Manager master abnormally terminates, the shadow manager issues warning message #4397 and takes over as the ESP Workload Manager master.

SHADGOAL MASTER(FAIL) AFTER(300) WARN TAKEOVER

The following example specifies the shadow goal for the LEAVE option is deleted immediately.

SHADGOAL DELETE MASTER(LEAVE)

Note: Once a shadow-enabled ESP Workload Manager becomes the active master in the XCF group, all shadow goals for that shadow-enabled ESP Workload Manager are deleted and the SHADGOAL command ceases to be available for that master.

Manually moving control

You can switch control of the workload to shadow manager, without shadow goals defined in your initialization parameters. You use an ESP Workload Manager XCF command or an z/OS MODIFY command issued manually. ESP Workload Manager XCF commands can be issued from the ESP Workload Manager master or from any ESP Workload Manager proxy that is joined to the same ESP Workload Manager XCF group as the target shadow manager.

Important: When you are connected to an ESP Workload Manager proxy, you must have the XCF ROUTING service enabled and the ROUTING LOCAL command must be issued to instruct the ESP Workload Manager proxy to process subsystem requests itself. Then you can issue the ESP Workload Manager XCF commands from the ESP Workload Manager proxy you are logged on to.

For more information on XCF ROUTING, see “XCF Routing Service” on page 400.

XCF command examples

The following is an example of shutting down the ESP Workload Manager master (ESPM), displaying the group to ensure ESPM is in a QUIESCE state, and then moving control of the workload to shadow manager (ESPS):

XCF STOP MEMBER ESPM XCF DISPLAY GROUPXCF SET MEMBER ESPS MASTER

Section–ARM Registration

398 ESP-5.4-UG-05

The following is an example of the ESP Workload Manager master (ESPM) being disabled and moving control of the workload to shadow manager (ESPS):

XCF FORCE MEMBER ESPMXCF DISPLAY GROUPXCF SET MEMBER ESPS MASTER

z/OS MODIFY command

Shadow manager will take control of the workload if the following z/OS MODIFY command is issued to the shadow manager when the ESP Workload Manager master is not active:

F jobname,SHADOW TAKEOVER

In the preceding command, jobname is the name of the shadow manager started task.

ARM Registration

The ESP Workload Manager High Availability Option provides support for the IBM Automatic Restart Management (ARM) function of OS/390.

The ARMELEM initialization parameter enables ESP Workload Manager to register with ARM. If an ESP Workload Manager fails, it can now be automatically restarted with ARM.

For more information on the ARMELEM initialization parameter, see the ESP Workload Manager Installation and Configuration Guide.

How it works

ARM will restart a registered ESP Workload Manager subsystem that fails if an ARM policy (either the IBM default or a user-defined policy) is active on the system where the failure occurs and on the system where the restart is to occur.

If the ESP Workload Manager master fails or the system the ESP Workload Manager master is running on fails, the registered ESP Workload Manager master can be restarted on the same system or restarted on another system in the sysplex.

If an ESP Workload Manager proxy is registered with ARM and the ESP Workload Manager proxy fails, the ESP Workload Manager proxy will be restarted on the same system by default. Restarts should be limited to the system the ESP Workload Manager proxy runs on.

ARM couple data set

The ARMELEM initialization parameter requires the system the ESP Workload Manager is running on to be connected to an ARM couple data set.


ESP-5.4-UG-05 399

ARM and shadow manager

If an installation uses shadow manager, it can consider ARM unnecessary for the ESP Workload Manager master and shadow managers. However, ARMELEM co-exists well with shadow manager. The default RESTART keyword value for shadow-enabled ESP Workload Manager masters and shadow managers has deliberately been set to ELEMENT_FAILURE, so that restarts on other systems in the sysplex do not occur when the system the ARM-registered ESP Workload Manager is running on fails.

An installation can use ARM instead of shadow manager for ESP Workload Manager master restarts.

Note: Shadow manager does not require an ARM couple data set and ARM policy.

XCF Status Monitoring

Note: XCF status monitoring is also available with the ESP Workload Manager High Performance Option (HPO)

XCF status monitoring is a feature that monitors ESP Workload Manager XCF members’ activity for any possible problems. An ESP Workload Manager XCF member requests XCF status monitoring when it joins the XCF group.

When XCF status monitoring is enabled, ESP Workload Manager notifies XCF of an interval period. The interval period is specified in seconds. ESP Workload Manager then updates its status with XCF according to the specified interval.

XCF status monitoring is enabled by coding the INTERVAL operand on the SYSPLEX initialization parameter.

How XCF status monitoring works

If an ESP Workload Manager subsystem has not updated its XCF status monitoring field for at least two intervals, XCF will warn the other members in the XCF group of a possible problem with that ESP Workload Manager. There can be either a loop or hang in the ESP Workload Manager main task. Message ESP4316I is issued.

ESP4316I XCF status update missing, possible main task loop or hang

Note: This message may not necessarily indicate a problem with the ESP Workload Manager. For example, the system that ESP Workload Manager is running under can be heavily loaded and z/OS is not dispatching ESP Workload Manager.

Second warning message

When XCF does not receive a positive response from the failing ESP Workload Manager subsystem, XCF will broadcast to all the other ESP Workload Manager XCF

Section–XCF Routing Service

400 ESP-5.4-UG-05

members in the XCF group that a status update missing condition exists for that member.

Message ESP4331W is issued:

ESP4331W XCF status update missing

XCF member failure

If the failing ESP Workload Manager subsystem terminates, message ESP4317I is issued:

ESP4317I XCF member state change

Normal operating status resumed

If the failing ESP Workload Manager subsystem resumes its normal operating status, message ESP4318I is issued:

ESP4318I XCF status update resumed

For the full explanation of the ESP Workload Manager messages indicated above, see the ESP Workload Manager Messages manual.

XCF Routing Service

Note: XCF routing service is also available with the ESP Workload Manager High Performance Option (HPO)

XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the XCF ROUTING and SCOREBD Services.

Note: Cybermation recommends that the default routing be changed from LOCAL to MASTER during installation. You can display your current routing status by using the ROUTING STATUS command.

Overview

The ROUTING Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and Workstation servers) connected to the ESP Workload Manager proxy the ability to route subsystem requests, usually ESP Workload Manager commands, to the ESP Workload Manager master. The ESP Workload Manager master processes the subsystem requests, and routes command responses back to the ESP Workload Manager client through the ESP Workload Manager proxy. In this scenario, the ROUTING MASTER command must be specified.


ESP-5.4-UG-05 401

Description

Without ESP Workload Manager High Availability Option or High Performance Option

Typically installations run an ESP Workload Manager proxy on each system in the Sysplex and the ESP Workload Manager master runs on one of the systems. To issue subsystem requests to the ESP Workload Manager master, an ESP Workload Manager client must connect directly to the ESP Workload Manager master. Therefore, the TSO/ISPF user and/or Workstation Server must be on the same system as the ESP Workload Manager master.

With ESP Workload Manager High Availability Optionor High Performance Option

By connecting an ESP Workload Manager client to the ESP Workload Manager proxy rather than to the ESP Workload Manager master, the client (TSO/ISPF users or Workstation Servers) can run on any system in the sysplex and issue subsystem requests to the ESP Workload Manager master through the XCF ROUTING Service.

Benefit

It does not matter which system in the sysplex the ESP Workload Manager master is running on. The ESP Workload Manager proxy always knows through its XCF group member State Awareness capabilities, where the ESP Workload Manager master is and how to access it.

Enabling XCF ROUTING

XCF START SERVICES must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. Cybermation recommends that the shadow manager uses the same initialization parameter data set as the ESP Workload Manager master. You can use symbolic variables to set the different XCF group member names.

The following is an example enabling XCF ROUTING:

XCF START SERVICE ROUTING

The ROUTING command

The ROUTING command is an ESP Workload Manager command that can be issued in ESP Workload Manager page mode or in a line mode interface. It can be issued by both TSO/ISPF users and ESP Workstation users.


402 ESP-5.4-UG-05

Purpose of the ROUTING command

The ROUTING command is used to instruct the connected ESP Workload Manager subsystem to either process subsystem requests itself, or to route subsystem requests to the ESP Workload Manager master.

How it works

When an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to the ESP Workload Manager master, the ROUTING command is not needed, as the LOCAL and MASTER options mean the same thing.

However, when an ESP Workload Manager client (TSO/ISPF user or Workstation Server) is connected to an ESP Workload Manager proxy, entering ROUTING LOCAL instructs the ESP Workload Manager proxy to process subsystem requests itself. Subsystem requests are usually ESP Workload Manager commands. If you enter ROUTING MASTER, this instructs the ESP Workload Manager proxy to route subsystem requests to the ESP Workload Manager master.

When an ESP Workload Manager client is connected to the local ESP Workload Manager proxy, subsystem requests can only be forwarded to the ESP Workload Manager master if an active XCF ROUTING connection exists between the local ESP Workload Manager proxy and the ESP Workload Manager master.

Examples

The following example instructs the connected ESP Workload Manager subsystem to route subsystem requests to the ESP Workload Manager master:

ROUTING MASTER

The following example instructs the connected ESP Workload Manager subsystem to process subsystem requests itself:

ROUTING LOCAL

XCF Scoreboard Service

Note: XCF scoreboard service is also available with the ESP Workload Manager High Performance Option (HPO)

XCF Services are functions of ESP Workload Manager that use sysplex architecture. The same XCF commands that apply to the XCF TRACKING and DSTRIG Services, also apply to the new XCF ROUTING and SCOREBD Services.

The SCOREBD Service is an XCF connection between an ESP Workload Manager proxy and the ESP Workload Manager master that enables ESP Workload Manager clients (TSO/ISPF users and/or Workstation Servers) connected to the ESP Workload Manager proxy, to view the ESP Workload Manager scoreboard. When an ESP


ESP-5.4-UG-05 403

Workload Manager proxy’s XCF SCOREBD Service connects to the ESP Workload Manager master, the master transmits the contents of the scoreboard to the ESP Workload Manager proxy. Thereafter, the ESP Workload Manager master transmits every scoreboard update it makes to all ESP Workload Manager proxies connected to it via the XCF SCOREBD Service.

Benefit

The ESP Workload Manager proxies can maintain their own respective copies of the scoreboard.

The XCF SCOREBD Service makes it possible for an ESP Workload Manager TSO/ISPF client connected to an ESP Workload Manager proxy to view the scoreboard through CSF. It also makes scoreboard information accessible to Workstations connected to a Workstation Server that, in turn, is connected to an ESP Workload Manager proxy.

Enabling XCF SCOREBD

XCF START Services must be coded in the initialization parameter data set of all the ESP Workload Manager subsystems in the XCF group, that is, the ESP Workload Manager master and all the ESP Workload Manager proxies. It should also be in the shadow manager initialization parameter data set if the data set is different than the ESP Workload Manager master.

The following is the command syntax to enable XCF SCOREBD:

XCF START SERVICE SCOREBD


404 ESP-5.4-UG-05

ESP-5.4-UG-05 405

Glossary

Absolute day By default, ESP Workload Manager considers each day to begin at 00:00. ESP Workload Manager refers to a day that begins at 00:00 as the absolute day.

Note: Cybermation recommends you use absolute days (as opposed to logical days) because of their ease of use and because they can handle almost all scheduling requirements.

AFM Automated Framework Message. A structured message used to communicate commands and status between clients and servers.

Agent See “ESP Agent” on page 407.

Agentmon Workload object that monitors the status of ESP Agents.

Alert A mechanism to trigger ESP Workload Manager activity when specific actions take place in your Application. For example, you can use ESP Workload Manager to trigger an Event when a job fails.

Application See “ESP Application” on page 407.

Audit log An audit trail of ESP Workload Manager activity. It stores information on administrative activities, operator commands, and Application and Event processing. The audit log is in the job log.

406 ESP-5.4-UG-05

AUTOVAR Automatic variable representing lines of JCL, data, or comments that ESP Workload Manager automatically includes at the beginning or end of a job’s JCL.

Calendar Used to specify what day is the first day of the week and what are the workdays. A collection of definitions of holidays and special days that are unique to your installation.

CCCHK Statement used to detect condition codes. Using it, you can immediately stop a failing job, without running any subsequent steps regardless of the conditional operands.

CCFAIL Abbreviation for condition code fail. CCFAIL statements define conditions that, if met, cause the job to fail.

CLANG Control language. This is a high level programming language developed for ESP Workload Manager.

Command A request made to ESP Workload Manager. The most frequent types of commands are:

• General commands—are issued without general restrictions• OPER commands—must be preceded by the word OPER• Authorized commands—can be issued by users authorized in the security

system• Authorized OPER commands—can be issued by users authorized in the

security system and must be preceded by the word OPER

Commands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.

Consolidated StatusFacility (CSF)

An ESP Workload Manager facility for displaying and manipulating the workload in ISPF.

COPYJCL A user data set containing a copy of the JCL for jobs submitted by ESP Workload Manager when you specify the COPYJCL statement.

Critical path The longest path to a workload object representing a critical point in the ESP Application. It is based on historical execution time.

Data object See “Variable” on page 412.

DJC Dependent Job Control. A Cybermation product used to control resources and job networks at the initiator level.

DJC job network A group of related jobs where dependencies are controlled at the initiator level.

DOCLIB A user data set containing job documentation entries.

DSTRIG A workload object used to build a dependency between an Event or an ESP Application and data set activity, such as FTP transfer or creation of a data set.

Enqueue Provides the capability for a job to request exclusive or shared use of a resource without the need to define the resource explicitly in advance. ESP Workload

Glossary

ESP-5.4-UG-05 407

Manager will prevent jobs with mutually exclusive requests from executing concurrently. ESP ENQUEUE behaves like the z/OS enqueues.

ESP Agent Software running on a distributed platform allowing ESP Workload Manager or ESP Espresso to control workload on distributed platforms, such as UNIX, OS/400, or Windows NT, or in distributed environments, such as SAP or PeopleSoft.

ESP Application A specific instance of a group of related workload objects. It is generated from one or more ESP Procedures when an Event is triggered and runs under the control of ESP Workload Manager. ESP Applications include the scheduling relationship between workload objects.

ESP Encore ESP Encore is a rerun/restart product that works with ESP Workload Manager to restart batch jobs with a minimum amount of intervention. ESP Encore makes the necessary adjustments to batch JCL to allow for an error-free restart. ESP Encore can automatically clean up data sets or back out batch jobs. ESP Encore can also predict errors.

ESP Espresso A decision-making product running on UNIX or Windows.

ESP Procedure A source list of statements and commands entered by users. ESP Workload Manager reads one or more ESP Procedures when an Event is triggered. ESP Procedures containing the APPL statement are used by ESP Workload Manager to generate ESP Applications. ESP Procedures are used to specify how the workload is scheduled.

ESP Workload Manager A decision-making product running on z/OS. It manages the workload across the enterprise.

ESP Workload ManagerHigh Availability Option

(HAO)

ESP Workload Manager High Availability Option takes full advantage of the IBM clustering sysplex technology to increase enterprise IT performance by improving the availability of system resources throughout the organization. It includes:

• Shadow manager: to provide your environment with the ability to shift the workload to another ESP Workload Manager master, so processing can continue.

• Support for the IBM Automatic Restart Management (ARM) function of OS/390.

• XCF status monitoring: to monitor ESP Workload Manager XCF members’ activity for any possible problems.

• XCF routing service: to connect an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave the ability to route subsystem requests to the ESP Workload Manager master.

• XCF scoreboard service: to connect between an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave to view the ESP Workload Manager scoreboard.

408 ESP-5.4-UG-05

ESP Workload ManagerHigh Performance

Option (HPO)

ESP Workload Manager High Performance Option optimizes workload to significantly increase the performance of the enterprise IT environment. It includes:

• Expedite: to define actions specifying how a job should be accelerated based on criteria you specify.

• Resource balancing: to enable ESP Workload Manager to monitor all the ESP Workload Manager resources in the ESP resource topology for availability and utilization.

• Workload balancing: to select where to run workload. • XCF status monitoring: to monitor ESP Workload Manager XCF members’

activity for any possible problems.• XCF routing service: to connect an ESP Workload Manager slave and the

ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave the ability to route subsystem requests to the ESP Workload Manager master.

• XCF scoreboard service: to connect between an ESP Workload Manager slave and the ESP Workload Manager master, enabling ESP Workload Manager clients connected to the ESP Workload Manager slave to view the ESP Workload Manager scoreboard.

ESP Workstation A graphical user interface for defining, monitoring, and controlling the entire enterprise workload. It is a significant productivity tool for those defining and scheduling applications and for the data-center production personnel who manage them.

Event An anticipated scheduling milestone. Events include the conditions under which they are triggered and the commands to be performed when they are triggered. Events are used to determine the conditions under which workload objects are scheduled. An Event starts a function such as sending a message or invoking an ESP Procedure.

Event initiator class Event initiator classes classify ESP Workload Manager workload into distinct streams.

External job A job defined in an ESP Application that ESP Workload Manager submits from another Application.

EXTMON A workload object used to monitor a job executed by an external scheduler.

File trigger A workload object used to build a dependency between an ESP Application and file activities for a file located in an environment controlled by an ESP Agent.

Global variable See “Variable” on page 412.

HAO High Availability Option.

HPO High Performance Option.

Initialization parameter A request made to ESP Workload Manager at initialization time. Initialization parameters are listed alphabetically in the ESP Workload Manager Installation and Configuration Guide.

Glossary

ESP-5.4-UG-05 409

JCLLIB A user data set containing the JCL for jobs submitted by ESP Workload Manager.

Job ID An identification assigned automatically to every job by JES. The format of the Job ID varies according the following rules:

Note: The same format is used for the JES job identifier used by JOBONQ.

Job monitor An ESP Workload Manager facility for monitoring a job’s progress at any stage of processing and for taking action at significant points. ESP Workload Manager can automatically trigger an Event when a job reaches a particular stage in processing, such as the end of a step or job.

Link A workload object in an Application that is marked complete automatically when its dependencies are met. You can use a link to process commands such as sending messages, issuing operator commands, and so on. Common use of links include simplifying job relationships, keeping an Application active, notification when something happens and notification when something does not happen.

Logical day A day defined by your organization that begins at a time different than 00.00.

Note: Cybermation recommends you use absolute days because of their ease of use and because they can handle almost all scheduling requirements.

Manual job A dependency on a job that ESP Workload Manager does not submit either as part of an ESP Application or a DJC/JES3 job network.

Master An ESP Workload Manager subsystem that centrally controls the workload across multiple z/OS images.

Notwith A mechanism to prevent mutually incompatible jobs from running at the same time.

Operand A parameter of a statement, command, or initialization parameter.

Page mode A method to communicate with ESP Workload Manager using ISPF, producing scrollable output from ESP Workload Manager.

Condition Format

JES2 not running in z2 mode (with large job numbers disabled)

JOBnnnnn

JES2 running in z2 mode (with large job numbers enabled)

Jnnnnnnn

JES3 For job numbers less than 100000:JOBnnnnnFor job numbers greater than 99999:Jnnnnnnn

410 ESP-5.4-UG-05

Pnode Processing node. A processing stage through which a job must pass during its time on the system. At installation time, the input, exec and output Pnodes are defined. ESP tracks jobs through these Pnodes automatically. You can define additional (manual) Pnodes, for example, bursting of output, distribution, and so on.

Pnode Application states How ESP Workstation represents the Application Pnode. The Application Pnode is determined with a hybrid method that uses the status information supplied by ESP Workload Manager and the status of its workload objects.

Positional operand Variable that is passed to a script at the time it is invoked, and is assigned in the order it is passed.

Post To mark a workload object complete at a specific Pnode. For example, you can post a job complete.

Predecessor A workload object that must complete before another workload object can be submitted.

Procedure See “ESP Procedure” on page 407.

PROCLIB A user data set containing ESP Workload Manager procedural code, for defining work to be performed by ESP Workload Manager. This includes Application workload object definitions.

Qualifier An addition to the job’s name. It can be used to uniquely identify jobs with the same name. It is used only within the ESP Application. The qualifier has no meaning to the operating system that the object runs on.

Resource A resource can be an item of hardware or software, or it can be an abstract condition. Resources are used to ensure a job is not submitted until all of its requirements are met.

Depletable resource—a resource that is used up upon submittal of a workload object. The resource can only be replenished through an explicit action, such as issuing an appropriate ESP Workload Manager command. A depletable resource could refer to the number of scratch tapes available or to a permanent DASD space.

Renewable resource—A resource that is removed from the resource pool upon submittal of a workload object and then is returned upon completion. Some examples include tape drives, a data base, or sort workspace.

Threshold resource—A sizing resource. ESP Workload Manager sizes the workload object against the current level of the threshold resource. For example, this type or resource could be used to prevent certain workload objects from executing until a NITESHIFT period begins.

Note: Enqueues are implicit resources.

REXX A high level, procedural language. You can invoke the REXX language interpreter from ESP Workload Manager to extend ESP Workload Manager capabilities.

Glossary

ESP-5.4-UG-05 411

SADGEN A user data set containing scheduled activity information on jobs. This data set is used for reports.

Schedule criteria Conditions related to date, time, or frequency, used to identify eligibility of workload for execution.

Script A file containing commands to be executed in an environment controlled by an ESP Agent.

Shadow Manager Provides your environment with the ability to transfer the control to another ESP Workload Manager master, so processing can continue seamlessly. Requires HAO.

Proxy An ESP Workload Manager subsystem that captures SMF data for the workload running on that z/OS image and transmits that data to the master.

Special day A custom defined day with special significance for scheduling at your installation.

Special period A period of processing with special significance for scheduling at your installation. A special period is the time between two identically named special days. An example is a fiscal month.

Statement A definition or part of a definition given to ESP Workload Manager. Statements are always specified in procedures.

Commands and statements are listed alphabetically in the ESP Workload Manager Reference Guide.

SubApplication A logical grouping of workload objects within an ESP Application.

Successor A workload object that awaits the completion of another workload object before it can be submitted.

Symbolic variable See Variable.

SYMLIB A user data set containing symbolic variables.

Sysmsg A facility used to intercept system messages as they are written to the system message data set, and to take action subsequently.

Tag A user-defined field defining a workload object further.

Task A placeholder in your Application. A task may represent a process that requires manual intervention.

TEMPLIB A user data set containing temporary or override JCL to be used when you specify the TEMPLIB statement.

Tracking model A centralized definition of the attributes and processing phases of a group of jobs.

412 ESP-5.4-UG-05

User data sets See COPYJCL, DOCLIB, JCLLIB, PROCLIB, SADGEN, SYMLIB, and TEMPLIB.

Variable Data object—Serves as a data repository. It is coded in an Application as any other workload object.

Global variable—A variable available across Applications. Global variables are stored in global-variable tables. Using a global-variable trigger, global variables can also be used to trigger Events based on changes of their value.

Symbolic variable—An integer or a character string whose value may be changed during ESP Workload Manager processing. When ESP Workload Manager encounters a symbolic variable, it substitutes the current value of that variable. Symbolic variables are useful in defining date operands, specifying job names, and defining job dependencies. There are built-in symbolic variables and user-defined symbolic variables.

Workday Calendar definitions representing a site’s workdays. The default workdays are Monday trough Friday excluding any holiday that has been defined for the site.

Workload object Workload objects represent the work to be scheduled. For example, these objects can represent z/OS jobs, UNIX scripts, AS/400 programs, NT and OS/2 command files, data set and file trigger objects, commands, tasks, and links.

ESP-5.4-UG-05 413

Index

Symbols%ESPAPTAG, 205%ESPATIME, 203%ESPTRDSN, 81%ESPTRGDG, 203%SHADOW, 395

Numerics4-4-5 period, example, 70

Aabsolute day

definition, 405vs. logical day, 49

ABSOLUTE, scheduling term, 50ABSORB, statement, 343ACTIVE, built-in function, 118, 124Advancing job based on holiday, 67AFM, 405AFTER, statement, 165Agent

definition, 405workload balancing, 339, 385

agentmon, definition, 405alert processing

definition, 25uses, 26

alert, definition, 405ALTCAL

command, 62use to alter a calendar, 62

ALTER, Event command, 100Alternative input data sets, Panvalet

and Librarian, 42AND, scheduling term, 50ANYCLOSE

FTP trigger operand, 87indicate any closure of a data set, 194trigger an Event at closure, 82

ANYDAY, scheduling term, 50APPLEND

additional considerations, 191does not generate SMF, 191example, 18, 191how to use, 190limitations, 190setting, 190with link, 244

414 ESP-5.4-UG-05

workload object, 18APPLHOLD, Pnode field, 223Application, See ESP ApplicationAPPLJOB

command, 216example

bypassing a job, 217completing an Application, 217inserting a link to add a job relationship, 217requesting a job, 217

options, 217APPLWAIT, Pnode field, 223Arithmetic

expression, 115operations, 115

ARMand shadow manager, 399couple data set, 398how it works, 398registration, 398

ARMELEM, definition, 398audit log, definition, 405automated framework message, 405Automatic Restart Management

ARMELEM initialization parameter, 398description, 398

AUTOVAR, definition, 406

Bbatch

convert an existing PDS job documentation library, 271

creating history report in, 276creating schedule activity report in, 299defining a repetitive holiday, 66example of explicit-data-set trigger

notification, 90executing ESP Workload Manager

commands in, 38executing program CYBESDT1 in, 88invocation of ESP Workload Manager, 38issuing commands in, 4MAPGEN command, 304specifying input parameters

of CYBESDT1, 88use of hyphen, 276, 288using JOBMAP in, 306using JOBTREE in, 309

browsingCOPYJCL (CSF), 233last executed JCL (CSF), 233

built-in functionsdefinition, 117example

calculating the length of a symbol, 123checking available cartridge drives, 127checking if CICSPROD is active, 124combined functions, 128DAYS_BETWEEN to

calculate weeks, 120DAYS_BETWEEN to

calculate workdays, 119DAYS_FROM, 119DAYS_TO, 119defining an undefined variable, 123extracting the last character

of a variable length symbol, 124JOBONQ, 126selecting a job when

another is not selected, 122selecting one job based on another, 122TAPES, 127TODAY, 120TOMORROW, 121using a substring of a

time variable, 124YESTERDAY being a holiday, 121YESTERDAY being first day of month, 121

summary by function, 117testing for a true condition, 118using calendaring functions, 118using functions for job selection, 122using functions for symbolic variables, 123ACTIVE, 124DAYS_BETWEEN, 119DAYS_FROM, 119DAYS_TO, 118DEFINED, 123ESP Procedure, 117JOBONQ, 125LENGTH, 123SELECTED, 122SUBSTR, 124TAPES, 126TODAY, 120TOMORROW, 120

Index

ESP-5.4-UG-05 415

YESTERDAY, 121built-in symbolic variables, definition, 113BY, CSF command, 233BYPASSED, Pnode field, 223bypassing

a job (CSF), 233a job in CSF, 242a job without waiting for

predecessor, example of, 161a job, example of, 217a scheduled Event execution, 103Event, specific day, 78example

bypassing a job and wait for predecessor, 161

jobs and dependencies, 160execution of an Event, 104job dependencies, 160jobs, 160, 242

Ccaching an ESP Workload Manager Procedure, 135CALENDAR

command, 59, 61, 97command, to specify additional

calendars for an Event, 64, 97suppressing field in a report, 308suppressing the calendar field in reports, 308use in an Event to refer to two calendars, 64

calendaraccessing, 59altering, 62contents, 58default calendar, 60default values, 60defining, 60defining using panels, 61defining your organization’s

logical day in, 64deleting, 60, 63deleting of entries, 60display information about a specific, 62displaying, 62displaying holidays and special days, 63displaying more detailed information on

holidays and special days, 63example, 59

altering, 62

defining, 61defining the SYSTEM calendar, 61displaying, 63displaying the SYSTEM calendar, 63specifying in an Event, 97

first day of the week, 49LOGICAL as a default, 51main menu option, 33optional specifications, 61period intervals, 69planning, 59referencing, 64retaining entries, 60setting special, 97specifying in Event, 97SYSTEM, 59system, 59terms, implied periods, 48using, 9, 58using calendar terms, 59what it can contain, 9, 59workdays, 49, 53

calendar, definition, 406CCCHK, definition, 406CCFAIL, definition, 406changes in an ESP Apllication

that take effect immediately, 218changes in an ESP Application

that take effect for the next Application generation, 218

CLANGexample

calculating time periods, 133overriding an ESP Procedure on a particular

date, 134scheduling a job on the last day of the

month, 132taking different action based on time, 134taking different action on a weekday, 132taking different actions based on the status of

CICS, 133usage, 13using calendaring functions, 133

in templates, 129language elements, 110other techniques for schedule criteria, 57specifying different DELAYSUB

times for a job, example, 156

416 ESP-5.4-UG-05

using for job documentation, 258using in ESP Procedures, 110

CLANG, definition, 406CLASS, Event command, 100CLIST

calling ESP Workload Manager from, 40invoking the ESP Workload Manager

command from, 39to access ESP Workload Manager, 40

Coding RESDEF with WLM operand, 383command

definition, 406entering, 2example, 4, 212issuing, 211issuing from console, 4ALTCAL, 62APPLJOB, 216CALENDAR, 59, 61, 97COPYJCL, 94DEFHOL, 65DEFSPEC, 67DELCAL, 64ENQSELF, 171EVENT, 74EXPECT, 99HOLD, 104INFOMSG, 37INVOKE, 93, 131JOBMAP, 305JOBTREE, 309LDTE, 84LDXE, 84LIBSUB, 92, 131LIST, 101LISTCAL, 62LISTHOL, 63LISTSCH, 98LISTSPEC, 63LOAD, 40LSAR, 300NOSCHED, 78QUIESCE, 396RESDEF, 335RESREFR, 337RESUME, 81ROUTING, 389, 401SADGEN, 298

SADUPD, 301SCHEDULE, 77SEND, 131SHADGOAL, 396SIGCYCLE, 131SIGPOST, 131SIMULATE, 101SUBMIT, 131SUSPEND, 81SYMLIB, 96TEST, 57TRIGGER, 102USE, 35VS, 95XCF SPIN TRACE, 374XCF START SERVICE, 371

commentsadding in an Event, 98ESP Procedure, 3, 109how to include, 3in job documentation, 258procedure syntax, 109

comparison operators, definition and list of, 116COMPLETE

condition, 254Pnode field, 223scheduling term, 50STATUS, 293

complete, post, 410completing

an Application, example of, 217jobs, 242

Consolidated Status Facility, definition, 406Consolidated Status Facility, See CSFcontinuation character

ESP Procedure, 2, 109use of, 2

copying JCL, 94COPYJCL

changing the copy, 95command, 94compressing, 95, 148definition, 406editing, 234example of using, 95specifying a COPYJCL library, 147suppressing, 148using the JOBID operand, 95

Index

ESP-5.4-UG-05 417

using the JOBNAME operand, 95COREQ, statement, 165CPU availability, Resource representing the

percentage of, 385CPU service unit resources, use of, 383CRITICAL, 153critical path

analysis, for all Applications, 209analysis, using, 208CSF condition, 254definition, 406displaying, 211example, 208external jobs on, 210identifying critical jobs, 209label, 211multiple, 210overriding elapsed times, 210preparing to use, 209turn on analysis, 209using CSF, 211using the list Application command, 211with EXPEDITE, 378

CSFadding a job relationship in an

Application, 243adding a job with a delayed

submission time, 243adding a job with a time dependency, 243Adding a LINK process, 244adding a link that processes commands, 244adding a relationship between two

unrelated jobs in an Application, 243adding job dependencies, 243bases for filtering, examples, 248bypassing a job, 242changing a time dependency for a job, 240color options, 231command

BY, 233DD, 234for customizing views, 227HR, 234IJ, 234IJA, 234IJB, 234L, 234LI, 234

LR, 234, 245ME, 246MR, 246R, 234working with Applications, 233working with jobs, 233working with other ESP

Workload Manager definitions, 235working with subApplications, 233

completing a job, 242customizing, 20customizing a view, 227defining a view, 226defining your sorting requirements, 230definition, 20, 406deleting a view, 232deleting a view if you know the

name of the view you want to select, 232deleting a view, if you do not know

the name of the view you want to select, 232displaying data, 222entering a freeform filter, 248example

adding a job relationship in an Application, 244

adding a job to an Application with IJ, 236adding a job to an Application with IW, 236adding job dependencies, 243changing column position, 229display, 222removing dependency time, 241removing job dependencies, 239seeing all incomplete jobs, 228seeing all incomplete jobs in

Application Payroll, 228seeing all jobs that are complete OR

failed, 229seeing all jobs that are incomplete

AND not failed, 229setting the user status field, 245

extensions, 247fields, 223filter criteria syntax, 248filtering information, 227freeform filtering, 229, 247

conditions, 254examples of freeform filter, 250examples of substring notation, 249

418 ESP-5.4-UG-05

keywords, 250relational operators, 253term syntax, 248

inserting a jobIJ option, 236IW option, 236

logic applied to multiple filtering conditions, 228

Pnode fields, 223presentation column length, 230presentation titles, 230presenting information, 229removing job dependencies, 239rerunning multiple jobs, 238resetting a time dependency, 240resetting the User Status field to null, 226resubmitting a job, 237selecting color options, 231selecting views, 232setting and resetting the user status field, 244setting the user status field, 225setting up views, 222sort sequence, 230sorting information, 230status fields, 225storing views, 226updating a view, 231usage of extensions, 247using other commands, 247

customizing CSF, 20CYBESDT1

See also explicit-data-set triggeringdefinition, 88input parameters, 202return codes, 203syntax for submitting, 88

DDAILY, scheduling term, 50data object, definition, 406data set, prefix, 42data-set names in ESP Procedure, 3, 109data-set triggering

abnormal closures, 82any closure, 82concept, 10data-set creation, 82displaying Events, 84

example, 11job specific creation, 82running a compress

job after 100 closures of a data set, 84user specific creation, 83waiting on multiple data sets, 83

limiting data set activity to a job, 82limiting data set activity to a user, 83multiple closures, 83multiple data sets, 83process flow, 82usage, 81waiting for any closure of a data set, 82waiting on multiple closures

of the same data set, 83waiting on multiple data sets, 83XCF Service, 371

data-set-trigger workload objectcontrolling, 197displaying data-set-triggering information, 197example

data-set-trigger has a dependency, 197job specific creation, 195user specific creation, 197waiting for a data set creation, 194waiting for any closure of a data set, 195waiting on more than one data set, 196waiting on multiple closures of a data

set, 196limiting data set activity to a job, 195limiting data set activity to a user, 196preparing to use, 193setting up in an Application, 193using, 193visual perspective, 194waiting for any closure of a data set, 194waiting on multiple closures of the

same data set, 196waiting on multiple data sets, 195

data-set-triggered Eventsdisplaying, 84holding, 80specifying, 81

DAYS_BETWEEN, built-in function, 117, 119DAYS_FROM, built-in function, 117, 119DAYS_TO, built-in function, 117, 118DD, CSF command, 234DEFCAL

Index

ESP-5.4-UG-05 419

command, 60defining a calendar, 60defining a logical day, 64

DEFHOLcommand, 65defining holidays, 65

DEFINED, built-in function, 117, 123DEFSPEC

command, 67defining special days, 67defining the first day of a period, 68

DELCALcommand, 64deleting calendars, 64

DELETE, Event command, 100delimiter, 3dependencies, displaying, 234depletable resource, definition, 24, 327, 410detailed information about a job, displaying, 234displaying

holiday, 63special day, 63

distributed jobretrieving the spool file, 235selecting options, 235

Distributed Managerexample

not recommended structure, 362recommended structure, 361

features and limitations, 361planning optimal Applications, 360unsupported functions, 364

distributed workload objects, 19DJC

definition, 406job network, definition, 406

DOgrouping with DO-ENDDO, example, 112statement in procedures, 111

DOCLIBdefinition, 406

DOCMEM operand of JOB statement, 265DROPNOTW

example, 174excluding jobs from a

NOTWITH statement, 174dropping

all predecessors, 234

all resource dependencies, 234individual dependencies, 234

dsname, 200DSTRIG

and scheduled Events, 82command to trigger an Event, 81data-set-trigger object identification, 178definition, 406explicit data-set triggers, 87setting up a data-set-trigger object, 193specifying data-set -triggered Events, 81specifying several, 84XCF services, 370

DUEOUT EXEC time, setting with MAXRUNTIME, 162

dueout timesintroducing, 157propagating, 158propagating example, 159

EEACH, scheduling term, 50ELSE, statement in procedures, 110ENDDEF

command ending Event definition, 74example of Event definition, 74

ENDDOgrouping with DO-ENDO, example, 112statement in procedures, 111

ENDING, scheduling term, 50ENQSELF

command, 171disadvantage of setting to ALWAYS, 171displaying status, 171example, modify, 171modify the status of, 171

ENQUEUEautomatic generation by the NOTWITH

statement, 172capabilities, 166displaying enqueue status in

the resource file, 169example of displaying, 169examples, 167excluding jobs from

an ENQUEUE statement, 168removing mutual exclusivity, 168specifying mutually exclusive jobs, 167

420 ESP-5.4-UG-05

usage, 167use by NOTWITH feature, 166

enqueuedisplaying, status, 169manipulating enqueue list of a specified

job in a generated Application, 170enqueue, definition, 406enqueues, modifying, 234entering

commands, 2statements, 2

ESP Agent, definition, 407ESP Application

anticipated end times, 156changes

that take effect for the next Application generation, 218

that take effect immediately, 218changing definition, 218changing ownership of an, 367changing ownership of an, dynamically, 368coding a job-dependency relationship, 166completing, example of, 217compressing COPYJCL, 148controlling, 216controlling concurrent processing

of multiple generations, 142controlling the use of temporary JCL, 146creating an ESP Application that optimizes

the Distributed Manager's capabilities, 366creating distributed, 365critical path, 208defining, 14, 140defining ownership of an, 366definition, 13, 137, 407definition example, 141deselecting jobs, 176displaying, 215dueout times, 157dynamically changing ownership of an, 368ESP Procedure statements, 140example, 14

an Event invokes an ESP Procedure to create an Application, 219

deselecting jobs for submission with DESELECT, 176

deselecting jobs for submission with NORUN, 176

identifying JCL libraries, 143inheriting job relationships, 177inter-Application dependency, 178keeping active, 186limiting the use of temporary JCL, 147notification on submit and abend, 207notifying when complete, 187overdue notification, 207selecting jobs for submission

with RUN, 175selecting jobs for submission

with SELECT, 175tagging high priority jobs, 205tagging jobs with Application name, 205tagging jobs with the scheduled

day of week, 205using a different TEMPLIB based on year

and day, 147using COPYJCL, 148

excluding default resources for an, 335generating a report for a specific, 307generation number, 140generation phase, 139getting notified of progress, 206home and distant, 178identifying, 142identifying JCL libraries, 143identifying jobs, 149identifying that a job is part of another

Application, 178, 182inheriting job relationships, 176inserting a job in an active, 235inserting additional workload into

an active, 234introduction, 138invoking, 219invoking via an ESP Event, 219job types in an, 177limiting the use of temporary JCL, 147manipulating the enqueue list

in a generated, 170mutually exclusive run, 166naming, 142optimizing to use distributed manager, 359owner of an, 365phase status, 139phases, 139planning to optimize distributed manager, 360

Index

ESP-5.4-UG-05 421

process phase, 139processing, 138processing at the end of, with APPLEND, 190providing notification on job status, 206relationship with ESP Procedure, 12removing resource dependencies, 162reporting on, 287selecting jobs for submission, 175specifying a COPYJCL library, 147specifying a JCL library, 143specifying a member name for a JCL library

search, 145specifying an EXTERNAL job, 180specifying job relationships, 165specifying multiple jobs, 165specifying predecessor, 165specifying successor, 165specifying the JCL library for a single job, 145statements for different job types, 158streamlining, 14subApplications, 212submit time, 175suppressing COPYJCL, 148tagging jobs, 205using different job types, 177using SELECT vs. RUN statements, 176using the JOBID keyword, 148when ESP Workload Manager

completes an, 153working with, 215working with, in CSF, 233writing the JCL to a GDG, 148

ESP commands, loading, 40ESP distributed manager, 19ESP Encore

definition, 407viewing the panels, 235

ESP Espresso, definition, 407ESP Procedure

and Applications, 12arithmetic operators, 115browse in CSF, 235built-in functions, 117caching, 135comments, 3, 109comparison operators, 116continuing a line, 2, 109controlling processing requirements, 12

data-set names, 3, 109definition, 12, 107, 407delimiter, 109edit in CSF, 235example

an Event invoking, 109checking if CICS is active, 128CLANG usage, 13grouping with DO-ENDDO, 112retrieving a variable from

a global variable table, 114using IF-THEN-ELSE, 112using QUIT and EXIT, 113using symbolic variables, 114waiting for a job, 129

expressions, 115indentation, 3, 110invoking, 108label, 110logical operators, 116name, 109order of precedence, 116overview, 108re-executing, 128relationship with Event, 264statements in an Application, 140suppressing field in report, 308symbolic variables in, 113syntax, 109terminating with EXIT, 111terminating with QUIT, 112usage, 13uses of, 13using CLANG, 110using Event definition commands in, 131using expressions, 115using expressions and strings in, 114using literal strings, 114using operators, 115

ESP Workload Manageraccessing

as a program, 39as a TSO command processor, 40from a CLIST, 39in batch, 38ISPF option, 32

definition, 407exiting, 40

422 ESP-5.4-UG-05

master, 394ESP Workstation

benefit of XCF scoreboard service, 391, 403changing the ownership of an Application, 368defining the ownership of an Application, 366definition, 21, 408entering commands, 2graphical user interface, 21ROUTING command, 390, 402working with Applications, 215

ESP XCF commands, 370ESP_APPL_GEN, 139ESP_APPL_PROC, 139ESPAPQUAL, 266EVENT

command, 74Event

accessing, 75adding comments in, 98adding executions, 103advance/delay/ignore/processing, 79altering, 105browse in CSF, 235bypassing

a scheduled, 103execution of, 104one execution, 103

CALENDAR command, 59canceling

for specific day, 78next execution, 103

changing characteristics, 105classes, 105commands and their function, 100comments, 98controlling scheduling, 79data-set triggering, 10data-set-triggered, 82defining

example, 74how, 74system identifier, 76when it will execute, 76where it will execute, 76

definition, 408deleting, 106displaying

data-set-triggered Events, 84

names and times of the current schedule cycle, 98

names or definitions, 101the schedule, 98when it will execute, 99

duplicate, 75edit in CSF, 235example, 10

altering system identifier, 105changing processing, 79deleting, 106displaying the next execution time, 99displaying the schedule, 98expected time, 99holding, 104holding a data-set-triggered Event, 80naming, 76overdue, 105sending a message, 91setting symbol libraries, 96specifying a calendar, 97starting tasks, 96submitting a job, 92submitting multiple jobs, 92suspending, 104using comments, 98

expected time, 99explicit-data-set trigger, 87FTP data-set trigger, 11FTP data-set-triggered, 84function

issuing operator command, 95sending message, 91specifying, 91submitting job, 91

global-variable-table triggering, 12held and suspended, 81holding and releasing, 104holding from being processed at

a particular time, 80information in MAPGEN, 304initiator class, definition, 408invoking

an Application, 219an ESP Procedure, 93, 108

issuing operator commands, 95job mapping, 303listing names or definitions, 101

Index

ESP-5.4-UG-05 423

main menu options, 33missed, 78name, 75naming, 74next execution times, 99overdue, 78, 105overlapping criteria, 77pending execution, 80performing tasks, 10postponing execution of an, 104prefix, 75, 101, 332processing

advancing, 79delaying, 79ignoring, 79

processing of holiday, 66relationship procedure, 264replacing scheduled executions, 103report sorted by, 314resuming, 104schedule the deletion of, 79scheduled and data-set-triggered, 82scheduled Events, 82scheduling, 77, 79security, using the prefix, 75sending messages with, 91setting calendars, 97setting symbol libraries, 96simulating, 101specifying

data-set-triggered, 81FTP data-set-triggered, 84other requirements, 96scheduled Events, 77the function of, 91time and frequency, 48

submitting JCL, 91suppressing field in reports, 308suppressing name in reports, 308suspended and held, 81suspending and resuming, 104trigger, 76triggered in error, 103triggering expected, 99triggering manually, 102triggers for, 10using event definition commands

in procedures, 131

working with defined, 100Event initiator class, definition, 408EVERY, scheduling term, 50example

using the notification list in an Event, 98using the notification list in NOTIFY, 207

EXCEPT, scheduling term, 51exceptions

Event scheduling, 78handling, 78report on, 30using NORUN and DESELECT, 176

EXEC, Pnode field, 223EXIT

statement in procedures, 111using, 113

exiting, ESP Workload Manager, 40EXPECT

command, 99expected execution, 99triggering expected Events, 99

expected time of Event, 99EXPEDITE

example, 379example of statement, 380statement, 379

expediteactions, 378description, 378host security check, 380overview, 378usage, 378

expedite policyadding or altering an, 379associating with an Application, 379defining, 378definition, 378designating for one job only, 379host security resource name, 380

explicit data-set triggeringdefinition, 11SMF record requirement, 88, 201

explicit-data-set triggeringCYBESDT1, 88CYBESDT1 input parameters, 88CYBESDT1 return codes, 90example

Connect:Direct (NDM) run task, 90

424 ESP-5.4-UG-05

notification batch, 90invoking CYBESDT1 from page mode or line

mode, 90notification utility program, 88specifying, 87

explicit-data-set-trigger workload objectexample

explicit data-set trigger notification batch, 204

explicit data-set trigger notification Connect:Direct (NDM) run task example, 204

invoking CYBESDT1 from page mode or line mode, 203

notification utility program (CYBESDT1), 201using, 201

expressioncomparing, 116definition, 115logical, 115usage, 115

EXTERNAL jobauthorization string, 181controlling, 179definition, 408forced complete, 181job qualifiers usage, 181marking complete, 179posting options, 181specifying an Application, 180usage, 178USERMOD 30, 181

EXTERNAL, Pnode field, 223EXTMON, definition, 408

FFAIL, Pnode field, 223file trigger, definition, 408first day of week, 49FIRST, scheduling term, 51FLOWDOC

components, 313data base generation, 313data generation, 313definition, 312example

specific Application sorted by days, 317specific Application, specific period, 316

specific Application, specific period ending in the future, 316

specific Event, specific date, 316graphical representation, 312Report generation, 314Report headings, 315Report organization, 314sample JCL and report, 317

freeform filteringdefinition, 247to display the critical path, 211

FTP data-set triggeringANYCLOSE, 87, 200definition, 11direction, 85, 198dsname, 87, 200Event, 84example, 11

FTP RECEIVE and SEND, 85host specific creation, 85logon specific creation, 86user-specific creation, 86with operands, 87

HOST, 85, 198limiting data set activity to a host, 85limiting data set activity to a user ID, 86limiting data-set activity

to a logon ID, 86LOGON, 86, 199operand

ANYCLOSE, 87dsname, 87RENAME, 87

RECEIVE, 85, 198RENAME, 87, 200SEND, 85, 198specifying, 84specifying the direction

of the transfer, 85USER, 86, 199workload object, 198

FTP data-set-trigger workload objectexample

FTP RECEIVE and SEND, 198host specific creation, 199logon specific creation, 200sending a message, 200user-specific creation, 199

Index

ESP-5.4-UG-05 425

limiting data set activity to a logon ID, 199limiting data-set activity to a host, 198limiting data-set activity to a user ID, 199specifying the direction of the transfer, 198using, 198

Functions of ESP Workload Manager, 8

Ggeneration

number, of an application, 140phase of an Application, 139

GENTIME, 57global variable table

definition, 22retrieving a variable from, 114triggering, 12triggering, example, 12

global variable, definition, 408graphical user interface, 20groups, 332

HHAO

ARM support, 398definition, 393, 407XCF routing, 400XCF status monitoring, 399

HELP facility, 33Help panels, 35High Availability Option, 393, 407High Performance Option, 377, 408history

example of report, 28fields to use as selection criteria

for reporting, 28reporting, 28, 276

history reporting fieldaccumulating, 297list, 289numeric, 296

HOLDan Event from being processed at

a particular time, 80and APPLEND, 190application hold Pnode, 223command, 104controlling Event scheduling, 79

defining held jobs, 153Event command, 100field in reports, 315hold count, 138hold count field in reports, 315holding a data-set-triggered Event, 80holding an Application in CSF, 233holding an Event, 104holding and releasing an Event, 104holding subApplication in CSF, 233listing jobs on, 125manual hold Pnode, 223operand of JOB, 153postponing execution of an Event, 104suppressing hold count field in reports, 308

holidaydefining, 65defining a holiday using a panel, 66defining a repetitive, 66defining a static, 129displaying, 63Event processing of, 66example

advancing / delaying a job, 67defining, 65defining a repetitive, 66defining using a panel, 66

job processing of, 67LISTHOL command to list, 63start date, 65time duration, 65using to schedule, 66

HOLIDAYS, scheduling term, 51HOST

limiting data set activity to a, 85, 198security check (EXPEDITE), 380security programs, 30

HOURLY, scheduling term, 51HPO

definition, 377, 408expedite, 378resource balancing, 382XCF routing, 388XCF status monitoring, 387

IIF

statement in Procedure, 110

426 ESP-5.4-UG-05

use in documentation, 268using instead of TEMPLIB, 146using parenthesis, 115

IF-THEN-ELSEexample of use, 112in job documentation, 266

indentation, 3index entries, displaying, 234info records, displaying, 234INFOMSG command, 37inheriting, job relationships, 14initialization parameter, definition, 408Input line entry, 36INPUT, Pnode field, 223interception, system message, 26INVOKE

an ESP Procedure, 93, 109, 219, 264command, 131command, in Event, 93

ISPF interfacecontrolling Events, 100retrieving information, 269screen, 32

ISPF option, 32ISPF panels

accessing, 100exiting ESP Workload Manager, 40special periods, 69

Issuing operator command, using Event, 95IW, CSF command, 234

JJANCWAIT, Pnode field, 223JCL

control the use of temporary, 146copying, 94creating a copy, 94example

creating a scheduled activity data set, 301report generation, 317reporting in batch, 288tailoring, 22updating a scheduled activity data set, 301

executing ESP Workload Manager commands in batch, 38

FLOWDOC data base generation, 313FLOWDOC data generation, 313FLOWDOC report generation, 314

generate a copy for every job, 147identifying JCL libraries, 143issuing commands in batch, 4limiting the use of temporary, 147routing jobs to other systems, 329specifying a library, 143specifying a library for a single job, 145specifying a temporary library, 144submitting in an Event, 91submitting JCL from Librarian and

Panvalet data set, 92tailoring, 22writing to a GDG, 148

JCL, editing the last executed, 234JCLLIB, definition, 409JES status of a job, displaying, 234JES, format of job ID, 409job

bypassing, 160canceling a PeopleSoft, 235changing job attributes, 192completing, 233CRITICAL operand, 153defining

conditional jobs, 153critical jobs, 153held jobs, 153requirements, 155with different attributes, 192

delayrelease

using the RELDELAY statement, 156submission, 155

different types, 177displaying

resources, 234duplicate names, 150example

changing a job attribute, 192combined statement, 150delaying submission of a job from

ready time, 156identifying a delayed submission time, 156multiple runs of a job, 150on-request, 152qualified jobs, 150sending messages at different stages, 154specifying a due-out time, 158

Index

ESP-5.4-UG-05 427

specifying a late submission time, 158using different submission times, 156

expediting manually, 235external, 178holding with a reason, 234identifying as on-request, 151inserting, 234

after a selected, 234before a selected, 234

mapping, 29monitoring, 25on-request, 16other methods for handling on-request, 152qualifying, 149readying, 234releasing, 233REQUEST operand, 151requesting, 234requesting the job, 153rerunning, 234restarting, 234resubmitting, 234retrieving a distributed spool file, 235scope of a JOB statement, 154selecting distributed option, 235specifying time dependencies, 155tracking, 24tracking, example, 25un-bypassing, 235un-requesting, 235un-waiting, 235using symbolic variables as qualifiers, 149z/OS, canceling and purging in JES, 234z/OS, canceling in JES, 233z/OS, canceling in JES with a dump, 234z/OS, executing on a goal mode system, resuming

the original service class of, 234z/OS, executing on a goal mode, quiescing, 234z/OS, issuing

a JES hold command on a, 234a JES release command on a, 233a system STOP command on an

executing, 234z/OS, owner of a, 365

job documentation, 19commands, 272contents, 258control information, 258

converting an existing PDS job documentation library into an ESP Workload Manager documentation library, 271

converting existing, 271creating, 260creating a job documentation member

for a job, 261customized labels, 260DOCMEM method, 266example

control information, 259documenting a job and a link, 268documenting links and tasks, 268ESP Procedure, 264overriding, 265retrieving job-documentation

information, 270start of job documentation, 258storing phone numbers, 273updating, 263using GENDOC to convert job doc., 272with customized labels, 260

IF-THEN-ELSE method, 266job qualifier, 266other uses, 273overriding rules, 265referencing members, 265relationship with Event and Procedure, 264retrieving information, 269retrieving your existing job documentation

through ESP Workload Manager, 271storing requirements, 259temporary override, 266updating, 262user description, 259using, 263using an operator console, 270using CSF, 269using for links and tasks, 267using for qualified jobs, 266using the control information, 264using the jobs option, 261using TSO, 269

job ID, definition, 409job mapping, 303job monitor, definition, 409job relationships, inheriting, 14

428 ESP-5.4-UG-05

job submittingfrom Librarian, 92using Event, 91

job tracking, XCF Service, 371JOB, statement, 149JOBENQ, example, 170JOBMAP, command, 305JOBONQ

built-in function, 118, 125example, 126returning values, 125using with REEXEC, 126variables, 125

JOBRES, 338JOBTREE, command, 309JUMPTO, statement in Procedure, 112

Llabel

customizing for job documentation, 260in ESP Procedures, 110in job documentation, 259use in ESP Procedures, 110

LABEL, command of GENDOC, 272LAST, scheduling term, 51LDTE, command, 84LDXE

command, 84example, 197to display data-set-triggering information, 197

LENGTHbuilt-in function, 118, 123example

calculating the length of a symbol, 123extracting the last character of a

variable length symbol, 124LESS, scheduling term, 51Librarian

data setsas input, 42ESP Procedure, 3, 109submitting jobs, 92

data-set prefix, 42submitting a job directly from

a Librarian data set, 92LIBSUB, command, 92, 131line mode

exiting ESP Workload Manager in, 40

how to work in, 39invoking CYBESDT1, example, 90, 203invoking ESP Workload Manager

in, from CSF, 247retrieving job-documentation information, 270

linkdefinition, 16, 409example, 17

issuing a command, 186keeping an Application active, 186notifying when an Application

completes, 187sending messages, 185simplifying job relationships, 185starting a task, taking action after

completion, 187LINK operand of JOB statement, 184owner, 365usage, 16, 184uses, 186vs. task, 185

LISTcommand, 101Event command, 100listing Events, 101RESDEF command operand, 340

LISTCALcommand, 62display a calendar, 62displaying holidays and special days, 63

LISTHOL, command, 63LISTSCH

command, 98displaying scheduled Events, 98

LISTSPEC, command, 63LOAD

command, 40example, loading diagnostic commands

from a data set, 41load a report definition, 281load an Event definition, 74

loading commands, 40logical calendar, 65logical day

defining your organization, 64specifying, 64vs. absolute day, 49

logical day, definition, 409

Index

ESP-5.4-UG-05 429

logical expression, 115logical operators

list, 116order of precedence, 116

LOGICAL, scheduling term, 51logon ID, limiting data-set activity to a, 86, 199logon specific creation, example, 86, 200LR, CSF command, 245LSAR, command, 300

MMAILLIST, 97, 206main menu

options, 33screen, 32

MANHOLD, Pnode field, 223MANSUB, Pnode field, 223MANUAL job

authorization string, 184controlling, 183defining, 182definition, 409example

on certain days, 182sending a message, 182

forced complete, 184marking complete, 183posting options, 184usage, 182

mapping, jobs, 29master, definition, 409MAXRUNTIME, 162MAXRUNTIME, using to set DUEOUT EXEC

time, 162ME, CSF command, 246menu panels in ESP Workload Manager, 33MIDDAY, scheduling term, 51MIDNIGHT, scheduling term, 51MINRUNTIME, 162modeling

definition, 29reports, 30

MODIFY command, 4MONTHLY, scheduling term, 51MR, CSF command, 246mutual exclusivity, removing, 168, 174mutually exclusive run requirements

definition, 15

example, 15

NNEXT

command, 99displaying the next scheduled

executions of an Event, 99Non-z/OS workload, 19NOSCHED

command, 78handling exceptions, 78

notification list, 97, 206NOTWITH

automatic generation of ENQUEUE commands, 172

definition, 409examples, 173excluding jobs from a

NOTWITH statement, 174removing mutual exclusivity, 174specifying mutually exclusive jobs, 172statement, 171

NOWdifference with REALNOW, 53scheduling term, 51

OOF, scheduling term, 52ONCE, scheduling term, 52one-time Event

example, 78scheduling a, 77

on-request jobs, 16, 151operand, definition, 409operator commands

from Events, 95issuing, 95

operator precedence, 115operators

arithmetic, 115comparison, 116comparison, in reports, 279in CRITERIA command (reports), 282logical, 116order of precedence, 116relational, in CSF, 253using, 115

430 ESP-5.4-UG-05

OR, scheduling term, 52overdue Event, 78, 105OVERDUE, scheduling term, 52

Ppage mode

benefit, 32comparing with ISPF Browse, 36displaying informational messages, 37displaying informational messages

where they occur in the input instead of at the top of the screen, 37

exiting ESP Workload Manager in, 40how to use, 36invoking CYBESDT1, 90, 203retrieving job-documentation

information in, 270returning informational messages

to the top of the screen, 38screen example, 36switch to from main menu, 34usage, 36using JOBMAP in, 306using JOBTREE in, example, 309using other commands in CSF, 247using the screens, 37

page mode, definition, 409Panvalet data sets

as input, 42ESP Procedures, 3, 109submitting JCL from, 92submitting jobs, 93

Panvalet, prefix for data sets, 42PeopleSoft, canceling a job, 235period, See special periodplanning

Applications to optimize Distributed Manager, 360

calendars, 60example, planning for a system shutdown, 353

PLUS, scheduling term, 52Pnode

definition, 410list of, 223APPLHOLD, 223APPLWAIT, 223BYPASSED, 223COMPLETE, 223

EXEC, 223EXTERNAL, 223FAIL, 223INPUT, 223JANCWAIT, 223MANHOLD, 223MANSUB, 223PREDWAIT, 223READY, 223RESWAIT, 223SANCWAIT, 223SUBDELAY, 223, 224SUBERROR, 223, 224SYSERROR, 223TASK, 223WAITING, 223

Pnode Application states, definition, 410positional operand, definition, 410post, definition, 410POSTREQ, statement, 165predecessor, definition, 410PREDWAIT, Pnode field, 223PREMEND operand, notification and alerting

process, 162PREREQ, statement, 165previous line, re-entering, 36PRIORITY statement, using, 332Procedure, See ESP ProcedurePROCLIB, definition, 410propagating dueout times

example, 159how to, 158

proxy, definition, 411purging a service, example (XCF), 373

Qqualifier, definition, 410QUEUE file, 371QUIESCE, command, 396QUIT

encountered, SUBERROR Pnode, 225example, 113statement in Procedure, 112

RREADY, Pnode field, 223REALNOW

Index

ESP-5.4-UG-05 431

difference with NOW, 53scheduling term, 52

redirecting Event messages to a notification list, 97RELEASE

Event command, 100statement, 165

RELEASE command, in Event, 80RENAME, FTP data-set trigger operand, 87, 200renewable resource

definition, 24, 327example

controlling access to a data base, 349controlling mutually exclusive jobs, 345defining a, 336usage, 346

renewable resource, definition, 410replying to an AS/400 message, 234report

content, 277creating flowcharts, 318customizing your job-activity report, 307ending the report definition, 287example

creating a scheduled activity data set, 301DATEFORM, 285displaying scheduled activity data, 300job-descendent report specific

to an Application, 310multiple criteria, 286reporting in batch, 288reporting on an Application, 287SADGEN, 299sample batch job for putting it all

together, 311selecting jobs based on EXCP

and CPU time, 284selecting jobs based on multiple criteria, 284selecting jobs belonging to an

Application, 283selecting jobs submitted outside

an Application, 283selecting jobs that belong to an Application

and start with a letter, 283selecting jobs that belong to an Application

or start with a letter, 283selecting jobs that ended during

a certain time, 283selecting jobs that have restarted, 283

specifying a format, 287updating a scheduled activity data set, 301using JOBMAP in batch, 306using JOBMAP in Page mode, 306using JOBTREE in batch, 309using JOBTREE in page mode, 309with MAPGEN, all jobs, 304with MAPGEN, selected jobs, 305writing report output to a data set, 289

extracting data, 299extracting tape information, 302field

categories, 278character, 278comparisons, 279CPU time, 280date, 280elapsed time, 279example

character, 278comparisons, 279CPU time, 280date, 280elapsed time, 280numeric, 278time, 279

formats, 278numeric, 278time, 279

flowcharting, 318generating an index, 307generating data, 298generating data for the report, 304generating flow charts with ESP Workload

Manager and Timeline, 321generating flowcharts using MS Project, 319generating for a specific Application, 307generating projected versus actual data, 302generating scheduled versus actual report, 301identifying the history file, 281Invoking the function, 281job-mapping data set, 304producing a job-activity report, 305producing a job-descendent report, 309putting it all together, 311reviewing the job-activity output, 307reviewing the job-descendent output, 310scheduled activity, 298

432 ESP-5.4-UG-05

sections, 277separating data into different files, 284setting up job mapping, 304setting up schedule forecasting, 298specifying an output data set, 284specifying fields to display, 285specifying input criteria, 281specifying other formats, 286specifying output criteria, 284specifying the date format, 285specifying the selection criteria, 282specifying the sort criteria, 286specifying the time range, 282structuring, 276suppressing fields, 308testing and using the GENFLOW feature, 321testing and using the GENPROJ feature, 319using a history file other than current, 281using job mapping, 303using the JOBMAP command, 305using the JOBTREE command, 309

reportingdefinition, 27history, 28, 276in batch, 276

REQUEST, 151RESDEF with MONITOR(CPU) operand,

coding, 385RESDEF, command, 335resetting, User Status field, 235resource

absorption, 342adding requirements, 331balancing, 382changing, 337default, 333default assignments, 334defining, 335defining a real resource, 336defining using the RESDEF command, 335definition, 326, 410deleting, 339depletable, 327determining a default assignment, 334device counts, 328displaying information about a resource, 340displaying one or more resources, 340

displaying requirements for jobs not yet submitted in an active Application, 341

displaying the resources associated with a job and determine what jobs have resources allocated, 340

displaying the resources of a job, 234dropping default, 332dropping requirements, 331example

ABSORB statement, 343adding requirements, 331Application with absorption, 344Application with absorption (CSF), 344changing, 337controlling access to a data base, 349controlling access to an online system, 346controlling mutually exclusive

groups of jobs, 350controlling mutually exclusive jobs, 345default scratch tape resource, 334defining a real resource, 337defining a renewable resource, 336defining a threshold resource, 336dropping default, 332dropping requirements, 332long resource name with no restrictions, 336planning for a system shutdown - Part

1, 353planning for a system shutdown - Part

2, 354real devices, 328requesting resources, 331routing jobs on other systems, 329running jobs on a particular system, 349schedule dependency, 356setting priority for more than one job, 333setting priority for one job, 333STEPEND statement, 342time periods for low priority jobs, 347using a resource for a self-completing

task, 348examples of different, 326excluding default resources for

an Application, 335gravity, 329in reports, 315job requiring multiple, 329managing jobs, 329

Index

ESP-5.4-UG-05 433

modifying, 234removing dependencies, 162renewable, 327requesting, 330requirement, 24scope of, 328setting, 337setting quantities automatically, 337setting up default resources, 334step-level resource release, 341threshold, 327types, 24types of, 326using real devices, 328working with, 335

RESOURCE statementplacing, 330using, 330

RESREFR, command, 337RESUME

command, 81command, usage, 104Event command, 100resuming an Event, 104

RESWAIT, Pnode field, 223REXX

CSF extensions, 247definition, 410in job documentation, 258interface, 27use of, 27

ROUND, scheduling term, 52ROUTING

command, 389, 401enabling XCF, 389, 401examples, 390, 402purpose of command, 390, 402service, overview, 388, 400XCF service, 388, 400

routingJCL, 329jobs to other systems, 329

run times, minimum, maximum, average, 162RUN, vs. SELECT, 176

SSADGEN

command, 298

definition, 411SADUPD, command, 301SANCWAIT, Pnode field, 223SCHEDULE

command, 77data-set-triggered and scheduled Events, 82example

schedule exception, 78schedule exception once, 78

examples, 77handling exceptions, 78overdue Events, 105overlapping criteria, 77setting to execute only once, followed

by a deletion of the Event, 77schedule criteria

date format, 47date range, 47days of months, 46days of the week, 44definition, 411example

daily or multiple times a day, 54monthly, 55multiple times a month, 56multiple times a week, 54one-time examples, 56testing criteria, 57weekly, 54yearly, 56

how to use with data-set triggering, 76implied periods, 48Julian date, 47matching criteria, 48month names, 45ordinal numbers, 47, 53spaces, 49specifying, 44specifying both an algorithm

and a starting date and time, 49testing, 57time and frequency, 48time of day, 46time zones, 46using, 43using CLANG, 57using GENTIME, 57using other techniques for, 57

434 ESP-5.4-UG-05

using the first day of the week, 49using workdays, 49where you can use, 44

scheduled activity, report, 29, 300scheduled Event

adding execution, 103bypassing, 103displaying, 98

SCHEDULED, operand of JOB statement, 180scheduling

controlling Event, 79Event, 77example

a job on the last day of the month, 132an hourly Event during a time range, 81

one-time Event, 77time and date, 9time zone abbreviations for, 46

scheduling termlist, 50using in calendars, 64ABSOLUTE, 50AND, 50ANYDAY, 50COMPLETE, 50DAILY, 50EACH, 50ENDING, 50EVERY, 50EXCEPT, 51FIRST, 51first day of week, 49HOLIDAYS, 51HOURLY, 51LAST, 51LESS, 51LOGICAL, 51MIDDAY, 51MIDNIGHT, 51MONTHLY, 51NOW, 51OF, 52ONCE, 52OR, 52OVERDUE, 52PLUS, 52REALNOW, 52ROUND, 52

STARTING, 52TIMES, 51TODAY, 52TOMORROW, 53UNTIL, 53WEEKDAYS, 53WEEKENDS, 53WITHIN, 53workday, 49WORKDAYS, 53YEARLY, 53YESTERDAY, 53

SCOPEoperand of JOB statement, 154, 180report heading, 315suppressing field in a report, 308

screenISPF interface, 34Main Menu, 32Page mode, 36

script, definition, 411security

authorized commands, 3authorized OPER commands, 3calendar, 58definition, 30for Applications, 142for EXPEDITE statement, 380FTP transfer-triggered Event, 200limiting data set activity to a user, 83limiting data-set activity to a user ID, 86, 199naming Events, 74use of the Event prefix, 75

SELECT, vs. RUN, 176SELECTED

built-in function, 117, 122built-in function syntax, 122example

selecting a job when another is not selected, 122

selecting one job based on another, 122SEND

command, 131example, sending messages at different

stages, 154using Events to send messages, 91

sending messages, 91services

Index

ESP-5.4-UG-05 435

description, 370displaying, 372enabling, 371purging, 373starting, 372XCF DSTRIG, 370, 390, 402XCF SCOREBD, 390, 402XCF scoreboard, 390, 402XCF TRACKING, 370, 390, 402

setting symbol libraries, 96SHADGOAL

command, 395, 396defining a shadow goal, 395examples, 397

shadow goaldefining, 395definition, 395deleting, 396how does it work, 395listing, 396what action it can take, 395

shadow manager, 394%SHADOW symbolic variable, 395and ARM, 399data-set usage, 394definition, 411description, 394example of moving control to, 397SHADGOAL command, 396shadow goal, 395shadow-disabled ESP master, 394shadow-enabled, 394shadow-enabled ESP master, 394START operand, 394START operands, 394switching control to, 397usage, 394z/OS MODIFY command, 398

shadow-enabled ESP Workload Manager master, 394

SIGCYCLE, command, 131SIGPOST, command, 131SIMULATE

command, 101Event command, 100options, 102options to specify, 102results, 101

simulatingan Event, 101an Event, example, 102

special daydefining, 67definition, 411displaying, 63example, 68

defining, 68using REPEAT, 68

listing, 63usage, 58using to schedule, 68

special perioddefining, 67defining the first day of, 68defining using ISPF panels, 69definition, 68, 411example

defining fiscal years, 69defining payroll periods, 69quarters and fiscal years, 72

intervals, 69listing, 63using, 58using to schedule, 70working, 70

SPIN TRACE, 374start service, starting XCF services, 372START, shadow manager operand, 394STARTING, scheduling term, 52state awareness, 373statement

definition, 411entering, 2ABSORB, 343AFTER, 165COREQ, 165DO, 111ELSE, 110ENDDO, 111EXIT, 111EXPEDITE, 379IF, 110JOB, 149JUMPTO, 112NOTWITH, 171POSTREQ, 165

436 ESP-5.4-UG-05

PREREQ, 165PRIORITY, 332QUIT, 112RELEASE, 165RESOURCE, 330STEPEND, 341TAG, 205THEN, 110

status of ENQSELF, 171STEPEND, statement syntax, 341step-level statistics, displaying, 234STEPLIB, 38stopping XCF services, 372subApplication

controlling, 214definition, 411displaying, 214example

coding, 213requesting a subApplication, 214

identifying, 212selecting, 213using, 212

SUBDELAY, Pnode field, 223SUBERROR, Pnode field, 223SUBMIT

command, 91Event command, 131submitting multiple jobs, example, 92using Events to submit JCL, 91

SUBSTRbuilt-in function, 118, 123example

extracting the last character of a variable length symbol, 124

using a substring of a time variable, 124subsystem name, 38successor, definition, 411SUSPEND

bypassing execution of an Event, 104command, 81Event command, 100example

scheduling an hourly Event during a time range, 81

suspending an Event, 104usage, 104

symbol introducer character, 110, 114

symbol librarysetting, 96specifying in Event, 96

symbolic variable%SHADOW, 395‰ESPAPTAG, 205‰ESPATIME, 203‰ESPTRDSN, 81‰ESPTRGDG, 203as qualifiers, 149attributes of, 21definition, 21, 412determining length, 123embedding in strings, 114ESP_APPL_PROC, 139ESPAPQUAL, 266example

notifying when an Application completes, 187

representing a scheduled date, 22usage, 114using a different TEMPLIB based on year

and day, 147generating with GENTIME, 57MAXRUNTIME, 162MINRUNTIME, 162stored in SYMLIB, 411substring, 123symbol introducer, 110to tailor JCL, 22using function for, 123using in ESP Procedures, 113

SYMLIBcommand, 96setting symbol libraries, 96

SYMLIB, definition, 411syntax conventions, 5SYSERROR, Pnode field, 223sysmsg, definition, 411SYSTEM calendar

definition, 59example

changing the first day of the week, 62

defining, 61displaying, 63

referencing, 64search order, 97

Index

ESP-5.4-UG-05 437

system console, issuing command from, 4system identifier

altering, 105Event, 76

system message interceptiondefinition, 26example, 26

TTAG

definition, 411statement, 205

TAPES, built-in function, 118, 126task

definition, 17, 411example

checking a report, 188specifying a due-out time for a task, 158usage, 17

marking complete, 188owner, 365uses, 189using, 188vs. link, 185

TASK, Pnode field, 223template

defining, 129example

defining a static holiday, 129defining similar jobs, 130

using, 129using a template you have defined, 129

TEMPLIB, definition, 411TEST, command, 57testing schedule criteria, 57THEN

statement in Procedure, 110terminator of IF expression, 115

threshold resourcedefinition, 24, 327displaying, 340example

defining, 336schedule dependency, 356time periods for

low priority jobs, 347usage, 327

threshold resource, definition, 410

time and date scheduling, 9time dependency

resetting, 235TIMES, scheduling term, 51TODAY

built-in function, 117, 120example, 120scheduling term, 52

TOMORROWbuilt-in function, 117, 120example, 121scheduling term, 53

traceactivating XCF trace, 374SPIN TRACE, 374XCF trace facility, 374

trackingjobs, 24models, 25

tracking model, definition, 411TRIGGER

adding execution, 103command, 102Event command, 100example

creating and triggering an Event, 212triggering an Event, 212

triggerdifferent ways to trigger an Event, 10for a data set, 10kinds of, 109

triggering an Eventcreating and, example, 212example, 212manually, 102

triggering expected Events, 99TSO command processor, accessing ESP

Workload Manager through a, 40TSO mode message, 39turning on the TSO mode message, 39

UUNTIL, scheduling term, 53updating an Info record, 235USE, command, 35USER

example, user-specific creation, 199operand

438 ESP-5.4-UG-05

limiting data set activity to a user, 83, 196limiting data set activity to a user

ID, 86, 199user

setting and resetting the status field, 245setting the status field, 225

user data sets, definition, 412user-defined variables, definition, 113

Vvariable

AUTOVAR, definition, 406definition, 412example

basic, 21defining an undefined variable, 123retrieving a variable from

a global variable table, 114using a substring of a time variable, 124using symbolic variables, 114

global, definition, 412length, 123symbolic, definition, 412use of symbol introducer, 114using, 21

viewing ESP Encore panels, 234VS

command, 95Event command, 131issuing an operator command, 95

WWAITING, Pnode field, 223WEEKDAYS, scheduling term, 53WEEKENDS, scheduling term, 53wildcard, masking, 3WITHIN, scheduling term, 53WLM workload balancing

introduction, 382scenario using, 384using, 338

workdaydefault, 60using, 49

workday, definition, 412WORKDAYS, scheduling term, 53workload balancing

(Agent) requirements, 339, 385(Agent) scenario using, 386(WLM) requirements, 338, 382(WLM) scenario using, 384description, 382

workload objectdefinition, 137, 412establishing ownership of a, 364owner of a distributed, 365type in history file, 295

Workstation, See ESP Workstationwriting session data, 37

XXCF

command examples, 397commands, 370Display Service connections, 372displaying the members in the XCF group

and their respective states, 374how status monitoring works, 387, 399manually moving control, 397member failure, 388, 400member or group member termination, 396migrating from QUEUE file, 371Purging a Service, 373QUEUE file migration, 371routing service, 388, 400

benefit, 389, 401description, 389, 401overview, 388, 400

Services, 371Start Service, 372State awareness, 373status monitoring, 387, 399Stop Service, 372stopping all the XCF members in the

XCF group simultaneously, 374stopping an XCF member, 374Trace, 374

XCF ROUTINGcommand syntax, 389, 401enabling, 389, 401ROUTING command, 389, 401

XCF SCOREBOARD, 390, 402XCF service

description, 370displaying, 372

Index

ESP-5.4-UG-05 439

displaying active connections, 372enabling, 371example

purging, 373restarted, 373

purging, 373restarting on the fly after it has

been stopped, 372scoreboard

benefit, 391, 403definition, 390, 402

starting, 372stopping, 372XCF DSTRIG, 370, 390, 402XCF SCOREBD, 390, 402XCF scoreboard, 390, 402XCF TRACKING, 370, 390, 402

XCF SPIN TRACE, command, 374XCF START SERVICE

command, 371enabling XCF routing, 389, 391, 401

enabling XCF SCOREBD, 403restarting an XCF Service on

the fly after it has been stopped, 372starting XCF services, 372

XCF trace facilitydebug tool for XCF, 374definition, 374

XCF trace, activating and capturing data using, 374

YYEARLY, scheduling term, 53YESTERDAY

built-in function, 117, 121example

process only if YESTERDAY was a holiday, 121

process only if YESTERDAY was the first day of the month, 121

scheduling term, 53

440 ESP-5.4-UG-05

esp workload manager user’s guide

Documents