esp user guide

ESP Workload ManagerVersion 5.2

User's GuideESP-UG-02

2

Second Edition (October 1999)

This edition applies to Version 5 Release 2 of ESP Workload Manager Documentation.

The software and related manuals are protected by copyright law.

ESP Workload Manager Documentation 1992-1998,1999 Cybermation Inc.All rights reserved.

No portion of this publication may be reproduced, stored in a retrieval system, or transmitted inany form or by any means without express written permission of Cybermation Inc.,80 Tiverton Court, Markham, Ontario, L3R 0G4, Canada, (905)-479-4611.www.cybermation.com

U.S. Government Users. RESTRICTED RIGHTS - Use, Duplication or Disclosure restricted byGSA ADP Schedule Contract with Cybermation Inc.

Trademark Notice:

ESP Workload Manager is a registered trademark of Cybermation Inc.

IBM is a registered trademark of International Business Machines Corporation, Armonk, NY.

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

3

Table of Contents

About this Guide ................................................................................................................. 9Conventions Used in this Guide........................................................................................ 10Summary of Changes ........................................................................................................ 11

Introduction to ESP Concepts................................................................................................ 13Overview ........................................................................................................................... 13Functions of ESP............................................................................................................... 14Time and Date Scheduling ................................................................................................ 15ESP Events ........................................................................................................................ 16Data Set Triggering ........................................................................................................... 17ESP Procedures ................................................................................................................. 18Applications ...................................................................................................................... 19Inheriting Job Relationships.............................................................................................. 21On Request Jobs................................................................................................................ 22Links.................................................................................................................................. 23Tasks.................................................................................................................................. 24Distributed Workload Objects........................................................................................... 25Job Documentation............................................................................................................ 26Consolidated Status Facility (CSF) ................................................................................... 27Graphical User Interface.................................................................................................... 28Symbolic Variables ........................................................................................................... 29Tailoring Job Control Language........................................................................................ 30Resources .......................................................................................................................... 32Tracking Jobs .................................................................................................................... 34Job Monitoring and Alert Processing................................................................................ 35System Message Interception ............................................................................................ 36REXX Interface................................................................................................................. 37Reporting........................................................................................................................... 38Modeling ........................................................................................................................... 41Security.............................................................................................................................. 42

Getting Started ........................................................................................................................ 43Overview ........................................................................................................................... 43Accessing ESP................................................................................................................... 44Accessing ESP as an ISPF Option .................................................................................... 45Accessing ESP as a Batch Program .................................................................................. 54Accessing ESP as a Program in TSO ................................................................................ 55Accessing ESP as a TSO Command Processor................................................................. 56Exiting ESP ....................................................................................................................... 57Loading Commands .......................................................................................................... 58Alternative Input Data Sets ............................................................................................... 60

Processing ESP Events............................................................................................................ 61

4

Overview ........................................................................................................................... 61Defining an ESP Event...................................................................................................... 62Naming an Event ............................................................................................................... 63Defining Where an Event Will Execute............................................................................ 65Defining When an Event Will Execute ............................................................................. 66Specifying Scheduled Events ............................................................................................ 67Controlling Event Scheduling ........................................................................................... 71Specifying Data Set Triggered Events............................................................................... 74Specifying the Function of an Event ................................................................................. 78Issuing Operator Commands ............................................................................................. 84Specifying Other Requirements ........................................................................................ 85Displaying the Schedule.................................................................................................... 88Expected Execution........................................................................................................... 89Displaying when an Event will Execute............................................................................ 90Working with Defined Events........................................................................................... 91Listing Event Names or Definitions.................................................................................. 93Simulating an Event .......................................................................................................... 94Triggering an Event Manually........................................................................................... 96Postponing Execution of an Event .................................................................................... 98Bypassing Execution of an Event...................................................................................... 99Overdue Events ............................................................................................................... 100Altering Events................................................................................................................ 101Deleting Events ............................................................................................................... 102

Schedule Criteria................................................................................................................... 103Overview ......................................................................................................................... 103Where You Can Use Schedule Criteria........................................................................... 104Specifying Schedule Criteria........................................................................................... 105Schedule Terms ............................................................................................................... 111Using Other Techniques for Schedule Criteria ............................................................... 122Testing Schedule Criteria ................................................................................................ 123Using Calendars .............................................................................................................. 124Using Calendar Terms..................................................................................................... 125Defining Holidays ........................................................................................................... 126Using Holidays ................................................................................................................ 128Defining Special Days..................................................................................................... 129Using Special Days ......................................................................................................... 130Special Periods ................................................................................................................ 131Using Special Periods...................................................................................................... 133Working with Periods...................................................................................................... 134

Working with ESP Procedures ............................................................................................ 137Overview ......................................................................................................................... 137Overview of ESP Procedures .......................................................................................... 138Invoking an ESP Procedure............................................................................................. 139ESP Procedure Syntax..................................................................................................... 140Using ESP’s Control Language in Procedures................................................................ 141

5

Using Symbolic Variables in Procedures ........................................................................ 145Using Expressions and Strings in Procedures ................................................................. 147Built-in Functions............................................................................................................ 150Using Calendaring Functions .......................................................................................... 152Using Functions For Job Selection.................................................................................. 156Using Functions For Symbolic Variables........................................................................ 158Using System Activity Functions.................................................................................... 160Combining Functions ...................................................................................................... 165Re-executing an ESP Procedure...................................................................................... 166Using Templates.............................................................................................................. 168Using Event Definition Commands in Procedures ......................................................... 172Examples ......................................................................................................................... 173

Using Applications ................................................................................................................ 178Overview ......................................................................................................................... 178Introducing Applications................................................................................................. 180Identifying the Application.............................................................................................. 185Identifying JCL Libraries ................................................................................................ 186Identifying Jobs ............................................................................................................... 192Defining Job Requirements............................................................................................. 199Specifying Time Dependencies....................................................................................... 200Specifying Job Relationships .......................................................................................... 208Selecting Jobs for Submission ........................................................................................ 210Using Different Job Types .............................................................................................. 213Defining External Jobs .................................................................................................... 214Defining Manual Jobs ..................................................................................................... 218Using Links ..................................................................................................................... 221Using Tasks ..................................................................................................................... 227Changing Job Attributes.................................................................................................. 229Using Data Set Trigger Workload Objects...................................................................... 230Tagging Jobs ................................................................................................................... 236Providing Notification on Job Status .............................................................................. 238Using Critical Path Analysis ........................................................................................... 241Issuing ESP Commands .................................................................................................. 246Using subApplications .................................................................................................... 247Working with Applications ............................................................................................. 251Displaying an Application............................................................................................... 252Controlling an Application.............................................................................................. 254Changing an Application Definition ............................................................................... 256Invoking an ESP Application .......................................................................................... 257

Consolidated Status Facility................................................................................................. 258Overview ......................................................................................................................... 258Setting up CSF Views ..................................................................................................... 259CSF Fields ....................................................................................................................... 260Defining a View .............................................................................................................. 264Customizing a View........................................................................................................ 265

6

Updating a View.............................................................................................................. 269Deleting a View............................................................................................................... 270Selecting Views............................................................................................................... 271Working with CSF .......................................................................................................... 272Commands....................................................................................................................... 273Inserting a Job ................................................................................................................. 276Resubmitting a Job.......................................................................................................... 277Removing Job Dependencies .......................................................................................... 278Resetting a Time Dependency......................................................................................... 279Bypassing and Completing Jobs...................................................................................... 280Adding Job Dependencies ............................................................................................... 281Adding a Job with a Time Dependency .......................................................................... 282Adding a Job Relationship in an Application.................................................................. 283Adding a LINK Process................................................................................................... 284Setting and Resetting the User Status Field .................................................................... 285Using Other Commands .................................................................................................. 286Extensions to CSF........................................................................................................... 287Freeform Filtering ........................................................................................................... 288Specifying Boolean Operators......................................................................................... 294

Creating Reports ................................................................................................................... 296Overview ......................................................................................................................... 296History Reporting ............................................................................................................ 297Structuring the Report ..................................................................................................... 298Reporting Fields .............................................................................................................. 299Field Formats................................................................................................................... 300Invoking the Report Function.......................................................................................... 304Specifying Input Criteria ................................................................................................. 305Specifying Output Criteria .............................................................................................. 309Ending the Report Definition .......................................................................................... 312ESP’s History Reporting Fields ...................................................................................... 314Accumulating Fields ....................................................................................................... 320Reporting on Scheduled Activity .................................................................................... 321Allocating a Sequential Data Set..................................................................................... 322Generating Data............................................................................................................... 323Extracting Data................................................................................................................ 325Generating Scheduled Versus Actual Report .................................................................. 326Generating Projected Versus Actual Data....................................................................... 328Extracting Tape Information ........................................................................................... 329Using Job Mapping ......................................................................................................... 330Job Mapping Data Set ..................................................................................................... 331Generating Data for the Report ....................................................................................... 332Producing a Job Activity Report ..................................................................................... 333Producing a Job Descendent Report................................................................................ 338Putting it All Together..................................................................................................... 340ESP FLOWDOC ............................................................................................................. 341

7

Flowcharting.................................................................................................................... 350Generating Flowcharts Using MS Project....................................................................... 351Generating Flowcharts with ESP and Timeline .............................................................. 354

Job Documentation ............................................................................................................... 357Overview ......................................................................................................................... 357Contents of Job Documentation ...................................................................................... 358Control Information......................................................................................................... 359User Description.............................................................................................................. 360Creating Job Documentation........................................................................................... 362Using The Jobs Option.................................................................................................... 363Updating Job Documentation.......................................................................................... 366Using Job Documentation ............................................................................................... 367Using the Control Information ........................................................................................ 368Referencing Job Documentation Members ..................................................................... 370Overriding Job Documentation ....................................................................................... 371Using Job Documentation for Qualified Jobs ................................................................. 372Using Job Documentation for Links and Tasks .............................................................. 374Retrieving Information .................................................................................................... 376Converting Existing Job Documentation ........................................................................ 378Other Uses of Job Documentation .................................................................................. 381

Using Resources..................................................................................................................... 383Overview ......................................................................................................................... 383What is a Resource? ........................................................................................................ 385Types of Resources ......................................................................................................... 386Scope of Resources ......................................................................................................... 387Using Real Devices ......................................................................................................... 388Routing Jobs to Other Systems ....................................................................................... 389Managing Jobs................................................................................................................. 390Requesting Resources ..................................................................................................... 391Default Resources ........................................................................................................... 396Working with Resources ................................................................................................. 398Defining Resources ......................................................................................................... 399Setting Resources ............................................................................................................ 401Deleting Resources.......................................................................................................... 402Displaying Resource Information.................................................................................... 403Step-level Resource Release ........................................................................................... 405Resource Absorption ....................................................................................................... 407Example: Controlling Mutually Exclusive Jobs.............................................................. 410Example: Controlling Access to an Online System ........................................................ 412Example: Time Periods for Low Priority Jobs................................................................ 414Example: Using a Resource for a Self-completing Task ................................................ 416Example: Controlling Access to a Database ................................................................... 417Example: Running Jobs on a Particular System.............................................................. 418Example: Controlling Mutually Exclusive Groups of Jobs ............................................ 420Example: Planning for a System Shutdown - Part 1 ....................................................... 424

8

Example: Planning for a System Shutdown - Part 2 ....................................................... 426Example: Schedule Dependency..................................................................................... 428

Using XCF with ESP............................................................................................................. 431Overview ......................................................................................................................... 431Commands....................................................................................................................... 432XCF Services................................................................................................................... 433State Awareness .............................................................................................................. 437Trace................................................................................................................................ 438

Optimizing ESP Applications to Use Distributed Manager .............................................. 439Overview ......................................................................................................................... 439Planning Applications to Optimize DM.......................................................................... 440Establishing Ownership of a Workload Object............................................................... 446Creating Distributed Applications for use with Distributed Manager ........................... 447Defining Manager Ownership of an Application ............................................................ 448Changing Manager Ownership of an Application........................................................... 450Changing Manager Ownership of an Application Dynamically ..................................... 451

Glossary of Terms ................................................................................................................. 453Glossary........................................................................................................................... 453

9

About this Guide

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

Who shouldread this guide

If your job involves scheduling and managing jobs, you should find this guideuseful. Because it expects users to already have a basic understanding of ESP,new users may want to work through the Getting Started with ESP guide first.

How to use thisGuide

The preliminary chapters, Introduction to ESP Concepts on page 13 andGetting Started on page 43, provide important background information as astarting point. These sections, along with the glossary and index, are usefulreference tools both now and when you are more familiar with the aspects ofESP discussed in this guide. The other chapters, Processing ESP Events toUsing Resources, explain ESP in more detail.

10

Conventions Used in this Guide

Input ESP is not case sensitive. Even though we show commands in uppercase,when you type a command on the command line, you do not need to type thecommand in uppercase letters.

Syntaxconventions

The Syntax diagrams in this guide use the following conventions:

Notation MeaningApostrophes “ or ‘ Must be entered as shown.Comma , Must be entered as shown.Ellipsis … The parameter can be repeated. Do not enter ellipsis.Lower Case Italicsparameter

A parameter must be substituted. User supplied variableor character string.

Uppercase parameter The parameter must be spelled as shown. You can enterthe command and the parameter in either upper or lowercase.

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

Underline ______ If you do not enter one of the parameters, the systemsupplies the underlined parameter, which is the default.

Parentheses ( ) andspecial characters

Parameter enclosed in parentheses is mandatory and mustbe entered as shown.

Single parameter insquare brackets [ ]

Optional parameter, do not type the brackets.

Stacked parameters inbraces { } { }

Mandatory, you must enter one of the parameters. Youcannot enter more than one.

Stacked parameters insquare brackets [ ] [ ]

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

Stacked parameterswith OR-bars ( | ) andsquare brackets[ ]|[ ]

Optional, mutually exclusive parameters. Enter one ornone.

Stacked parameters insquare brackets withinbraces {[ ]}

Mandatory, you must enter one of these parameters. Youcan enter more than one.

11

Summary of Changes

Introduction This guide contains information previously presented in ESP-UG-01, whichsupports ESP Workload Manager version 5 release 1.

ChangedInformation

This guide contains terminology, maintenance and editorial changes. Avertical line to the left of the text indicates technical changes or additions tothe text.

NewInformation

The following new sections were added:

• Using XCF with ESP• Optimizing ESP Applications to Use Distributed Manager.

The following features were added to the Using Resources section:

• Step-level Resource Release• Resource Absorption.

The following feature was added to the Creating Reports section:

• ESP FLOWDOC

13

Introduction to ESP Concepts

Overview

Introduction ESP Workload Manager is a very flexible and versatile job scheduling andworkload-management system. Many of ESP’s basic features are outlined inthis guide. Other, more complex and lesser- used functions are covered in theAdvanced User’s Guide.

In this chapter This chapter contains the following topics:

Topic See PageFunctions of ESP 14Time and Date Scheduling 15ESP Events 16Data Set Triggering 17ESP Procedures 18Applications 19Inheriting Job Relationships 21On Request Jobs 22Links 23Tasks 24Distributed Workload Objects 25Job Documentation 26Consolidated Status Facility (CSF) 27Graphical User Interface 28Symbolic Variables 29Tailoring Job Control Language 30Resources 32Tracking Jobs 34Job Monitoring and Alert Processing 35System Message Interception 36REXX Interface 37Reporting 38Modeling 41Security 42

14

Functions of ESP

Introduction ESP helps you automate and manage workload in your installation through avariety of functions. These functions include:

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

to MVS• 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

15

Time and Date Scheduling

Introduction With ESP, you use simple, everyday English to schedule. ESP has a built-inunderstanding of common scheduling terms. ESP handles any variety andcombination of schedule statements, such as:

• 9am daily• 2pm first weekday of each month• 7pm 3rd 13th 23rd day of month• 5pm 10th-19th day of month• 2nd and last Friday of each month• every 30 minutes starting 6pm today.

Using calendars Although ESP is familiar with the standard calendar, you may requirescheduling terms that are specific to your installation. To define your owncustomized set of scheduling terms, you can define one or more calendars. Acalendar may contain:

• A list of holidays. Holidays can span one day, several days or just parts ofa day.

• Lists of special processing dates.• Descriptions of periods, such as fiscal months, fiscal years, 4-4-5 periods,

etc.• 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 criterialike this:

• 8am last day of fiscal_month• 5pm inventory_day• christmas plus 1 workday• 8am 8th-10th workday of fiscal_year• 2nd workday of 3rd fiscal_month of fiscal_year.

Additionalinformation

For more information on time and date scheduling, refer to Schedule Criteriaon page 103.

16

ESP Events

Introduction In ESP, an Event is a basic unit of work. Information in an Event defines:

• When ESP must perform the work• What actions ESP must take to perform the work.

Triggers for anEvent

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

Performingtasks

ESP can perform a variety of tasks through the Events you define. An Eventmust 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. It is an Event scheduled at 8 a.m.each day that submits a job.

EVENT ID(USER.MESSAGE)SCHEDULE 8AM DAILYSUBMIT 'SYS1.JCLLIB(PAYJOB1)'ENDDEF


For more information on Events refer to Processing ESP Events on page 61.

17

Data Set Triggering

Introduction You can tell ESP when to process your Events depending on a date, or youcan tell ESP to process your Events depending on data set activity. Thisfeature of ESP is called data set triggering, and you can use it in conjunctionwith, or instead of, time and date scheduling.

Triggers for adata set

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

Example An example of a data set triggered Event appears below. This Event sends amessage to a user each time the data set ‘CYB.APPL.BASKET’ closes.

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

You can also use data set triggering for establishing individual jobdependencies within your ESP Applications.


For more information on data set triggering refer to Processing ESP Events onpage 61, and Using Applications on page 178.

18

ESP Procedures

Introduction An ESP Procedure is a set of stored instructions that ESP invokes. Part or allof these instructions may define a group of jobs and tasks as an ESPApplication. While you use an ESP Procedure to define all ESP Applications,not all ESP Procedures contain an ESP Application definition.

Controllingprocessingrequirements

Using a combination of CLANG (ESP’s Control LANGuage), ESP built-infunctions, job specification statements, templates, and symbolic variables in aProcedure, you can control any processing requirements.

Uses of an ESPprocedure

The main uses of an ESP Procedure are to:

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

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

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

19

Applications

Introduction An ESP Application consists of one or more workload objects (e.g. job,message, command, script, manual task). An ESP Procedure describes anApplication to ESP. A Procedure consists of a series of statements to:

• Identify the Application• Tell ESP where the appropriate JCL is located• Identify the jobs• Describe the job relationships• Describe when ESP 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.

Diagram Visually, an Application might look like this:

A

B C

E

F

D

Daily

Friday

Last workday of month

Continued on next page

20

Applications, Continued

Applicationdefinition

The corresponding Application definition might look like this:

APPL PAYROLLJCLLIB 'CYBER.ESP.JCL'JOB A RUN DAILY RELEASE (B,C)JOB B RUN DAILY RELEASE DJOB C RUN DAILY RELEASE DJOB D RUN DAILY RELEASE EJOB E RUN FRIDAY RELEASE FJOB F RUN LAST WORKDAY OF THE MONTHENDJOB

StreamliningApplications

ESP lets you streamline the way you schedule and manage entireApplications. When ESP creates an Application it assigns a generationnumber to the Application. One generation does not need to complete beforethe next one starts. Several generations of the Application can runconcurrently. ESP manages dependencies within the Application as well asbetween different Applications.


For more information on Applications refer to Using Applications on page178.

21

Inheriting Job Relationships

Introduction All jobs in an Application do not require the same frequency. When ESPselects jobs for submission, it automatically checks to see if any relationshipsamong jobs should be inherited. Once you pre-specify your job relationships,ESP’s advanced decision making skills determine the relationships requiredunder different processing conditions.

Example Consider the following three jobs and their schedule frequencies.

J2

J3

J1 Daily

Friday

Daily

On Fridays all three jobs execute in order, but on any other day of the weekjob J2 does not run. On these days, ESP selects J1 and J3 and inherits theirrelationships with J2. When J1 completes successfully, it releases J3.


For more information on how ESP inherits job relationships, refer to UsingApplications on page 178.

22

On Request Jobs

Introduction An on-request job is a job normally run on demand; it is not a regularlyscheduled job. With Applications, you can identify certain jobs as on-requestand define their relationships to other jobs. The on-request jobs take theirplace in the schedule. You can request a job anytime, from the time yougenerate the Application up to the time ESP submits the job. If you have notexplicitly requested the job using a command, ESP bypasses it and treats it asa normal completion.


For more information on request jobs, refer to Using Applications on page178.

23

Links

Introduction A link is a task that does not require completion. You can use a link toprocess commands such as sending messages, issuing operator commands,and so on, during the processing of an ESP Application.

Uses of links Common uses of links include:

• Simplifying job relationships• Keeping an Application active• Notification when something happens• Notification when something does not happen.

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

B CA

E FD

LINK


For more information on using links, refer to Using Applications on page 178.

24

Tasks

Introduction You can define tasks in an Application and establish dependencies betweenthem and other tasks and jobs. You must mark a task complete before itssuccessors become eligible for submission.

Task A task may represent a manual process which requires intervention or it mayrepresent a process which can be automated. You may choose to use tasks for:

• Balancing reports• Receipt of input tapes• Completion of a job step• Data set triggering at the job level• Any other special handling requirements.

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

CHECKRPT.J1

J2

J1(Job)

(Task)

(Job)


For more information on using tasks, refer to Using Applications on page 178.

25

Distributed Workload Objects

Introduction ESP Workload Manager Extensions extend the functionality of ESPWorkload Manager to other platforms. Workload is scheduled by ESPWorkload Manager and run on Agents. From a single point of control, yourworkload can be automatically managed on various platforms throughout yourenterprise.

ESPDistributedManager

ESP Distributed Manager manages UNIX and Windows NT workloadafter it is scheduled by ESP Workload Manager. Once the workload isscheduled, if the mainframe becomes unavailable, the workload can continueprocessing.


For information on scheduling workload on non-MVS platforms, refer to theESP Workload Manager Extension documentation for the platform in whichyou are interested.

26

Job Documentation

Introduction You can use ESP’s job documentation facility to create a complete andcentralized definition of all or any of your jobs. This powerful feature allowsyou to document the entire requirements of a job at the individual job level,including a job’s predecessors and successors, schedule criteria, due out timefrom various processing phases, resources required by the job, and more.

Scope of jobdocumentation

As an extension to ESP Procedures, job documentation is much more than alist of processing requirements for a job. ESP can use the information youdefine and ensure that the job is processed as specified in the jobdocumentation entry. ‘If-then-else’ statements within the job documentationentry allow the job definition to fit with a variety of conditional or complexrequirements.


For more information on job documentation see Job Documentation on page357.

27

Consolidated Status Facility (CSF)

Introduction The Consolidated Status Facility (CSF) is a focal point that provides a real-time view of the current workload. The CSF allows you to see which jobshave executed, which ones are currently on the system, and which jobs haveyet to execute. CSF allows you to “zoom in” on any job or workload object tofind out more information. You can also manipulate jobs, edit JCL, and restartjobs while in CSF. With CSF you can create customized views where youchoose what you want to see and how you want it displayed. You may want tofocus on one particular Application, or view all jobs that have failed.

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

CustomizingCSF

Through the use of CSF Extensions, you can further customize your use ofCSF by writing your own commands, or by replacing existing commands. Forexample, 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 on page 258.

28

Graphical User Interface

Introduction Schedulers and operators sometimes find graphical presentation of theworkload helpful. Graphic flows make it easier to see job dependencies and tomonitor the progression of work.

ESPWorkstation

ESP Workstation is a graphical user interface for ESP Workload Manager.From a single point, ESP Workstation allows you to define, monitor andcontrol your entire workload across multiple platforms. ESP Workstationusers can:

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


For more information on ESP’s graphical user interface, refer to the ESPWorkstation User's Guide.

29

Symbolic Variables

Introduction A symbolic variable is an object whose value may be changed during ESPprocessing. ESP provides powerful substitution capabilities through the use ofsymbolic variables. When ESP encounters a symbolic variable, it substitutesthe current value of that variable. With symbolic variable you have all theflexibility you need to define date parameters, specify job names, and definejob dependencies.

Using variables ESP provides you with several built-in variables (such as times and dates) thatcan 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 The following are some examples of variables:

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

Attributes ofsymbolicvariables

Each symbolic variable has a name and a value, and starts with a symbolicintroducer 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 asconcatenation and using sub-strings.


For more information on symbolic variables and symbol libraries, refer to theSymbolic Variables chapter of the Advanced User’s Guide.

30

Tailoring Job Control Language

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

Example 1 ESP has a number of built-in symbolic variables, many of which relate todates and times. The following example shows how to represent the scheduleddate of a job in the format MM/DD/YY using built-in symbols. In thisexample, a user requests date information as data; you can use also symbolicvariable as part of JCL.

//SYSIN DD *%ESPSMM%ESPSDD%ESPSYEAR

Example 2 When ESP submits this JCL for an Event scheduled on June 9,2000, ESPsubstitutes the built-in symbolic variable as shown below.

//SYSIN DD%ESPSMM%ESPSDD%ESPSYEAR

//SYSIN DD06092000

Original JCLSubstituted JCL on

June 9, 2000

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

Additionaltailoring

In addition to using symbolic variables to insert different parameters such astime, date, day of week, and data set name into JCL, you can further tailoryour JCL by using:

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


31

Tailoring Job Control Language, Continued


For more information on tailoring JCL, refer to the Advanced User’s Guide.

32

Resources

Introduction A resource is an item of hardware or software, or an abstract condition. Thereis 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.

Resources ESP supports the three following types of resources:

Type ofresource ...

Explanation

Renewable A renewable resource is a ‘borrowed’ resource. When ESPsubmits a job, the job removes the resource from theresource pool and returns it upon completion. Someexamples of renewable resources include tape drives, adatabase, or sort work space.

Depletable A depletable resource is a ‘consumed’ resource. When ESPsubmits a job, it removes the resource from the resourcepool, and does not return it at the end of execution. Theresource is used up and can only be replenished through anexplicit action, such as issuing an appropriate ESPcommand. A depletable resource could refer to the numberof scratch tapes available or to permanent DASD space.


33

Resources, Continued

Resources (continued)

Type ofresource ...

Explanation

Threshold A threshold resource is a ‘sizing’ resource. You can think ofa threshold resource as a variable height doorway into thesystem. If the resource quantity is set to 2, any number ofjobs requiring 2 or less units are able to be submitted.However, any job requiring 3 or more units are too high topass through the door and so is not submitted. In otherwords, ESP sizes the job against the current level of thethreshold resource. This type of resource could be used toprevent certain jobs from executing until a ‘NITESHFT’period begins, for example.

ResourceRequirement

You can define resource requirements for any job. You can also use defaultresources where ESP automatically determines resource requirements for ajob based on historical data.


For more information on resources see Using Resources on page 383.

34

Tracking Jobs

Introduction ESP’s job tracking facility tracks job data in real time as jobs are beingprocessed. You can use ESP’s job tracking facility to tell ESP to track yourjobs and keep information on the progress of these jobs. You can ask ESP totrack both jobs that it submits and jobs that it does not submit. Also, you cantell ESP to track Started Tasks (STCs) and TSO users (TSUs). ESP providesdetailed step-level statistics in real-time. ESP maintains completion codes foreach job step, and provides data such as CPU time, elapsed time, disk andtape 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 trackingdata for job ‘PAYD008A’.

LJ PAY008A(6308)PAYD008A JO6308, COMPLETED, CC SOC1, NODE CYBJESSUBMITTED BY ESP AT 10.06 ON TUE 13APR, EVENT CYBBP01.PAYJCL FROM CYBBP01.ESP.DEMO.JCL(PAYD008A)JCL COPIED TO CYBBP01.ESP.DEMO.COPYJCL(PAYD08A)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

Trackingmodels

ESP allows you to define a tracking model to track a group of jobs withsimilar characteristics. This tracking model has the advantage of enabling youto define and modify the tracking characteristics of multiple jobs at the sametime. You can, for example, use a tracking model to identify jobs for whichyou want to keep long term historical data and then use the data with ESP’shistory reporting facility. For more information on setting up your job trackingenvironment, see the Administrator’s Guide.

35

Job Monitoring and Alert Processing

Introduction ESP’s Job Monitor facility and Alert Processing facility can automaticallytake action at different processing points, for example, stepend, jobend, andoverdue.

Uses For example, you can use Job Monitoring and Alert Processing to tell ESP 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 database.• Submit a recovery job• Activate or deactivate resources by issuing the appropriate command.

ESP provides a number of symbolic variables that you can use with eitherfacility.


For more information on Job Monitoring and Alert Processing, see theAdvanced User’s Guide.

36

System Message Interception

Introduction ESP can intercept any message while it is being written to the systemmessages data set. This happens in real-time and can be used to detectconditions such as ‘NOT CATLGD’ and other important message portions ormessage identifiers. ESP may cancel the job, fail the job with a JCL error orCondition code failure, trigger an Event, or rebroadcast the message as aWTO (write-to-operator).

Example The following example requests the cancellation of a job whenever a ‘NOTCATLGD’ message starting anywhere between column 50 and 60 is generatedfor that job. It also specifies that this message be routed to consoles with routecode 2. Descriptor code 2 is used to highlight the message:

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


For more information on intercepting system messages, see the AdvancedUser’s Guide.

37

REXX Interface

Introduction You can use IBM’s high level, procedural language called REstructuredEXtended eXecutor language (REXX) with ESP. REXX extends ESP’scapabilities by providing it with another powerful command language. Youcan use REXX anywhere you use ESP’s Command Language (CLANG), oryou can mix the two languages together to provide powerful functions in aneasy-to-use fashion.

Uses of REXX You can use REXX with ESP to:

• Perform repetitive tasks, such as defining a static holiday• Trap output from ESP commands• Extend the functions of the Consolidated Status Facility• Build ESP Application code• Perform data set I/O.


For more information on using REXX with ESP, see the Advanced User’sGuide.

38

Reporting

Introduction ESP’s reporting facilities can give you up-to-date information aboutscheduled jobs that executed in the past or will execute in the future.Reporting facilities include:

• History• Scheduled activity• Job mapping.

Historyreporting

ESP has a powerful and versatile generalized reporting facility which providesdetail about the progress of your jobs at any time up to the present. Thisfacility extracts and formats data from the ESP history files to meet a varietyof requirements. The reports specified can be as detailed or as simple as yourequire. You can include a variety of job aspects such as jobname, status, tapeallocation, and so on. The report formats you define can be named and usedrepeatedly. In addition, reports are available online and in hardcopy.

Fields to use asselectioncriteria

ESP retains over 60 items of history data for each tracked job. The fields youcan use as selection criteria and for display in your reports include, but are notlimited to:

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


39

Reporting, Continued

Example The following is an example of a report on all PAY- jobs which executed onMarch 3,1998:

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


For more information on history reporting, refer to Creating Reports on page296.

Scheduledactivityreporting

The scheduled activity reporting facility forecasts, at the job level, the systemworkload for a future time period. This reporting facility allows you togenerate both hardcopy and online reports displaying a variety of statisticsabout jobs that ESP scheduled, including:

• Execution time• CPU time• Print lines• Tape requirements• Application name.


For more information on scheduled activity reporting, refer to CreatingReports on page 296.


40

Reporting, Continued

Job mapping Job mapping is a reporting facility that allows you to produce detailed jobinformation. You can generate the following reports:

• Job activity report. This report contains detailed information on jobsincluding job name, Application name, job type, Event name, ESPProcedure name, JCL library, execution time, CPU time, and predecessorand successor jobs.

• Job descendent report. This report shows a job and its successors.


For more information on scheduled activity reporting, refer to CreatingReports on page 296.

41

Modeling

Introduction ESP has a modeling feature that forecasts how ESP processes a group of jobsin your particular systems environment. Scheduled activity reporting providesyou with information based on what ESP schedules. Modeling takes this onestep further. ESP combines the schedule with what it knows about thescheduling environment to predict future activity. You define yourenvironment and then ESP creates a “picture” showing how a future scheduleperiod looks. Modeling allows ESP to forecast the influence of factors such asCPUs, initiators and resources.

ModelingReports

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

Use ofmodelingreports

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

• Assist you in capacity planning• Test the effects of under-initiating or over-initiating• Determine the impact of changes to a schedule• Uncover potential resource problems.


For more information on modeling, see the Advanced User’s Guide.

42

Security

Introduction Whether you have schedulers and operators scheduling all of the work or endusers submitting their work, ESP provides you with the security flexibility toensure the integrity of your system. ESP performs work based on the securityattributes of the user, not on the attributes of ESP itself. Because ESP uses aclient/server design, it requests work to be done on behalf of the user. Beforethe ESP server executes the requested routines, it checks to see if the user isauthorized for the requested work. This method of security works for any typeof user: individuals, production groups, or service bureau customers.

Host securityprograms

ESP supports RACF, CA-ACF2 and CA-TOP SECRET. It manages supportfor these host security programs without the need to use exits or modify JCL.ESP offers further security measures through a SAF interface. ESP’s SAFinterface provides granular security over all functions and resources.


For more information on security, see the ESP Administrator’s Guide.

43

Getting Started

Overview

Introduction This chapter provides some general notes on how you can use ESP.

Objective By the end of this chapter you should be able to access ESP, load commandsinto ESP, and how to use different data set types as input for ESP.


Topic See PageAccessing ESP 44Accessing ESP as an ISPF Option 45Accessing ESP as a Batch Program 54Accessing ESP as a Program in TSO 55Accessing ESP as a TSO Command Processor 56Exiting ESP 57Loading Commands 58Alternative Input Data Sets 60

44

Accessing ESP

Introduction You can access ESP in one of several ways:

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

45

Accessing ESP as an ISPF Option

Introduction If your MVS system has ISPF you can use ESP’s menus and panels. ESP haspanels that step you through the definition of Events, Applications, calendars,and jobs. Other panels allow you to display job tracking information and forreporting scheduled activity. ESP’s ISPF interface uses the dialog manager. Itallows the use of ISPF functions such as split screen, edit, and multiplesessions. As well as menus and panels, ESP’s Page mode provides scrollabledata, and the ability to edit and save any portion of an ESP session. Themethod for accessing ESP from ISPF differs with each installation. Checkwith your system administrator for the method that your site uses.

Screens forISPF interface

The layout of each screen is designed as similar as possible to the panels youare already accustomed to seeing when using ISPF. The Command or Optionfield is always at the left of the second panel line. Short messages aredisplayed top right, while long messages occupy line three, which is otherwiseblank. The maximum length of most panels is 23 lines. This facilitates the useof split-screen mode where it is available. Panels with scrollable data willextend to the entire screen capacity.

When you invoke ESP, the Main Menu appears. It displays the availableoptions: Events, Calendars, Consolidated Status Facility, and so on. ManyESP commands are available through menu mode. There is a wide choice ofmenus, entry panels and help screens.


46

Accessing ESP as an ISPF Option, Continued

Main MenuScreen

The screen below shows the ESP Main Menu.

ESP's menupanels

To use a command, first select an option from any menu or selection panel.Then specify your requirements by entering appropriate data in labeled fieldson the entry panel. All entry fields are labeled with an arrow (===>).ESP’s menu panels are easy to use. Required fields are indicated, and you areprompted if you omit required information or make a recognized error in anyof your entries. If a short message prompt is insufficient to clarify an error oromission, display a long message by entering the HELP command (PF1) toprovide more information.


47


ESP MainMenu Options

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

Option Use this option to ...O Set your ESP defaults • Display information about a user or

group of users• Set security parameters• Set CSF (Consolidated Status Facility)

display options• Specify default names for data sets that

you use frequently during your ISPFsessions. ESP automatically transfersyour input to the appropriate panels. Forexample, ESP can use a default ESPProcedure Library when you define anEvent. You can override information inany 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 triggeran Event you have already defined

• Obtain a list of Events by prefix.A Applications • Get information on the status of your

Application• Create an Application definition using

panels.L Calendars • Define and display calendar information

including holidays, special days, andspecial periods.


48


ESP Main Menu Options (continued)

Option Use this option to ...J Jobs • Set up job documentation. You can

specify processing requirements for anyjob as well as user information such asABEND codes and messages.

T Job Tracking • Display job status• Access commands to display job tracking

information• Display tracking models• Use P-Nodes• Display the number of jobs on each P-

Node queue• Display the names of jobs on P-Node

queues• Display jobs on the ABEND queue.

S Scheduled Activity • View information on the scheduledactivities you want ESP to perform. Thisinformation gives you a snapshot ofwhich jobs will be on the scheduleduring a specified future time. It alsoprovides some additional informationabout 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 andApplications that ESP tracks. Once youhave chosen a display, you can usecommands to manipulate jobs,Applications, subApplications, or any ofthe related ESP definitions.


49


ESP Main Menu Options (continued)

Option Use this option to ...U ESP Utilities • Load a series of ESP commands

• Display information on key ESP datasets, tracking cells, data set triggers andsystem attributes.

G Page Mode • Switch directly into the Page modemethod of communicating with ESP. Inthis mode you can use the command linefor input, while receiving scrollableoutput in return. Refer to the section“Using ESP’s Page Mode” ON PAGEfor detailed information on using thisoption.

M ESP Administration • This option is only available to the ESPAdministrator and departmentaladministrators. The administrator can usethis option to define and update users,groups, and calendars, and to test andmodify job tracking definition tables. Ifyour installation uses your host securitysystem for ESP security, you do not usethis option to define users and groups.

R ESP Encore • Take you to the Job List Panel of ESPEncore, Cybermation’s rerun/restartproduct. This option only appears onyour menu if you have ESP Encoreinstalled.

USE Command • Enter the USE command on the OPTIONline, from the ESP main menu, to displayESP statistics on various activities. Thesestatistics are reset to zero following anESP cold start.


50


USE commandsample

ESP ------------ Usage ------------ ROW 1 TO 4 OF 4Command ==> Scroll ===> CSR

This This This Since Last Activity Year Month Day ESP Start-------------------------------------------------------------Applications completed 2930 430 25 75Applications created 2994 450 32 100Events executed 3232 472 41 115Jobs submitted 65678 8250 563 1694

Using ESP’sHelp Option

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

Using ESP’sPage mode

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


51


Example: Pagemode screen

The following is an example of using Page mode:

Input line entry Each time you complete an input line, press Enter. ESP adds the line,highlighted, to the bottom of the input display. To re-enter a previous linefollow the steps below:

Step Action1 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 toISPF Browse

Page mode appears very similar to ISPF Browse. However, not all Browsecommands are available. If you want to use the delete and find features, youmust type EDIT on the command line. The EDIT command lets you delete orchange the Page mode output and store it.When you use the EDIT command, ESP automatically copies all the session’sdata into a temporary work file that it displays immediately. You can write thedata into a more permanent existing data set or a new member of a PDS usingthe CREATE or REPLACE commands.


52


Writing sessiondata

Follow these steps when writing session data to a data set:

Step Action1 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. REPLACEoverwrites 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 yournew 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.

WARNING Do not use the SAVE command. The SAVE command writes the data back tothe temporary work file which ESP discards at the end of your session.

Using The Pagemode screen

In Page mode, ESP retains your entire session on the screen. As you entermore data, the screen scrolls up to make room. You can scroll the screen up ordown to view all of the data. If any headings are attached to your input, theheadings remain in view at the top of your screen while the data scrolls belowthem. Also, any informational, warning, and error messages appear in theshort message fields at the top of the screen, as in ISPF.

Notes A few notes about using the Page mode:

• To scroll use the standard scroll keys: PF7 to move up, and PF8 to movedown.

• To scroll more quickly you can enter TOP or BOTTOM in the commandline.

• To access a specific line number quickly use the LOCATE command.


53


DisplayingInformationalMessages

To display informational messages where they occur in the input instead of atthe 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 thecommand line:

INFOMSG SET PR('STRING')

To return informational messages to the top of the screen, type on thecommand line:

INFOMSG RESET

54

Accessing ESP as a Batch Program

Introduction Although many of ESP’s commands are available through the ISPF interface,there may be times when you want to execute ESP commands in batch.Perhaps you want a hardcopy report, or you need to execute a repetitive seriesof commands.

ESP in Batch To execute ESP commands in batch, use the following JCL after yourjobcard:

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

Caution Do not end a line with a hyphen (-) else it will be treated as a continuationcharacter. If you are using a hyphen as a mask, you should follow it with asemi-colon. For example, LTJ -;

Subsystemname

If the subsystem name for ESP is not ESP, you need to type the subsystemname. 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 aSTEPLIB or JOBLIB statement in your JCL. Your statement may look like:

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

55

Accessing ESP as a Program in TSO

Invoking ESPas a program inTSO

To invoke ESP 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 thesubsystem name. For example, if the subsystem name is ‘ESPA’, type:

ESP SUB(ESPA)

When you access ESP through TSO, TSO prompts you for input with anarrow:==>TSO refers to this prompt as a MODE message. To turn on the TSO modemessage, at the TSO prompt, type:

PROFILE MODE

You are now in ESP 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 are finished, type END to exit.This method is quick and direct, but you must know the commands and theirsyntax. You can find the ESP commands and syntax in the ESP CommandReference manual.

Example:Invoking theESP Commandfrom a CLIST

The following is an example of a CLIST that invokes the ESP commandprocessor directly. The CLIST:

• Prompts a user for the name of a job to be submitted• Accepts the name of the job• Invokes the ESP 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

56

Accessing ESP as a TSO Command Processor

Calling ESPfrom a CLIST

You can also access ESP as a TSO command processor by using a CALLinstruction to the ESP load library.

Note Using this method, you may be limited by the size of the parameter list youpass on the CALL instruction.

Example:Calling ESPfrom a CLIST

The following is an example of a CLIST using a CALL instruction. In thisexample 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 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'

57

Exiting ESP

Methods ofexiting ESP

To exit ESP at any time follow the instructions below:

If you are... Actionusing the ISPF panels... Press the END key (PF3/15) until

you return to the ISPF PrimaryOption Menu

in Line mode... Type ENDin Page mode... Press PF3/15

58

Loading Commands

Introduction The LOAD command lets you load for execution a series of ESP commands.You can enter your commands into a PDS or sequential data set. Later,issuing the LOAD command in Page mode, you can process this series ofcommands.

Example:Loadingdiagnosticcommandsfrom a data set

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

SMFSTATSLISTRAKOPER LISTAPTFLISTCKPTLISTQ

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

LOAD 'CYB.ESP.DATA(DIAG)'


59

Loading Commands, Continued

Sample output SMFSTATSESP SUBSYSTEM INITIALIZED AT 12.43.58 ON MONDAY JUNE 27TH, 19949213 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 27TH, 19939296 SLOTS TOTAL, 8857 AVAILABLE, NEXT IS 6223

OPER LISTAPTFDATASET CYB3.ESP430NV.APPLFILEFORMATTED AT 15.00.54 ON MONDAY OCTOBER 18TH, 19936000 SLOTS TOTAL, 5735 AVAILABLE, NEXT IS 2504---1 ENTRY DISPLAYED

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

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

60

Alternative Input Data Sets

Introduction In addition to standard O/S and VSAM data sets, ESP lets you inputcommands from ROSCOE, Librarian and Panvalet data sets. Each of thesedata set types has specific conventions.

Prefixes fordata sets

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

Prefix Type of Data setROS- ROSCOELIB- LibrarianPAN- Panvalet

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

JCLLIB PAN-PROD.JCL

Note You cannot use ESP to write to ROSCOE, Librarian, and Panvalet data sets.

61

Processing ESP Events

Overview

Introduction In ESP, an Event is a basic unit of work. Information in an Event defineswhen ESP must perform the work and the actions it must take to do so.


Topic See PageDefining an ESP Event 62Naming an Event 63Defining Where an Event Will Execute 65Defining When an Event Will Execute 66Specifying Scheduled Events 67Controlling Event Scheduling 71Specifying Data Set Triggered Events 74Specifying the Function of an Event 78Issuing Operator Commands 84Specifying Other Requirements 85Displaying the Schedule 88Expected Execution 89Displaying when an Event will Execute 90Working with Defined Events 91Listing Event Names or Definitions 93Simulating an Event 94Triggering an Event Manually 96Postponing Execution of an Event 98Bypassing Execution of an Event 99Overdue Events 100Altering Events 101Deleting Events 102

62

Defining an ESP Event

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

Defining anEvent

You can define an Event by:

• Using the ISPF panels• Modifying and saving an existing Event under a new name• Loading an Event definition from a sequential data set or member of a

PDS, using the LOAD command• Defining the individual commands of an Event line by line.

Example In the example below:

• The definition begins with the EVENT command and the Event’s name.• The SCHEDULE command tells ESP when to schedule the Event.• The SUBMIT command tells ESP what to do; in this case, submit a job.• The ENDDEF command indicates the end of the definition.

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

When ESP encounters the ENDDEF command, it sends the Event to the ESPsubsystem 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 theuser that no schedule elements exist.

63

Naming an Event

Introduction The first step in defining the Event is naming. Naming an Event establishes itsownership, which is important for security. Not all users have the sameauthority or access to functions and resources. A security system such asRACF, CA-ACF2, or CA-Top Secret, as well as ESP’s internal security, cancontrol the authority and access users have.

Event name An Event name has two parts:

Part of Event name ExplanationPrefix The name of a user or group containing up to eight

alphanumeric characters, including the nationalcharacters. This prefix must be a prefix you areallowed to use. Your ESP administrator controlswhich prefixes you are allowed to use.

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

DuplicateEvents

When an Event with the same name already exists, ESP ignores your newdefinition. To replace the old definition with the new one, use the REPLACEkeyword.

Use of theprefix

When ESP triggers an Event, it must verify the security requirements of theactions the Event performs. The security identifier ESP uses is determined bya number of settings. For more information on security, refer to theAdministrator’s Guide.


64

Naming an Event, Continued

Event Prefixes In the next diagram:

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

with the prefix ‘PROD’.

DOROTHY

PROD.TRAINING

PROD.PAYROLL

DOROTHY.PHONE_BILL

Example:Naming anEvent

A production scheduling group might use a prefix of PROD. They might usethe descriptive name PAYROLL_PROCESSING to describe an ESP Event:

PROD.PAYROLL_PROCESSING

65

Defining Where an Event Will Execute

Introduction In a multiple CPU environment you should use the SYSTEM keyword on theEVENT 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 bywhich ESP knows the system and may not necessarily be the same as the SMFidentifier. Check with your system administrator or use the LSYS commandfor the correct name to use.

Systems All Events that create ESP Applications should point to the ESP systemdesignated as the Master system. Other Events may need to execute on aspecific system as they need to process commands for that system. If thesystem does not matter, you can specify ‘SYSTEM(-)’.Note: This does not affect where jobs run; JES controls this.

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

EVENT ID(PROD.BILLING) SYSTEM(ESPM)

66

Defining When an Event Will Execute

Trigger for anEvent

The trigger for the Event can be:

• A scheduled date and time• A data set 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 triggeringin Events, and how to manually trigger an Event. For information on othertypes of Events, including signalled, job monitor, and Alert Events, refer tothe Advanced User’s Guide.

67

Specifying Scheduled Events

Introduction The schedule criteria you enter tells ESP when to execute your Event. Youcan use the SCHEDULE command to specify this criteria, which generallyincludes a time and a frequency.

SCHEDULEcommand

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

SCHEDULE 10AM DAILY

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

SCHEDULE 4PM WEEKDAYSSCHEDULE 2PM WEEKENDS

OverlappingCriteria

If the times in more than one SCHEDULE command coincide, the Event onlyexecutes once. The following example only executes once at midnight, eventhough the second statement also schedules an execution at midnight everyfourth execution.

SCHEDULE MIDNIGHT DAILYSCHEDULE EVERY 6 HOURS ROUND WEEKDAYS

Examples:SCHEDULEstatements

Here are examples of schedule statements:

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


68

Specifying Scheduled Events, Continued

Scheduling anEvent once

If you want a SCHEDULE command to execute only once, followed by adeletion of the Event, use the ONCE keyword. This keyword might be usefulif you want to schedule a one-time Event.

Example:One-time Event

The following Event executes once at 8 a.m. on August 29, 2000. Because ofthe ONCE keyword, the Event deletes itself 24 hours later.

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

Caution:If you schedule an Event for a particular date and omit the ONCE keyword,ESP assumes a default schedule frequency of DAILY.

Handlingexceptions

An Event executes once at every time and date you specified in yourSCHEDULE statements. You can use the NOSCHED command to handleexceptions.If your SCHEDULE statement has a time, then you must use the same time onthe NOSCHED statement.

Example:Scheduleexception

This example schedules an Event at 8 a.m. each workday, except at 8 a.m. onthe last workday of each month:

SCHEDULE 8AM WORKDAYSNOSCHED 8AM LAST WORKDAY OF MONTH


69


Example:Scheduleexception-once

This example schedules an Event at 8 a.m. each workday, except on February13, 2000. The use of the keyword ONCE causes the Event not be scheduledon this date only.

SCHEDULE 8AM WORKDAYSNOSCHED 8AM FEB13,2000 ONCE

Missed Events An Event could miss its scheduled time for reasons such as:

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

When ESP is unable to execute an Event at the time you scheduled itsexecution, it considers the Event overdue. When the Event becomes eligible,for example after an outage, ESP checks the Event definition to determinehow to process the Event. The overdue count specifies how many overdueoccurrences of the Event ESP must process.

Advance/Delay/Ignore/Processing

Your scheduling criteria for Event execution may create conflicts. Forexample, if you want the Event to execute on the second day of every month,but it cannot run on a weekend, tell ESP to either:

• Advance the Event (run it sooner than usual) by any number of days orweekdays

• Delay the event (run it later than usual) by any number of days orweekdays

• 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 commandsin an Event.


70


Example:Changingprocessing

If you schedule your Event to run on the 12th day of every month, but do notwant it to run if the 12th falls on a weekend or holiday, you can delay theEvent’s processing using the ON command. Type ON followed by the criteriayou do not want the Event to run. Then type your DELAY keyword and theamount of time you want the Event delayed.

Your Event might look 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 ona Saturday, Sunday, or a Holiday, it runs during the week.

71

Controlling Event Scheduling

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

DELETEcommand

Use the DELETE command to schedule the deletion of an Event. You mightuse the DELETE command if, for example, you want to delete an Event that isonly temporary. Perhaps you want to delete a daily Event after a particulardate.

DELETE 10AM AUG 23, 2000

HOLD andRELEASEcommands

Use the HOLD command in an Event if you want to hold an Event from beingprocessed by ESP at a particular time. When ESP encounters a HOLDcommand in an Event, it increases the Event’s hold count by one at the timeand date specified in the command. As long as the hold count has a value of atleast one, ESP delays the Event’s execution. This way you can use the HOLDcommand to postpone an Event.

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

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

For example:

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

Refer to Missed Events earlier in this chapter for a further explanation of theoverdue count. After you release the Event, ESP checks the overdue count. Ifyou specified a number other than zero, or let the count default to one, theEvent executes immediately for every occurrence it missed while on hold, upto the value of the overdue count.


72

Controlling Event Scheduling, Continued

Example:Holding a dataset triggeredEvent

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

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

SUSPEND andRESUMEcommands

The SUSPEND command works similarly to HOLD, but has a slightlydifferent purpose. If an Event misses its scheduled execution time whilesuspended, ESP ignores the Event and does not execute it at all or mark itoverdue. Each time ESP encounters SUSPEND it increases the Event suspendcount by one at the specified time and date. While the suspend count is greaterthan zero, ESP bypasses the Event without executing it.

The RESUME command reduces the suspend count by one at eachoccurrence. When the suspend count is zero, ESP can execute the Event at thenext scheduled time.


73

Controlling Event Scheduling, Continued

Example:Scheduling anhourly Eventduring a timerange

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 a.m. to 4 p.m. The SUSPEND command stops ESP from sending themessage after 4:01 p.m. and the RESUME command restarts the messageagain at 7:59 a.m.:

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

Suspended andHeld Event

If an Event is both suspended and held at its scheduled execution time, ESPignores the hold state and considers the Event suspended

74

Specifying Data Set Triggered Events

Introduction An Event can be triggered automatically by the creation, closure, or renamingof a data set by another job, by a started task, or by a TSO user. Triggeringcan be restricted to data sets created by a specific job or group of jobnames.Events can also be made to wait for triggers from activity in more than onedata set. Refer to the section “Using Applications” for techniques on settingup data set triggering for individual jobs in an ESP Application.You can use data set activity to trigger an Event through the DSTRIGcommand.

Data setTriggered andScheduledEvents

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 aswell as DSTRIG commands, executions caused by the time schedule do notaffect the DSTRIG conditions. The Event executes at both the scheduled timesand, in addition, when the DSTRIG conditions are satisfied.

AbnormalClosures

ESP does not trigger a data set triggered Event when the data set closes duringan abnormal termination of a task or job step. When more than one DD (datadefinition) statement in a step references the data set, the Event is onlytriggered if the DD being closed is the one that specifies DISP=NEW

Waiting for anyclosure of adata set

You can use the ANYCLOSE keyword to trigger an Event at closure of a dataset. This means the creation of a new data set or the updating of an existingdata set. If you do not specify ANYCLOSE, ESP triggers the Event only whenthe applicable data set is created.

Example: AnyClosure

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

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


75

Specifying Data Set Triggered Events, Continued

Process flow Visually, the flow looks like this:

PROD.NIGHTLY(Event)

PROD.CICS.FILE1602(data set)

Limiting dataset activity to ajob

You can restrict the trigger to only specific data sets created by a particularjob. Use the JOB keyword followed by the full name or jobname prefix of thejob.

Example: Jobspecificcreation

The following Event triggers when job ABC creates a generation of the dataset ‘USER1.PAYROLL’.

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

Waiting onmultiple datasets

You may have an Event that needs multiple data sets to close before it istriggered. You can indicate each of the multiple data sets with the MULTIPLEkeyword. When ESP encounters the MULTIPLE keyword it notes theindividual closures of data sets, but it does not trigger the Event until all theDSTRIG commands containing a MULTIPLE keyword have been satisfied bya data set closure.


76


Example:Waiting onmultiple datasets

When both of the following criteria have been met, the following Eventtriggers:

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

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

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

Waiting onmultipleclosures of thesame data set

It is possible that a data set will be closed several times. You can use theCOUNT keyword to specify how often this closure will actually trigger theEvent. With each closure, ESP increases its internal counter by one. When thecounter reaches the number you set in your COUNT statement, the Eventtriggers and the counter resets to zero. You can display the Event at any timeto see the current value of the counter.You can specify several DSTRIG commands for one Event and each canmaintain its own separate counters.

Example:Running acompress jobafter 100closures of adata set

If you want a job to submit automatically after every 100 closures of a dataset, you could use the COUNT keyword followed by ‘100’ as below. Thisexample Event submits a COMPRESS job for a COPYJCL data set afterevery 100 closures of that data set:

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


77


Displaying dataset triggeringinformation

Below are commands that relate to data set triggering. They are useful fordisplaying data set trigger information.

Command Use this command to ...LDXE display data set triggered Events.LDTE display data sets being checked for closures, creations, or

renames.

Output from these commands might look like this:

LdteTHE FOLLOWING DATASET(S) ARE BEING CHECKED FOR DATASET TRIGGERSCYBER.PAYROLL.DATA1 ANYCLOSEUSER.INPUT.CYCLE CREATE-CLOSE

LdxeEVENT/APPL (WOB)----------DATASETCYBER.PAYROLL(WAIT4.DS) CYBER.PAYROLL.DATA1,ANYCLOSECYBER.CYCLES USER.INPUT.CYCLE

78

Specifying the Function of an Event

Introduction ESP can perform a variety of tasks through the Events you define. An Eventmust 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.

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

Sendingmessages

You may want to use an Event to send a message to yourself, another user, agroup of users, or an operator console. To send a message, enter the SENDcommand followed by the message in single quotes, and the userid or consoleidentifier to which the message is being sent. You can include several SENDcommands in any single Event.

Example:Sending amessage

The following Event is scheduled at 8 a.m. each day and sends a message toUSER1.

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

SubmittingJCL

You can use an ESP Event to submit JCL from a data set to the internal readerusing the SUBMIT command. A single Event can submit more than one job. Ifthere are relationships between the jobs you are submitting, you must use anESP Procedure, not an Event, to submit them. For more information onsubmitting related jobs refer to Chapter 6, Using Applications.You can also use ESP to submit jobs from ROSCOE, Librarian, and Panvaletdata sets using different statements as outlined in the next section.Note:You cannot use the Consolidated Status Facility to monitor and control jobssubmitted from an Event.


79

Specifying the Function of an Event, Continued

Example:Submitting ajob

You can create an Event PROD.INVENTORY that, at 7 a.m. on the lastworkday of every month, submits member BACKUP1 of data setPROD.JCL.CNTL. The Event looks like this:

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

Example:Submittingmultiple jobs

The following Event submits two jobs at 7 a.m. on the last workday of eachmonth. The jobs can run in any order. 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

SubmittingJCL fromROSCOE,Librarian andPanvalet datasets

In addition to the SUBMIT command, there are special commands to submitjobs directly from ROSCOE, Librarian, and Panvalet data sets. You can usemultiple commands in an Event. ESP effectively concatenates the input datato form one or more jobs.

ROSCOE datasets

To submit a job directly from a ROSCOE data set, enter the ROSSUBcommand followed by the name of the data set you want to submit, like this:

ROSSUB RDS.JOBS

If you omit the ROSCOE prefix from the data set name, ESP uses theROSCOE prefix of the user who defines the Event.ESP supports multiple ROSSUB commands.

Note:You do not need to specify the “ROS-” data set identifier because theROSSUB command implies a ROSCOE data set.


80


Librarian datasets

To submit a job directly from a Librarian data set, enter the LIBSUBcommand followed by the data set name and the name of the data set memberyou want to submit, like this:

LIBSUB LIB1.DATA(PRODCNTL)

ESP supports multiple LIBSUB commands.

Note:You do not need to specify the “LIB-” data set identifier because the LIBSUBcommand implies a Librarian data set.

Panvalet datasets

There are two methods you can use to submit a job directly from a Panvaletdata set. You can either enter the PANSUB command followed by the data setname and the name of the member you want to submit:

PANSUB PANDS.DATA MEMBER(DLYPAYROLL)

ORIf the member name is no more than 8 characters, you can use this format:

PANSUB PANDS.DATA(PAYROLL)

ESP supports multiple PANSUB commands.

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


81


Invoking ESPProcedures

You can create an Event to invoke an ESP Procedure. An ESP Procedure is aset of instructions for ESP. The most common use of an ESP Procedure is todefine an ESP Application. A Procedure may contain statements that:

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

Invoking a Procedure causes ESP to execute the instructions within theProcedure. To invoke any Procedure, you must first create the Procedure andthen define an Event to invoke that Procedure.

The INVOKE command invokes an ESP Procedure by specifying where theESP Procedure is stored. In the following example, the ESP Procedure isstored 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 allows multiple INVOKE commands. However, an Event can onlygenerate one Application. To invoke more than one Application requires oneEvent per Application.


For information on using ESP Procedures, refer to Working with ESPProcedures on page 137.


82


Copying JCL The COPYJCL command lets you generate a copy of the JCL for every job, asESP submits it. You can specify COPYJCL in the Event definition of anyEvent that submits jobs. This copy is written to a member of a PDS, providinga working copy of the JCL with, where applicable, all symbolic variablesresolved and NET cards (for DJC/JES3) included. This JCL can be used forjob re-submission. ESP keeps track of where the job was submitted from andthe JCL that was used.

You can also specify COPYJCL within an Application definition to identifyone or more jobs for which you want to use COPYJCL. This gives you theadvantage of using COPYJCL for specific jobs.

When you use the COPYJCL command you must also specify the library thatis to receive the copy, followed by either the JOBNAME or JOBID keyword.The keywords you use influence the member name ESP assigns to the JCLcopy.

Using theJOBNAMEkeyword

The JOBNAME keyword requests that the member name used for storing theJCL for a job is the same as the jobname. This is the default. Each submissionof a particular job overwrites the previous copy of that job’s JCL.

Using theJOBIDkeyword

Use the JOBID keyword when you want ESP to store the copy of the JCL byjob number. ESP creates a member name starting with JOB, followed by afive-digit JES job number. The system assigns this number sequentially. Amember is not overwritten until its five-digit number reoccurs.

Example: UsingCOPYJCL

This example requests that a copy of submitted JCL be written to the currentgeneration of the data set ‘CYBER.JCL.COPY’ and stored by jobname.

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


83


Using a GDGfor COPYJCL

With either the JOBID or the JOBNAME method, you can write the JCL to aPDS GDG. A new generation can be created each day to maintain severalgenerations of JCL. Schedule an Event each day to submit a job that createsthe next generation.

CompressingCOPYJCL

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

Changing thecopy

Your original JCL may contain data that you do not want to copy. ESP has aJCL Tailoring facility that automatically changes certain aspects of theoriginal JCL when it copies the JCL to a COPYJCL data set. Refer to theAdvanced User’s Guide for more information on tailoring JCL.

84

Issuing Operator Commands

Issuing anoperatorcommand

To issue an operator command, enter the VS command followed by the‘operator command’ you want to issue.

Example:Starting tasks

If you want ESP to start IMS10 and IMS20 each day at 6 a.m., use the VScommand in your definition, as shown below. The commands will be issuedon 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. Contactyour system administrator to find out if you are authorized to issue anyoperator commands.

85

Specifying Other Requirements

Options When you define an Event, you can also specify:

• Symbol library names• Calendar names• Comments.

Setting symbollibraries

ESP has a set of built-in symbolic variables. Your ESP administrator maydefine symbol libraries to store user-defined symbolic variables. A symbollibrary consists of one or more data sets or data set members. Variables mayinclude date formats, control cards, and other information ESP can use whenprocessing the workload. You can use the SYMLIB command in an Event tospecify symbol libraries. If a variable is assigned more than one value, ESPuses the last assigned value.

Example This example references the symbol library called DATES. When ESPprocesses the Event, it opens each data set associated with this symbol libraryand 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.Refer to the Advanced User’s Guide for detailed information on creating andusing symbolic variables.


86

Specifying Other Requirements, Continued

Setting specialcalendars

ESP lets you define dates that might be unique to your organization. If, forexample, Labor Day is a regular holiday at your installation, you can define itas such in your calendar.

ESP contains an installation defined SYSTEM calendar based on the 12-month Gregorian calendar. You can use the CALENDAR command to specifyup to two additional calendars for the Event, so that you can schedule Eventsin terms that might be unique to your calendar. If you do not specify acalendar, ESP uses the calendar(s) assigned by default to the group or userthat owns the Event. For more information on calendars, refer to the nextchapter, Specifying Schedule Criteria.

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

Calendar1 First calendar you define for the Event, or first default calendar.2 Second calendar you define for the Event, or second default

calendar.3 The SYSTEM calendar.

Example:Specifying acalendar in anEvent

If you want your Event to execute on the second day of your fiscal month, youmust first set the calendar so that ESP knows where to look for the definitionof what a fiscal month is. In the Event below, the CALENDAR command tellsESP which previously defined calendar (i.e. FISCAL) to refer to whenscheduling the Event:

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

Addingcomments

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


87

Specifying Other Requirements, Continued

Example: Usingcomments in anEvent

If you want to include a comment in your Event that tells you the Event is amanually 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

88

Displaying the Schedule

Introduction You can use the LISTSCH command to display the Event names and times ofthe current schedule cycle (normally 24 hours). These elements include thenames and execution times of all the Events in the schedule, and the overdue,held, or deferred queues. The LISTSCH command does not display the namesor submission times for individual jobs within Events. To display theschedule for jobs refer to the section on scheduled activity reporting inChapter 8, Creating Reports.

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 only displays the time of the first execution. ESP stores only one instanceof the Event and does not calculate the next execution time until it hasexecuted the Event.

89

Expected Execution

Introduction The LISTSCH command can only display scheduled Events. If you want todisplay Events that do not have SCHEDULE commands, such as Eventstriggered 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 timeof an Event

If your Event is usually triggered by the creation of a data set every morning atapproximately 11 a.m., you could insert an EXPECT command in your Eventdefinition to tell ESP when to expect the Event, like this:

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

TriggeringExpectedEvents

The EXPECT command normally does not affect the schedule. If the data setthat triggers the Event, in the above example, has not been created by theexpected time, the Event continues to wait. However, if you trigger an Eventthat has an EXPECT statement and you keep the REPLACE option, ESPtreats the EXPECT statement the same as a SCHEDULE statement. ESPselects jobs and substitutes variables based on the expected time and date.

90

Displaying when an Event will Execute

Introduction Using the NEXT command, you can display the next scheduled executions ofan Event. The NEXT command lets you specify the number of execution timesyou want to test, up to a maximum of 99. As long as your Event contains atleast one SCHEDULE command, ESP computes the execution times anddates for the number of executions you specify.

Example:Displaying thenext executiontimes of anEvent

If you would like to know the next five execution dates and times for theEvent PROD.LWD, you could use the NEXT command. The following showsthe NEXT command and sample output from the command. ESP displays thenext five scheduled times and dates:

NEXT 5 PROD.LWDSCHED AT 19.00.00 ON SATURDAY JANUARY 31ST, 2000SCHED 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

91

Working with Defined Events

Introduction The section Controlling Event Scheduling earlier in this chapter describes fivecommands for controlling an Event during definition. You can use ESPcommands in Line mode, Page mode, batch and through the ISPF interface, tocontrol an Event after you define it.

Commands andtheir function

The following table summarizes the available commands and their function:

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


92

Working with Defined Events, Continued

For ISPF users To access the ISPF panels:

Step Action1 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:

Step Action1 Select Option E on the Main Menu.2 Select Option 3 on the Event Management Menu.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 appropriate code letter, beside the Event name, for the

action you want to take.

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

93

Listing Event Names or Definitions

LIST command ESP 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 Eventsstarting with the prefix ‘PROD’, type the command below. The LEVELparameter identifies the Event prefix.

LIST LEVEL(PROD)

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

94

Simulating an Event

Introduction You should simulate the functions of any defined Event using the SIMULATEcommand. For the Event you select, the SIMULATE command tells you whichjobs ESP submits, any messages it sends, how it substitutes symbolicvariables, and so on. This command is particularly useful with ESPProcedures because you can use it to see how the complex and conditionalcomponents of your Procedure will run at a particular date and time. ESP alsodisplays error messages if it encounters problems, such as syntax errors orsuccessor loops in an ESP Procedure. You can simulate an Event for a day onwhich it is not normally scheduled; ESP simulates what would happen if theEvent was triggered on that particular day.

Options There are a number of other options available with the SIMULATEcommand. 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 Eventexecution.

• Perform full syntax checking on all ESP 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 theoptions

You specify these options using the SIMULATE command or on the SimulateEvent Execution panel.On the SIMULATE command, specify the Event name and any scheduleparameters. If you do not enter any parameters ESP either simulates the nextoccurrence of the Event, or, if the Event has no schedule execution, it assumesan execution time NOW.


95

Simulating an Event, Continued

Example:Simulating anEvent

You might want to simulate the results of executing an Event namedCYBER.TEST1 on the last workday of the current month. Enter the followingcommand in Page mode:

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

96

Triggering an Event Manually

Triggering anEvent

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

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

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

AddingExecutions

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

For example, if you need to run an Event now in addition to its scheduledtime of 7 p.m., 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 orREPLACE.


97

Triggering an Event Manually, Continued

Replacingscheduledexecutions

When you want to process an Event at a time different than its next scheduledtime, you can use the REPLACE option. REPLACE advances the executiontime for an Event. For example, if you need to run an Event now instead of at7 p.m., trigger the Event with the REPLACE option.

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

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

TRIGGER PROD.PAYROLL REPLACE

Bypassing ascheduledEvent

If you want to bypass the next execution of a scheduled Event, you can triggerthe Event and specify NOXEQ. This might be used when you trigger an Eventin error, and you need to ‘undo’ this operation, or when you want to cancelone execution of an Event.

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

TRIGGER PROD.BAD_EVENT NOXEQ

98

Postponing Execution of an Event

Introduction When you use the HOLD command outside the Event definition process, ESPincrements the Event’s hold count immediately. When you use the HOLDcommand within a definition (explained in “Controlling Event Scheduling”earlier in this chapter) ESP does not increment the count until the scheduleddate and time.

Holding andreleasing anEvent

By issuing the HOLD command followed by an Event name, you postponeexecution of that Event until its hold count is reduced to zero. Every HOLDincreases the count by one; every RELEASE command reduces it by one.When a held Event is released and it has missed a scheduled execution, ESPexecutes 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 theOVERDUE parameter on a SCHEDULE statement and defaults to 1.

Example:Holding anEvent

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

HOLD PROD.MYEVENT

99

Bypassing Execution of an Event

Introduction Outside of an Event definition, the SUSPEND command immediatelyincreases the suspend count by one, telling ESP to bypass the Event youname. A suspended Event remains in that state until it is resumed. Allscheduled executions and manual triggers of the Event are bypassed.

Suspending andResuming anEvent

By issuing the SUSPEND command followed by an Event name, you bypassthe execution of that Event until its suspend count is reduced to zero. EverySUSPEND increases the count by one; every RESUME command decreases itby one. When the suspend count reaches zero, the Event is eligible forexecution. If the Event misses any execution times while suspended, ESPignores them and does not consider the Event overdue.

Example:Suspending anEvent

If you have an Event with the name ‘PROD.MYEVENT’, you can suspend itby typing the following:

SUSPEND PROD.MYEVENT

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

100

Overdue Events

Event classes After a long system outage, ESP makes it easy for you to manipulate classesof Events so that the system can process high priority work first. For moreinformation on manipulating classes of Events refer to the ESP Operator’sGuide.

OverdueEvents

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

Example:OverdueEvents

If you do not want an Event to run, even if it misses its 10 a.m. scheduledexecution time, type the command below. Since you do not want it to execute,type the number zero in the brackets:

SCHEDULE 10AM WORKDAYS OVERDUE(0)

101

Altering Events

ALTEVENTcommand

Use the ALTEVENT command to change certain characteristics of one ormore Events. Specify any number of parameters to cause multiple changes toa single Event or group of Events. When the name contains asterisks or ahyphen, ESP alters all matching entries. If you are unsure of which Events aparticular 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 tocompute a new set of time and date schedules.

Example:Altering systemidentifier

The example below alters all Events prefixed by ‘MYGROUP’, withSYSTEM identifiers beginning with ‘OLDA’, to execute on the system‘NEWA’. The SYSTEM identifier corresponds to the ESP system identifier,defined by ESP’s SYSID Initialization Parameter.

ALTEVENT MYGROUP.- SYSTEM(NEWA OLDA)

102

Deleting Events

DELETEcommand

Use the DELETE command to delete an existing Event. This removes theEvent from the Event data set.

Example:Deleting anEvent

The following example deletes the Event called TEST.FIRST_EVENT.

DELETE TEST.FIRST_EVENT

Caution:If you delete an Event corresponding to an active Application, ESP is unableto continue processing that Application.

103

Schedule Criteria

Overview

Introduction ESP allows you to use free format, everyday English to specify schedulecriteria when scheduling Events and jobs. ESP has a built-in understanding ofgeneral scheduling terms. You may also add your own unique schedulingterms to ESP. This may include special processing periods, holidays, andother special days. You can specify schedule criteria up to the year 2042.


Topic See PageWhere You Can Use Schedule Criteria 104Specifying Schedule Criteria 105Schedule Terms 111Using Other Techniques for Schedule Criteria 122Testing Schedule Criteria 123Using Calendars 124Using Calendar Terms 125Defining Holidays 126Using Holidays 128Defining Special Days 129Using Special Days 130Special Periods 131Using Special Periods 133Working with Periods 134

104

Where You Can Use Schedule Criteria

Schedulecriteria

You can use schedule criteria in the following ways:

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

Events• In commands that control Events (e.g. HOLD, SUSPEND, TRIGGER,

etc.)• In RUN/NORUN statements in an Application to specify schedule

frequencies for individual jobs• To specify other time dependencies for jobs in an Application (e.g. early

start time, late submission time, etc.)• To define holidays, special days and special processing periods• 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 (e.g. TODAY,

DAYS_FROM, etc.) available with ESP Procedures.

105

Specifying Schedule Criteria

Days of theweek

ESP 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 canshorten the names such as: ‘sun’, ‘thu’, ‘fri’. The minimum number ofcharacters for days of the week is 3. You can specify multiple days of theweek too. For example, ‘monday wednesday friday’.

Specify If you specify a day and a date that do not match each other, ESPautomatically calculates the first specified day of the week on or after the dateyou requested. For example, October 26th, 1998 falls on a Monday.If you mistakenly specify the following:TUESDAY OCTOBER 26TH 1998

you actually get this:TUESDAY OCTOBER 27TH 1998

Month Names ESP recognizes the following months of the year:

January February MarchApril May JuneJuly August SeptemberOctober November December

You can abbreviate any month specification to a minimum of 3 letters, forexample:

• APR• AUG


106

Specifying Schedule Criteria, Continued

Time Zones You can use the following time zone abbreviations for scheduling in ESP:

LT Local time LOCAL Local timeADT Atlantic Daylight

TimeAST Atlantic Standard

TimeEDT Eastern Daylight

TimeEST Eastern Standard

TimeCDT Central Daylight

TimeCST Central Standard

TimeMDT Mountain Daylight

TimeMST Mountain

Standard TimePDT Pacific Daylight

TimePST Pacific Standard

TimeBST British Summer

TimeGMT Greenwich Mean

Time

You should not need to specify your own time zone in your schedule criteria.These are set in ESP’s Initialization Parameters.

Note:ESP assumes that any number preceding a time zone abbreviation is a timespecification.

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

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

Note ESP assumes that any number preceding the letters AM or PM is a timespecification, for example:

• 3AM• 6PM


107


Days of months A number joined to the name of a month is recognized as a day of the month(e.g. ‘jun3’, ‘22oct’, ‘6nov2001’). The ordinal qualifiers st, nd, rd or th arealso used with a month name. For example, ‘january21st’, ‘august29th’.

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

Format Exampleyy.ddd 99.056yyyy.ddd 1999.056

Date format ESP recognizes the date format xx/xx/xx. The DATEFORM InitializationParameter instructs ESP how to interpret this format. The following tableshows the different formats (yy=year number, mm=month number, dd=daynumber) and how to express January 2, 2000 using them.

Format Exampleyy/mm/dd 00/01/02dd/mm/yy 02/01/00mm/dd/yy 01/02/00

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


108


Ordinalnumbers

Use ordinal numbers (1st, 5th, etc.) to refer to scheduling terms other than justday of month. For example, ‘2nd monday of year’. You may use more thanone 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 a.m. on the third day of eachmonth.

10AM 3RD MONTHLY

The next example requests activity at 10 a.m. on the first Monday after thethird day of each month.

10AM MONDAY 3RD MONTHLY

Date range Use a hyphen (-) to designate a range of dates. For example, ‘3rd - 6th day ofmonth’ represents the 3rd, 4th, 5th, and 6th day of the month.

Implied periods The following calendar terms are implied periods:

• WEEK• WEEKEND• MONTH• YEAR

The following are valid:

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


109


Specifying atime andfrequency

A schedule specification in an Event may consist of two parts. One part givesa starting date and time, while the other part describes an algorithm forcomputing subsequent dates and times. In an ESP Application, you must useseparate statements to specify the time and the frequency of a job.

Starting Date and Time• 9AM JANUARY 1ST• MIDNIGHT 9 DECEMBER 2000• 3PMSubsequent Times• DAILY• EVERY 2 WEEKS• MONTHLY• 4 TIMES

MatchingCriteria

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

• DAILY AT 19.00• WEDNESDAYS AT 3PM• WORKDAYS

Specifying anAlgorithm anddate / time

To specify both an algorithm and a starting date and time, separate the twoparts of the schedule specification with the keyword STARTING.

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


110


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

• SAT25JUN• EVERY5MINUTES

Using the firstday of the week

Each calendar identifies the day that ESP considers the first day of the week.By default ESP considers Sunday to be the first day of each week. If youspecify ‘1st day of week’, ESP uses the calendar to determine what day this is.

UsingWorkdays

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

workday weekend weekend holiday workday Workday workday

1 X X X 2 3 4

Absolute vs.logical days

By default a day is considered to be an absolute day beginning at midnight(00:00). To override the default, you can define a calendar as logical andidentify the start time of your logical day.For example, if your logical day begins at 08:00 and you schedule an Event toexecute Monday at 2 a.m., the Event actually executes Tuesday morning at 2a.m.

Absolute Calendar

SCHEDULE 2AM MONDAY

Event scheduled at 2 a.m. Monday

Logical Calendar

SCHEDULE 2AM MONDAY

Event scheduled at 2 a.m. Tuesday

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

111

Schedule Terms

Terms You may use words and phrases other than specific dates and times to defineschedule criteria. The following is a list of other terms recognized by ESP.

Term recognized by ESP ExplanationABSOLUTE Specifies that you are using an absolute day

(i.e. beginning at 00:00). This is only requiredwhen your calendar is a logical calendar, witha start time other than 00:00.

AND Used to specify multiple similar schedulingterms (e.g. days of the month, months of theyear) 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; separateschedule statements are required.

ANYDAY Specifies that there is no day of the weekrestriction. You can abbreviate this term toANY.

COMPLETE Used only with the ‘LAST’ keyword. Ensuresthat the schedule only occurs during acomplete period. For example you can specify‘last complete week of year’ or ‘last completeweek of quarter’ If a fiscal week starts in onequarter but finishes in the next quarter, ESPprovides a schedule for the previous completefiscal week.

DAILY Means ‘every one day’.ENDING Allows you to specify the end date for any

schedule interval, for example, ‘daily at 9amstarting tomorrow ending 1jul2000’. Youcannot use this qualifier in a RUN/NORUNstatement.


112

Schedule Terms, Continued

Term recognized by ESP ExplanationEACH Means ‘every occurrence of’.EVERY n units Requests a recurrence of the Event at every n

units of time. The units can be any ofSECONDS, MINUTES, HOURS,WORKDAYS, DAYS, WEEKS, MONTHS orYEARS, while n can be any number from 1 to32767. For example, ‘every 1 hour round less5 minutes’ requests an Event at five minutesbefore the hour, every hour. Note that fiveminutes are subtracted from the base time(every hour on the hour). You cannot use thisqualifier in a RUN/NORUN statement.

EXCEPT Used to exclude a day of the week or holidays.For example ‘weekdays except wednesdays’limits activity to Monday, Tuesday, Thursdayand Friday. ‘daily except holidays’ limitsactivity to days which are not holidays. Youcannot specify more than one day of the weekwith EXCEPT. You cannot use EXCEPT witha term other than a day of the week or the termHOLIDAYS.

FIRST To specify the first occurrence of a particularday or period. For example, you can specify‘first monday of month’, ‘first fiscal_month offiscal_year’. You can also use the ordinalnumber ‘1st’.

HOURLY Means ‘every one hour’. You cannot use thisterm in a RUN/NORUN statement.

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


113


Term recognized by ESP ExplanationLAST Specify the last (i.e. final) occurrence of a

particular day or period. For example you canspecify ‘last holiday of year’, ‘last workday offiscal_month’, ‘first and last tuesday ofmonth’.

LESS n units Specifies a value to be subtracted from thebase time to produce a time/date executiontime. n must be a whole number. For example,you can specify ‘less 2 weekdays’, ‘less 1month’, ‘less 0 workdays’.

LOGICAL Specifies that you are using a logical asopposed to an absolute day (i.e. beginning at00:00). The start time of your logical day mustbe specified in a calendar. For example, youcan specify ‘2am logical tuesday’, ‘7am firstlogical workday of month’. LOGICAL can beset as a default at calendar definition time.

MIDDAY 12.00, noonMIDNIGHT 24.00, midnight. 24.00 is normally recognized

as being the same as 00.00. Thus, if youspecify ‘monday at 24.00’ it will be stored as‘00.00 tuesday’. However, specifying‘midnight’ ensures that the time associatedwith the previous day - ‘midnight monday’ isconsidered to be the end of Monday and notthe start of Tuesday.

MONTHLY Means ‘every one month’. You cannot use thisqualifier by itself in a RUN/NORUN statement(i.e. you can use RUN 15TH MONTHLY butyou cannot use RUN MONTHLY).


114


Term recognized by ESP Explanationn TIMES Allows you to specify the number of times you

want a schedule to occur, such as ‘daily at 9am6 times starting tomorrow’. You cannot usethis qualifier in a RUN/NORUN statement.

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

ONCE Means that a scheduled command will beprocessed once only, at the time specified. Ifyou specify a date in an Event without‘ONCE’, the default frequency is DAILY. Youcannot use this qualifier in a RUN/NORUNstatement.

OR Allows you to specify either of two similarscheduling terms, such as ‘monday ortuesday’. OR implies ‘whichever happensfirst’, and as such can only be used where it ismeaningful and does not lead to ambiguity. Astatement such as ‘1st january or 2nd february’is meaningless to ESP.

OVERDUE(n) Specifies how many overdue occurrences of anEvent are to be initiated should an Event missits scheduled time. ESP schedules the Eventonce for each missed occurrence, up to thenumber specified. You can only use this on aSCHEDULE statement in an Event definition.


115


Term recognized by ESP ExplanationPLUS n units Specifies a value to be added to the base time

to produce a time/date execution time. n mustbe a whole number. For example, you canspecify ‘plus 2 weekdays’, ‘plus 0 workdays’,‘plus 1 week’.

QUIT Used to quit an entire process and the Eventthat invoked it. ESP does not process anypending requests from this or any otherProcedure invoked by the same Event.

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

ROUND This word can be used together with theEVERY n UNITS phrase. It specifies that thecomputed time is an integral multiple of theunits parameter. For example, specifying‘every 1 hour round’ requests every hour at thehour mark. ‘every 6 hours round’ requests thetimes 00.00, 06.00, 12.00 and 18.00. ‘every 5hours round’ provides the next hour that is anintegral multiple of five hours from 00.00 on1st January 1900.

STARTING Allows you to split the schedule specificationinto two parts. The first part is an algorithmand the second part is the starting time or date.The time or date to the left of STARTING iswhen you want the Event to execute. The timeor date to the right of STARTING is when youwant the first execution to occur. Use an actualdate or time after STARTING. A repetition,such as ‘every 5 minutes’, is not valid. Youcannot use this qualifier in a RUN/NORUNstatement.

TODAY TodayTOMORROW Tomorrow. You cannot use this term in a

RUN/NORUN statement.


116


Term recognized by ESP ExplanationUNTIL Allows you to specify the end date for any

schedule interval, for example, ‘daily at 9amstarting tomorrow until 1jul1995’. You cannotuse this qualifier in a RUN/NORUNstatement.

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

WEEKENDS Requests that the scheduled actions occur onlyon Saturday and Sunday.

WORKDAYS Each calendar identifies workdays. Workdaysexclude holidays. Default workdays areMonday through Friday.

YEARLY Means ‘every 1 year’. You cannot use thisqualifier in a RUN/NORUN statement.

YESTERDAY Yesterday. This term is useful in reporting.You cannot use YESTERDAY in an Eventdefinition or in a RUN/NORUN statement.

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


117


Using ordinalnumbers

If you use an ordinal number as part of the ‘STARTING’ parameter with aspecial period or special day, and without using nested levels, ESP assumesthat you are implying ‘from today’. For example, ‘10pm daily starting 5thpayroll_day’ provides the fifth payroll day from now.

If you use an ordinal number with a schedule term (other than with theSTARTING parameter) without stating what the schedule term refers to, ESPassumes the following defaults:

Schedule Term ESP Defaultdate, day name or workday ‘of month’week or month ‘of year’holiday ‘of year’special day or period ‘of year’.

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

3RD FRIDAY AT 9AM ! 3RD Friday of month at 9 a.m.9AM LAST HOLIDAY ! 9 a.m. on last holiday of year

Examples ofschedulecriteria

Here are some examples of schedule criteria, each of which can be handledwith one statement. Refer to the next section Other Techniques for ScheduleCriteria for information on handling more complex criteria.

Daily ormultiple timesa day

6 a.m. each day:• 6AM DAILY

Every day in October:• ANYDAY OF 10TH MONTH OF YEAR

Every 30 minutes beginning at 2 p.m. today:• EVERY 30 MINUTES ROUND STARTING 2PM TODAY


118


Multiple timesa 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


119


Monthly 8 a.m. on the last Saturday of each month, beginning in October 1998:• 8:00 LAST SATURDAY OF MONTH STARTING OCTOBER, 1998

8 a.m. 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 nextworkday after the first Friday of the month:• FIRST FRIDAY OF MONTH PLUS 0 WORKDAYS

First weekday (i.e. Monday through Friday) on or after the 15th day of themonth:• 15TH DAY OF MONTH PLUS 0 WEEKDAYS

Friday after the 1st Sunday of the month:• 1ST SUNDAY OF MONTH PLUS 5 DAYS


120


Monthlycontinued

1st Saturday of the month. If this is also the first day of the month then run on2nd Saturday of month:• SATURDAY 2ND MONTHLY

ESP interprets the above expression as the first Saturday on or after the 2ndday of the month.

Multiple Times a Month10 a.m. on the 3rd, 13th and 23rd day of month:• 10AM 3RD 13TH 23RD DAY OF MONTH

6 a.m. from the 10th to 20th day of each month:• 6AM 10TH - 20TH DAY OF MONTH

3rd, 9th, 10th, 11th, 12th, 14th workday of each month:• 3RD 9TH - 12TH 14TH WORKDAY OF 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, 4th Sunday of month if 4 Sundays in month;3rd, 5th Sunday of month if 5 Sundays in month:• 3RD AND LAST SUNDAY OF MONTH

Yearly Each year on July 23:• JULY 23 YEARLY


121


One-timeExamples

11 p.m. 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

Default Time When using schedule criteria where a time can be used, and none is specified,the time defaults to the start of the day as identified in a calendar (default is00:00).

122

Using Other Techniques for Schedule Criteria

CLANG andGENTIME

For some criteria you may need to use ESP’s CLANG (Control Language) orthe GENTIME command.

ESP Command ExplanationCLANG Provides you with IF-THEN-ELSE logic and some

built-in functions (e.g. DAYS_TO). Refer to ESPProcedures on page 137, for more information.

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

The Advanced User’s Guide contains some examples of schedule criteria thatuse 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.

123

Testing Schedule Criteria

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

Example:Testing criteria

If you want to test ‘last workday of month’ for the next 5 months, type

TEST (5) LAST WORKDAY OF MONTH

ESP displays output similar to the following:

00.00.00 MONDAY JANUARY 31ST, 1998, DAY 03100.00.00 MONDAY FEBRUARY 28TH, 1998, DAY 05900.00.00 THURSDAY MARCH 31ST, 1998, DAY 09000.00.00 FRIDAY APRIL 29TH, 1998, DAY 12000.00.00 TUESDAY MAY 31ST, 1998, DAY 151

124

Using Calendars

Introduction You do not need to define calendar terms to ESP in order to use them. ESPalready recognizes general scheduling terms. Administrators may createcalendars to store definitions of scheduling elements unique to yourinstallation - your holidays, special days and special processing periods. Acalendar also identifies workdays, the first day of the week, and the start timefor a day. Your administrator defines calendars and controls access to them.

Special daysand Periods

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

125

Using Calendar Terms

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

CALENDARstatement

Use a CALENDAR statement in an Event to refer to a maximum of twocalendars. If you do not refer to a calendar in the Event, ESP automaticallyuses the default calendars your administrator assigned to you or your group.ESP merges holiday definitions in all calendars associated with an Event. Forspecial days, workdays, and the first day of the week, ESP uses the firstdefinition it encounters.

Defaultcalendar

When defining holidays, special days and special periods, specify whichcalendar will be used to store the definition. If you do not specify a calendarname, your first default calendar as defined in your userid entry will be used.If you do not have a first default calendar, your second default calendar isused. If you do not have any default calendars defined, the entry automaticallygoes into the SYSTEM calendar.

SYSTEMcalendar

Only global holidays and special days should be stored in the SYSTEMcalendar. Department-specific holidays and special days can be stored in asmany calendars as required.

Retainingentries

ESP checks for and deletes old entries only when a calendar is updated forother define and delete requests. When more than two days have gone bysince holiday and special day entries have occurred, they are automaticallydeleted unless you specify otherwise using the RETAIN parameter atdefinition time.

126

Defining Holidays

Process To define holidays, use the DEFHOL command or use Option L of the MainMenu. You can use up to 16 characters to name each holiday, and you mustgive a start date in each holiday definition. The time duration for a holiday is24 hours, unless you specify otherwise. You can define multiple holidays withthe same name, but you must define each one separately.

If the holiday you define coincides with what would have been 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 termseven if stored in a LOGICAL calendar.

Example:Defining aHoliday

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

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

Example:Defining aholiday using apanel

This example uses Option L to define a holiday.


127

Defining Holidays, Continued

Example:Defining arepetitiveholiday

This example shows how a batch job defines a 24-hour holiday calledCHRISTMAS for 3 years. The subsystem name for ESP in this example isESPM:

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

128

Using Holidays

Introduction Once holidays are defined, you can use them as you would any otherscheduling terms. Some examples are shown below.

16:00 every holiday:• 16:00 HOLIDAY10 p.m. on Christmas:• 10PM CHRISTMASOne workday before BANK_HOLIDAY:• BANK_HOLIDAY LESS 1 WORKDAY

Holidayprocessing ofEvents

In an Event definition, you can schedule on holidays or use an ON commandsuch as ‘on holiday’. This allows you to bypass, delay or advance the scheduleif it normally falls on a holiday or a particular day of the week. The calendarsassociated with the Event and the SYSTEM calendar are searched for holidayentries. If there are no calendars specified in the Event, the owning group’s oruser’s default calendars and the SYSTEM calendar are used.

Holidayprocessing ofjobs

The RUN statement identifies schedule criteria for a job in an ESPApplication. For more information, refer to Using Applications on page 178.

Run every holiday: RUN HOLIDAYRun on Christmas: RUN CHRISTMASRun on workdays: RUN WORKDAYS

Example:Advancing /Delaying a Job

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

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

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

RUN FRIDAY PLUS 0 WORKDAYSRUN FRIDAY LESS 0 WORKDAYS

129

Defining Special Days

Process To define special days, use the DEFSPEC command or use Option L of theMain Menu.

Example The following example defines April 20, 2000 as a special day calledBALANCE_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')

130

Using Special Days

Using a specialday as a specialterm

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

17:00 on BALANCE_DAY:• 17:00 BALANCE_DAY

2 workdays before BALANCE_DAY at 10 a.m.:• 10AM BALANCE_DAY LESS 2 WORKDAYS

One week after BALANCE_DAY at 4 p.m.:• 4PM BALANCE_DAY PLUS 1 WEEK

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

The following example shows how to define the next 10 fiscal years onFebruary 1.

Each FISCAL_YEAR definition will be retained in the calendar calledFISCAL for 2 years.

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

131

Special Periods

Defining specialPeriods

Use the DEFSPEC command to define the first day of each period. Whendefining multiple regular periods, you can use the ‘REPEAT’ parameter of theDEFSPEC command. Specify either ‘n times’ for the special period or‘until...’ to define as many periods as you need. If you are not using‘REPEAT’, include one extra period at the end of your definitions to giveESP a final reference point. For example, define the first day of at least twoconsecutive fiscal years, so that ESP can calculate the start and finish of thefirst year. Use an alphanumeric name of up to 16 characters for the name ofyour special period. The first character must be alphabetic, and you should notuse blanks. You can also specify the name of a particular calendar to whichthe 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,may start three weeks after the beginning of the previous trading period, andfive weeks before the beginning of the next. Simply tell ESP when eachperiod starts. When two special days of the same names are defined in acalendar, you have essentially defined a period from the first special day up tothe second special day. In the above example, ESP knows that the last day ofeach FISCAL_YEAR is 31st March.

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

Example This example shows how to define payroll periods every 2 weeks for the nextyear using the REPEAT parameter. Each PAYROLL_PERIOD is retained onthe PAYCAL calendar for 1 year after it occurs.

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


132

Special Periods, Continued

Using ISPFpanels

Achieve the same result using ESP’s ISPF panels as follows:

Step Action1 Select Option L (Calendars) from the Main Selection Menu.2 Select Option 4 (Define a Special Day) from the Calendar Control

Menu.3 Proceed as illustrated below:

133

Using Special Periods

Examplespecial 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

134

Working with Periods

This example illustrates the use of 4-4-5 periods, where there is a 4-weekperiod, followed by a 4-week period, followed by a 5-week period.The first few periods look like this:

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


135

Working with Periods, Continued

Quarters andfiscal years

You can also define quarters and fiscal years, if you need to. Once this isdone, you can use such criteria as shown below. You do not need to know theday of the week or the date to which each statement refers. ESP calculates thisfor 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

137

Working with ESP Procedures

Overview

Introduction An ESP Procedure is a set of stored instructions that ESP invokes. When youcreate an ESP Procedure you use CLANG, a high level programminglanguage. You can also use IBM’s REXX language in ESP Procedures.The main use of an ESP Procedure is to provide a framework for an ESPApplication. ESP’s Procedure capability lets you control an Application fromone Event definition, regardless of the Application’s complexity or number ofconditional requirements. You can use a single ESP Procedure to control acomplete batch run or even multiple batch runs. The Procedure automaticallyaccounts for any daily changes, or month-end processing. For moreinformation on using ESP Procedures to define Applications, refer to UsingApplications, in this guide.


Topic See PageOverview of ESP Procedures 138Invoking an ESP Procedure 139ESP Procedure Syntax 140Using ESP’s Control Language in Procedures 141Using Symbolic Variables in Procedures 145Using Expressions and Strings in Procedures 147Built-in Functions 150Using Calendaring Functions 152Using Functions For Job Selection 156Using Functions For Symbolic Variables 158Using System Activity Functions 160Combining Functions 165Re-executing an ESP Procedure 166Using Templates 168Using Event Definition Commands in Procedures 172Examples 173

138

Overview of ESP Procedures

Options When you create an ESP Procedure definition, you can:

• Store it in a member of a PDS or in a sequential data set• Use as many statements as your needs demand• Add to or edit the Procedure to make instant changes• Specify the Procedure line by line using the syntax described later in this

chapter• Invoke the Procedure with any type of Event• Use several Event commands• Set or test symbolic variables, whether built-in or user-defined.

Note:You must create the ESP Procedure prior to creating the Event to invoke theProcedure.

139

Invoking an ESP Procedure

INVOKEcommand

To invoke an ESP Procedure, use the INVOKE command in an Event or inanother ESP Procedure.

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: AnEvent invokesan ESPProcedure

The following example demonstrates how to use an Event to invoke an ESPProcedure.

The Event appearing below runs each weekday at 4 p.m. and invokes an ESPProcedure. The Event looks like this:

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

140

ESP Procedure Syntax

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

Syntax Rules ExplanationName The name of an ESP Procedure can contain up to eight

alphanumeric characters. The first character must be a letter.You must type a colon after the last character followed bythe keyword ESPPROC. For example, MYJOBS:ESPPROC.This name is optional and not commonly used.

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

Comments Enclose comments between /* and */. You can omit the last*/ since 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 adds your TSO data set prefix to the name.Use ROS-, LIB-, or PAN- prefixes to identify Roscoe,Librarian, and Panvalet data sets.

Delimiters Use single quotation marks when you want to denotecharacter strings and literal data in expressions, inassignment statements, and in built-in functions. You mustinclude single quotation marks around a string that containsblanks.

Indentation Indentation, though not required, improves readability.Variables You must 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 lefthand side of an assignment statement.

Labels Use labels in a Procedure to denote different sections. Labelscan be up to 16 characters. The first character must be aletter and you must type a colon after the last character. Inaddition to identifying sections for editing purposes, labelscan also act as targets in JUMPTO statements, where theycontrol logical flow.

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

141

Using ESP’s Control Language in Procedures

Introduction CLANG is an integral component of ESP Procedures and provides greatpower and flexibility. Its several language elements listed below allow you tospecify conditional processing requirements.

IF IF conditionally processes an instruction or group of instructions dependingon the evaluation of an expression. When you use an IF statement, theexpression that follows it must return a true or false value. You can use anynumber of nested IF statements.

Example:

IF logical-expression THEN ...

THEN The Procedure processes the statement after THEN only if the expression thatfollows the IF statement returns a true value. If a THEN statement continuesto another line, use a line continuation character (‘-’ or ‘+’). If there is nocontinuation character, ESP ignores the THEN statement. You must begin andend 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 theexpression that follows the IF statement returns a false value. If you do notinclude an ELSE statement after an expression returning a false value, ESPpasses control on to the next line. You must begin and end a group ofinstructions with DO and ENDDO language elements. If an ELSE statementcontinues to another line, use a line continuation character (- or +). If there isno continuation character, ESP ignores the ELSE statement.

Example:

ELSE statement


142

Using ESP’s Control Language in Procedures, Continued

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

Example:

DOstatementstatement

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

Example:

DOstatementstatementENDDO

EXIT Use EXIT to quit from your current point in a Procedure. ESP continues toprocess pending requests up to the point at which you use EXIT. ESP alsoprocesses any action statements in the calling Event, or other ESP Proceduresinvoked in the same Event. ESP ignores EXIT statements within the scope ofa JOB statement during the generation of an ESP Application. DuringApplication processing, EXIT within the scope of a JOB statement causesESP to process all statements up to the EXIT and submit the job.

Example:

EXIT


143


QUIT Use QUIT to quit an entire process and the Event that invoked it. If you useQUIT, ESP does not process any pending requests from this or any otherProcedure invoked by the same Event. ESP ignores QUIT statements withinthe scope of a JOB statement during the generation of an ESP Application.During Application processing, QUIT within the scope of a JOB statementcauses ESP not to process any statements for that job and does not submit thejob, causing the job to fail with a SUBERROR. Therefore, any of the jobsdependencies are not released.

Example:

QUIT

JUMPTO Use JUMPTO to search forward through the existing Procedure to find thenext label of the name given in the JUMPTO statement. Use JUMPTO to skipover whole sections of a Procedure. You can use JUMPTO with or without anIF statement.

Example:

JUMPTO error_handler

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

Example: UsingIF-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 want to use continuation characters and indentation, the above examplemight look like this:

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


144


Example:Grouping withDO-ENDDO

This example groups instructions together using DO and ENDDO:

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

Example: UsingQUIT andEXIT

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

• If today is ‘CHRISTMAS’ ESP quits the ESP Procedure and noinstructions are processed.

• If today is not ‘CHRISTMAS’ but it is a holiday, ESP sends a messageand exits the Procedure at that point.

• If none of the above conditions are true, ESP sends a message indicating itwill 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, refer to the Examples section at the endof this chapter.

145

Using Symbolic Variables in Procedures

Introduction You can use symbolic variables in an ESP Procedure. The different types ofvariables are:

Type of Variable ExplanationBuilt-in Variables ESP provides a set of built-in variables for such

information as the current date, time, and Eventname. You can use these variables in an ESPProcedure but their values cannot be changed.Refer to the Advanced User’s Guide for acomplete list of these variables.

User Defined Variables These are alphanumeric strings or integers thatyou can use in an ESP Procedure to representcharacter strings, literal data, and numbers. Whenusing an integer variable, you must first definethe variable with an INTEGER statement beforeyou use it.

When you want to use the value of a symbolic variable, you use the symbolintroducer character (default is the per cent sign (%)) followed by the symbolname. For example: %NAME.

Note:Your installation may use a different symbol introducer character. Check withyour system administrator to find out what symbol introducer character isused at your site.

Example: UsingSymbolics

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.

INTEGER NUMBERNUMBER=52NAME='FRED'SEND '%NAME IS %NUMBER YEARS OLD TODAY' U(USER01)

The message ESP sends to USER01 looks like this:

FRED IS 52 YEARS OLD TODAY


146

Using Symbolic Variables in Procedures, Continued


Refer to the Advanced User’s Guide for a detailed discussion of symbolicvariables.

147

Using Expressions and Strings in Procedures

Introduction You can also use strings, expressions, and operators in your Procedures. Thissection outlines the syntax and use for each of these.

Using literalstrings

A literal string is a group of characters enclosed in single quotes. You canembed symbolic variables in a string. ESP later substitutes the actual value ofthe variable into the string during processing.

When you want to enter text and have it appear exactly as you typed it,enclose in single quotes:

'THIS IS A CHARACTER STRING'

When you want to enter a text statement containing a changing variable, suchas the time (%ESPATIME), you could type:

'THE TIME IS %ESPATIME'

ESP substitutes the actual system time in place of the symbolic variable name%ESPATIME.

Usingexpressions

An expression is a variable, number, or character string connected byoperators. Expression evaluation is from left to right; this is overridden byoperator precedence. You can modify this order using parentheses.

A logical expression resolves to the value 1 if true, or 0 if false. Conversely, ifan arithmetic expression resolves to 1, it is false. For any other value, theexpression is true. If you do not enclose a logical expression in parentheseswhen you use an IF statement, ESP understands the THEN statement to be theterminator. Some examples are shown below:

• In the first statement, ESP processes the THEN statement if NUM=100.• In the second statement, ESP 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 ...


148

Using Expressions and Strings in Procedures, Continued

Using operators You can use arithmetic operators, comparison operators, and logical operatorsin an expression.

Arithmeticoperators

Numbers may 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 performs the division internally usingfloating- point arithmetic but the resulting value is an integer. If you use “//”for division, ESP disregards any remainder. For example, if A is an integerthen A = A/2*2 is always true, but A = A//2*2 is true only if A is even.

Comparisonoperators

The comparison operators return the value 1 if the result of the comparison istrue or 0 otherwise. You can use the following operators, in either theirsymbol or letterform 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

Logicaloperators

You can use the following logical operators in an expression:ANDOR


149

Using Expressions and Strings in Procedures, Continued

Order ofprecedence

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 avalid character string that ESP assigns to the variable “E”. ESP assigns thevalue “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. Thismeans that ESP does not have to evaluate C > D. This order of precedence isuseful for expressions such as “IF I = 0 AND J/I > 4”. This expression doesnot cause an error since J is divided by I only if I is non-zero.

150

Built-in Functions

Introduction A function is a sequence of instructions that can receive data, process thatdata, and return a value. ESP provides a set of built-in functions. To use afunction, type the function name directly followed by one or more argumentswithin parentheses, like this:

function(arguments)

Note:There can be no space between the function name and the left parenthesis.

Built-infunctions

The built-in functions fall into the following categories:

Category ExplanationCalendaring Test schedule criteria and calculate time periods.Job Selection Check if a job has already been selected for

submission.Symbolics Perform operations on symbolic variables.System Activity Check the status of activity on the system, including

jobs and tape drives.

Summary byfunction

The following table summarizes the functions by category:

Category Function DescriptionCalendaring DAYS_BETWEEN Calculates the number of units

(days, weekdays, workdays, etc.)between two dates.

Calendaring DAYS_FROM Calculates the number of daysfrom a date.

Calendaring DAYS_TO Calculates the number of daysaway from a date in the future.

Calendaring TODAY Tests to see if today matches aspecified schedule expression.

Calendaring TOMORROW Tests to see if tomorrow matchesa specified schedule expression.

Calendaring YESTERDAY Test to see if yesterday matches aspecified schedule expression.


151

Built-in Functions, Continued

Summary by function (continued)

Category Function DescriptionJob Selection SELECTED Checks to see if a job has been

selected.Symbolics DEFINED Checks to see if a symbolic

variable has been defined.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 currentsystem.

System Activity JOBONQ Checks to see if a job or addressspace is active on any system inthe shared spool environment.

System Activity TAPES Checks the status of tape drives.

Testing for atrue condition

Each one of the SELECTED, TODAY, TOMORROW, and YESTERDAYbuilt-in functions returns a true value (1) or a false value (0). To test for a truecondition you do not have to specify the true value, since this is the default. Ifyou want to test for a false value, you must specify either “=0”, “EQ 0”, or usethe word “NOT”.

In the following example, both statements have the same effect. Each checksto see if today is not Monday.

IF TODAY('MONDAY') EQ 0 THEN ...IF TODAY('NOT MONDAY') THEN ...


The following sections describe ESP’s built-in functions in detail and containsome examples of using these functions. For more examples, refer to theExamples section at the end of this chapter.

152

Using Calendaring Functions

DAYS_TO The DAYS_TO function returns a positive number representing the numberof 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_TOassumes the next year and returns a positive number. If the date is in the past,ESP returns a negative number.

Example:DAYS_TO

If you want to determine the number of days to December 25 from the currentday, 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 thenumber of days from a date in the past. DAYS_FROM assumes the currentyear if you do not specify one. If the date is in the future, ESP returns anegative number.

Example:DAYS_FROM

The following is an example of an expression containing the DAYS_FROMbuilt-in function:

IF DAYS_FROM('AUGUST 1ST') GT 0 THEN

DAYS_BETWEEN The DAYS_BETWEEN function returns a whole number representing thenumber of a specified unit of time between two given dates. You do not haveto 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. The followingare other possible restrictors; HOURLY, DAILY, WORKDAYS,WEEKDAYS, WEEKLY, SATURDAYS, WEEKENDS, MONTHLY,YEARLY. Your restrictor cannot be any unit of time less than ’hourly’. Thevalue that this function returns is the number of occurrences of the restrictorbetween the first date and the second date. If the first date is not prior to thesecond date, the function returns a negative number. The maximum value thefunction returns is 50,000 for any restrictor other than 'DAYS'.


153

Using Calendaring Functions, Continued

Example:Days_Between toCalculateWorkdays

If you want to know the number of workdays there are from January 30, 1998,up to but not including June 30, 1998, you would type:

DAYS_BETWEEN('JAN 30 1998','JUNE 30 1998','WORKDAYS')

Example:Days_Between toCalculate Weeks

You could also determine the number of Saturdays from the 6th workday ofthe 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 totoday’s schedule date. It returns a true or a false value, depending on whetherthe expression matches today. ESP returns a number code indicating theresult:

1 = true0 = false

In the following example, ESP only processes the instructions following theTHEN statement if today is a Friday.

IF TODAY('FRIDAY') THEN ...

When the statement is false, ESP skips to the next ELSE statement or to thefollowing 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:

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

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


154


TOMORROW The TOMORROW function compares the expression following theTOMORROW keyword to tomorrow’s date (i.e. the day after the scheduledate). ESP returns a true or false value, depending on whether the expressionmatches tomorrow. ESP returns a number code indicating the result:

1 = true0 = false

Examples:TOMORROW

Here are two examples using the TOMORROW function:

• In the first example, ESP only processes the instructions following the THEN statement if tomorrow is the last workday of the month.

• In the second example, ESP only processes the instructions following the THEN statement if tomorrow is a holiday.

IF TOMORROW('LAST WORKDAY OF MONTH') THEN ...IF TOMORROW('HOLIDAY') THEN ...

When the statement is false, ESP skips to the ELSE statement or thefollowing line.

YESTERDAY The YESTERDAY function compares the schedule expression that youspecify to yesterday’s date (i.e. the day before the schedule date). ESP returnsa true or false value, depending on whether the expression matches yesterday.ESP returns a number code indicating the result:

1 = true0 = false

Example:YESTERDAY

In the following example, ESP only processes the instructions following theTHEN statement when yesterday is the first workday of the month:

IF YESTERDAY('FIRST WORKDAY OF MONTH') THEN ...

When the statement is false, ESP skips to the ELSE statement or to thefollowing line.


155


Example:YESTERDAY

In the following example, ESP only processes the instructions following theTHEN statement when yesterday is a holiday:

IF YESTERDAY('HOLIDAY') THEN ...

When the statement is false, ESP skips to the ELSE statement or to thefollowing line.

156

Using Functions For Job Selection

SELECTED The SELECTED function returns a true or false value that indicates whether ajobname has been selected as a result of a previously processed SELECT orRUN statement. To return a true value, ESP must have selected the job in thisESP Procedure, or in another ESP Procedure invoked by the same Event,prior to evaluating the function. This function does not return a true value fora job selected via a POSTREQ, PREREQ or COREQ statement.

ESP returns a number code for the value:1 = true, the jobname has been selected.0 = false, the jobname has not been selected.

The syntax is:

SELECTED('JOBNAME')

If the job you are checking for selection is a qualified job, you will need toinclude the qualifier, like this:

SELECTED('jobname.qualifier')

This function is useful for scheduling jobs with the same frequency as it caneliminate the need to specify complicated criteria multiple times. The functionis also useful when you want to schedule a job whenever another job is notscheduled.

Example:Selecting onejob based onanother

You could use the SELECTED function to select Job B whenever ESP selectsanother job, Job A.

IF SELECTED('A') THEN SELECT B

Example:Selecting a jobwhen another isnot selected

In this example, ESP selects Job Z whenever it does not select Job X. ESPselects Z on all days except for the 3rd, 13th and 23rd day of the month.

JOB XRUN 3RD 13TH 23RD DAY OF MONTHENDJOBJOB ZIF NOT SELECTED('X') THEN RUN TODAYENDJOB

The above results are valid only at Application generation time and not atApplication process time.

158

Using Functions For Symbolic Variables

DEFINED The DEFINED function checks to see if a symbolic variable has been definedand returns the following values:

1 = true0 = false

The syntax is:

DEFINED(variable)

Example:Defining anundefinedvariable

This example defines an integer variable called COUNT if it has not beendefined.

IF NOT DEFINED(COUNT) THEN - INTEGER COUNT

LENGTH The LENGTH function returns a number equal to the length of the variablefollowing the LENGTH keyword in parentheses. The syntax is:

LENGTH(variable)

This function does not return a true or false value. Instead, it resolves to awhole number equal to the length of the named variable’s value.

Example:Calculating thelength of asymbol

In this example, the LENGTH function assigns the length of a user-definedvariable called ‘LETTER’ to the integer variable ‘SIZE’. As a result, SIZE hasa value of 7.

INTEGER SIZELETTER='OMICRON'SIZE=LENGTH(LETTER)

SUBSTR The SUBSTR function resolves to a partial string from the variable string thatfollows the SUBSTR keyword in parentheses. The syntax is:

SUBSTR(start,length,variable_name)


159

Using Functions For Symbolic Variables, Continued

Example: Usinga substring of atime variable

The ESPATIME built-in variable represents the actual time, 19.35.42, forexample. This example assigns the number of minutes in the ESPATIMEsymbolic variable to the symbol ‘MIN’.

MIN=SUBSTR(4,2,ESPATIME)

Example:Extracting thelast characterof a variablelength symbol

This example uses the LENGTH and SUBSTR functions to extract the lastcharacter of the scheduled month name. The LENGTH function calculates thelength of the month name. The SUBSTR function extracts the last character.

INTEGER XX=LENGTH(ESPSMONTH)LAST_CHAR=SUBSTR(%X,1,ESPSMONTH)

For example, if the scheduled month is December:

• X=8, because there are 8 characters in the word ‘December’• LAST_CHAR=SUBSTR(8,1,‘DECEMBER’), which resolves to ‘R’, the

last character in the word ‘December’.

160

Using System Activity Functions

ACTIVE The ACTIVE function tests to see if a job or any address space is active onthe current system and returns a value based on that test. ESP returns anumber 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 ifCICSPROD isactive

This example sends a message to console identifier 01 if CICSPROD is activeon the current system.

IF ACTIVE('CICSPROD') THEN +SEND 'CICSPROD IS STILL ACTIVE' CN(01)

JOBONQ Use the JOBONQ function to determine, by checking JES, whether a job orgroup 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 parameters: a jobname, a prefix and searchcriteria.

Parameter Explanationjobname The name of the job or jobname prefix. You can only use a

jobname prefix with the U criteria.prefix The prefix of the variables you want to generate. This

parameter is optional. For example, you can specify:

IF JOBONQ('MYJOB', '', 'E') THEN -SEND 'MYJOB IS EXECUTING' U(*)


161

Using System Activity Functions, Continued

Parameter Explanationcriteria The search criteria consist of any combination of the letter

codes below. If this parameter is omitted, ESP looks in allqueues.

ReturningValues

The following list contains all the acceptable search criteria codes:

Search Criteria Codes Explanation I Examine the input queue E Examine the execution queue O Examine the output queue H Examine held jobs only U Treat the jobname as a userid. The search

includes any job with a name consisting of thejobname plus one character.

JOBONQVariables

The JOBONQ function returns the count of jobs that meet the criteria. Foreach job it generates a series of four variables beginning with the specifiedprefix (the second parameter). 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 1 to thenumber of jobs found.

Example:JOBONQ

The JOBONQ function in the following example verifies the existence of anyjob in the input queue (I) in hold status (H). ESP assigns the number of jobsthat 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 generates a set ofvariables for each job it finds. These variables all begin with the prefix ‘Z’.


162


Example For example, for the first job it finds the variables are:

Variable ExplanationZJOBID1 JES job identifier. This is ‘JOB’ followed by the 5-digit job

number (e.g. JOB01234).ZJOBNO1 JES job number (e.g. 1234).ZJOBH1 Equal to 0 if JES is not holding the job, or equal to 1 if JES is

holding the job.ZJOBQ1 Equal to “I”, “E”, or “O” depending on whether the job is on

the input, execution, or output queue respectively.

When ESP finds more than one job, the variables it generates for the secondjob are: ZJOBID2, ZJOBNO2, ZJOBH2, and ZJOBQ2. ESP repeats thisseries with the last digit incrementing by one for additional jobs it finds.

If you use the ‘U’ criteria, the JOBONQ function also returns the JOBNvariable, with the appropriate prefix and suffix.

UsingJOBONQ withREEXEC

You can also use the JOBONQ function in conjunction with the REEXECstatement to allow you to re-execute an ESP Procedure at a specified time orafter a certain time interval. In the following example, ESP re-executes theProcedure if MYJOB is found on any queue.

IF JOBONQ('MYJOB') THEN REEXEC IN(5)


163


TAPES ESP evaluates the TAPES function to check the status of tape drives on thesystem and compares the status to the resources required by the job. Whenyou use the TAPES function at the job level for a job in an Application, youcan verify the status of the tape drives before you submit a job.

Note:To check the status of tape drives, Cybermation recommends you useresources. Resources provide you with easier, more efficient ways of definingtape requirements. For more information, refer to Using Resources, in thisguide.

Example:TAPES

To use this function enter TAPES followed by two parameters from the listsbelow:

TAPES('xy')

ESP evaluates both parameters (x and y) of the function and returns a wholenumber.

You can choose one of the following three options as the first parameter:

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

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

Option Explanation A Available O Online D Defined

The default is CA.


164


Example:Checkingavailablecartridge drives

If a job in an Application requires two cartridge drives, you can use theTAPES function to check that two cartridge drives are available before yousubmit the job. If they are not, ESP can check again after two minutes:

JOB TAPEJOB1IF TAPES('CA') < 2 THEN REEXEC IN(2)

165

Combining Functions

Introduction You can combine built-in functions using the ‘AND’ and ‘OR’ logicaloperators. Specify the built-in function name each time you need to use it.

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

• 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 ortomorrow is a holiday:

• IF TODAY('MON WED FRI') AND (YESTERDAY('HOLIDAY') OR +TOMORROW('HOLIDAY')) THEN

166

Re-executing an ESP Procedure

Introduction Use the REEXEC statement to request re-execution of an ESP Procedure at aspecific time or after a certain time interval. ESP stores the number of re-executions in a symbolic variable called ESPREEXEC#. If you use REEXECwithin the scope of a JOB statement in an Application, ESP re-executes onlythe code associated with that job, and maintains a separate ESPREEXEC# foreach job.

Example:Checking ifCICS is active

This ESP Procedure checks to see if a job or address space called CICS isactive on the current system.

• If CICS is active, ESP sends a non-deletable message to console id 01 andre-executes the Procedure in 5 minutes.

• If CICS is not active, ESP submits the member CICSBKUP from thelibrary PROD.JCL.CNTL.

The ESP Procedure looks like this:

IF ACTIVE('CICS') THEN DO SEND 'CICS IS DUE TO COME DOWN' CN(01) NONDEL REEXEC IN(5)ENDDOELSE SUBMIT 'PROD.JCL.CNTL(CICSBKUP)'

Note:If you want to set up a dependency with an online region, such as CICS, for ajob in an ESP Application, the preferred method is to use ESP’s resourcefeature. For information on using resources, refer to Using Resources.


167

Re-executing an ESP Procedure, Continued

Example:Waiting for ajob

This ESP Procedure checks to see if a job called RMTJOB is on the inputqueue.

• If RMTJOB is on the input queue on hold, ESP releases the job.• If RMTJOB is not on the input queue on hold, ESP checks the number of

re-executions. If the number of re-executions is less than 5, ESP re-executes the Procedure in 30 minutes. Otherwise, ESP sends a message.


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

168

Using Templates

Introduction A template is an element of CLANG that allows you to specify repetitiouscommands or statements once, such as those you use to define holidays orjobs.

This section contains a brief introduction to templates. For more informationon using templates, refer to the Advanced User’s Guide.

Defining atemplate

To define a template, you:

• Use a TEMPLATE statement to give your template a name and identifyparameters you want to pass through the template

• Define the statements that make up your template• End the template definition with the ENDTEMPL statement.

Using atemplate

To use a template you have defined, you specify the name of the templatefollowed by any parameters you want to pass through the template.


169

Using Templates, Continued

Example -Defining astatic holiday

This example uses a template to define a static holiday, called CHRISTMAS,for 6 years. The DEFHOL command defines a holiday for a particular date.Use a template in an ESP Procedure to specify the DEFHOL command andsupply the template with different years.

In this example:

• The name of the template is XMAS and it accepts 1 positional parameterrepresented by the variable YEAR.

• The body of the template consists of one statement that definesCHRISTMAS as a 24 hour holiday, on Dec. 25 each year, in the SYSTEMcalendar. The year is represented by the variable YEAR.

• The ENDTEMPL statement ends the template definition.• The template XMAS is then used with the years 1998 through 2003. Each

of these years is passed to the template and substituted for the variableYEAR within the template.

TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START('DEC 25, %YEAR') + FOR(24) CAL(SYSTEM)ENDTEMPLXMAS 1998XMAS 1999XMAS 2000XMAS 2001XMAS 2002XMAS 2003

Set up an Event to invoke this ESP Procedure and trigger it manually todefine your holidays.


170


Example -Definingsimilar 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 RUN DAILYENDJOB

Because of the similarity of the jobs, you can define a print job template andpass 1 parameter for the name of each job. The template contains details forthe print job, such as SUBAPPL PRTJOBS and RUN DAILY.


171


Example -Definingsimilar 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 substitutes the jobname for the %NAME variable within the template.

172

Using Event Definition Commands in Procedures

Commands 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 ROSSUB Submits JCL from a Roscoe 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).

173

Examples

Introduction This section contains some additional examples of using CLANG.

Example:Scheduling ajob on the lastday of themonth

In this example, ESP selects a job if it is the last day of the month and themonth has 31 days in it. The Procedure uses the ESPSDD built-in symbolicvariable that represents the number of the scheduled day of the month.


IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN SELECT MONTHEND

Alternatively, if you normally use RUN statements for your jobs, the ESPProcedure looks like this:

JOB MONTHEND IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN RUN TODAYENDJOB

Example:Takingdifferent actionon a weekday

In this example, ESP takes different actions based on whether or not thescheduled day is a weekday.

• If the scheduled day is a weekday, ESP sends a message and submitsJOB1.

• If the scheduled day is not a weekday, ESP sends a different message andsubmits 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


174

Examples, Continued

Example:Takingdifferentactions basedon the status ofCICS

In this example, ESP takes different actions based on whether or not CICS isactive.

• If CICS is active on the current system, ESP jumps to a label calledSTOP. ESP issues an operator command, schedules a re-execution in 5minutes, and exits this Procedure.

• If CICS is not active on the current system, ESP jumps to a label calledGO and issues a command to trigger an Event.


IF ACTIVE('CICS') THEN JUMPTO STOP ELSE JUMPTO GOSTOP:VS 'F CICS SHUTDOWN'REEXEC IN(5)EXITGO:VS 'F ESP,TRIGGER PROD.NIGHTLY'

Example: Usingcalendaringfunctions

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


175

Examples, Continued

Example:Calculatingtime periods

This example calculates the number of days, from a specific time and date inthe past. ESP sends the results back to your terminal.


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 anESP procedureon a particulardate

There may be occasions where you need to use an alternate ESP Procedure fora specific date. One method is illustrated below:

DAILY:ESPPROCIF TODAY('specific date') THEN - DO INVOKE 'PROD.ALT.ESPPROC(DAILYEX)' EXITENDDO/*REGULAR PROCEDURE*/...

The first statement checks to see if today is a specific date. If so, ESP invokesan alternate ESP Procedure. Otherwise, ESP processes the statements in theregular procedure.


176

Examples, Continued

Example:Takingdifferent actionbased on time

In this example, ESP takes different actions based on when a job becomeseligible for submission. The criteria are:

• If Job THISJOB becomes ready for submission between 3 a.m. and 3:59a.m., ESP submits the job and sends a message indicating it is almost toolate to run the job.

• If THISJOB becomes ready for submission at 4 a.m. or later, ESP does notsubmit the job.

• Otherwise, if THISJOB becomes ready between midnight and 2:59 a.m.,ESP sends a message indicating the job is on time.

The ESP Procedure is shown below. The ESPAHH symbolic variablerepresents the actual 2-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 SEND 'THISJOB IS ON TIME' U(OP1)ENDJOB

178

Using Applications

Overview

Introduction An Application consists of one or more jobs, or other workload objects. Aworkload object can be a job, a manual task, a command you want processed,or a non-MVS object, such as a Unix script. For example, an Applicationmay consist of all of your payroll jobs. You can define an Application usingthe Application Definition panels, ESP Workstation, or by editing a memberof a PDS. All Application definitions are stored in ESP Procedures.


Topic See PageIntroducing Applications 180Identifying the Application 185Identifying JCL Libraries 186Identifying Jobs 192Defining Job Requirements 199Specifying Time Dependencies 200Specifying Job Relationships 208Selecting Jobs for Submission 210Using Different Job Types 213Defining External Jobs 214Defining Manual Jobs 218Using Links 221Using Tasks 227Changing Job Attributes 229Using Data Set Trigger Workload Objects 230Tagging Jobs 236Providing Notification on Job Status 238


179

Overview, Continued

In this chapter (continued)

Topic See PageUsing Critical Path Analysis 241Issuing ESP Commands 246Using subApplications 247Working with Applications 251Displaying an Application 252Controlling an Application 254Changing an Application Definition 256Invoking an ESP Application 257

180

Introducing Applications

Overview This section describes the following concepts of an Application:

• How ESP manages jobs in an Application• Generating and processing an Application• Application generations.

Process anApplication

ESP performs the following processing steps for jobs in an Application:

Step Action1 When a job’s submission time arrives, ESP 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 thejob. A job in an Application is not eligible for submission if thehold count exceeds zero.

3 When a predecessor job terminates successfully, ESP subtracts ‘1’from the successor job’s hold count. For instance, if the holdcount for a job is ‘3’ and a predecessor job terminates successfully,the hold count decreases to ‘2’.

4 When the hold count reduces to zero, ESP “readies” the job forsubmission, unless the job is in another type of hold status such asManual hold or Resource Wait.

5 ESP submits the job when all required resources are available.

Types of phases An Application passes through the following two phases:

• Generation• Process.

Generationphase

When an Event is triggered that invokes an ESP Application definition, ESPmust first generate the Application. ESP reads the definition and creates arecord in a file known as the APPLFILE. This record includes the informationESP needs in order to process the jobs in the Application. The recorddescribes the Application and all the jobs within it.


181

Introducing Applications, Continued

Process phase Once ESP generates an Application, it then begins to process that Applicationas follows:

• A component of ESP called the Application Manager has a queue of jobsawaiting submission. Jobs can be in a waiting state due to such things astime, predecessors, and resources.

• The Application Manager looks at the jobs and assesses whether any timedependencies have been met. If so, the job goes into a job dependencystate and waits until the last predecessor dependency has been met.

• The job then enters a resource wait state, which allows ESP’s resourcemanager to verify that the job’s resource dependencies are met.

• ESP re-drives the Event to submit the job when the required resources areavailable.

• The Application manager uses real-time SMF data to update the executionstatus of each job.

Phase status You can find out the phase status of an Application by using theESP_APPL_PROC and ESP_APPL_GEN symbolic variables in anApplication definition.

ESP sets these symbolic variables as follows:ESP_APPL_GEN =1, during generation phase

=0, otherwise.ESP_APPL_PROC =1, during process phase

=0, otherwise.

In the following example, ESP sends a message to a user only during thegeneration phase of an Application.

IF ESP_APPL_GEN=1 THEN - SE ‘ESP IS GENERATING THE PAYROLL APPLICATION’ U(TAXMAN)


182


ApplicationGenerations

Each Application has a generation number assigned by ESP when theApplication is generated. This number increments with each generation of anApplication. Using the generation number, ESP can identify the particulargeneration of an Application to which a job belongs.

A generation of an Application does not have to complete within any 24 hourperiod; an Application can span many days or weeks, or you can schedule anApplication many times in one day. Different generations of an Applicationcan process at the same time.

Defining anApplication

You must use an ESP Procedure to describe an Application to ESP. Refer toWorking with ESP Procedures on page 137 for detailed information on ESPProcedures.


183


ESP Procedurestatements

An ESP Procedure that defines an Application consists of a series ofstatements that:

• Identifies the Application• Tells ESP where the appropriate JCL is located• Identifies the jobs• Describes the job relationships• Describes when ESP should select the jobs to run• Describes other job dependencies, such as time.

In addition, an ESP Procedure may also indicate which job documentationlibrary is used, or specify what condition codes cause a job to fail.Visually, an Application might look like this:

A

B C

E

F

D

Daily

Friday

Last workday of month


184


Applicationdefinition

The corresponding Application definition might look 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.

185

Identifying the Application

Introduction 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 eight alphanumeric or nationalcharacters.

Your security administrator may require you to code other information on theAPPL statement, such as the SAF_PROF_APPL keyword, to provide moregranular security for the Application.

Controllingconcurrentprocessing

Normally, if two generations of an Application are active on the system at thesame time, they execute at the same time. You can control concurrentprocessing at different levels, as follows:

Parameter Explanation Example

WAIT parameter onAPPL statement

A generation of an Application must wait untilits previous generation is complete

APPL PAYROLL WAIT

WAIT parameter onthe SUBAPPLstatement

The subApplication must wait until the samesubApplication in the previous generation iscomplete

SUBAPPL PAYREQ WAIT

JOB_ANCESTOR_WAIT(ANY)parameter on theAPPL statement

Indicates that a job is not eligible forsubmission if the same job in any previousgeneration of the Application has notcompleted successfully

APPL PAYROLL +JOB_ANCESTOR_WAIT(LAST)

JOB_ANCESTOR_WAIT(LAST)parameter on theAPPL statement

Indicates that a job is not eligible forsubmission if the same job in the previousgeneration of the Application has notcompleted successfully. ESP only looks at the-1 generation.

APPL PAYROLL +JOB_ANCESTOR_WAIT(ANY)

None of the aboveparameters

Applications can process at the same time. APPL PAYROLL

For more information on subApplications, refer to Using subApplications onpage 247.

186

Identifying JCL Libraries

Introduction Use global statements in your Application to specify the default JCL librariesyou want to use throughout an Application. This saves you the task ofrepeatedly specifying the same information as part of each job’s definition.The scope of a global statement extends from the point at which you specify itto either the end of the Application, or to the point at which you specify acorresponding global statement. This way you can change or override jobdefaults several times during an Application, if necessary.

You can specify any of the following: a JCL library, a temporary JCL libraryand a COPYJCL library at a global level. You can override the JCL library,member name, or COPYJCL library at a job level.

Example The following example identifies three libraries in the BILLJOBSApplication. These global statements are specified prior to any JOBstatements.

APPL BILLJOBSJCLLIB ‘PROD.JCL.CNTL’TEMPLIB ‘PROD.OVERRIDE.JCL’.COPYJCL ‘CYBER.JCL.COPY’ GEN(0)

Each of these statements is described in the following sections.

Specifying aJCL library

Use the JCLLIB statement to specify the JCL library you want to use for alljobs following this statement.For example,

JCLLIB ‘PROD.JCL.CNTL’

When ESP encounters a JOB statement for a job, it uses the JCL member inthe JCLLIB with the same name as the job. You can use the MEMBERstatement to override this action.

The JCLLIB statement cannot be used at the job level. If you code a JCLLIBstatement within the scope of a JOB statement, it affects all jobs after it, oruntil another JCLLIB statement is specified. To override the JCL library for aparticular job, use the DATASET statement.


187

Identifying JCL Libraries, Continued

Specifying atemporary JCLlibrary

Use the TEMPLIB statement to specify the temporary, or override JCL libraryyou want to use as the default for all jobs following this statement. ESP usesJCL from this library for job submission if it exists. Otherwise, it uses JCLfrom the most recent JCLLIB statement. By default, the member name is thesame as the job name. You can use the MEMBER statement to override thisaction.For example:

TEMPLIB ‘PROD.OVERRIDE.JCL’

As long as JCL exists for a job in the temporary library, and you specified aTEMPLIB statement in your Application, ESP submits the job from there.ESP does not automatically delete the member from the TEMPLIB data setwhen a job completes.

Controlling theuse oftemporary JCL

The following are some options for controlling the use of temporary JCL:

• Use ESP control statements in JCL to limit the time period for usage. Thistechnique is described later in this section.

• Use ESP’s automatic variable insertion facility (AUTOVARS) to insert atrailer step that deletes the TEMPLIB member. For information on usingAUTOVARS, refer to the Advanced User’s Guide.

• Use another method for cleaning out the TEMPLIB members. Forexample, on a daily basis, delete the members.

• Instead of using TEMPLIB, use IF logic with the DATA SET statement tooverride the JCL library for a particular job. This technique is describedlater in this section.

• Instead of using TEMPLIB, use %INCLUDE/%EXCLUDE statementswithin the JCL. This may be practical if the differences in JCL areminimal. For information on using these statements, refer to the AdvancedUser’s Guide.

• Use different data sets. For example, you could use a different data seteach day.


188


Example: Usinga differentTEMPLIBbased on yearand day

In the following example, ESP symbolic variables are used as part of theTEMPLIB data set name. %ESPSYEAR resolves to the 4-digit year;%ESPSDDD resolves to the Julian day. For example, on February 28, 1998this resolves to: ESP.OVERRIDE.1998059.

TEMPLIB ‘ESP.OVERRIDE.%ESPSYEAR%ESPSDDD’

Limiting theuse oftemporary JCL

A job may need to run from a temporary JCL library for a period of time. Ifyou want to limit the time period in which temporary JCL is to be used for ajob, you can:

• Use a //*FROM statement in the job’s JCL to identify the beginning dateand time. The default is NOW.

• Use a //*UNTIL statement in the job’s JCL to identify the ending date andtime. There is no default. ESP uses the TEMPLIB JCL up to, but notincluding, the date and time specified.

You can use either one of these statements or you can use both. Place thesestatements before the job card in a JCL member of the temporary library(TEMPLIB). You can use any ESP scheduling term that resolves to a singledate and time.

Example In the following example, ESP uses the temporary JCL from midnight onFebruary 1, 1998 up to, but not including, February 14, 1998. At any timeafter February 13, ESP uses the default JCL library. Note these dates arebased on the scheduled date of the Event, which may not be the actual date ofjob submission.

//* FROM FEB 1,1998//* UNTIL FEB 14,1998//BILLJOBA JOB . . .


189


Specifying aCOPYJCLlibrary

Use the COPYJCL statement to generate a copy of the JCL for every job, asESP submits it. This copy is written to a member of a PDS, providing aworking copy of the JCL with, where applicable, all symbolic variablesresolved. This JCL can be used for job re-submission. ESP keeps track ofwhere the job was submitted from and the JCL that was used. ESP can storethe copy of the JCL either by jobname (JOBNAME keyword) or by JES jobnumber (JOBID keyword).

Using theJOBNAMEkeyword

The JOBNAME keyword requests the member name used for storing the JCLfor a job is the same as the jobname. This is the default. Each submission of aparticular job overwrites the previous copy of that job’s JCL.

Using theJOBIDkeyword

Use the JOBID keyword when you want ESP to store the copy of the JCL byjob number. ESP creates a member name starting with JOB, followed by afive-digit JES job number. The system assigns this number sequentially. Amember is not overwritten until its five-digit number reoccurs.

Writing theJCL to a PDSGDG

With either the JOBID or the JOBNAME method, you can write the JCL to aPDS GDG. A new generation can be created each day to maintain severalgenerations of JCL. Schedule an Event each day to submit a job that createsthe next generation.

Example: UsingCOPYJCL

This example requests that a copy of submitted JCL be written to the currentgeneration of the data set ‘CYBER.JCL.COPY’ and stored by jobname (bydefault).

COPYJCL ‘CYBER.JCL.COPY’ GEN(0)

SuppressingCOPYJCL

If you do not want to create COPYJCL for a particular job, you can specifythe following:

JOB MISC COPYJCL NONE


190


CompressingCOPYJCL

If you re-use the same data set continually, submit a compress job frequentlyto ensure the data set does not run out of space. You can use a data settriggered Event to submit the compress job automatically after a number ofclosures.

Overriding themember for ajob

By default, the member name of the JCL library (either JCLLIB or TEMPLIB)used is the same as the jobname. To override this, use the MEMBERstatement and specify the name of the member that contains the JCL for thejob. The jobname must match the name specified on the job card.

Example For example, the following specifies that the JCL for job PAY123A is inmember PAYA of the JCL library ‘CYBER.JCL.CNTL’:

JCLLIB ’CYBER.JCL.CNTL’JOB PAY123A MEMBER PAYA

Overriding theJCL library fora job

In addition to using the JCLLIB and TEMPLIB default specificationsstatements, you can identify the JCL library and optional member name that aparticular job requires using the DATASET job statement. For this particularjob only, the DATASET statement overrides.


191


Example: Usinga different JCLlibrary for ajob

In the following example, jobs J1 and J3 use the ‘CYBER.JCL.CNTL’ libraryfor job submission, as this is the global JCL library specification. Job J2 usesthe ‘CYBER.ALT.JCL’ library for submission because of the presence of theDATASET statement.

APPL J123JCLLIB ‘CYBER.JCL.CNTL'JOB J1 RUN DAILY RELEASE J2JOB J2 DATASET ‘CYBER.ALT.JCL' RUN DAILY RELEASE J3JOB J3 RUN DAILYENDJOB

Example:Temporarilyusing adifferent JCLlibrary for ajob

In the following example, ESP uses the JCL from ‘CYBER.ALT.JCL’ for jobJ2 only on February 14, 2000.

JOB J2 IF TODAY(‘FEB 14,2000’) THEN - DATASET ‘CYBER.ALT.JCL’ RUN DAILY RELEASE J3ENDJOB

192

Identifying Jobs

Introduction An ESP Application is made up of a group of related jobs and other tasks. Thejobs and tasks have jobnames assigned to them.Before identifying job requirements, you must use a JOB statement to identifythe name of the job in an Application. You can define jobs in any order. ESPsubmits 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 ENDJOBstatement or another JOB statement signifies the end of a job definition. Youmust use an ENDJOB statement after defining all of your jobs. Althoughoptional, 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 lets you qualify jobnames with a qualifier consisting of up to 8alphanumeric characters, and separated from the jobname by a period,‘.’ Youcan qualify jobs, links and tasks but you cannot qualify Manual jobs. Usequalification of jobnames 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.


193

Identifying Jobs, Continued

Symbolics asqualifiers

You should not use %ESPA (actual) variables as time qualifiers for jobs sincethe actual time differs from Application generation to the time ESP submits ajob as part of the Application. You can use %ESPS (scheduled) variables astime qualifiers as these refer to the scheduled time of the Event.

Examples:Qualified Jobs

The following are some examples of qualified jobs. The last example uses aqualifier that consists of the first 3 characters of the symbolic variable%ESPSDAY. This is the scheduled day name. For example, on Monday thisresolves to ‘MON’.

JOB MYJOB.RUN1JOB STILL.RUNNINGJOB BACKUP.SYSRESJOB PAYJOB.%ESPSDAY(1:3)

Duplicatejobnames

Duplicate jobnames are not allowed in an Application. You can define thesame jobname more than once in an Application by using a unique qualifierfor each job.

Example:Multiple runsof a job

This example shows how you can define a job more than once in anApplication using a job qualifier. Job A appears twice in the Application. Thequalifier 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


194


Identifying ajob as On-request

With Applications, you can identify certain jobs as on-request and define theirrelationships to other jobs. The on-request jobs take their place in theschedule when they are selected. From the time you generate the Applicationup to the time of job submission, you can use CSF or the APPLJOB commandto request the job. If you have not explicitly requested the job, ESP bypasses itand treats it as a normal completion, releasing its successor jobs. To mark ajob as on-request, use the REQUEST parameter of the JOB statement.

REQUEST job By selecting a REQUEST job, you are not requesting the job, you are onlymaking it eligible for explicit request via CSF or the APPLJOB command.You must first generate the Application before you can request any of theApplication’s jobs. To allow users to request jobs, you may want to generatethe Application containing these jobs early in the morning and use submittime dependencies (i.e. DELAYSUB statements) on the jobs with nopredecessors so they are not submitted at the time ESP generates theApplication.

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

jobname.

For information on CSF, see Consolidated Status Facility on page 258.For information on using links, see Using Links on page 221.For information on using Symbolic Variables, see Advanced User’sGuide.


195


Example In the following example, if job J2 is not requested at the time it is scheduledfor submission, ESP 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

Requesting thejob

To request the job, use the RQ command from the Consolidated StatusFacility, or use the APPLJOB (abbreviated AJ) Command.

The following example shows requesting job J2 in the current generation ofAPPL1, with the abbreviated APPLJOB command:

AJ J2 REQUEST APPL(APPL1.0)


196


Definingcritical jobs

Use the CRITICAL keyword on the JOB statement to identify a critical job Inyour Application. If critical path analysis is turned on for the Application,ESP 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 usingCSF 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 onpage 241.

Defining heldjobs

Use the HOLD keyword on the JOB statement to identify a job that you wantto hold from submission until you release it. This places the job on manualhold when ESP generates the Application. You can display jobs that are onmanual 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 amanual process, it is better to use a task in the Application as a predecessor.

For information on using tasks, see Using Tasks on page 227.

Definingconditional jobs

Normally, all jobs in an Application must complete, or be bypassed, in orderfor the Application to complete. In some situations, you could have someoptional jobs (other than on-request jobs) which may or may not run as part ofthe Application. These jobs are referred to as conditional jobs. ESP completesan Application when all non-conditional jobs are complete and bypasses anyincomplete conditional jobs.

For example, you might have a recovery job that only runs when another jobin 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 arecomplete then you want ESP to complete the Application.


197


ConditionalJob

Use the CONDITIONAL keyword on the JOB statement to identify a job thatmay 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 Advanced User’s Guide.

Scope of a JOBstatement

The scope of a JOB statement includes all statements up to an ENDJOBstatement or the next JOB statement. ESP processes commands based onwhere they are placed, as follows:

• ESP processes commands outside the scope of JOB statements when theApplication is generated and every time a job becomes eligible (i.e. alldependencies met).

• ESP processes commands within the scope of a JOB statement only whenthe job becomes eligible (i.e. all dependencies met).

Example:Sendingmessages atdifferent stages

The following Application contains three SEND commands. ESP sends thefollowing messages at the following points:

• MESSAGE1, when ESP generates the Application and each time itsubmits a job in the Application.

• MESSAGE2, when ESP submits job A.• MESSAGE3, when ESP submits job B.

The Application looks like this:

APPL ABCJCLLIB . . .SEND ‘MESSAGE1’ U(*)JOB A SEND ‘MESSAGE2’ U(*) RUN DAILY RELEASE BENDJOBJOB B SEND ‘MESSAGE3’ U(*) RUN DAILYENDJOB

199

Defining Job Requirements

Introduction Once you name a job, you can use different statements to define the job’srequirements. These requirements generally fall into the following three areas:

Dependency

SelectionTiming

200

Specifying Time Dependencies

Types of timedependencies

A job can have different types of time dependencies. These include thefollowing:

• 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.You can refer to different times to compensate for varying conditions usingCLANG.

Delayingsubmission of ajob

Use the EARLYSUB (early submit time) or DELAYSUB (delayed submit time)statements to mark a job for delayed submission relative to the scheduled timeof the Event. Both statements achieve the same results. Since you can specifyany valid schedule criteria that resolves to a single date and time when theApplication builds, you can use the EARLYSUB (or DELAYSUB) statement toallow an Application to span many days or weeks.

Example:Identifying adelayedsubmissiontime

This example specifies that job J2 should not be submitted prior to 9 p.m.:

JOB J2 DELAYSUB 9PM

Example: Usingdifferentsubmissiontimes

This example uses CLANG to specify different DELAYSUB times for a job.The second DELAYSUB statement overrides the first on weekends only. Thedifferent times are:

• 9 p.m. on weekdays• 5 p.m. on weekends.JOB J2 RUN DAILY DELAYSUB 9PM IF TODAY(‘WEEKEND’) THEN DELAYSUB 5PM


201

Specifying Time Dependencies, Continued

Delaying theRelease of a job

You can also use the RELDELAY statement to delay job submission at thetime a job becomes eligible (i.e. ready). This statement uses minutes as itsunit of measure. You can delay submission up to 255 minutes.

Example:Delayingsubmission of ajob from“Ready” time

This example delays submission of job J2 by 5 minutes when it becomesready for submission.

JOB J2 RELDELAY 5

IntroducingAnticipatedEnd Times

When ESP generates an Application, it calculates anticipated end times for alljobs in the Application. ESP adjusts anticipated end times automatically as theApplication processes; for example, when a job is submitted or a job ends.This allows you to review the Application, at any stage, and determine whenany job is expected to finish. This information is displayed to you wheneveryou list the Application (e.g. LISTAPPL command).

IntroducingDueout Times

If a job is not complete by its anticipated end time, ESP continues to adjustthis time. There is no indication that a job has missed its original anticipatedend time. If you need to provide some awareness when jobs are late, you canidentify 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-outtime, the status field shows OVERDUE in the Consolidated Status Facility(CSF) display of the job.

ESP can also send a message or trigger an Event when a job becomes overdueby using a NOTIFY statement. For more information, refer to ProvidingNotification on Job Status later in this chapter.

ESP also provides critical path analysis. For information on using criticalpath, refer to the Using Critical Path Analysis on page 241.


202


Specifying due-out times

You can use any of the following statements to identify dueout times for ajob:

Statement ExplanationLATESUB Specifies a late submission for a job. This identifies a

time by which ESP should submit a job. TheLATESUB time for a link, task or data set trigger objectrepresents the time by which all of its predecessor andtime dependencies should be met (i.e. the READYtime).

LATESUB does not force, or bypass, submission of thejob. Use the ABANDON DEPENDENCIES statementto force submission of the job, regardless ofdependencies; use the ABANDON SUBMISSIONstatement to bypass submission of the job.

DUEOUT INPUT Specifies a due-out time from the INPUT processingnode. This refers to the start time.

DUEOUT EXEC Specifies a due-out time from the EXEC processingnode. This refers to the successful end time. For a link,task, or data set trigger object, this represents the timeby which it should complete.

Statements fordifferent jobtypes

The following table indicates the statements you can use for different jobtypes. For more information on job types, refer to Using Different Job Typeson page 213.

Job Type LATESUB DUEOUTINPUT

DUEOUTEXEC

Job X X XExternal Job X X XManual Job X X XLink X XTask X XData set Trigger Object X X


203


Example:Specifying alate submissiontime for a job

In the following example, Job X has a late submission time of 9 p.m.

JOB X LATESUB 9PM

Example:Specifying adue-out timefor a job

This example specifies that job Z is due out of the execution queue by 3 a.m.

JOB Z DUEOUT EXEC 3AM

Example:Specifying adue-out timefor a task

This example specifies that the task called WAIT4.TAPE should be markedcomplete no later than two hours after the trigger time of the correspondingEvent.

JOB WAIT4.TAPE TASK DUEOUT EXEC REALNOW PLUS 2 HOURS

Propagatingdueout times

ESP propagates dueout times, up-stream, to all predecessors of a selected jobwhere you specified a LATESUB or DUEOUT statement. This reduces theneed for you to code a lot of LATESUB or DUEOUT statements in anApplication. ESP sets these dueout times based on historical average elapsedtimes.

When ESP propagates a time to a predecessor, it sets the DUEOUT EXECtime and adjusts this time if it is already specified. ESP provides notificationwhen this time is not met, just as it does when you specifically code aDUEOUT time. If you need to reset the time, you can use CSF or theAPPLJOB command.

Note:Your system administrator may have turned this propagation feature off.


204


Example:Propagatingdueout times

In the following example, PAYJOB6 should be submitted by 7am.

PAYJOB1

PAYJOB6

PAYJOB5PAYJOB4PAYJOB3

PAYJOB2

By specifying a LATESUB time for PAYJOB6, ESP automatically setsdueout execution times for all predecessors to this job. If any job in thePAYROLL Application is late, ESP highlights it on CSF. Further notificationcan take place using the NOTIFY statement.

A sample Application is:

APPL PAYROLLJCLLIB ’CYBER.JCL.CNTL’JOB PAYJOB1 RELEASE PAYJOB2JOB PAYJOB2 RELEASE (PAYJOB3,PAYJOB4,PAYJOB5)JOB PAYJOB3 RELEASE PAYJOB6JOB PAYJOB4 RELEASE PAYJOB6JOB PAYJOB5 RELEASE PAYJOB6JOB PAYJOB6 LATESUB 7AMENDJOBSELECT (PAYJOB1,PAYJOB2,PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)


205


Bypassing jobdependencies

Use the ABANDON DEPENDENCIES job statement to drop a job’spredecessor dependencies once it meets a specified time. This does notoverride a manual hold, a time dependency, or a resource dependency for ajob.An example of this statement is:

ABANDON DEPENDENCIES 10PM

Bypassing Jobs Use the ABANDON SUBMISSION job statement to bypass a job after aspecified time.An example of this statement is:

ABANDON SUBMISSION 11PM

Example:Bypassing jobsanddependencies

The following example submits Job J2 when Job J1 completes successfully,or at 10 p.m., whichever comes first. When J2 completes successfully, ESPchecks that the time is before 11 p.m. If it is, ESP submits Job J3; otherwise,it bypasses J3 and submits Job J4.

APPL APPL3JCLLIB...JOB J1 RUN DAILY RELEASE J2JOB J2 RUN DAILY ABANDON DEPENDENCIES 10PM RELEASE J3JOB J3 RUN DAILY ABANDON SUBMISSION 11PM RELEASE J4ENDJOB JOB J4 RUN DAILYENDJOB


206


Example:Bypassing a joband wait forpredecessor

Jobs A, B and C are 3 sequential, daily jobs. Job B has a submission time of 9a.m. If job B is not submitted within an hour (10 a.m.), then job B should notrun but job C should wait for job A to complete.

The following part of an Application identifies a delayed submission time of 9a.m., and an abandon submission time of 10 a.m. for job B. Job B’s executionis abandoned if it is not submitted by 10 a.m. Job B is not actually bypasseduntil job A completes successfully and job C waits until this happens.

JOB A RUN DAILY RELEASE BJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AMJOB C RUN DAILYENDJOB


207


Example:Bypassing a jobwithout waitingfor predecessor

Jobs A, B and C are 3 sequential, daily jobs. Job B has a submission time of 9a.m. If job B has not been submitted within an hour (10 a.m.), job C shouldstart (even if job A is running) and job B should not run.

The following part of an Application identifies a delayed submission time of 9a.m. and an abandon submission time of 10AM for job B. Job B waits for jobA to complete successfully prior to being bypassed. By coding an abandondependencies time of just after 10 a.m., job B does not wait for job A tocomplete before it is bypassed and job C starts.

JOB A RUN DAILY RELEASE BJOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AM ABANDON DEPENDENCIES 10:01AMJOB C RUN DAILYENDJOB

Removingresourcedependencies

Use the ABANDON RESOURCES job statement to submit a job without itsresource dependencies, once it meets a specified time. An example of thisstatement is:

ABANDON RESOURCES 8AM

This example indicates ESP should not wait for resources for the job after 6p.m.

JOB PREPJOB RESOURCE (1,NITESHFT) ABANDON RESOURCES 6PM

208

Specifying Job Relationships

Introduction To specify predecessor and successor job relationships, include theappropriate job dependency parameters. A list of job dependency parametersappears below:

JobDependencyParameter

Explanation

AFTER Specifies any job that is a predecessor to this job and shouldindicate a release to this job upon its completion. (Thedefault is successful completion).

RELEASE Specifies successors to a job that are released upon itscompletion. (The default is successful completion).

PREREQ Specifies the names of any other jobs that must be completebefore this job can be allowed to execute. These areprerequisite jobs. ESP automatically selects the prerequisitejobs for submission whenever this job is selected forprocessing.

COREQ Specifies the names of any other jobs which must beselected automatically whenever this job is selected forprocessing. The named job and all of its co-requisites areallowed to execute simultaneously; there is no relationshipbetween a job and its co-requisites.

POSTREQ Specifies the names of any other jobs which must run afterthis job has executed. These are post-requisite jobs. ESPautomatically selects the post-requisite jobs for submissionwhenever this job is selected for processing.


209

Specifying Job Relationships, Continued

SpecifyingMultiple jobs

If you need to specify more than one jobname, enclose the jobnames inparenthesis. For example:

RELEASE (PAYJOB2,PAYJOB3,PAYJOB4)

If you need to continue to another line, use either a ‘+’ or a ‘-‘ as a linecontinuation character. For example:

RELEASE (PAYJOB2,PAYJOB3,PAYJOB4,-PAYJOB5,PAYJOB6)

Two methodsof coding a jobdependencyrelationship

The following are two ways of coding a job dependency relationship. Witheither method, there is no difference in the way ESP generates or processesthe Application.

Method Code1 JOB A

RELEASE B

2 JOB B AFTER A

210

Selecting Jobs for Submission

Selecting a jobfor submission

To select a job for submission you need to 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 sameApplication. This Guide contains more information on the schedulefrequencies 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 selects job A eachtime the Procedure is invoked; ESP selects job B if the scheduled day isFriday.

JOB A RUN DAILY RELEASE BJOB B RUN FRIDAYENDJOB

Example-method 2

This method uses SELECT statements after identifying specific jobrequirements. ESP selects job A each time the Procedure is invoked; ESPselects job B if the scheduled day is Friday.

JOB A RELEASE BJOB BENDJOBSELECT AIF TODAY(‘FRIDAY’) THEN SELECT B

Submit time If a job has a time dependency for submission, you must use either anEARLYSUB or a DELAYSUB statement. The statement ‘RUN 5PM DAILY’is not valid.


211

Selecting Jobs for Submission, Continued

Using SELECTvs. RUNstatements

Some users prefer to use RUN statements; other users prefer SELECTstatements. The following are some reasons for choosing either method:

• RUN statements are used within the scope of a JOB statement. This allowsyou to look at a job definition and see the schedule frequency for the job.Many criteria can be handled with RUN statements without the need forusing “IF TODAY” type logic.

• SELECT statements allow you to easily see all the jobs with the samecriteria. Changing the criteria for these jobs requires a change to a singleSELECT statement. You can also select a subApplication.

Deselectingjobs

Use the NORUN and DESELECT statements to handle exceptions to a job’sregular schedule criteria. These statements tell ESP when not to select a job.ESP allows multiple RUN and NORUN statements for the same job. Youshould normally code your NORUN statements after your RUN statements. Ifyou specify a job with a NORUN statement and without a RUN statement,ESP schedules the job each time the Event executes except when it managesto satisfy the NORUN schedule criteria.

Example 1 In the following example Job X runs daily except on the first Monday of themonth.

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 jobrelationships

Jobs in an Application may not require the same run frequency. When ESPselects jobs for submission, it automatically checks to see if any relationshipsamong jobs should be inherited.


212

Selecting Jobs for Submission, Continued

Example Consider the following three jobs and their schedule frequencies.

J2

J3

J1 Daily

Friday

Daily

On Fridays all three jobs execute in order, but on any other day of the weekJob J2 does not run. On these days, ESP selects Jobs J1 and J3 and inheritstheir relationships with job J2. When job J1 completes successfully it releasesjob J3.


For information on overriding the inheritance of job relationships, refer to theAdvanced User’s Guide.

213

Using Different Job Types

Introduction An Application may consist of different types of jobs. You can define thefollowing job types in an Application by using different keywords on a JOBstatement or different job-like statements.

Type Description IdentificationJob JCL submitted by ESP (default) BlankExternal job JCL submitted by another

ApplicationEXTERNAL keyword

Manual job JCL submitted outside an ESPApplication

MANUAL keyword

Link Task that does not require manualcompletion

LINK keyword

Task Task that requires manualcompletion

TASK keyword

DatasetTriggerObject

Object that completes based on dataset trigger activity

DSTRIG statement

The next few sections describe the job types other than “Job”. You can alsodefine non-MVS workload, such as Unix scripts, in your ESP Application.For information on defining this type of workload, refer to the ESP Agents forUNIX Operating Systems, User Guide.

214

Defining External Jobs

EXTERNALkeyword

Use the EXTERNAL keyword as part of a JOB statement to identify to ESPthat the job is part of another Application. This allows you to establishrelationships between jobs in different Applications. As long as theApplication containing the successor is active at the time the predecessorcompletes 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-Applicationdependency

In this example, ESP submits Job X on Fridays, as part of ApplicationAPPL1. Job Z in the Application APPL2 waits for Job X. The homeApplication for Job X is APPL1; the distant Application for Job X is APPL2.Visually, the dependencies look like this:

A

X

X

Z

APPL1 APPL2

(External job)

(job)(job)

(job)


215

Defining External Jobs, Continued

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 generates APPL2 on Fridays, job Z waits until job X completes inits home Application, APPL1.

ControllingExternal jobs

Under different situations, ESP must decide whether or not it should mark anEXTERNAL job complete. The following are some general rules ESP uses:

• A job defined as EXTERNAL in an Application is normally markedcomplete by ESP if the job is run manually.

• If more than one generation of an Application is active when an Externaljob ends, ESP posts the job as complete in all active Applications.

Some of the ways you can control the posting complete of External jobs aredescribed below.


216


Specifying anApplication

When you define an External job, you can use the APPLID parameter tospecify the name of the Application that submits the job. ESP does not markthe External job complete unless it was submitted by the Applicationspecified. For example, ESP only marks the following job as complete whenthe job is submitted from the Application called ‘ANOTHER’.

JOB ABC EXTERNAL APPLID(ANOTHER)

SCHEDULEDparameter

You can specify a SCHEDULED parameter on a JOB statement to reflectwhen an External job is scheduled. The Application containing the Externaldoes not have to be active when the job in the home Application ends. ESPautomatically looks back to see if the dependency has been satisfied.The job in the example below only gets marked complete when run fromanother Application with the same scheduled date. This providessynchronization of Applications. Refer to the Advanced User’s Guide formore information.

JOB ABC EXTERNAL SCHEDULED(‘TODAY’)

The following example shows specifying a range:

JOB ABC EXTERNAL SCHEDULED(‘NOW LESS 2 HOURS ENDING NOW PLUS 2HOURS’)

Job qualifiers In order for ESP to mark an External job complete, the job qualifier mustmatch what was defined in the home Application. You can use job qualifiersto ensure that an External job does not get marked complete when it is runmanually. You might want to qualify External jobs with the “home”Application name. For example:

JOB ABC.BILLING EXTERNAL

Authorizationstring

You can specify that ESP checks an authorization string for External jobs sothat it tracks and posts the correct job. The authorization string is the field youuse at your site to identify job ownership, such as a userid or an account field.For example, ESP only marks the following job as complete when the job isrun with an authorization string of ‘CYBER’.

JOB ABC EXTERNAL AUTHSTR(CYBER)


217


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 whenmultiple generations of an Application are active. Refer to the AdvancedUser’s Guide for more information.

Forcedcomplete

When an External job is forced complete in a distant application, this willhave no effect on the status of the same job in any other distant application, orin the job’s home application.

When an External job is forced complete in its home application, this changewill be transmitted to every distant application in which the job is defined asexternal.

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 homeApplication has actually been submitted. With release 5.1.0 and 5.2.0, theremote Application job is now marked complete even if the home Applicationjob was forced complete prior to submission. This USERMOD disables thenew functionality, for those users who rely on the previous behavior.

218

Defining Manual Jobs

MANUALkeyword

Use the MANUAL keyword as part of a JOB statement to identify to ESP thata job is submitted outside of an ESP Application. As a result, ESP does notlook for JCL, nor does it try to submit the job. The job may be submitted by aperson, an operator command, an Event, or another scheduling product.

You can use Manual jobs as predecessor or successor jobs within anApplication. As long as the Application containing the successor is active atthe time the predecessor completes successfully, the required dependency issatisfied.

Notes When defining a MANUAL job in an Application, keep the following inmind:

• You must define a manual job as a tracked job if you want to use it in anApplication. Check with your system administrator to find out abouttracked 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 onMondays, Wednesdays, and Fridays. On other days Job ZZ does not wait forJob YY.

JCLLIB...APPL SMALLJOB ZZ AFTER YY RUN DAILYJOB YY MANUAL RUN MON WED FRIENDJOB


219

Defining Manual Jobs, Continued

Example In this example, Job B is a Manual job that should not complete until Job Aruns successfully. After Job A is submitted, ESP has no control over thesubmission time for Job B, since Job B is a manual job. However, ESP canremind someone to submit the job at the time it should be submitted.

Visually, the flow of jobs looks like this:

A

B

C

MANUALLYSUBMITTED

The Application is shown below. The PROCESS keyword on the manual jobcauses ESP to process the SEND command when job B is eligible forsubmission.

JCLLIB...APPL ABCJOB A RELEASE B RUN DAILYJOB B MANUAL PROCESS SEND ‘TIME TO SUBMIT JOB B’ USER(SW) RUN DAILY RELEASE CJOB C RUN DAILYENDJOB


220

Defining Manual Jobs, Continued

ControllingManual jobs

Under different situations, ESP must decide whether or not it should mark aMANUAL job complete. The following are some general rules ESP uses:

• A job defined as MANUAL in an Application is normally markedcomplete if the job is run as part of another Application.

• If more than one generation of an Application is active when a Manual jobends, ESP posts the job as complete in all active Applications.

Some of the ways you can control the posting complete of Manual jobs aredescribed below.

Authorizationstring

You can specify that ESP checks an authorization string for Manual jobs sothat it tracks and posts the correct job. The authorization string is the field youuse at your site to identify job ownership, such as a userid or an account field.For example, ESP only marks the following job as complete when the job isrun 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 whenmultiple generations of an Application are active. Refer to the AdvancedUser’s Guide for more information.

Forcedcomplete

When a Manual job is forced complete in one application, this will have noeffect on Manual jobs in other applications that just happen to refer to thesame physical job instance.

If it is desired to modify the status of a specific manually submitted job inmultiple applications that define this job as Manual, the modification willhave to be performed explicitly in each of the dependent applications.

221

Using Links

Using links A link is a task that does not require manual completion. Use a link when youneed to take an action (for example, issue a command or send a message) butthe Application does not need to wait for you to notify ESP that the action hasbeen completed. A link can also be used as a dependency node to simplifycomplex dependencies.

LINK keyword The LINK keyword on the JOB statement identifies a link. ESP does not tryand submit JCL for it. You define relationships and other dependencies for alink the same way you do for a job that ESP would submit. A link usually hasa 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. Ifyou want to use a link to process commands, you must specify LINKPROCESS, as shown in the next example.

Example In the following example, a link is used to send a message to user BP01 afterMYJOB1 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 automatically marks a link ascomplete 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 needto use a self-completing task.


222

Using Links, Continued

Example:Simplifying jobrelationships

You have an Application that contains two groups of three jobs. The secondgroup of jobs cannot run until all jobs in the first group have completed.

B CA

E FD

To create this dependency configuration without using a link means thatdependencies must be created from all three jobs in the first group to all threejobs in the second group. While ESP can create an Application that includesmany inter-linked dependencies like this, the Application may be hard to readand maintain.Visually, you need to define the dependencies like this:

B CA

E FD


223


Solution A better approach is to create a link that represents the completion of the firstthree jobs, and releases the second group of three jobs. This simplifies thedefinition of job relationships and makes it easier to add or delete jobs in eachgroup.Visually, the dependencies look like this:

B CA

E FD

LINKJOB

One way of coding LINKJOB is shown below:

JOB LINKJOB 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• Notification when something happens• Notification when something does not happen.

The following examples illustrate some typical uses of Links.

Example:Issuing acommand

This example uses a link to start some initiators.

JOB OPEN.INITS LINK PROCESS VS ‘$SI1-10’ RUN DAILYENDJOB


224


Example:Keeping anApplicationactive

This example uses a link called KEEPOPEN to keep an Application activeuntil 23:59. This technique is useful when you need an Application active toinsert on-request jobs.

JOB KEEPOPEN LINK DELAYSUB 23:59 RUN DAILYENDJOB

Example:Notificationwhen anApplicationcompletes

This example sends a message at the end of an Application. The messageincludes 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, refer to the Advanced User’sGuide.


225


Example:Starting a task,taking actionaftercompletion

You may have a started task that you wish ESP to start, monitor, and then runa job when it comes down. This example shows how you can set up thesedependencies.

Visually the dependencies look like this:

STC1

BATCHJOB

START.STC1(Link)

(Manual)

(Job)

Setting-up thisApplication

To set up this Application:

• Use a link to start the started task• Identify the started task as a Manual job (because the task is started by an

operator command)• Run a job when the Manual job ends successfully.


226


Application The Application looks like this:

APPL MYAPPLJCLLIB ‘SYS1.JCL’JOB START.STC1 LINK PROCESS RUN DAILY VS ‘S STC1’ENDJOBJOB STC1 MANUAL RUN DAILY RELEASE BATCHJOBENDJOBJOB BATCHJOB RUN DAILYENDJOB

227

Using Tasks

IdentifyingTasks

You can define tasks in an Application and establish dependencies betweenthem and other tasks and jobs. A task may represent a manual process such asbalancing a report, or an automated process such as a step in a job completing.

You identify a task using the TASK keyword on a JOB statement. ESP doesnot try and submit JCL for it. You define relationships and other dependenciesfor a task the same way you do for a job that ESP would submit. A taskusually has a schedule frequency and may have a time dependency. It can beon-request, conditional, defined on hold, and can be inserted into an activeApplication.

When you mark a job as a TASK and select it for execution, ESP builds it aspart of the Application. The AJ command, or the C command from CSF, canbe used to mark a task complete.

Example:Checking areport

In this example, a report needs to be checked on workdays after Job J1completes successfully.Visually, the dependencies look like this:

CHECKRPT.J

J2

J1(Job)

(Task)

(Job)


228

Using Tasks, Continued

IdentifyingCHECKRPT.Jas a TASK

The following Application identifies CHECKRPT.J1 as a TASK. When J1completes successfully on a workday, ESP issues the SEND command to userBP01, indicating the actions to be taken. ESP submits Job J2 only whenCHECKRPT.J1 is marked complete. On non-workdays, J2 inherits therelationship with J1, and ESP submits J2 after J1 completes successfully.

JCLLIB ’CYBB.JOBS.CNTL’APPL ABC WAITJOB J1RUN DAILYRELEASE CHECKRPT.J

ENDJOBJOB CHECKRPT.J TASKRUN WORKDAYSSEND ’JOB J1 HAS COMPLETED SUCCESSFULLY ’ USER(BP01)SEND ’COMPLETE THE CHECKRPT.J TASK’ USER(BP01)RELEASE J2

ENDJOBJOB J2 RUN DAILYENDJOB

Uses for tasks You may choose to use tasks for:

• Balancing reports• Input tapes• Step-level dependencies• Any other special handling jobs.


For more examples of using tasks, refer to the Advanced User’s Guide.

229

Changing Job Attributes

Introduction In ESP, you can define a job with a number of different attributes usingdifferent keywords on the JOB statement. Some examples of attributes areCRITICAL, HOLD, REQUEST, CONDITIONAL, LINK, and MANUAL.A job may have different attributes based on different criteria. For example,you may wish to define a job on hold but only for a particular date. This jobhas different attributes based on schedule criteria.

Defining a jobwith differentattributes

To define a job with different attributes, use the JOBATTR statement. Thisstatement lets you change any attributes of a job within the scope of the JOBstatement or in job documentation. Attributes include the keywords you canuse on the JOB statement.

Example -Changing a jobattribute

In the following example, Job ABC runs daily. On December 9, 1998, it needsto be defined on hold.

JOB ABC RUN DAILY IF TODAY(’DEC9,1998’) THEN JOBATTR HOLDENDJOB


For more examples of changing job attributes, refer to the Advanced User’sGuide.

230

Using Data Set Trigger Workload Objects

Introduction You can use ESP’s data set triggering facility at the Event level or at the joblevel. This section describes how to use this facility at the job level. Forinformation on using data set triggering at the Event level, refer to ProcessingESP Events on page 61.

Data set triggerworkloadobject

You can define a data set trigger workload object as part of an ESPApplication. This allows you to set up data set dependencies at the job level.A data set trigger workload object can be completed by the successfulcreation, closure, or renaming of a data set by another job, by a started task, orby a TSO user. This activity can be restricted to data sets created by a specificjob or group of jobnames.


The next sections describe how to set up data set trigger objects. For moreexamples using these objects, and for other techniques on handling data setdependencies, refer to the Advanced User’s Guide.

Preparing touse data settrigger objects

In order to use a data set trigger object, the Systems Programmer responsiblefor ESP must add a Workload Object Module (WOBDEF) statement to theESP Initialization Parameters (i.e. WOBDEF LOAD CYBESODT).


231

Using Data Set Trigger Workload Objects, Continued

Setting-up dataset triggerobjects

To set up a data set trigger object in an Application:

Step Action1 Use the DSTRIG statement to assign a name to the data set trigger

workload object. You can use some of the same keywords you useon a JOB statement. These include REQUEST, HOLD andCONDITIONAL.

2 Use the DSNAME statement to identify the name of the data set.Quotation marks are optional. You can use a hyphen at the end ofthe data set name as a wildcard and you can use keywords such asCOUNT, ANYCLOSE, JOBNAME, and RENAME to handledifferent requirements. Only one DSNAME statement is supportedper workload object.

3 Use a RUN or SELECT statement to identify when you want thisobject to build as part of the Application.

4 Use other statements, such as DELAYSUB, DUEOUT,RELEASE, etc. to identify other requirements.

Example:Waiting for adata setcreation

In this example:

• The DSTRIG statement identifies a data set trigger object calledBIGFILE.

• The DSNAME statement identifies PROD.CICS.FILE1602 as the data set.Because no other parameters are specified, ESP waits for this data set tobe 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 watches for thePROD.CICS.FILE1602 data set to be created. When it is created, theBIGFILE object completes and releases the successor job ABCJOB.


232


Visualperspective

Visually, the flow looks like this:

ABCJOB(Job)

PROD.CICS.FILE1602(data set)

Waiting for anyclosure of adata set

You can use the ANYCLOSE keyword to indicate any closure of a data set.This includes the creation of a new data set and the updating of an existingdata set. If you do not specify ANYCLOSE, ESP waits for the data set to becreated.

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 PAYJOB1JOB PAYJOB1 RUN DAILYENDJOB

Limiting dataset activity to ajob

You can restrict the trigger to only specific data sets created by a particularjob. Use the JOB keyword followed by the full name or jobname prefix of thejob.

Example: Jobspecificcreation

The following example indicates a data set trigger occurs when job ABCcreates a generation of the data set ‘USER1.PAYROLL’.

DSTRIG USERDATA DSNAME ‘USER1.PAYROLL.G-’ JOB(ABC)


233


Waiting onmultiple datasets

To set up a dependency on multiple data sets, you need to use a separate dataset trigger object for each.

Example:Waiting onmore than onedata set

In this example, job XYZ waits for two data set trigger objects, FILEA andFILEB.

• 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 XYZDSTRIG FILEB DSNAME CYBER.DATA999.CNTL ANYCLOSE RUN DAILY RELEASE XYZJOB XYZ RUN DAILYENDJOB

Waiting onmultipleclosures of thesame data set

It is possible for a data set to be closed several times. You can use theCOUNT keyword to specify how often this closure is required before the dataset trigger object completes. The count begins when the data set trigger objectbecomes ready (i.e. any time and predecessor dependencies have been met).The CSF STATUS field displays the counter and its current value once thedata set trigger object becomes ready.

With each closure, ESP increases its internal counter by one. When thecounter reaches the number you set in your COUNT keyword, ESP completesthe data set trigger object. The next time the Application gets generated, thecount is set to zero.


234


Example:Waiting onmultipleclosures of adata set

In the following example, the data set trigger object completes after twocreations of a data set:

DSTRIG DOUBLE.INPUT DSNAME ‘SITE1.BILLING.FILE’ COUNT(2)

Controllingdata set triggerobjects

A data set trigger object must be “ready” before ESP looks for the activityspecified on the DSNAME statement. It is possible for a data set triggerobject to 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 takeagainst it is complete it.

Example: Dataset trigger has adependency

In the following example, the data set trigger object INPUT.DATA has adelayed submission time of 6 p.m. If the CYBER.BILLING data set is createdprior to this time, the data set trigger object does not complete. At 6 p.m., ESPsends 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


235


Displaying dataset triggeringinformation

While DSTRIG workload objects are active, you can use the LDXE commandto display them. The LDXE command differentiates between Event level andApplication 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 calledWAIT4.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

236

Tagging Jobs

TAG statement You can use the TAG statement to “tag” jobs in an Application with acharacter string up to 16 characters in length. The “tag” can apply to all jobsin an Application or to individual jobs depending on where you place it. Youmay want to 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 jobswith thescheduled dayof week

The following example uses a symbolic variable to tag all jobs in anApplication with the 3-character day of the week:

TAG ‘%ESPSDAY(1:3)’APPL BILLING

Example:Tagging highpriority jobs

This example tags PAYJOB as a high priority job:

JOB PAYJOB TAG ‘HIGH_PRIORITY’

Example:Tagging jobswithApplicationname

This example uses the TAG statement to specify the name of the Applicationthat submits the job. This is useful when you have an Application containingExternal 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.


237

Tagging Jobs, Continued

SampleApplication

A sample Application looks like this:

APPL PAYROLLJCLLIB . . .TAG ‘PAYROLL’JOB A RUN DAILY RELEASE BJOB B RUN DAILY RELEASE CJOB C RUN DAILY AFTER XJOB X EXTERNAL TAG ‘BILLING’ RUN DAILYENDJOB

238

Providing Notification on Job Status

Introduction You can use the NOTIFY statement within an Application to keep yourself orother users informed about the progress of jobs in an ESP Application. TheNOTIFY statement can inform you when:

• A job is submitted• A job starts• A job becomes overdue from different processing points• A job ends abnormally (ABENDs)• A job fails (for example, condition code failures)• A job ends (successfully or unsuccessfully)• ESP resubmits a job.

Using this statement, the only type of notification you can receive for Externaljobs, Manual jobs, data set trigger objects, links, and tasks are overdue. Thisis based on the LATESUB and DUEOUT statements.

Example:Notification onsubmit andabend

For example, suppose that you know that a programmer has modified the JCLfor Job D and you want to find out:

• When ESP submits the job• If the job ABENDs.

In this example, the NOTIFY statement tells ESP to notify user USER01 (you)when ESP submits Job D, and if Job D ABENDs.

JOB D NOTIFY SUBMIT ABEND USERS(USER01) RELEASE E RUN DAILYENDJOB

Example:Overduenotification

This example notifies user USER02 when job LONGJOB becomes overdue.ESP sends a message to USER02 if LONGJOB does not complete executionsuccessfully by 5 a.m.

JOB LONGJOB NOTIFY OVERDUE USER(USER02) DUEOUT EXEC 5AM RUN DAILYENDJOB

239


240

Providing Notification on Job Status, Continued


The NOTIFY statement can notify users and trigger an Event.For information on triggering an Event, refer to Chapter 3, Job Monitoringand Alert Processing, in the Advanced User’s Guide.

241

Using Critical Path Analysis

Introduction Critical path analysis, combined with the ability to set time dependencies andtrigger Events automatically, provides the framework for advanced due outnotification when mission critical workload does not complete within thedesignated time frame or window.

ESP allows you to identify a job within an Application that represents acritical point of that Application. The longest path to that job, based onhistorical execution time, is a critical path.

Example of acritical path

In the following diagram, job ’Z’ is identified as the critical point in anApplication. The longest path to job ’Z’, based on historical execution time,represents the critical path. If all jobs are selected, the critical path consists ofjobs A, B, X, Y and Z.

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


242

Using Critical Path Analysis, Continued

Example of acritical path(Cont'd.)

ESP determines the critical path when it generates an Application. The criticalpath for an Application may vary depending on which jobs are selected. Basedon the previous example, the critical path may 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

Preparing touse criticalpath

Prior to using critical path, check with your system administrator to ensure thecritical path feature is enabled. Through the CRITPATH ESP InitializationParameter or command, an installation can disable critical path analysis for allApplications, enable critical path analysis for selected Applications, or turn oncritical path analysis for all Applications.

To use the critical path feature:

Step Action1 Turn on critical path analysis for an Application.2 Identify one or more critical jobs.

TurningOn/Off criticalpath for anApplication

To turn on critical path analysis for an Application, use the CRITPATH ONstatement as a global statement before your job definitions. For example,

APPL BILLINGJCLLIB ‘CYBER.JCL’CRITPATH ONJOB A...


243


Critical pathanalysis for allApplications

Some installations may turn on critical path analysis for all Applications usingan ESP Initialization Parameter or command. If critical path analysis is on forall Applications:

• You do not need the CRITPATH ON statement to use critical path analysisfor an Application.

• You must use the CRITPATH OFF statement as a global statement, toturn off critical path analysis for an Application.

Identifyingcritical jobs

Use the CRITICAL keyword on a job that represents a critical point in theApplication, as follows:

JOB Z CRITICAL

If critical path analysis is turned on for an Application, but no selected jobsare coded with the CRITICAL keyword, ESP calculates the path to the job thatwill finish last and identifies that path as the critical path.

External jobson critical path

Jobs defined as External jobs in an Application may be part of the criticalpath. However, if those external jobs have predecessors, the predecessors inthe home Application are not defined as part of the critical path.


244


Multiplecritical paths

An Application may have more than one critical path. In the followingdiagram, four jobs (represented by grayed boxes) are critical jobs. The longestpaths to each of these jobs, based on historical execution time, are identifiedas critical paths.

A

L

PO

K

F

G IH

EB C D

V

TS

U

R

N Q

M

J

Overridingelapsed times

There may 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 may runlonger than normal. Or maybe there is no historical information for a job onthe critical path, because this is the first run of the job. In these situations, youcan override historical elapsed time defaults using the DURATION statementto 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


245


Displaying thecritical path

After ESP generates an Application, you can display the critical path usingCSF freeform filtering or the List Application (LAP) command.

Using theconsolidatedstatus facility

You can use CSF’s freeform filtering feature to filter jobs in an Applicationthat 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 thePAYROLL Application.

CRITICAL_PATH AND APPL EQ ’PAYROLL’


For more information on freeform filtering, refer to the Consolidated StatusFacility on page 258.

Using the listApplicationcommand

The LISTAPPL (LAP) command displays information about yourApplication. All jobs on the critical path are identified with a label of‘CRITICAL PATH’. Any job in the Application coded with the ’CRITICAL’keyword is identified with a label of ’CRITICAL’. You can limit your displayto jobs on the critical path, or jobs not on the critical path.

The following LAP command uses the CRITPATH keyword to display onlythose jobs on the critical path for the current generation of the PAYROLLApplication:

LAP PAYROLL.0 ALL CRITPATH

246

Issuing ESP Commands

Introduction As part of an Application you may want to issue ESP commands. This isuseful, for example, when you want to issue commands to manipulate jobs,trigger Events, and perform displays. Use the ESP or ESPNOMSG statementin an Application to issue an ESP command. ESPNOMSG suppressesresponses from the command.

Example:Triggering anEvent

This example uses a link called MORE.WORK. It issues an ESP command totrigger an Event called CYB.OTHER in addition to its regular schedule. ESPsuppresses the response ( i.e. EVENT TRIGGERED) from the triggercommand.

JOB MORE.WORK LINK PROCESS RUN ANY ESPNOMSG TRIGGER CYB.OTHER ADDENDJOB

Example:Creating anEvent,triggering anEvent

This example issues a series of ESP 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

247

Using subApplications

Introduction An Application can consist of one or more subApplications. This is useful, forexample, when you have a large Application you would like to break up intosmaller, easier to manage, groups of jobs. You can display, manipulate, andreport on subApplications. This lets you control a group of jobs belonging tothe same subApplication by using a single command. Use CSF or theLISTAPPL (LAP) and APPLJOB (AJ) commands to display and controlsubApplications respectively.

Identifying asubApplication

Use the SUBAPPL statement in an Application to identify a subApplicationand choose a name different from any jobname in the Application. You canuse the SUBAPPL statement within the scope of a JOB statement to associatea job with a subApplication, or outside the scope of a JOB statement to applyto multiple jobs. Use the WAIT keyword if you have not used it on the APPLstatement and you want a subApplication to wait on the previous generationof the subApplication.


248

Using subApplications, Continued

Example The following example shows two subApplications defined within theApplication 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 NIGHTLYsubApplication must wait until the previous generation of thecorresponding subApplication completes execution.

APPL ACJOBSSUBAPPL PREPJOBSJOB CYB1 RELEASE CYB3ENDJOBJOB CYB2 RELEASE CYB3ENDJOBSUBAPPL NIGHTLY WAITJOB CYB3 RELEASE CYB4ENDJOBJOB CYB4ENDJOBSELECT (CYB1,CYB2,CYB3,CYB4)


249


Selecting asubApplication

If your jobs within a subApplication have the same frequency, you maychoose 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 SELECTstatement that specifies the name of each job.

To select a subApplication, use the SELECT statement to specify one or moresubApplication names, followed by the keyword SUBAPPL. In the followingexample, 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 asubApplication.

Displaying asubApplication

Use the LS command from CSF or use the LISTAPPL (LAP) command withthe SUBAPPL parameter to display subApplications. For example, thefollowing results in a structured view of the subApplication PREPJOBSwithin the Application called ACJOBS.

LAP ACJOBS SUBAPPL(PREPJOBS) ALL


250


Controlling asubApplication

You can use either CSF or different keywords on the APPLJOB command tocontrol subApplications similar to the way in which you control jobs. Youcan:

• Bypass or un-bypass a subApplication• Ready a subApplication• Request or un-request a subApplication• Hold or release a subApplication• Complete a subApplication• Un-wait a subApplication.

Example:Requesting asubApplication

In the example below, ESP requests, the subApplication called REQJOBS inthe Application MYAPPL. The system requests each “selected” job marked asREQUEST in this subApplication. This eliminates the need to request eachjob individually.

AJ REQJOBS REQUEST APPL(MYAPPL.0)

Note:“Requesting” a subApplication is not the same as “selecting” each job in thesubApplication.

251

Working with Applications

Introduction Once ESP generates an Application, you can display and control jobs,subApplications, and the Application itself. You can perform any of thesetasks using:

• Commands in page mode, a batch job , or an ESP Procedure• The Consolidated Status Facility (CSF)• ESP Workstation• Option A.2, the Application Status panel.

This section describes the common commands that are available.


For more information on CSF, refer to Consolidated Status Facility on page258. For more information on Workstation, refer to the ESP WorkstationUser’s Guide.

252

Displaying an Application

Introduction After you generate an Application, use the LISTAPPL command to display it.The short form of the command is LAP. Use the command with the ALLkeyword to give a structured view of an active Application or with otherkeywords to give a summary of active or completed Applications. You canlimit the display to specific generations of an Application and to specific jobswithin an Application.

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 11TH, 1998 BY EVENT CYBBP01.PAY PAYD001A J6281, COMPLETED, CC 0 PAYD002A J6282, COMPLETED, CC 8 PAYD003A J6283, STARTED, STEP 3 PAYD004A, HC=1 SUBMISSION AT 10.15 ON MONDAY MAY 11TH, 1998 ANTICIPATED END TIME: 10.20 ON MONDAY MAY 11TH, 1998 PREDECESSORS: PAYD003A SUCCESSORS: PAYD100A PAYD100A, HC=1 ANTICIPATED END TIME: 10.29 ON MONDAY MAY 11TH, 1998 DUE OUT BY 10.30 ON MONDAY MAY 11TH, 1998 PREDECESSORS: PAYD004A SUCCESSORS: PAYD006A ABCJOB, HC=0 ANTICIPATED END TIME: 10.59 ON MONDAY MAY 11TH, 1998 EXTERNAL PREDECESSORS: NONE SUCCESSORS: PAYD006A PAYD006A, HC=2 ANTICIPATED END TIME: 11.12 ON MONDAY MAY 11TH, 1998 PREDECESSORS: PAYD100A, ABCJOB SUCCESSORS: ENDAPPL RESOURCES: 1,CICSUP ENDAPPL, HC=1 ANTICIPATED END TIME: 11.29 ON MONDAY MAY 11TH, 1998 PREDECESSORS: PAYD006A SUCCESSORS: (NONE)

----- 1 ENTRY DISPLAYED


253

Displaying an Application, Continued

Other Other options are available on the LISTAPPL command. For example, youcan display particular jobs, a previous generation of an Application, or asubApplication.

254

Controlling an Application

APPLJOBcommand

The APPLJOB command controls jobs, subApplications, and Applications.The short form of this command name is AJ.

Options onAPPLJOBcommand

There are many different options available on this command. Some of theseoptions 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 currentgeneration (.0) of an Application called PAYROLL.

Example:Requesting ajob

This example requests MYJOB.

AJ MYJOB REQUEST APPL(PAYROLL.0)

Example:Bypassing a job

This example bypasses PAYJOB3. ESP bypasses the job at the time it wouldnormally submit it.

AJ PAYJOB3 BYPASS APPL(PAYROLL.0)

Example:Inserting a linkto add a jobrelationship

This example inserts a link called LINKME. It has a predecessor ofPAYJOB1 and a successor of PAYJOB2, which means that PAYJOB1 mustcomplete successfully prior to submitting PAYJOB2.

AJ LINKME INSERT PRED(PAYJOB1) SUCC(PAYJOB2) -ATTRIBUTES(LINK) APPL(PAYROLL.0)


255

Controlling an Application, Continued

Example:Completing anApplication

This example completes the entire Application.

AJ ALL COMPLETE APPL(PAYROLL.0)

You will likely use the Consolidated Status Facility to perform many of thesetasks. More information on controlling jobs, subApplications andApplications, see the Consolidated Status Facility section, in this guide.

256

Changing an Application Definition

Introduction ESP does not submit a job to JES until all of its dependencies have been met.This allows you to make changes to the ESP Procedure where the Applicationdefinition resides while the Application is processing. Some changes youmake take effect immediately (i.e. next job submission); others do not takeeffect until the next time the Application is created.

Changes thattake effectimmediately

You can make changes to any of the following commands and statementslisted below. Global changes, outside the scope of any JOB statements, applyto all subsequent submissions. Job specific changes, within the scope of aJOB statement, apply to the next submission of that job.

CCFAIL, CCCHK, NOTIFY, MEMBER, DATASET COPYJCL, DOCMEM,MODEL, PNODES, MONITOR, TEMPLIB, JCLLIB, DOCLIB, ESP, VS,SEND, SUBMIT, INVOKE commands and statements.

Changes thatdo not takeeffect until nextgeneration

You can drop dependencies and change time dependencies for an activeApplication through CSF. However, any of the changes listed below to thecoded Application definition do not take effect until the next generation.

• Job relationships (AFTER, RELEASE, POSTREQ, PREREQ, COREQ)

• Time dependencies - ABANDON SUBMISSION, RELDELAY,RELCOUNT, DUEOUT, LATESUB, ABANDON DEPENDENCIES,ABANDON RESOURCES, DELAYSUB/EARLYSUB

• Schedule criteria (e.g. RUN/NORUN, SELECT/DESELECT statements)

• RESOURCE, TAG, APPL, SUBAPPL, JOBATTR, DURATION,CRITPATH

• JOB statement keywords (e.g. MANUAL, EXTERNAL, TASK, LINK,REQUEST, CONDITIONAL, CRITICAL).

If you need to make temporary, one-time changes, such as inserting orbypassing a job, use the Consolidated Status Facility, or the AJ command.

257

Invoking an ESP Application

Invoking via anESP Event

Use an ESP Event to invoke an ESP Application. The trigger for the Eventcan 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 processone Application per Event.Normally, you should not change an Event to invoke another Applicationwhile it is still processing an active Application.

Example: AnEvent invokesan ESPprocedure tocreate anApplication

The following example demonstrates how to use an Event to invoke an ESPApplication.

The Event below runs each weekday at 4 p.m. It invokes an ESP Procedurethat defines the Application and job relationships. The Event looks like this:

EVENT ID(PROD.PAYDAILY)SCHEDULE 4PM WEEKDAYSINVOKE ‘CYBER.ESP.PROC(PAYDAILY)’ENDDEF

258

Consolidated Status Facility

Overview

Introduction The Consolidated Status Facility provides a focal point for monitoring andcontrolling the workload. You will see which jobs have recently executed, arecurrently running and are scheduled to execute. You can “zoom” in on any jobto get greater detail, edit JCL, and restart jobs.Note: You can use CSF for jobs in an Application, but not for jobs submitteddirectly from an Event.


Topic See PageSetting up CSF Views 259CSF Fields 260Defining a View 264Customizing a View 265Updating a View 269Deleting a View 270Selecting Views 271Working with CSF 272Commands 273Inserting a Job 276Resubmitting a Job 277Removing Job Dependencies 278Resetting a Time Dependency 279Bypassing and Completing Jobs 280Adding Job Dependencies 281Adding a Job with a Time Dependency 282Adding a Job Relationship in an Application 283Adding a LINK Process 284Setting and Resetting the User Status Field 285Using Other Commands 286Extensions to CSF 287Freeform Filtering 288Specifying Boolean Operators 294

259

Setting up CSF Views

Introduction ESP may handle a large workload at your installation. Different people areinterested in different aspects of this workload. One person may be interestedin a particular Application, whereas someone else may only be interested injobs that have failed regardless of the Application to which they belong.

Displaying data Using the Consolidated Status Facility, you can display only relevant data inthe format you want. You do this using views. A “view” is a customized wayof looking at ESP’s 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 someattribute of the job, such as the job name, Application generation number,PNODE (processing node), job number, and status. An example of what theCSF might look like is shown below. Here the CSF presents the current statusof an Application:

260

CSF Fields

Introduction This section describes some special fields that CSF uses.

PNODE Fields A job in an Application goes through different stages in processing. Thesestages are known as PNODES. Using CSF you can filter and sort your viewby PNODE, and display PNODE information.The following table describes the PNODE fields:

PNODE DescriptionAPPLHOLD Application holdAPPLWAIT Application waiting on previous

generationBYPASSED BypassedCOMPLETE Completed successfullyEXEC ExecutingEXTERNAL External job submitted by another

ApplicationFAIL Completed unsuccessfullyINPUT Input queue - JES number assignedJANCWAIT Job ancestor waitMANHOLD Manual holdMANSUB Manual submissionPREDWAIT Predecessor waitREADY EligibleRESWAIT Resource waitSANCWAIT SubApplication ancestor waitSUBDELAY Submission delayedSUBERROR Submission errorSYSERROR System errorTASK Task requiring completionWAITING Delayed submission time

Note:The term PNODE is also used to describe the phases through which ESPtracks a job. The PNODES described here apply only to jobs in an ESPApplication and do not include post-execution phases.


261

CSF Fields, Continued

SUBDELAYPNODE

The following table provides more information on what you might see in theStatus field if a job is in the SUBDELAY PNODE.

PNODE Status DescriptionSUBDELAY Submit delayed by

REEXEC nThe submission of the job hasbeen delayed.

SUBDELAY Submit delayed, Eventsetclosed

The Eventset in which theEvent is stored is currentlyclosed. As soon as it isopened, the Event will bescheduled.

SUBDELAY Submit Delay, DSContention

The execution of the Eventwas delayed due to data setcontention. It will be retried at5 minute intervals.

SUBDELAY Submit Delay, DS Offline The execution of the Eventwas delayed due to a data setbeing offline. It will be retriedat 5 minute intervals.

SUBDELAY Submit Delay, DSRecalled

The execution of the Eventwas delayed due to a data setthat was in a migrated state. Arecall has been requested, andthe Event will be retried at 5minute intervals.


262


SUBERRORPNODE

This table provides more information on what you might see in the Statusfield if a job is in the SUBERROR PNODE.

PNODE Status Description

SUBERROR Submit Eventset I/O error An I/O error has occurred inthe Eventset. The Eventcannot be processed.

SUBERROR Submit error, Event notfound

The Event needed by theApplication has been deleted.It will need to be redefined.

SUBERROR Submit error, Group notdefined

The ESP Group definition forthe Event has been deleted. Itwill need to be redefined.

SUBERROR Submit error, Applfile notfound

The APPLFILE in which theAPPL resides could not befound.

SUBERROR Submit error, Applfile I/O An I/O error occurred whilereading the ATR (ApplicationTracking Record) from theAPPLFILE.

SUBERROR Submit Failed, Event error An error occurred processingthe Event. This wouldnormally be due to a syntaxerror in the ESP Procedure.An error message would havebeen sent to the Event’sowner. This may also occurwhen the master ESP comesdown while trying to submit ajob.

SUBERROR Submit error, Invalid Jobname

ESP encountered an invalidjobname

SUBERROR Submit Error, JCLmissing

The JCL for the job to besubmitted was not found inthe specified data set, or adata set was not specified forthe job.


263


SUBERROR PNODE (continued)

PNODE Status Description

SUBERROR Submit Error, Membermissing

The PDS member in which aJOB’s JCL resides was notfound.

SUBERROR Re-execution countexhausted

The maximum re-executioncount has been reached

SUBERROR Submit error, Quit QUIT statement encountered

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

Status Field DescriptionUser Status Displays information set by the user.

System Status Displays the system state of a workload object. This isthe system state that ESP continues to change during jobprocessing. You cannot change the values in this field.

Status Displays the user status, if set. If the user status is set tonull, it displays the system status.

Setting the UserStatus field

You can set the User Status field when you use either of the following:

• HR command - hold 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 notifyothers of the reason for this action. The User Status field for a job might looklike this:

JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY

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

264

Defining a View

Introduction The process of defining a view involves replicating an existing view andcustomizing the new view to your requirements.

Define a View To define a view, take the following steps:

Step Action1 Select option C from the ESP Main Menu to access CSF.2 Type V at the Command Line. ESP 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 anew name. ESP takes you to the Replicate View panel.

4 Type the name, an applicable description, and the message youwant displayed when there are no items matching the view criteria.The view you selected appears, showing all the jobs that fall withinthat view definition.

5 Customize the view as described in the next section

Storing views ESP stores your view definitions in the ESPCSFA member of your ISPFprofile data set. This allows you to use the same view on different systems.

265

Customizing a View

Introduction Once you select a view, you can customize the information presented. Someexamples of types of views are:

• Application specific• Exception monitoring. For example, you may wish to 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 thecharacteristics of a view:

Command Characteristic FI Filter information PR Presentation information PT Presentation titles PL Presentation lengths SO Sort the information presented CO Define color options based on job status. You can use

colors to distinguish workload states.

The following sections describe each of these areas.


266

Customizing a View, Continued

Filteringinformation

When you filter information, you are describing the criteria for displaying ajob as part of a view. For example, you can filter by Application name toselect only those jobs in a particular Application. This information defines therows in your display.

To filter information, type FI on the CSF Command Line. This takes you tothe Filter Specification panel where you can adjust which characteristics ofyour jobs ESP filters into the display. You can filter based on differentconditions (e.g. failed jobs) and based on other criteria such as jobname,Application name, and tag.

Example For example, to see all incomplete jobs:Type N in the Completed ==> field.

Or to see all incomplete jobs in Application Payroll:Type N in the Completed ==> field and PAYROLL in the Appl ==> field.

Note:Extensive help facilities are available with pop-up menus and hypertext links.Use your HELP key for additional information.

FreeformFiltering

Freeform filtering is an extension to the CSF filtering capabilities that allowsyou a more versatile and customizable method of filtering your ESPApplications. If you cannot use the standard filter panel for your requirements,refer to the Freeform Filtering section on page 288 for information on usingthis feature.


267


Presentinginformation

Once you have filtered the information you want, you can specify theattributes of the filtered jobs you want presented. For example, you may wantto see the job number, PNODE (processing node), and status information foreach 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 anyPresentation command from CSF.

To present information, type PR on the CSF Command Line. This takes youto the Presentation Fields panel. On this panel, indicate which fields you wantdisplayed by entering a number or letter beside each desired field. Thenumbers and letters also represent the order you want them to appear acrossthe screen. You can alter the presentation order easily by using numeric andalphabetic characters.

Example The following example positions the “Appl Generation” column between the“Application” and “Completion Code” columns.

Appl Generation ! 2AApplication ! 2Completion Code ! 3

Note:ESP always lists the job name in the first column; you cannot change this.To further define the presentation information, you can change the presentationcolumn lengths and titles.

Presentationtitles

The PT command takes you to the Presentation Fields panel. On this panel,you can define the titles that ESP presents for each of the fields listed. This isuseful for long titles you want to abbreviate. For example, you may want toshorten 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 youcould change the TAG title to reflect how you are using tags in an Application.


268


Presentationcolumn length

The PL command takes you to the Presentation Fields panel. On this panelESP lists all the columns used in the CSF view. You can override the defaultdisplay length of these columns by entering the number of characters you wantin the display.

Sortinginformation

Sorting information defines the order in which ESP presents the rows ofinformation. To define your sorting requirements, type SO on the CSFCommand Line. The Presentation Fields panel lets you identify the fields bywhich you want to sort your view, and the order in which you want ESP to sortthem. You can select one or more fields to sort on by typing a 1 or 2 characterstring next to the field. The strings are sorted in normal collating sequence (i.e.blank before letters before numbers) to determine the sort order of thedisplayed data.Note: If a field contains multiple words (e.g. STATUS field), the sort occursonly on the first word.

Sort Sequence A “Sort Sequence” field allows you to specify an ascending or descendingsort sequence for a field. Specify an ’A’, or leave the field blank, for ascendingorder; specify a ’D’ for descending order.

Color options Color screens allow you to use different colors and highlighting options toindicate job status. You may choose different colored and highlighted optionsto represent different job status conditions, including:

• Submitted• Overdue• Task awaiting post• Executing• Failed.

Selecting colors To select color options, follow the steps below:

Step Action1 Type CO on the COMMAND line.2 Complete the fields as required.

269

Updating a View

Introduction You can update a view at any time by selecting the different options forcustomization, such as FI, PR and SO.

Update a view To update a view, follow the steps below:

Step Action1 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 viewcriteria in the respective fields.

3 Press Enter. ESP returns you to the View Definitions panel.

270

Deleting a View

Introduction You can delete an existing view at any time.

Delete a view To delete an existing view, follow the steps below:

Step Action1 Enter D to the left of the view name you want to delete.2 Press Enter. ESP removes the View from the View Definitions

panel.

271

Selecting Views

Methodsemployed

There are two methods for selecting a view.

Method 1 If you do not know the name of the view you want to select, follow thesesteps:

Step Action1 Type V on the COMMAND line of the Consolidated Status View

panel. ESP presents you with a list of Views.2 From the list of views, type S beside the View you wish to select.

Method 2 If you know the name of the view you want to select, type “V viewname” onthe COMMAND line.

272

Working with CSF

Introduction This section describes the generally available commands and procedures youcan use to work with the Consolidated Status Facility.

273

Commands

Introduction When ESP displays a view, it precedes each jobname with an entry field. Thecodes below represent commands that are valid in CSF. To use one of thesecommands, type the letter code in the entry field preceding the jobname youwant to manipulate. ESP issues the appropriate command (e.g. LISTAPPL,APPLJOB, etc.) in the background.

The next sections list the available commands in different categories.

Working withApplications

The following table lists the available commands for working withApplications.

Command DescriptionAA Release an Application held by ESPCA Complete an entire ApplicationHA Place Application into ESP hold statusLA List ApplicationLAD Dump Application dataUWA Remove Application from wait status

Working withsubApplications

The following table lists the available commands for working withsubApplications.

Command DescriptionAS Release a subApplication held by ESPBYS Bypass a subApplicationCS Complete an entire subApplicationHS Place subApplication into ESP hold statusLS List subApplicationRDS Ready a subApplicationRQS Request a subApplicationUBS Un-bypass a subApplicationURS Un-request a subApplicationUWS Remove subApplication from wait status


274

Commands, Continued

Working withjobs

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

Command DescriptionA Release a job held by ESPBC Browse COPYJCLBJ Browse last executed JCLBY Bypass a jobC Complete a job and reduce hold count of successorsDD Drop all job predecessor dependenciesDIN Display Info/System recordDR Drop all resource dependenciesEC Edit COPYJCLEJ Edit last executed JCLH Place a job into ESP hold statusHR Place a job into ESP hold status with a reasonIJ Insert a jobIJA Insert a job after the selected jobIJB Insert a job before the selected jobL List job dependenciesL/D Drop individual job dependencies (first enter L on CSF and

then D on next panel)LI List job index entriesLJ List step-level statisticsLR List job resource waitsR Resubmit or restart jobRD Ready a job, removing all dependencies except resourcesRP Reply to AS/400 messageRQ Request jobRR View ESP Encore panelsRT Reset a time dependencySUS Set User Status field for a jobUB Un-bypass a bypassed jobUIN Update Info/System recordUR Un-request a requested jobUW Un-wait a job from JANCWAIT


275

Commands, Continued

Working withother ESPdefinitions

The following table lists the available commands for working with other ESPdefinitions.

Command Description BD Browse Job Documentation BE Browse Event BP Browse ESP Procedure ED Edit Job Documentation EE Edit Event EP Edit ESP Procedure

276

Inserting a Job

Introduction Using CSF, you can insert different job types into an active Application. Theinserted job runs immediately unless you define a predecessor or insert the jobon hold.

Example For example, to add job NEWJOB to an Application with a predecessor ofJob PAYD006A and a successor of Job PAYD008A, take the following steps:

Step Action1 Type IJ beside any job in the Application.2 Type NEWJOB as the Object name on the Insert an Object panel.3 Type Y for Predecessors, Y for Successors, and press Enter.

3 Enter PAYD006A as the Predecessor Job name and press Enter.4 Enter PAYD008A as the Successor Job name and press Enter.5 Your job, NEWJOB, should now appear as part of your CSF

display.

277

Resubmitting a Job

Introduction Using CSF, you can resubmit a job that has terminated abnormally.

Example The following rules apply when you resubmit a job from the CSF panelillustrated below:

• If an override member name is specified (in the Member field), but nooverride JCL library name is specified (in the Dsname field), then thespecified member name is used together with the original JCL library.

• If the JCL library name is specified but the member name is blank, thenthe specified JCL library is used with the original member name.

• If both fields are blank, the original library name and original membername are used.

• If both fields are filled in, then the specified library name and specifiedmember name are used.

Resubmittingmore than onejob

Once an override library name has been specified on this panel, the Dsnamefield will always be pre-filled with the latest override library name used, forthe remainder of the CSF session. Once you exit from CSF, this default valueis lost.

278

Removing Job Dependencies

Introduction Using CSF you can remove different dependencies from a job in anApplication.

Example For 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:

You may enter a D in front of any predecessor that is not yetcompleted, to drop a dependency.

JOB PAYD008A

PREDECESSORSD PAY006A NEWJOB

SUCCESSORS PAYR009A

• Use the RD command to “ready” a job - remove all dependencies exceptresources

• Use the DR command to remove all resource dependencies.

279

Resetting a Time Dependency

Introduction A job in an Application can have different types of time dependencies. UsingCSF, you can reset any of these dependencies.

Process To change a time dependency for a job, type RT beside the job. This takes youto the Reset Object Times panel.

The following table associates each field on the Reset Object Times panelwith the corresponding Application statement.

Field ESP Procedure StatementEarliest submit time DELAYSUB or EARLYSUBLate submit time LATESUBOverdue time for job start DUEOUT INPUTOverdue time for job end DUEOUT EXECAbandon execution at ABANDON SUBMISSIONAbandon dependencies at ABANDON DEPENDENCIESAbandon resources at ABANDON RESOURCES

Example Suppose a job has an early submission time of 5 p.m. To remove thisdependency time, 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.

280

Bypassing and Completing Jobs

Introduction 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 bytyping BY next to the job. ESP updates the status field to BYPREQ indicatingthat 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 jobby typing UB next to the job anytime before the job actually becomesbypassed.

Completing ajob

When you complete a job, you are telling ESP 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.

You cannot un-complete a job. If you mistakenly complete a job, you caninsert another occurrence of the job (qualified for uniqueness) with therequired dependencies but successor jobs may have already been released.

281

Adding Job Dependencies

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

282

Adding a Job with a Time Dependency

Process Follow these steps to add a job with a delayed submission time:

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

283

Adding a Job Relationship in an Application

Unrelated jobs To add a relationship between two unrelated jobs in an Application, simplyinsert a link into the Application to “link” the two jobs.

Example For example, you may want to add a link to an Application to cause Job B towait for Job A to complete successfully. Visually, the dependencies look likethis:

A B

LINKME

Steps Follow these steps:

Step Action1 Type the IJ command beside any job in the Application.2 Enter the name of the link in the Jobname 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 completes the link and submits Job B.

284

Adding a LINK Process

Process Follow these steps to add a link that processes commands.

Step Action1 Edit the Application definition to define the link and specify the

commands you want processed. For example:

JOB EXTRA LINK PROCESSSEND 'THIS IS AN INSERTED LINK PROCESS' U(*)ENDJOB

2 Insert a link with the same name into the Application - specifyjobname, job type, and dependencies.

When the link becomes ready, ESP processes the commands.

285

Setting and Resetting the User Status Field

Process You can set the User Status field when you use either of the following:

• HR command to hold a job with a reason.• SUS command.

Example For example, if you bypass a job you can use the User Status field to notifyothers of the reason for this action. The User Status field for a job might looklike this:

JOBNAME PNODE USER STATUSTAPEJOB BYPASSED NO INPUT TODAY

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

286

Using Other Commands

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

Command Invokes ESP in ...ESP Line modeESPPM Page mode

Another way of processing ESP commands is to type ESP followed by thecommand you want processed. The following example issues a TRIGGERcommand from the command line.

ESP TRIGGER PROD.MORE_WORK ADD


For more information on using these modes, refer to Getting Started on page43.

287

Extensions to CSF

Introduction The Consolidated Status Facility can have extensions written in REXX. Yourinstallation may want to add its own commands and enhance or replace thestandard 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 system administrator to see if any customized commands areavailable to you.

288

Freeform Filtering

Introduction Freeform filtering is an extension to the CSF filtering capabilities that allowsyou a more versatile and customizable method of filtering your ESPApplications. You have the option to filter your Applications using thestandard filter panel or to use the Freeform filter panel for scenarios thatcannot be handled using the standard panels.

Example For example, you may choose to 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.

Filter criteria A filter consists of a filter string. A filter string consists of the following:

Keyword plus Logical Operator plus Value or Condition and optionallyBoolean Operator. The keyword identifies the kind of workload objects onwhich you want to filter, such as Applications or workload object names. Thelogical operator specifies the operation, such as filter on Application name,when it is equal to some specified character string. Value is what you wantApplication name to be equal to, such as PAYROLL.

If you want to see all Applications that are incomplete, filter on the conditionINCOMPLETE. Boolean operators are used to AND or OR one or morekeyword and value sets.

Entering afreeform filter

To enter a freeform filter:

Step Action1 Type FI on the CSF command line. This displays the Filter

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


289

Freeform Filtering, Continued

SpecifyingKeywords

The following keywords are valid entries for filtering:

Keyword Description Keyword DescriptionACCOUNT Account number JSBYTE Job status byte:

C-completedD-dependencyE-executingF-failedI-inputP-post-processR-resourcesS-scheduledT-timeW-wait

AGENT Agent name JSFLAG Job status flagAPPL Application name NETID DJC/JES3 network idAPPLFILE Application file NSCM Non-specific cart

mountsAPPLGEN Application generation NSRM Non-specific reel

mountsAPPLSEQ Application definition

sequencePNODE Processing node

APSLOT Application file slot # QUAL QualifierASFLAG Application status flag SADFLAG SAD flagsAUTH Authorization string SCBCYCLE Scoreboard cycleCMPC Completion code SCBENTRY Scoreboard entry #DMANAGER Distributed manager

nameSCBTOKEN Scoreboard token

ETIME Job end time SCHED Scheduled timeEVENT Event name STATUS StatusHC Hold count STIME Job start timeHWCM High water cart

mountsSUBAPPL SubApplication name


290


Specifying Keywords (continued)

Keyword Description Keyword DescriptionHWRM High water reel

mountsTAG Tag

JAFLAG Job attribute flag TRSLOT Trkfile slot #JOBNAME Job name USTATUS User statusJOBNO Job number WOBTYPE 2-character workload

object type for non-MVS

Note:For any of the time fields, (i.e. ETIME, SCHED, and STIME), you need touse the TIME function in a comparison. For example, STIME > TIME(11AMTODAY). You can compare against any time in a format that ESP recognizes.

Specifyingrelationaloperators

Relational operators include the following standard operators:>= GE greater than or equal<= LE less than or equal> GT greater than< LT less than= EQ equal¬= NE not equal to


291


UsingSubstrings

You may need to refer to portions of a value, rather than its full contents. Thefilter string uses substring notation to allow you to specify which characters ofa value you need. Substring notation consists of specifying 1 or 2 numbers inparentheses immediately following the value name, as follows:

VALUE(v1[,v2])

where:

• v1 and v2 are whole numbers• v1 refers to the starting position, the first character position is 1.• 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.• If v2 is omitted, it defaults to the remaining length of the variable.• If v2 is positive, it specifies a number of characters required.• If v2 is negative, it represents the remaining length less v2.

Example For example, assume that JOBNAME contains the string PRODJOB. Thefollowing table demonstrates the outcome that results when you specifycertain substring notations:

Specification Result

JOBNAME ‘PRODJOB’JOBNAME(1,4) ‘PROD’JOBNAME(5) ‘JOB’JOBNAME(5,1) ‘J’JOBNAME(-1,1) ‘B’JOBNAME(1,7) ‘PRODJOB’JOBNAME(1,-3) ‘PROD’


292


SpecifyingConditions

You can use the following conditions in your filter string:

Condition DescriptionALL All objectsAPPL_COMPLETE Application execution is completeBYPASSED Object execution has been bypassedCOMPLETE Object execution is completeCRITICAL_PATH Object is on a critical pathEXTERNAL Object is External to an ApplicationINCOMPLETE Object execution is not completeINTERVENTION_REQUIRED Object execution requires manual

interventionINTVRQ Object execution requires manual

interventionLINK Object is a LINKMANUAL_TASK Object is a manual taskNOT_APPL_COMPLETE Application execution is not completeNOT_BYPASSED Object execution has not been

bypassedNOT_CRITICAL_PATH Object is not on a critical pathNOT_EXTERNAL Object is not an External


293


Specifying Conditions (continued)

Condition DescriptionNOT_INTERVENTION_REQUIRED Object execution does not require

manual interventionNOT_INTVRQ Object execution does not require

manual interventionNOT_LINK Object is not a LINKNOT_ON_REQUEST Object is not defined as REQUESTNOT_OVERDUE_END Object execution end time has not

been exceededNOT_OVERDUE_START Object execution start time has not

been exceededNOT_REQUESTED Object has not been specifically

requestedNOT_RESTART_STEP_PRESENT Object does not have a restart stepNOT_TASK Object is not a TASKON_REQUEST Object is defined as REQUESTOVERDUE_END Object execution end time has been

exceededOVERDUE_START Object execution start time has been

exceededREQUESTED Object has been specifically

requestedRESTART_STEP_PRESENT Object has a restart stepTASK Object is a TASK

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

294

Specifying Boolean Operators

Introduction When you specify your filter string, you can connect 2 or more keyword andvalue sets with the logical operators AND and OR. Use AND when allconditions must be met. Use OR when any of the conditions meet yourcriteria. The AND operator takes precedence over the OR operator. You cannest expressions within parentheses to force precedence.

Example FilterStrings

The following table lists filter strings and what they reveal:

Enter the following filter To see...

CRITICAL_PATH Critical path jobs

ON_REQUEST AND REQUESTED On-request jobs that have beenrequested

APPL EQ 'PAYROLL' ANDRESTART_STEP_PRESENT

Jobs in the PAYROLL Applicationthat have a restart step

JOBNAME(1,1) EQ 'P' AND JSBYTEEQ 'F'

Failed objects that start with ’P’

CMPC EQ 'S222' AND SUBAPPL EQ'PAYJOBS'

Jobs with a completion code of’S222’ in the PAYJOBSsubApplication

JOBNAME(1,3) EQ 'PAY' ORJOBNAME(1,3) EQ 'ACC'AND APPLEQ 'FINANCE'

Objects that start with ’PAY’ or’ACC’ and belong to an Applicationcalled FINANCE

JOBNAME(1,4) EQ 'TEST' OR APPLEQ 'TESTAPPL' AND INCOMPLETE

Objects in Application TESTAPPLthat start with TEST and are notcomplete

APPL EQ 'CYBER' ANDOVERDUE_START AND REQUEST

Objects in Application CYBERwhose execution start time is overdue

JOBNAME(1,3) EQ 'CYB' ANDSTIME> TIME(11AM TODAY)

Objects whose names start with’CYB’ that started later than 11 a.m.today

WOBTYPE EQ 'HP' AND APPL EQ'BILLING'

All HP jobs in the BILLINGApplication


295

Specifying Boolean Operators, Continued

Example Filter Strings (continued)

Enter the following filter To see ...

JOBNAME(1,1) EQ 'X' AND APPLEQ 'MYAPPL' AND NOT_REQUESTED

Objects that start with X inApplication MYAPPL that have notbeen requested

(JOBNAME EQ 'TESTJOB' ORJOBNAME(1,2) EQ 'A' ORJOBNAME(1,2) EQ 'BC') AND(APPL EQ 'MYAPPL' OR APPL(1,2) EQ 'PA') ANDOVERDUE_START

Objects called TESTJOB and whosenames start with the characters ‘A’ or‘BC’ and are contained withinApplication MYAPPL or anyApplication whose name starts withPA and whose execution start time isoverdue

296

Creating Reports

Overview

Introduction ESP allows you to get information about your jobs in several ways. You maygenerate a report, flowchart a jobstream, view CSF, or use tracking commandsto give you the job information you require.


Topic See PageHistory Reporting 297Structuring the Report 298Reporting Fields 299Field Formats 300Invoking the Report Function 304Specifying Input Criteria 305Specifying Output Criteria 309Ending the Report Definition 312ESP’s History Reporting Fields 314Accumulating Fields 320Reporting on Scheduled Activity 321Allocating a Sequential Data Set 322Generating Data 323Extracting Data 325Generating Scheduled Versus Actual Report 326Generating Projected Versus Actual Data 328Extracting Tape Information 329Using Job Mapping 330Job Mapping Data Set 331Generating Data for the Report 332Producing a Job Activity Report 333Producing a Job Descendent Report 338Putting it All Together 340ESP FLOWDOC 341Flowcharting 350Generating Flowcharts Using MS Project 351Generating Flowcharts with ESP and Timeline 354

297

History Reporting

Overview ESP has a powerful and versatile reporting facility that you can use at anytime to generate details about the progress of jobs. Information in the jobhistory files, defined by the administrator or installer, provide the basis for thereports. You can generate reports online or in batch.

Note:You can report only on jobs, started tasks, and TSO users that the ESPadministrator requests ESP to track.


For more information on how to specify which of these ESP will track, referto the ESP Administrator’s Guide.

298

Structuring the Report

Introduction You can structure a report definition in several sections, some of which areoptional. Start each section of a report definition by a command, then codeeach section in free format and in any sequence.

Sections of areport

The sections which make up a report are:

• Input source selection• Selection criteria• Display format• Sort options• Titles and footings• Section break definitions• Subtotals.

Content of thereport

For most reports, you usually specify input source selection, selection criteria,and display format. You can make reports as detailed as you want, describingsuch aspects as:

• Jobname• Completion date• Application name• CPU time• Number of print lines.

299

Reporting Fields

Overview You can select, sort and display as many as 70 fields using the CRITERIA,SORT, and DISPLAY commands. With these commands you can create areport containing as much detail as you want.

Historyreporting fields

A list of ESP’s history reporting fields and their definitions appears later inthis chapter under the heading ESP’s History Reporting Fields.

300

Field Formats

Field categories Using ESP you can display or base selection criteria on the following fieldcategories:

• Character• Numeral• Time• Elapsed time• CPU times• Dates.

Characterfields

These include JOBNAME, ACCOUNT, CLASSID, and PGMR. These fieldsare always left justified. In the CRITERIA section, you can select characterfields by specifying the full field value or part of it. If you specify a part of thefield, you must include wildcard characters. The asterisk matches with anysingle character, while a hyphen specifies that any remaining charactersmatch.

Example:Characterfields

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 would alsoselect 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 displays themright justified with leading zeros translated into blanks. You can increase thedefault length for these fields by specifying whatever length you want on theDISPLAY statement or by defining a longer title.

Example:Numeric fields

The following example displays DASD EXCP counts to nine digits becausethe title length (‘DISK-EXCP’) is nine characters. The title for the tape EXCPcounts is ‘TAPE I/O’ but ESP displays the counts to a length of nine, asspecified. Blanks on the left fill the field. ESP justifies title and numeric fieldson the right.

DISPLAY DEXCP 'DISK_EXCP' TEXCP 9 'TAPE I/O'


301

Field Formats, Continued

Comparisons You can also make comparisons against numeric fields in the CRITERIAsection. ESP supports the following comparison operators: AND, OR.

Example:Comparisons

This example selects all jobs that perform I/O to tape, but which use less than1000 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 youcan omit the seconds by specifying a display size of five. The RDRON,EXECST, ENDT, and COMPT fields fall into this category. You can use anydate and time format valid on a SCHEDULE statement when you want toselect these fields.

Example:Time fields

The following example selects all jobs submitted since March 3rd, 1998.

CRITERIA RDRON GT MARCH 3RD 1998

Elapsed timefields

OVDSTART, INPUT, TOTALQT, and OVDCOMPT are examples ofelapsed times. ESP displays them in the following forms:

ESP Form Explanationss Seconds; where ss is the number of seconds when the elapsed

time is less than one minute.mmMss Minutes and seconds, when the elapsed time is less than one

hour. For example: 10M53 (ten minutes and fifty-threeseconds).

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 isgreater than 99 hours but less than 999 hours.

hhhH Hours, when the elapsed time is more than 999 hours.

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


302


Example:Elapsed timefields

The following example selects jobs that were in execution for one or moreminutes, 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 theform mm:ss.th, where mm is the number of minutes, ss is the number ofseconds, and th are the tenths of a second.

Example:CPU time fields

The following example selects all jobs that consumed between ten secondsand five 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 inthe form xxxddmmmyy, where:

Field Symbol Explanationxxx first three characters of the day of the week.dd day of month number.mmm first three characters of the month name.yy last two digits of the year.

You can change the way date fields are displayed in a report using theDATEFORM command within the report, as described in the “SpecifyingOutput Criteria” section of this chapter.

You can use any date and time format valid on a SCHEDULE statement whenyou want to select these fields as input criteria to your report.


303


Example:Date fields

The following example selects all jobs that were submitted since 9 a.m. onMarch 29th, 2000.

CRITERIA RDRONDATE GT 9AM MARCH 29TH 1999

The date fields also allow for some sorting by storing time information. Whenyou request sorting by a date field, ESP sorts by date and time. If you specifythe following, ESP reports only on those jobs with a reader-on time and dateof midnight, August 23, 2000.

CRITERIA RDRONDATE EQ AUGUST 23RD 1999

304

Invoking the Report Function

Methods usedto invoke thereportingfunction

Invoke the reporting function by 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 command processor.

When you enter the REPORT command, you are in report mode and can nowstructure your report.

305

Specifying Input Criteria

Input for areport

The input for a report consists of:

• A history file• A time range• Selection criteria.This section describes each of these areas.

Identifying theHistory file

Use the HISTFILE command to specify which history files you want to use asthe input source. If you omit the history file you want to use, ESP scans all thehistory files you can access. Your ESP Administrator determines history fileaccess.

The following specifies a history file called HIST1:

HISTFILE HIST1

Using Historyfile other thancurrent

Use the INPUT command to request that ESP read in other records from adata 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 havethe exact format of the ESP history file records. You will find this optionmost useful with files you create using the COPY statement.

If the ESP subsystem is not functioning when the system generates a report,use the INPUT statement rather than the HISTFILE statement. The sub-systemdoes not have to be active in order to use the INPUT statement.

Specifying thetime range

Use the FROM and TO commands to specify a time range for the history filesearch. In this way you can limit your search based on the job submission timein the history file. If you do not specify an end time, ESP uses the currenttime. You can use any valid schedule statement that resolves to a date andtime, for example:

FROM 10AM TODAYFROM 8AM YESTERDAY TO 8AM TODAYFROM 9AM TODAY LESS 1 WEEK TO 9AM YESTERDAY


306

Specifying Input Criteria, Continued

Specifying theselectioncriteria

Use the CRITERIA command to specify selection criteria. The syntax is:

CRITERIA field operator value

To view all the values possible for field, see the topic entitled ESP’s HistoryReporting Fields, starting on page 314.

You can specify several field, operator, and value groups. To be selected, allcriteria elements must be matched. Use the OR connective to providealternatives. If you do not specify a CRITERIA command, ESP reports on allrecords that meet the time range criteria.

You can use the following operators in either their symbol or letter form in aCRITERIA command. You cannot use the equal sign (“=”).

Symbol Form Letter Form Explanation>= GE Greater than or equal<= LE Less than or equal< LT Less than> GT Greater than¬= NE Not equal to

EQ Equal

If you want to compare a field to a null string, use a blank enclosed in singlequotes, as in ‘ ’ .

Note:You can specify several criteria sections in a single report, using multipleCRITERIA commands; ESP selects a job if it satisfies any criteria section.

Example The following example selects only those jobs that belong to the PAYROLLApplication:

CRITERIA APPLSYS EQ PAYROLL

Example The following example selects only those jobs that have been restarted:

CRITERIA RRJOBNO NE 0


307


Example The following example selects a job if it belongs to the PAYROLLApplication and the jobname starts with P.

CRITERIA APPLSYS EQ PAYROLL JOBNAME EQ P-

Example The following example selects a job if it belongs to the PAYROLLApplication or the jobname 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 The following example selects all jobs that ended between 8 a.m. and 4 p.m.on January 9, 1999:

CRITERIA ENDDATE GE 8:00 JAN9,1999 -ENDDATE LE 16:00 JAN9,1999

Example The following example selects all jobs that were submitted by ESP outside ofan ESP Application:

CRITERIA ESPSUB EQ YES AND APPLSYS NE ' '

Example 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*


308


Example The next example selects only those jobs that:

• Have more than 10000 EXCPs• Or have more than one minute of CPU time.

The commands look like this:

CRITERIA EXCP GT 10000CRITERIA CPUTIME GT 1:00

309

Specifying Output Criteria

Specifying anoutput data set

Use the COPY command if you want to specify an output data set or file toreceive all or subsets of the job history records read in from the input source.ESP writes to any format sequential data set. If a data set is new and you havenot yet specified a record format for it, ESP uses the following default:LRECL=4096, RECFM=VBS, BLKSIZE=6144.

Separating datainto differentfiles

You may find the COPY option useful when you want to separate data in ahistory file into one or more files. The example below sends records to tapeafter they are 12 weeks old:REPORTHISTFILE HIST1CRITERIA RDRON GT TODAY LESS 12 WEEKSCOPY SELECT FILE(DISK1)COPY REJECT FILE(TAPE1)

Specifying thedate format

History reporting displays date fields in DDMMMYY format. You canchange this default using the DATEFORM command. The options are asfollows

DATEFORM Results ExampleDMYThis is the default.

Day DDMMMYY MON21JUN99

JULIAN Day DDDYY MON17299YM Day YYYYMMM MON199906YMD Day YYYYMMMDD MON19990621MDY Day MMMDDYY MON062199

Notes This setting only affects the date format you use to display fields in a historyreport; it does not affect the date format you use on a CRITERIA commandand it does not affect the date format used in schedule criteria.


310

Specifying Output Criteria, Continued

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 inYYYYMMMDD format.

DATEFORM YMD

Specifyingfields to display

Use the DISPLAY command to specify which fields you want to display. Thenyou have the option to define titles.

Entering fieldnames

Once you start the DISPLAY section, you can enter several field names oneafter the other. Separate each by a blank or a comma, along with optionallengths and titles. ESP places the fields you specify on the report detail line inthe order you specified them. To view all the values possible for field, see thetopic entitled ESP’s History Reporting Fields, starting on page 314.

Example In the following example, ESP:

• Displays both jobname and the reader-on time and date, along with theirdefault 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'

Specifying sortcriteria

Use the SORT option to specify which fields you want to sort and whether youwant the sort sequence to be ascending or descending. The default isascending. The following example sorts data by decreasing use of CPU time.ESP displays the data in sequence of ascending DASD EXCP counts.

SORT CPUTIME D DEXCP


311

Specifying Output Criteria, Continued

Specifyingother formats

Use the BREAK command to define at which points in the report 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 subtotals onlymeaningful fields such as CPUTIME and DEXCP, but not JOBNO. Thesubtotal detail line has the same format as the normal detail line, except that italways has the word “subtotal” starting in column one. The next columndisplays the number of items ESP sub-totaled. The preceding informationoccupies the first 14 character positions on the line. When you create a detailline, do not place any fields you want ESP to subtotal in the first two columns.

Example:Specifying aformat

In the following example:

• When the first three characters of the first account number change, ESPprints a subtotal and starts a new page

• When the first two characters of the jobname change, ESP leaves oneblank line.

DISPLAY JOBNAME JOBNO ACCOUNT RDRON DEXCP TEXCPSORT ACCOUNT JOBNAMEBREAK ACCOUNT 3 EJECT SUBTOTALBREAK JOBNAME 2 SPACE 1

312

Ending the Report Definition

Introduction Use the ENDR command to mark the end of a report definition and initiate thereport generation.

Example:Reporting onan Application

This example reports on all jobs in an ESP Application called PAYROLL thathave changed status since 8 a.m. today. The SETWIDTH command sets thewidth of the report to 80 characters.

REPORTSETWIDTH 80FROM 8:00AM TODAYCRITERIA APPLSYS EQ PAYROLLDISPLAY JOBNAME CMPC EXECST EXECSDATE ENDT ENDDATE CPUTIMEENDR

Sample output from the above commands is shown below.

JOBNAME JOB COMP EXEC START EXEC END CPU TIME NO CODE START DATE END DATE

PAYD001A 2221 0 11.56 MON 13APR98 12.02 MON 13APR98 0:01PAYD002A 2227 0 12.02 MON 13APR98 12.02 MON 13APR98 0:00PAYD003A 2226 0 12.02 MON 13APR98 12.02 MON 13APR98 0:00PAYD004A 2229 0 12.02 MON 13APR98 12.07 MON 13APR98 0:04PAYD100A 2232 0 12.07 MON 13APR98 12.07 MON 13APR98 0:00PAYD006A 2233 0 12.08 MON 13APR98 12.08 MON 13APR98 0:00PAYD008A 2234 SOC1 12.08 MON 13APR98 12.08 MON 13APR98 0:00PAYD008A 2270 SOC1 12.57 MON 13APR98 12.57 MON 13APR98 0:00PAYD008A 2271 0 12.58 MON 13APR98 12.58 MON 13APR98 0:00PAYD009A 2272 0 12.58 MON 13APR98 12.58 MON 13APR98 0:00PAYD010A 2273 SOC1 12.59 MON 13APR98 12.59 MON 13APR98 0:00PAYD010A 2275 0 12.59 MON 13APR98 12.59 MON 13APR98 0:00PAYD011A 2276 0 12.59 MON 13APR98 13.04 MON 13APR98 0:01SUBTOTAL (13) 0:06TOTAL (13) 0:06


313

Ending the Report Definition, Continued

Example:Reporting inbatch

In the example below the first four lines represent JCL statements and theremaining lines define a report. The report includes information on jobswhose first account number begins with ‘PAY’ that ESP has tracked from 6p.m. yesterday until 8 a.m. 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 4 EJECT SUBTOTALENDR

Note:When reporting in batch, a hyphen at the end of a line indicates acontinuation. If you are using a hyphen as a mask, follow it with a semi-colon(e.g. PAY-;).

Example:Writing reportoutput to a dataset

The following example writes a history report to a new data set. The reportincludes information on jobs with names beginning with ‘CYB’ that ESP hastracked since 4 p.m. 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

314

ESP’s History Reporting Fields

Introduction The following are history reporting fields. An asterisk beside a field indicatesyou can use the field for non-MVS workload.

Field ExplanationACCOUNT Job’s first account parameter, can also be specified as

ACCOUNT1.ACCOUNT2 Job’s second account parameter.ACCOUNT3 Job’s third account parameter.ACCOUNT4 Job’s fourth account parameterALLOCQT Allocation queue time. This is the total time the job spent in

the allocation process (e.g. waiting for tape mount).APPLGEN Application generation number (absolute).APPLSYS* Application name for jobs defined to an Application, can also

be specified as APPL.APPLTAG Tag associated with a job in an Application.AUTHSTR* Indicates job’s authority string that you can use to verify

ownership of the job.CCFAIL Indicates whether or not the job failed due to condition codes.

The field has a value of ’YES’ if the job failed due to acondition code, and the value ’NO’ otherwise.

CLASSID ESP class to which you defined the Event.CMPC* Job completion code, including return code, user abend code

or system abend code. For information on the differentcompletion codes, go to the last page of the History ReportingField topic.

COMPDATE Job completion date, which is the date on which the jobcompleted its last post-processing phase. If the job has no post-processing phases, the completion date is the same as the purgedate. (See note at the end of the table.)

COMPT Job completion time, which is the time at which the jobcompleted its last post-processing phase. If the job has no post-processing phases, it is the same as the purge time. (See note atthe end of the table.)

CPUTIME Total CPU time, including both SRBTIME and TCBTIME.DEXCP Total EXCP count to DASD devices.ENDDATE Date at the end of execution.ENDT* Time at the end of execution.


315

ESP’s History Reporting Fields, Continued

Field ExplanationESPSUB Indicates whether or not the job was submitted by ESP. It has

a value of YES if the job was submitted by ESP (eitherthrough an Event or as part of an Application), otherwise ithas a value of NO.

EXCP Total EXCP count for the job during the execution phase.EXEC# Number of times the job has executed as part of a particular

generation of an Application.EXECNODE Node the job executed on. This refers to a JES node and not

the name given to an ESP node (i.e. LOCAPPL parameter).EXECQT Elapsed time for the job during the execution.EXECSDATE Date at the start of the execution.EXECST* Execution start time. For example, 08:26.EXECSYS System the job executed on. This does not get set until the

job is purged regardless of your tracking options.GROUP* Prefix of the Event associated with the job, if ESP submitted.INFOREC Info/System record number.INPUTQT Length of time the job was in the input queue.INSYS System the job was submitted on. This does not get set until

the job is purged regardless of your tracking options.JOBCLASS JES execution class.JOBNAME* Name of the job.JOBNO* Job number.JOBQUAL* ESP job qualifier.LINES Number of print lines.MSGFAIL Indicates whether or not the job failed due to an ESP

SYSMSGS command. The field has a value of ’YES’ if thejob terminated due to the ESP SYSMSGS facility, and thevalue ’NO’ otherwise.

MXCMPC Maximum completion code for the job.MXRC The highest return code from any step in the job. This is a

numeric field, for more information, go to the last page of theHistory Reporting Field topic.

NCI Number of card images submitted to the internal reader.NETID Network identifier for a job belonging to a DJC/JES3 job

network.


316


Field ExplanationNSTM Number of non-specific tape mounts (scratch tapes) for the

job.OUTSYS System the job was purged on. This does not get set until the

job is purged regardless of your tracking options.OVDCOMP Amount by which the job was overdue at the time of

completion. The criteria for being late is defined by theDUEOUT OUTPUT statement in an ESP Procedure or in ajob’s tracking model.

OVDEND Amount of time by which the job was late in endingexecution. The criteria for being late is defined by theDUEOUT EXEC statement in an ESP Procedure or in a job’stracking model.

OVDSTART Amount of time by which the job was late in startingexecution. The criteria for being late is defined by theDUEOUT INPUT statement in an ESP Procedure or in ajob’s tracking model.

PGMR Contents of the programmer name field for the job.POSTQT Elapsed time spent in post-output processing phases.PRINTQT Length of time the job remained in the print queue.PURGDATE Date of job purge.PURGT Purge time.RC The return code from the last step executed in the job. This is

a numeric field, for more information, go to the last page ofthe History Reporting Field topic.

RDRON Time at which ESP read the job into the system. If you areusing RDRONDATE, you do not require this field.

RDRONDATE Date at job submit time. This field also includes the timeESP read the job into the system.

RRJOB Name of job being rerun or null.RRJOBNO Job number of the most recent execution of a resubmitted

job. This field only has a value for a job that is being rerunby ESP (i.e. a job that has been resubmitted via an explicitAJ command or the R line command in CSF. If the job is nota rerun, this field is set to 0 (zero).

SCHEDDATE Scheduled date.SCHEDT Scheduled time.


317


Field ExplanationSPTM Number of specific (i.e. non-scratch) tape mounts for the job.SRBTIME CPU time consumed while in SRB mode.STATUS Job status. There are four possible values:

INPUT: defines submitted jobs not yet startedSTARTED: defines jobs currently in executionCOMPLETED: defines jobs that completed all phases ofprocessingENDED: defines jobs that completed execution but did notfinish all phases of processing.

STEPS Number of job steps.SUB# Submission number for a job in an Application.SUBAPPL* SubApplication identifier.SUBJOBNO Job number on the system that submits the job. This is useful

when a job is submitted on one system and routed to anothersystem where a different JES job number is assigned.

SUNITS Job service units, as defined by the SRM.SYSABD System abend code or null.TAPEM Number of tape mounts for the job.TAPEW 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. TAPEWcounts the number of different tape drives that were used atone time. For example, if a jobstep calls for 3 specific tapes,one at a time, on the same drive then TAPEW will be 1 butSPTM will be 3.

TCBTIME CPU time consumed while in TCB mode.TEXCP Total EXCP count to tape drives.TMODEL Name of the ESP tracking model that was used to track the

job.TOTALQT Total elapsed time for the job.


318


Field ExplanationTRANSACT Total time for which a transaction is active. In the case of a

batch job, this is approximately equal to the total executiontimes for the programs contained in the job. It is measured inunits of 1024 microseconds.

TRANSRES Total time during which a transaction was resident in realmemory. This is often identical to the transaction active time(TRANSACT), but may differ since it does not include anytime during which the task was swapped out of real memory. Itis measured in units of approximately 1 millisecond, or moreprecisely, units of 1024 microseconds.

TRUSER Userid that triggered the Event. It resolves to the userid thatmanually triggered an Event, and is blank otherwise.

UABEND 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 tostarting execution, and the value ’NO’ otherwise. These errorsare caused by such activities as an early (pre-execution) JCLerror, certain security system verification errors, and acancellation of a job while it is on the JES input queue.

Note: ESP may not track jobs through to the output stage at your installation. Forsuch jobs:

• The times specified in the COMPDATE and COMPT fields refer to whenthe jobs complete successfully.

• The LINES, POSTQT, PRINTQT, PURGDATE and PURGT fields arenot applicable.


319


Numeric fields The RC and MXRC fields contain strictly numeric values. For cases where acompletion code is non-numeric (e.g. JCL errors, system or user abends,CCFAIL), special values are inserted in these fields as an indication of theactual completion status.

The following table lists the completion codes:

Type of Error ValueSystem ABEND Abend code + 10000 (abend code converted to

decimal first)User ABEND Abend code + 20000SYSERROR 30000 (actual completion status unavailable)CCFAIL 30001 (terminated by CCFAIL or CCCHK logic)JCLERROR 30002RUNNING 32767 (job still executing)

Field lengthchange

All fields that represent Time previously displayed the minutes and hours. Asof ESP 5.1, these displays now include seconds. This causes an increase in thefield length for coding purposes. This is important if you produce a historyreport and use another program (e.g. SAS) to pull data out of the report.

320

Accumulating Fields

Description The following reporting fields are accumulated, totals will be produced foryou:

• EXCP• DEXCP• TEXCP• TAPEM• SPTM• NSTM• STEPS• SUNITS• NCI• LINES• OVDSTART• OVDEND• OVDCOMP• INPUTQT• EXECQT• PRINTQT• TOTALQT• POSTQT• ALLOCQT• TCBTIME• SRBTIME• CPUTIME• TRANSRES• TRANSACT

321

Reporting on Scheduled Activity

Introduction The scheduled activity facility reports on the scheduled workload for a timeperiod in the future. It lets you generate online and hardcopy reports aboutscheduled jobs, links, tasks, and manual jobs. The reports provide a variety ofjob statistics that indicate processing requirements. The data the reportgenerates uses average execution results from tracked jobs to provide a truepicture of what you can expect during the next scheduled occurrence of thejobs.

Note:This facility reports on job workload that is not yet active. This excludes jobsin an active Application, for example.

Set up scheduleforecasting

To set up schedule forecasting:

Step Action1 Allocate a sequential data set to store scheduled activity data.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).

322

Allocating a Sequential Data Set

Optionalattributes

Allocate a sequential data set to store the data. The following attributes areoptional:

Attribute ExplanationPS OrganizationVBS Record format32756 Record length32760 Block size

You can use any sequential data set; ESP assigns the correct attributes.

323

Generating Data

Introduction To generate data that you can use for scheduled activity reporting, ESP mustsimulate all the Events and ESP Procedures it would execute in a specifiedperiod. ESP does this by executing the ESP subsystem started task procedurein batch with a special parameter (PARM=‘SAR’ or PARM=‘SAD’). Theoutput that ESP generates by this simulation forms a scheduled activity dataset.

You can also create multiple schedule activity data sets. You may want togenerate separate data sets on scheduled activity for the next day or for thenext week, or you may want different activity data sets for differentproduction groups.

Note:ESP does not reflect an Event in the scheduled activity data set unless itcontains either a SCHEDULE or EXPECT command.

SADGENcommand

When creating a job to generate a scheduled activity data set, you can limit thesimulation to specific Event data sets, prefixes, and classes by the appropriateuse of the different parameters of the SADGEN command.

You can also use the ESPSADG symbolic variable in an ESP Procedure toaffect the simulation. This variable is set equal to 1 during SADGENprocessing, otherwise it is set to 0. For example, the following statement atthe beginning of an ESP Procedure causes ESP not to simulate the Procedureduring SADGEN processing:

IF ESPSADG=1 THEN QUIT

When ESP creates a scheduled activity data set, it contains a record for eachjob you want to submit, within the time range you have specified on aschedule statement. If you specify neither the FROM nor TO time range, ESPprovides the following default:

'NOW' TO '6AM TOMORROW'


324

Generating Data, Continued

Example The example below is a batch job, SADGEN, that generates a scheduledactivity data set called ‘CYBER.SAD’. The name of the started taskprocedure for ESP is ‘ESP’.

//SADGEN JOB...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD *//SYSIN DD *SADGEN DATASET('CYBER.SAD') -FROM('8AM TODAY')TO('8AM TOMORROW')

325

Extracting Data

Introduction After ESP generates the data, you can extract the data to produce a standardformat scheduled activity report. You can create the report either in batch oronline using the LSAR command, or using option S on the Main Menu.

LSARcommand

The LSAR command lists a scheduled activity report including the followingdata:

• Jobname• Scheduled submit time and date. This reflects the Event schedule time

unless you use the modeling feature to provide estimated submit times.• Number of samples ESP uses for averages• Elapsed execution time• CPU time• Number of print lines• Averages of specific and non-specific tape mounts• Number of tape drives ESP requires• DJC network and/or Application ID• A fully qualified Event identifier.If you do not use the FROM keyword, the starting time for the scheduledactivity report defaults to now. If you do not use either ENDING or UNTILwith the FROM keyword, and you do not specify TO, the scheduled activityreport contains all data generated by the SADGEN command, which ESPstores in the scheduled activity data set.

Example:Displayingscheduledactivity data

The following example requests a report on activity scheduled in an eighthour period starting at 5 a.m. using the data set ‘CYBER.SAR.’ ESP presentsthe data in scheduled time sequence.

LSAR DSN('CYBER.SAR') FROM('5AM TODAY UNTIL 1PM TODAY') TIMESQ

326

Generating Scheduled Versus Actual Report

Introduction You can update a scheduled activity data set with current job status, creating ascheduled versus actual report. This allows ESP to calculate the completionstatus of a schedule, so that you can see how much work has been completedand how much remains.

If you use CSF to monitor the workload, you receive more up-to-dateinformation because ESP automatically updates the CSF. However, togenerate a hardcopy report on the current status from CSF, you may need tocode your own extensions. For more information on CSF see Chapter 7,Consolidated Status Facility.

SADUPDcommand

You perform the schedule update in a similar way to the schedule activitygeneration. Instead of the SADGEN command, use the SADUPD command.ESP can run a job at frequent intervals during a day to update the scheduledactivity database. The job executes in a fraction of the time of the originalschedule generation.

After ESP has run the scheduled update, use the STATUS keyword on theLSAR command, or specified on the Option S panel, to request a statusdisplay instead of the regular schedule display. This provides the status of alljobs in the schedule, as well as the time and percent of the schedule stillremaining. ESP displays actual start and end times, completion codes, andrerun indicators.

Example 1:Creating ascheduledactivity 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')


327

Generating Scheduled Versus Actual Report, Continued

Example 2:Updating ascheduledactivity data set

This example shows the JCL which may be used to provide an update on thisscheduled activity:

//SADUPD JOB CYB1000,CLASS=A//S1 EXEC ESP,PARM='SAR'//SYSIN DD *SADUPD DATASET('CYBER.ESP.SAD')

328

Generating Projected Versus Actual Data

Introduction The scheduled activity update feature provides you with actual start and endtimes for jobs. ESP’s modeling feature can project these times in advance. Asa result, ESP can generate a Projected vs. Actual report that shows each job’sprojected and actual start and end times. For detailed information onmodeling, refer to the Advanced User’s Guide.

Projectedreport

To generate a projected versus actual report:

Step Action1 Before ESP starts the workload you are interested in, generate a

scheduled activity data set using the SADGEN command in a batchjob.

2 When the SADGEN completes, run a model in batch. The modelprocessor updates each job’s projected start and end times in theSAD file. Ensure that the model processing covers the appropriateperiod.

3 After all jobs in the SAD file are complete, update the scheduledactivity data set using the SADUPD command in a batch job.

4 Use the LSAR command with the PROJECTED keyword togenerate a Projected vs. Actual report.

LSAR DSN('CYBER.SADFILE') PROJECTED

329

Extracting Tape Information

Introduction You can request the ESP extract tape volume serial information during ascheduled activity data set generation run. ESP references the tapemanagement catalog when it generates the scheduled activity data set.ESP can then generate a data set using this extracted information and feed thedata set into the TMS or CA1 tape pull program.

Extractinformation

To extract information, take these steps:

Step Action1 Use the INPUTDS statement in the job documentation data set or

ESP Procedure identifying the tape data sets associated with eachjob. For example:

JCLLIB PROD.JCLAPPL PAYROLLJOB JOB1 RELEASE JOB2JOB JOB2 INPUTDS PROD.GDG(-1)ENDJOBSELECT (JOB1,JOB2)

2 Generate a scheduled activity using the SADGEN command in abatch job.

3 Use the LSAR command specifying TAPEPULL(dsname), wheredsname 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 creates a member for each job. You should re-initialize theTAPEPULL data set before you generate the scheduled activitydata set.

5 Use this PDS as input to the TMS or CA1 tape pull program.

330

Using Job Mapping

Introduction Job mapping is a reporting facility that allows you to produce detailed jobinformation. You can generate the following reports:

Type of Report Content of ReportJob activity This report contains detailed information on jobs

including job name, Application name, job type, Eventname, ESP Procedure name, JCL library, execution time,CPU time, and predecessor and successor jobs.

Job descendent This report shows a job and its successors.

Unlike the scheduled activity report, which is based on time, the job mappingfeature generates data based on Event names. These Events may be scheduledor may require data set or manual triggers. There is no need for these Eventsto have executed as history data is not required for the jobs. If history data isavailable, this historical information is incorporated into the reports.

Setting up jobmapping

To set up job mapping:

Step Action1 Allocate a sequential data set to store the job mapping data.2 Generate data for the report using the MAPGEN command.3 Use the JOBMAP command to display a job activity report or use

the JOBTREE command to display a job descendent report.

331

Job Mapping Data Set

Job mappingdata set

Allocate a sequential data set to store the data. This is referred to as the jobmapping data set.

Explanation Attributes for 3390 DASD Otherwise useOrganization PS PSRecord format VBS VBSRecord length 32756 32756Block size 27998 16384

332

Generating Data for the Report

Introduction Use the MAPGEN command to generate data for the job mapping data setthat can be used by the JOBMAP and JOBTREE commands to producereports. To use the MAPGEN command, use a batch job that executes theESP started task procedure with the special parameter, PARM=’SAR’ orPARM=‘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 thename of your job mapping data set and an Event descriptive name (i.e.without the prefix), which may include wildcards.

Note:You must use the MAPGEN command in batch.

Example 1 In the following example, ESP generates data for all Events and stores theoutput in the ESP.MAPGEN data set. The name of the started task procedurefor ESP is ‘ESP’.

//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(-)

Example 2 In the following example, the MAPGEN command causes ESP to generatedata for all Events with descriptive names that start with ‘PAY’ and store theoutput in the ESP.MAPGEN data set.

//MAPGEN JOB ...//S1 EXEC ESP,PARM='SAR'//SYSPRINT DD SYSOUT=*//SYSIN DD *MAPGEN DSN('ESP.MAPGEN') EVENT(PAY-)

333

Producing a Job Activity Report

JOBMAPcommand

Use the JOBMAP command to produce a job activity report. This reportcontains detailed job information. For each job, regardless of its frequency,the job activity report lists the following information:

• Jobname• Application name• Job type (job, request, manual, external, etc.)• Scheduled frequency• Job qualifier• Event name• Calendar name(s)• 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, you must specify the name of your jobmapping data set. Since this command uses the job mapping data set as input,you can report only on jobs contained in that data set. You can use theJOBMAP command in batch, by executing PGM=ESP with the correctSUBSYS parameter, or in Page mode.


334

Producing a Job Activity Report, Continued

Example -UsingJOBMAP inbatch

The following example creates a Job Activity Report for all jobs. Thesubsystem name for ESP in this example is ESPM.

//MYJOB JOB ...//S1 EXEC PGM=ESP,PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD *JOBMAP DSN('ESP.MAPGEN')

Example -UsingJOBMAP inPage mode

The following example creates a Job Activity Report, for all jobs, in Pagemode.

JOBMAP DSN('ESP.MAPGEN')

Reviewing theoutput

For each job, ESP produces output similar to the following:

JOB NAME APPL NAME TYPE SCHEDULING-------- --------- ---- ----------PAYJOB01 PAYROLL JOB SCHEDULED: DAILY

QUALIFIER:EVENT: CYBER.PAYJOB01

CALENDAR(S): SYSTEM 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:

Customizingyour jobactivity report

Because of the amount of data generated for each job, you may want to limitthe report to a specific Application, produce an index, or suppress certainfields in your report.

335


336


Generating areport for aspecificApplication

You can use the APPL parameter to restrict the data to a specific Application.The following example lists a job activity report for all jobs in the PAYROLLApplication.

JOBMAP DSN('ESP.MAPGEN') APPL(PAYROLL)

Generating anindex

You can use the JOBINDEX, APPLINDEX and RESINDEX keywords toproduce an index by job name, Application name, or resource name,respectively.

Example The following example creates a Job Activity Report with an index by jobname and an index by Application name.

JOBMAP DSN('ESP.MAPGEN') JOBINDEX APPLINDEX

Sample index ofjobs

The following is a sample index of jobs that will appear at the end of your JobActivity Report:

JOB INDEX

JOB NAME APPL NAME PAGE-------- --------- ----PAYJOB01 PAYROLL 1PAYJOB02 PAYROLL 2PAYJOB03 PAYROLL 2END OF LIST

Sample index ofApplications

The following is a sample index of Applications that will appear at the end ofyour Job Activity Report:

APPLICATION INDEX PAGEAPPL NAME JOB NAME PAGE--------- -------- ----PAYROLL PAYJOB01 1 PAYJOB02 2 PAYJOB03 2END OF LIST


337


Suppressingfields

To suppress certain fields, use the NODISPLAY parameter. You can suppressthe following fields:

Field DescriptionCALENDAR Calendar name(s)CLASS Job classCPU CPU timeELAPSED Elapsed execution timeEVENT Event nameHOLDCOUNT Hold countJCLDS JCL data set and member namePGMER Programmer namePRED List of predecessor jobsPROC ESP Procedure data set and member nameRESOURCE List of resourcesSCOPE Scope (externals and manuals only)SUCC List of successor jobsTAG TagTAPES Tape drives and mounts (both cartridge and reel)

Example The following example suppresses the display of CPU time, elapsedexecution time, and tape drives and mounts.

JOBMAP DSN('ESP.MAPGEN') NODISPLAY(CPU,ELAPSED,TAPES)

338

Producing a Job Descendent Report

Introduction Use the JOBTREE command to produce a job descendent report. This reportlists a job and all successor, or descendent, jobs.

Since the JOBTREE command uses the job mapping data set as input, youcan report only on jobs contained in that data set. You can use the JOBTREEcommand in batch, by executing PGM=ESP with the correct SUBSYSparameter, or in page mode.

To use the JOBTREE command, you must specify the name of the jobmapping data set, the specific name of a job, and optionally the name of anApplication to which the job belongs. If you do not specify the name of anApplication, ESP examines all Applications in the job mapping data set for amatch and uses the first one that it finds.

Example -UsingJOBTREE inbatch

In the following example, a Job Descendent Report is produced for jobPAYJOBA. The subsystem name for ESP, in this example, is ESPM.

//MYJOB...//S1 EXEC PGM=ESP, PARM='SUBSYS(ESPM)'//SYSPRINT DD SYSOUT=*//SYSIN DD*JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)

Example -UsingJOBTREE inpage mode

The following example creates a Job Descendent Report, for job PAYJOBA,in page mode.

JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)

Example In the following example, a job descendent report is produced for jobSTART.APPL in the PAYROLL Application.

JOBTREE DSN('ESP.MAPGEN') JOB(START.APPL) APPL(PAYROLL)


339

Producing a Job Descendent Report, Continued

Reviewing theoutput

The report uses indentation to indicate successor relationships. A job that isindented farther than the job on the previous line indicates a successorrelationship.

Consider the following flow of jobs:

PAYJOBA

PAYJOBB PAYJOBC

PAYJOBD

PAYJOBE

A Job Descendent Tree for PAYJOBA looks like the following. This indicatesthat PAYJOBA releases PAYJOBB and PAYJOBC, PAYJOBB andPAYJOBC release PAYJOBD, and PAYJOBD releases PAYJOBE.

JOB DESCENDENT TREEPAYJOBA JOB PAYROLL

PAYJOBB JOB PAYROLLPAYJOBD JOB PAYROLL

PAYJOBE JOB PAYROLLPAYJOBC JOB PAYROLL

PAYJOBD JOB PAYROLLPAYJOBE JOB PAYROLL

340

Putting it All Together

Sample batchjob

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 jobname (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)/*

341

ESP FLOWDOC

Overview ESP FLOWDOC provides the ability to generate reports detailing informationabout workload scheduled by ESP Workload Manager. The following outlineswhat information 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)⇒ jobname⇒ hold count⇒ released jobs⇒ resource information⇒ scope information (look back/ahead times for manual or external jobs)⇒ external job information (Application and job names)

Graphicalrepresentation

The entire process is represented as follows:

User Input ESP

CYBES091

CYBES090

SAD File

FlowDoc

VSAM


342

ESP FLOWDOC, Continued

ESPFLOWDOCcomponents

ESP FLOWDOC consists of three components:

1. ESP data generation2. Database generation3. Report generation

ESP datageneration

In order to generate the ESP information, an ESP SADGEN request is made.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)/*


343


Databasegeneration

The database generation step is used to create the VSAM database. Thefollowing 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

Note: The space allocated for the VSAM database should be approximately25% greater than the space consumed by the SADGEN data set.


344


Reportgeneration

ESP generates reports by Event or Application name along with a date range.Wild cards are permitted in the selection criteria. The following JCL would beused 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 PREFIX and NAME must be specified.

If selection by Applications is desired, the APPL parameter must be specified.Applications and Events are mutually exclusive. The names specified cancontain wild cards.

If a range of dates is desired, the FROM and TO must be specified. If only asingle date is desired, then DATE should be specified. Single dates and dateranges are mutually exclusive.

Multiple FLOWDOC statements may be present in the input stream.


345


Reportorganization

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 anEXTERNAL job, the referencing job name and Application name for that jobis shown provided that the referencing job is part of an Application which isalready on the database.

Repeated executions of an Application or Event are grouped together toeliminate redundant reporting. These repeating Applications are shown bydate. If there is any variation in the sequence of jobs executed, each variationwill be shown separately. For example, if an Application has a series of jobswhich run daily but some which only run on Monday, a thirty day reportwould display twenty five executions of the Application showing all of thenon-Monday jobs and four executions of the Application showing all jobs.


346


Reportheadings

The following shows the headings as they appear in the report, and what theymean:

Heading DescriptionHOLD This field is set to Y if the ESP JOB definition statement

specified the HELD keyword.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 itis blank, then the ESP SADGEN process has determinedno specific time. This time reflects ESP 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 hold count as determined by ESP. If a job

does not have a hold count, i.e. no predecessor(s), then avalue of 0 will be placed in the hold count field.

RELEASES This lists all of the jobs (two per line) which are releasedby this job. If a job does not have any successor(s), then“(NONE)” will be placed in the release field.

RESOURCE This lists all of the resources (one per line) which areused by this job.

SCOPE These fields are only present for external jobs. Theyrepresent the first and second scope times in the formathh: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 jobname. A “downstream” job is a job that references thisjob as an external. It may release this job or it mayrequire this job as a predecessor.


347


Sample reportgeneration jobs

The following are examples of report generation jobs that could be used toproduce ESP FLOWDOC reports:

Example 1 The following report generation JCL could be used to produce a reportdetailing information about the PAYROLL Application starting today endingtomorrow:

//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 reportdetailing information about an Application which is invoked be an Eventcalled CYBER.PAYROLL on August 29th, 1997:

//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, 1997’)

Example 3 The following report generation JCL could be used to produce a reportdetailing information about the BILLING Application from 4pm today until4pm 2 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’)


348


Example 4 The following report generation JCL could be used to produce a reportdetailing information about the CLAIMS Application from Monday to Friday.Jobs in the CLAIMS Application that have varying run frequencies will bedisplayed on their respective day, i.e. jobs coded as ‘RUN MONDAY’ will bedisplayed 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 JCLand report

The following example shows the report generation JCL and the reportproduced by that JCL.

Reportgeneration JCL

The following report generation JCL could be used to produce a reportdetailing information about the PAYROLL and ACCTPAY Applicationsfrom September 12, 1997 until September 13, 1997:

//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’)


349


Sample ESPFLOWDOCreport

The following FLOWDOC report results from the previous JCL:

APPLICATION: PAYROLL

RUN DATES: FRI 12 SEP 1997

SUB *** SUCCESSOR *** HOLD TAG TYPE TIME 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 ACCTPAY ACCT1 N PAYROLL JOB 20.00 PAY5 1 PAY6 N PAYROLL JOB 20.00 PAY6 4 PAY7, PAY8 PAY9 N PAYROLL JOB 20.00 PAY7 1 PAY10 N PAYROLL JOB 20.00 PAY8 1 PAY10 ACCTPAY ACCT5 N PAYROLL JOB 20.00 PAY9 1 PAY10 N PAYROLL JOB 20.00 PAY10 3 END CPUABS

350

Flowcharting

Introduction Schedulers and operators sometimes find it helpful to have a graphicalrepresentation of the workload. Graphic flow charts make it easier to see jobdependencies and to monitor the progression of work.

Creatingflowcharts

You can create flow charts of workloads using the following PC basedgraphics software:

• MS Project• TIMELINE.

ESP produces an input file for the PC software. This input file is then used increating the graphic flow chart of the workload. You have the option ofviewing the ESP workloads on the PC, or sending the output to the PC printeror plotter when you want a paper copy.

Generation of flow charts consists of some operations on the mainframe, a PCfile transfer, and some additional operations on a PC.

For a real-time, graphical view of the workload, refer to the ESP WorkstationUser’s Guide.

351

Generating Flowcharts Using MS Project

Introduction ESP’s GENPROJ feature exports data that describe an existing ESPApplication in a format that can be used by PC based project managementsoftware, Microsoft Project.

Exported fields The exported fields include:

• Jobname• SubApplication name• Start date and end date• Duration• Late start time and late end time• Percent complete• Tag.

GENPROJfeature

This section describes how to test and use the GENPROJ feature.Follow these instructions:

Step Action1 Create a data set to receive the GENPROJ data. The recommended

DCB attributes are RECFM=FB, LRECL=80, BLKSIZE=3120.However, you can use any sequential or partitioned data set withVB or FB format and an LRECL of at least 72.

2 Create an active ESP Application or use an Application you candisplay using the LISTAPPL command. If you need to create adummy test Application, you may want to insert a built-in delayprior to the first job by using an EARLYSUB command. Thisensures that the Application does not complete prior to theGENPROJ data extract. For example:

APPL TESTAPPLJOB JOB1EARLYSUB NOW PLUS 24 HOURSRUN DAILYRELEASE JOB2ENDJOB


352

Generating Flowcharts Using MS Project, Continued

GENPROJ feature (continued)

Step Action3 Use the GENPROJ command to extract data from the Application.

For example:

GENPROJ TESTAPPL.0 DATASET('SYS1.TESTAPPL.GENPROJ')

4 Download the data set (SYS1.TESTAPPL.GENPROJ) to a DOSfile, like TESTAPPL.TXT, using your installation’s file transferprocedure. You should specify the ASCII and CRLF file transferoptions.

5 Execute the Cybermation-supplied utility CONVERT.EXE onyour PC. You may need to copy this program from a diskettesupplied by Cybermation. If your installation did not receive thisdiskette, please contact Cybermation Technical Support. At theDOS prompt, or in Windows: File Run, switch to the appropriatedirectory and enter: CONVERT <input file> <output file>.For example:

CONVERT TESTAPPL.TXT TESTAPPL.MPX

The extension ‘.MPX’ identifies the file as an Microsoft Projectfile. If you enter CONVERT without operands the commandsyntax is displayed.

6 Start Microsoft Project on your PC. Within Microsoft Project,open the .MPX file, for example TESTAPPL.MPX. Once theproject has been opened within Microsoft Project, it can bemanipulated and viewed in the same way any other project. APERT chart displays the Application horizontally with each jobshown as a box within the chart. Bold boxes identify critical pathjobs. Boxes with a diagonal slash indicate that this job is complete.You should save the Application as a project file, e.g.TESTAPPL.MPP. Subsequent GENPROJ data extracts can beused to update the project status of an Application.


353

Generating Flowcharts Using MS Project, Continued

Illustration ofsteps 1-5

These steps are illustrated below:

APPL on APPLFILE

mydsn

mydsn.txt mydsn.mpx

mydsn.mpp

GENPROJ

Convert

download

MS Project

354

Generating Flowcharts with ESP and Timeline

Introduction ESP’s GENFLOW feature exports data that describes a scheduled ESPApplication in a format used by the PC based project management software,Timeline. ESP uses information from a Scheduled Activity data set andexports the following fields:

• Jobname• Start time and end time.

GENFLOWfeature

This section describes how to test and use the GENFLOW feature.Follow these instructions:

Step Action1 Access ESP in Page mode. Issue the GENFLOW command,

specifying two positional parameters:

• The name of a scheduled activity data set (SADGEN file). ESPuses this data set as input.

• The name of a file to which GENFLOW will write the data. Ifyou do not specify the DCB attributes, GENFLOW sets themto: 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 7characters. The FLOW command also identifies jobs and/orApplications to be included.

3 After the flow commands have been entered (you can specify asmany as required), type GO. ESP reads the SADGEN file andwrites the output to the target file.

GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER'FLOW PAYROLL APPL(PAYROLL)FLOW BACKUPS JOBS(BACK-)GO


355

Generating Flowcharts with ESP and Timeline, Continued

GENFLOW feature (continued)

Step Action4 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. Eachsection is preceded by a file identifier in the form:--ffffx.CSV where ffff is the flow ID, and x is T for TASK or Dfor dependencies.For the above 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 adependency section, ffffD.CSV, where ffff is the ID on the FLOWstatement.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 theflowchart, use the GRAPHIC, PERT function.


356

Generating Flowcharts with ESP and Timeline, Continued

Illustration ofsteps 1-8

These steps are illustrated below:

SADGEN file mydsn

mydsn.txt

mydsn.mlp

GENFLOWFLOWGO

Split file

download

Timeline

chart1t.csv

chart1d.csv

357

Job Documentation

Overview

Introduction ESP’s job documentation facility lets you create a complete and centralizeddefinition of each one of your jobs. This powerful feature allows you todocument a job’s entire requirements, including its predecessors andsuccessors, its schedule frequency, all the resources it requires, and so on.Users and operators can retrieve the job documentation information easilyusing the JOBINFO command or through the Consolidated Status Facility.Job documentation may also be used for informational purposes.


Topic See PageContents of Job Documentation 358Control Information 359User Description 360Creating Job Documentation 362Using The Jobs Option 363Updating Job Documentation 366Using Job Documentation 367Using the Control Information 368Referencing Job Documentation Members 370Overriding Job Documentation 371Using Job Documentation for Qualified Jobs 372Using Job Documentation for Links and Tasks 374Retrieving Information 376Converting Existing Job Documentation 378Other Uses of Job Documentation 381

358

Contents of Job Documentation

Introduction A job documentation entry is a member of a partitioned data set (PDS). Eachentry consists of the following information in two parts, either of which isoptional:

Job documentation entry ExplanationControl information Information that ESP will use

directly when processing a job, suchas the JCL library, job dependencies,and schedule frequency.

User description Other information you wish to storeabout a job. This may includeABEND codes, messages, restartinstructions, job severity, and so on.

Comment Either section may include comments within ‘/*’ ‘*/’ pairs.

359

Control Information

Introduction The control information comes first in your job documentation entry andfollows a very specific format, as shown below:

jobname: JOBDOC

Example For example, to specify the start of job documentation for the Job PAYJOB1enter the jobname followed by a colon, a space and the JOBDOC keywordlike this:

PAYJOB1: JOBDOC

Using CLANGand REXX

Control information uses the same job statement information you use in anESP Procedure. You can also use CLANG and REXX within jobdocumentation to handle conditional or complex requirements.

Examplecontrolinformation

Control information is specified as shown below:

PAYJOB: JOBDOCDATASET PROD.JCL.CNTLRELEASE (PAYJOB2,PAYJOB3)CCFAIL (STEP,GT,4)RUN WORKDAYSIF MONDAY(‘MONDAY’) THEN DELAYSUB 7PM ELSE DELAYSUB 6PM

Storingrequirements

You may choose to store all requirements for a job in a job documentationlibrary. Alternatively, you can also store some requirements in ESPProcedures and others in job documentation members. For example, you maychoose to use job documentation to store only the resource requirements for ajob and use ESP Procedures to store scheduled frequency, job relationships,and time dependencies.

360

User Description

Introduction The user description section of your job documentation must begin with thekeyword USERDESC as a heading. After that, the rest of the data can beformatted as you choose. You can divide the user description section intoparagraphs and identify each paragraph with a label. This will allow you toretrieve selected information by label name. ESP supplies the followingstandard labels:

ESP Label Use this Label to…FUNCTION Describe what the job does.PROGRAMMER Identify the programmer of the jobABENDS Identify ABEND codes and recovery activity. A

number sign (#) may precede each ABEND code. Thislets you request display information about a specificABEND code when retrieving information with theJOBINFO command.

MESSAGES Identify message codes and recovery activity. Anumber sign (#) may precede each message ID code.This lets you request display information about aspecific message ID when retrieving information withthe JOBINFO command.

Customizedlabels

You can use any of your own labels as long you observe the followingguidelines:

• A label consists of a word, 1-16 characters long, followed by a colon andat 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.


361

User Description, Continued

Example In the example below, the USERDESC keyword identifies this as the userdescription area of job documentation. Each of the five user descriptionparagraphs begins with a label (i.e. 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

362

Creating Job Documentation

Introduction Create one entry for each job you want to document. Use a member nameequal to the jobname; otherwise you will need to override this in an ESPProcedure. To create job documentation, use either ISPF edit or the Jobsoption of the ESP Main Menu

363

Using The Jobs Option

Introduction The Jobs Option (Option J on the Main Menu) provides panels for creatingjob documentation members. These panels do not provide fields for allpossible data, but they can assist you in specifying some of your requirements.You can then add to these requirements using ISPF edit.

Creating a jobdocumentationmember

Follow these steps to create a job documentation member for a job:

Step Action1 Select Option J

Note:The first time you select this panel, you must specify the name ofthe pre-allocated PDS file to store job documentation. This PDSthen becomes your default.

2 Complete the jobname and other control information on the JobSpecifications screen, as shown below.


364

Using The Jobs Option, Continued

Step Action3 Enter 1 on the command line to access the Job User Description

panel.4 Complete any user description information, as shown below.

5 If you have DJC or JES3 installed you can enter 2 on the commandline to define DJC/JES3 specifications. Refer to the AdvancedUser’s Guide for more information.

6 Press PF3 twice to return to the Main Menu.


365

Using The Jobs Option, Continued

Result You have now created and stored job documentation. ESP stores theinformation in a member of the job documentation PDS with the same nameas the jobname. 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 noteabout theexample shown

In this example, notice the following:

• The first line identifies the jobname 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.

366

Updating Job Documentation

Introduction You can return to the PDS member where your job documentation entryresides and update the information using either ISPF edit or the ED commandfrom the Consolidated Status Facility.

Note:Do not use the Job Specifications panel (Option J) to update existing jobdocumentation. 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 anerror message indicating the member already exists.

Updating thepreviousexample

For example, you could update the previous example to:

• Insert IF-THEN-ELSE statements to allow for different delayedsubmission times

• Insert a RUN statement to identify the job’s frequency• Add a user field to identify the job’s severity.

Resulting jobdocumentation

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

367

Using Job Documentation

Introduction You can use job documentation in the following ways:• To control processing using the control information directly• To allow retrieval of information.

368

Using the Control Information

Introduction To use the control information directly, you must use the DOCLIB statementin an ESP Procedure. This statement identifies the name of your jobdocumentation 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 thisProcedure.

APPL PAYJOBSJCLLIB ‘CYB.JCL.CNTL’DOCLIB ‘CYBER.JOBS.DOC’JOB PAYJOB1JOB PAYJOB2JOB PAYJOB3ENDJOB

ESP then uses the job documentation information to establish dependenciesand any other requirements. To invoke this Procedure, use an INVOKEcommand in an Event.


369

Using the Control Information, Continued

Relationshipwith Event andProcedure

The diagram below shows the relationship between an Event, an ESPProcedure and a job documentation library. When ESP executes the Event, theINVOKE command invokes the ESP Procedure. The DOCLIB statement inthe ESP Procedure identifies the name of the job documentation library. ESPretrieves the job documentation (if it exists) for each job identified by a JOBstatement. This includes jobs submitted as part of the ESP Procedure, links,tasks, qualified jobs, external jobs, and manual jobs.

A: JOBDOCRUN DAILYRELEASE B

Job Documentation Library

DOCLIB . . .JOB AINVOKE . . .

ESP ProcedureEvent

370

Referencing Job Documentation Members

DOCMEMkeyword

ESP retrieves job documentation by jobname. If you wish to reference a jobdocumentation member with a name other than the jobname, use theDOCMEM keyword 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)

371

Overriding Job Documentation

Introduction Job information can be specified in different places. This includes ESPProcedures, job documentation, and tracking models. As a result, it is possibleto have conflicting information specified for a job. Therefore, you mustensure ESP knows which information to use.

Rules ESP uses the following rules:

Type of information …overrides correspondingESP Procedure information… … job documentation information.Job documentation information… …tracking model information.

Example For example, if you specify a HISTFILE as below, it overrides the HISTFILEspecified in a tracking model for the job.

APPL PAYJOBSDOCLIB ‘CYBER.JOBS.DOC’JCLLIB ‘CYBER.JOBS.JCL’JOB PAYJOB1HISTFILE HIST2RUN DAILYENDJOB

Temporaryoverride

You can temporarily override the control information specified in jobdocumentation from within an ESP Procedure by specifying the new controlinformation you want to use. In this example, the RELEASE statement forPAYJOB1 overrides any RELEASE statement specified in the jobdocumentation for the job.

DOCLIB ‘CYBER.JOBS.DOC’APPL PAYJOBSJOB PAYJOB1 RELEASE NEXTJOBENDJOB

372

Using Job Documentation for Qualified Jobs

Job qualifier ESP uses the 8-character jobname to access job documentation. If you wish touse job documentation for jobs defined with a job qualifier, you can do one ofthe following:

• Use the DOCMEM keyword when you define the job in the ESPProcedure and specify the name of the member used for the job’sdocumentation.

• Use IF-THEN-ELSE logic in the job documentation member to check thequalifier of a job and process different statements. Use the ESPAPQUALsymbolic variable for jobs in an Application. Use the ESPJQUAL variablefor jobs in a DJC/JES3 network.

Each approach is illustrated below.

DOCMEMmethod

This method shows you how you use different job documentation membersfor 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. ESPprocesses 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.Visually, the dependencies look like this:

A.RUN1

Y

A.RUN2

Z


373

Using Job Documentation for Qualified Jobs, Continued

Jobdocumentationmember

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

374

Using Job Documentation for Links and Tasks

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

Example:Documentinglinks and tasks

In this example, the Application consists of a job, a task, and a link. TheApplication identifies their names and the job documentation library containsthe processing requirements, as shown below:

Example:Documenting ajob and a link

This example uses job documentation to store resource requirements. In thisApplication there are two jobs: MEMOBACK and MEMOBACK.MSG. Thespecifications are that:

• The first job requires 1 unit of a resource called DB2TAB• The second job is a link that sends a message when job MEMOBACK

completes successfully.


375

Using Job Documentation for Links and Tasks, Continued

IF statement ESP uses the same job documentation member for each job since it does notcheck the qualifier when accessing job documentation. In order to prevent thelink from using the resource, the job documentation member forMEMOBACK uses an IF statement to assign a resource requirement to theunqualified job only.

The ESP Procedure and job documentation member look like this:

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

376

Retrieving Information

Introduction You can retrieve job documentation information using the ConsolidatedStatus Facility (CSF), or the JOBINFO (JI) command from the operatorconsole, the ESP command processor, or ISPF interface (Line mode or Pagemode). You can display all information for a job or display selectedinformation as identified by fields and labels.

Using CSF You can access job documentation information directly from CSF with thefollowing commands.

Command Explanation BD Browse job documentation ED Edit job documentation

ESP retrieves the information from the data set identified by the DOCLIBstatement in an ESP Procedure. Using this method ESP retrieves allinformation on the job. You cannot select individual fields.

Using TSO If a job is submitted by an ESP Procedure, ESP searches the jobdocumentation library identified by the DOCLIB statement. If a jobdocumentation library was not identified in the ESP Procedure, or the job wasnot scheduled from an ESP Procedure, the JOBINFO command looks for thefile name ‘JOBDOC’. If the file is allocated, it is opened and searched for amember corresponding to the jobname. The JOBDOC file may consist of aconcatenation of several partitioned data sets.

To use the JOBINFO command in TSO you must pre-allocate a file to yourTSO session, either in LOGON procedure or LOGON CLIST. You candynamically allocate this file during a session by issuing the following TSOcommand:

ALLOC FI(JOBDOC) DA(‘data set name’) SHR

Using anoperatorconsole

The console version of the JOBINFO command requires the JOBDOC file inthe ESP started task procedure. You can issue the following commands froman operator console, or from Page mode, respectively:

F ESP,JOBINFO jobname or OPER JOBINFO jobname


377

Retrieving Information, Continued

Examples:Retrieving jobdocumentationinformation

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 ofthe 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 jobdocumentationinformation

The following table summarizes where and how you can retrieve jobdocumentation information:

Origin Command Retrieved fromConsolidated StatusFacility

BD or ED Library specified in the ESPProcedure

Page mode or line mode JOBINFO DOCLIB in ESP Procedure orJOBDOC DD allocated to yourTSO session

Page mode or line mode OPER JOBINFO JOBDOC DD allocated to theESP started task

Operator console F ESP,JOBINFO JOBDOC DD allocated to theESP started task

378

Converting Existing Job Documentation

Methods forconvertingdocumentation

You may already use some form of job documentation other than ESP’s thatyou would like to convert. There are two methods for convertingdocumentation. The method you use depends on how you want to use yourexisting job documentation.

• If you want to use ESP to retrieve your existing job documentation in itspresent format, you can insert a USERDESC label in each jobdocumentation member.

• If you want ESP to modify the data to allow retrieval of information bylabel name, you can use the GENDOC command.

Retrievingexisting jobdocumentation

In order to retrieve your existing job documentation through ESP, followthese steps:

Step Action1 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 file(s), with the DD name ofJOBDOC, to your TSO session or to the ESP started task. Thisenables you to use the JOBINFO command to extract information.


379

Converting Existing Job Documentation, Continued

Introduction You can convert an existing PDS job documentation library into an ESPdocumentation library using the GENDOC command in Line mode, Pagemode or in batch.

The GENDOC command identifies the input data set, members to be copied,and the output data set. It also lets you identify changes you want to makewhen the old documentation converts.

Commands You can use the following commands:

Command ExplanationREMOVE Identifies lines that are not to be copied to the output data set.LABEL Alters or replaces lines in the output data set, or inserts lines at

different locations.GO Indicates that all specifications are complete and that the copy

process should proceed

New data set For each selected member of the input data set, ESP generates acorresponding member in the output data set. ESP automatically adds thefollowing two lines to each member of the new data set:

jobname: JOBDOCUSERDESC

GENDOC can insert appropriate paragraph labels in the converted userdescription section to allow retrieval of information by label.


380

Converting Existing Job Documentation, Continued

Example:UsingGENDOC toconvert jobdoc.

Below is a set of sample conversion instructions for ESP:

GENDOC JOBDOC.DATA ESP.JOBDOC.DATA LEV(A-,B-) SNUMREMOVE ‘**’LABEL ‘SYSOUT REVIEW’ ‘SYSOUT_REVIEW’ INLINELABEL ‘RESTART PROCEDURES’ ‘RESTART:’ BEFOREGO

The above example tells ESP to:

• Copy all members beginning with ‘A’ and ‘B’ from the data set‘JOBDOC.DATA’ to the data set ‘ESP.JOBDOC.DATA’, suppressingany line numbers in the right-hand 8 columns of each source memberrecord.

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

Message at theend of theconversion

ESP issues the following message at the end of the conversion to indicate thenumber of members in the input and output data sets.

ESP000 nnn MEMBERS IN SOURCE DATASET, mmm MEMBERS PROCESSED

381

Other Uses of Job Documentation

Introduction You can use ESP’s job documentation facility for more than just jobs. Youcan 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 phonenumbers

This example shows you how to use a job documentation member to listphone numbers for software support. A label identifies the name of eachproduct 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 phonenumbers for ESP by typing the following:

JI SUPPORT FIELD(ESP)

ESP: REGULAR (905) 479-4611 AFTER_HOURS (416) 287-5021

OutputInput

383

Using Resources

Overview

Introduction You can ensure that jobs in an ESP Application are submitted only when allof their resource requirements are met. Because you do this without the needfor manual intervention, there are no unnecessary delays before a job starts.ESP’s Resource feature allows you to automate resource management.

Note:Before you start to use ESP’s Resource features, your Systems Programmerneeds to define a resource data set called the RESFILE, and specify the CPUsand nodes in your environment. If you want ESP to make default resourceassignments, the RESDFLT initialization statement must also be specified.


Topic See PageWhat is a Resource? 385Types of Resources 386Scope of Resources 387Using Real Devices 388Routing Jobs to Other Systems 389Managing Jobs 390Requesting Resources 391Default Resources 396Working with Resources 398Defining Resources 399Setting Resources 401Deleting Resources 402Displaying Resource Information 403Step-level Resource Release 405Resource Absorption 407Example: Controlling Mutually Exclusive Jobs 410Example: Controlling Access to an Online System 412Example: Time Periods for Low Priority Jobs 414Example: Using a Resource for a Self-completing Task 416Example: Controlling Access to a Database 417


384

Overview, Continued

In this chapter (continued)

Topic See PageExample: Running Jobs on a Particular System 418Example: Controlling Mutually Exclusive Groups of Jobs 420Example: Planning for a System Shutdown - Part 1 424Example: Planning for a System Shutdown - Part 2 426Example: Schedule Dependency 428

385

What is a Resource?

Definition of aresource

A resource is any type of real or abstract object that impacts a job’s ability torun successfully and can be quantified. Resources are classified by resourcetype and by scope.

Examples ofresources

Some examples of resources are:

• Tape drives• Scratch tapes• Online systems• Databases• Time periods• The completion of a job.

386

Types of Resources

Three types ofresources

ESP resources are classified into three types. They are:

• Renewable• Depletable• Threshold.

Renewableresource

A renewable resource is a ‘borrowed’ resource. When a job is submitted byESP, the job removes the resource from the resource pool. However, theresource is not permanently used up. Instead, it is returned to the resourcepool at the end of execution, whether successful or not. In other words, the jobtemporarily ‘borrows’ the resource to allow it to execute successfully.For example:A renewable resource can be used to control concurrent access to a database.

Depletableresource

A depletable resource is a ‘consumed’ resource. When a job is submitted byESP, the job removes the resource from the resource pool, and does not returnit at the end of execution. The resource is used up and can only be replenishedthrough an explicit action, such as issuing an appropriate ESP command. Thejob needs to consume the resource in order to execute successfully.For example:A depletable resource can be a scratch tape, which is removed from the poolwhen a job writes a permanent data set onto it.

Thresholdresource

A threshold resource is a ‘sizing’ resource. A job does not actually remove theresource from the pool of resources while it executes. You can think of athreshold resource as a variable height doorway into the system. If theresource quantity is set to 2, any number of jobs requiring 2 or less units aresubmitted. However, any job requiring 3 or more units are too high to passthrough the door and so are not submitted. ESP sizes the job against thecurrent level of the threshold resource.For example:A threshold resource can be used to represent elapsed time and limit the sizeof jobs entering the system. This allows you to prevent long-running jobsfrom being submitted just before scheduled downtime.

387

Scope of Resources

Resource levels You can classify the scope of the resources you define according to thefollowing resource levels:

Type of resource ExplanationLocal 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 oneESP system submits the work for all nodes.

388

Using Real Devices

Overview A real resource represents an actual hardware device. It is normally used fortape transports. The limitation is that they can work properly only in a singleCPU environment. There is no capability to be aware of the status of deviceson any CPU other than the one where the master ESP is running.

Device counts ESP determines the available count by first looking at the system controlblocks for the resources. Then ESP counts how many of the UCBs (unitcontrol blocks) within that device group are currently online and not allocated.If ESP schedules a job that requires a tape device, it could be several secondsor minutes before the job actually allocates the UCB. ESP ensures that it doesnot over-allocate a resource when scheduling jobs that require it. ESP uses aneffective available count that is the lower of the following values: real valueand the available count maintained by ESP.

Example For example, if a job requires three units of a real resource, and ESP’savailable count is three, ESP waits for the resource if there are only twodevices actually online and unallocated.

389

Routing Jobs to Other Systems

Overview In a multiple CPU environment, a job may require a mix of resources that arenot available on the ESP system submitting the job. However, these resourcesmay be available on another processor, either on the current node or on aremote node. ESP tries to find all the resources a job requires on one system.

Routing JCL ESP can automatically insert the appropriate JCL into a job to ensure the jobis routed to the required node or processor. The JCL ESP uses to route jobs isspecified as part of the NODE and CPU definitions in your ESP InitializationParameters. These are normally a/* EXEC nodename card and a /*JOBPARM SYSAFF=xxxx card.

Example For example, if ESP builds an Application on SYSA but the resource a jobneeds is on SYSB, ESP routes the job to SYSB. If these systems are withinthe same JES node, ESP submits the job and inserts a /*JOBPARMSYSAFF=SYSB card to route the job to SYSB.

Gravity ESP can cause a job to be routed to a remote node only if one of the resourcesrequired by the job has the GRAVITY attribute in its definition. ESP can causea job to be routed to another CPU within the same node regardless of theGRAVITY setting.

390

Managing Jobs

Overview When the Application Manager readies a job for submission, it checks to seeif the job has requested any resources. If so, the Application Manager passesthe job to the Resource Manager component. The Resource Manager submitsthe job when the required resources become available. If all of a job’sresource requirements cannot be met, ESP does not submit the job.

Multipleresources

If a job requires multiple resources, or multiple units of a single resource, andall of these resources are not available when the job is readied for submission,ESP does not hold on to any resources. As soon as another job ends that isusing a resource this job needs, or the resource status changes in any way - forexample, by the RESDEF command being issued - the job is rechecked forsubmission.

Renewableresources

If a job is using a renewable resource, the resource is taken when the job issubmitted and is freed up as soon as the job ends, whether it is successful ornot. A failed job, by default, has the same resource requirements upon restartas at submission time.

391

Requesting Resources

Overview To identify the resources required by individual jobs or by an Application,you use the RESOURCE statement within an Application definition. This canbe done at an Application level or at a job level. An individual job can requestany 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 canuse:• The RESOURCE statement• The PRIORITY statement.

Using theRESOURCEstatement

Use the RESOURCE statement to identify resource requirements. Inparenthesis, specify the number of units required, followed by the resourcename. If you omit the number of units, ESP uses a default of 1.

For example, to specify 1 unit of a resource called CICS, use:

RESOURCE (1,CICS) or RESOURCE (CICS)

If you want to request more than one resource, string your resourcespecifications together. For example, if your requirements are one unit of theresource called CICS and two units of a resource called SCRATCH, specify:

RESOURCE (1,CICS,2,SCRATCH)

Placing theRESOURCEstatement

When you use a RESOURCE statement within an Application to providespecific resource information for an individual job, you place the statementbetween the JOB ... ENDJOB pair. The RESOURCE statement then affectsonly that individual job. It also overrides any resources that occur before theJOB ... 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 untila new RESOURCE statement, outside the scope of a JOB statement, occurs.Jobs inserted into an Application after it has been generated do not inherit anyresource requirements.


392

Requesting Resources, Continued

Example:Requestingresources

In the following example, all jobs in the Application require 1 unit of theNITESHFT resource except job A that requires 1 unit of the CICS resource.

APPL ABCJCLLIB 'CYB.ESP.JCL'RESOURCE (1,NITESHFT)JOB A RESOURCE (1,CICS) RUN DAILYENDJOBJOB B RUN DAILY ENDJOBJOB C RUN DAILYENDJOB

Addingresourcerequirements

The ADD keyword on the RESOURCE statement allows you to specifyresources in addition to the resource requirements already specified for a jobor the Application. You use it by specifying RESOURCE ADD, the number ofunits, and then the resource name.

Example In the following example, job A needs 1 unit of the CICS resource in additionto 1 unit of the NITESHFT resource:

RESOURCE (1,NITESHFT)JOB A RESOURCE ADD(1,CICS)


393


Droppingresourcerequirements

The DROP keyword on the RESOURCE statement specifies that one or moreresource requirements are dropped for the jobs that follow, until a newRESOURCE statement occurs either within a JOB ... ENDJOB pair, or outsidethe scope of a JOB... ENDJOB pair. You use it by specifying RESOURCEDROP and then the resource name, like this:

RESOURCE DROP(T3420)RESOURCE DROP(CICS,T3420)

To free a job from any resource dependency (except default resources) youspecify:

RESOURCE DROP

Example In the following example, job ABC requires 1 unit of the LOWPRIO resourceand 2 units of the IMS resource. If the scheduled day is Friday, the LOWPRIOrequirement is removed.

JOB ABC RUN DAILY RESOURCE (1,LOWPRIO,2,IMS) IF TODAY('FRIDAY') THEN RESOURCE DROP(LOWPRIO)ENDJOB

Droppingdefaultresources

You cannot drop default resources using the DROP keyword. Instead, youmust request 0 units of the default resource to indicate you do not want to usethe default resource for a job or group of jobs.

Example In the following example, job ABC does not have the ELAPSED defaultresource assigned to it and has a requirement for 1 unit of CICS.

JOB ABC RESOURCE (0,ELAPSED,1,CICS)ENDJOB


394


Using thePRIORITYstatement

You can use the PRIORITY statement in a job definition to specify the relativepriority of the job within an ESP group. The maximum value is 99; the lowestpriority value, and the default, is 0.

This allows you to prioritize jobs within one group without the possibility ofdelaying jobs in another group. ESP uses the priority when one or more jobs,within the same ESP group, are competing for the same resource. In this case,ESP queues the higher priority job ahead of the lower priority job. Thequeuing sequence of jobs in other groups is not affected. PRIORITY onlyapplies to renewable and depletable resources.

ESP Groups The ESP group name is determined by the Event prefix. For example:

CYBER.nnn identifies a job belonging to the group CYBERPROD.nnn identifies jobs in the PROD group.

For instance, a job that is assigned a priority in a group called CYBER iscompared only to other jobs in the CYBER group, and not to jobs in anothergroup called PROD.

Example:Setting priority

The following example sets a priority of 99 for job BIGJOB. ESP queues thisjob ahead of other jobs from the same group when these jobs are waiting forthe MSTRFILE resource.

JOB BIGJOBPRIORITY 99RESOURCE (1,MSTRFILE)


395


Example:Setting priority

The following example sets a different priority for jobs B, C and D. Each jobrequires 1 unit of a renewable resource called MSTRFILE. When job Acompletes, ESP queues the jobs in the order D, C, B.

JOB A RUN DAILY RELEASE (B,C,D)JOB B RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 10JOB C RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 20JOB D RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 30ENDJOB

396

Default Resources

Introduction ESP can determine some of the significant resource requirements that a jobmight have by looking at the job’s run history. If required, ESP can then makedefault resource assignments automatically.

Defaultassignments

The resources for which ESP 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 adefaultassignment

The information used to assign default resources is based on informationcontained in ESP’s Job Index file. ESP bases the default resource levels that itassigns on an average of the samples found in the Job Index. The number ofsamples depends on the index count specified when the job’s tracking modelwas defined. Only information from normal job completions, and not fromabends, is used. The information is updated each time a new generation of anApplication is created.

Defaultresources

To set up default resources, you need to take these steps:

Step Action1 Use the RESDFLT initialization statement in the ESP Initialization

Parameters to identify the default resource you want to use.2 Issue the RESDEF ADD command to define the default resource.


397

Default Resources, Continued

Example:Default scratchtape resource

The following ESP initialization statement causes ESP to use a defaultresource for scratch tapes. The name of the resource is SCRTAPES.

RESDFLT SCRATCH(SCRTAPES)

The following ESP command defines the SCRTAPES resource as a global,depletable resource, with a maximum quantity of 293.

RESDEF SCRTAPES ADD GLOBAL DEPLETABLE MAX(293)

ESP uses historical information to assign scratch tape resource requirementsto each job in an Application when it creates a generation of that Application.

EffectingApplications

Each Application ESP creates uses default resources you have set up. In anApplication you can code RESOURCE (0,resname) if you do not want ESP toassign default resources for a job, or for an Application.

398

Working with Resources

RESDEFcommand

You define, display, set, and delete resources using the RESDEF command. Ina multiple CPU environment, you must issue the RESDEF command from amaster ESP system. This is normally the same system on which yourApplications are built.

Note:Your ESP administrator needs to grant you the necessary access for thesefunctions.

The following sections describe how to define and work with resources. Referto the Examples section later in this chapter for more examples of usingresources.

399

Defining Resources

Introduction Once you define a resource, the definition is stored in an ESP file, called theRESFILE. This information is saved across restarts of ESP unless ESP isrestarted with the RESFORM option. Resource definitions are normallystored in the ESP Initialization Parameter data set, or another data set thatESP reads at startup time.

Defining aresource

Use the RESDEF command to define a resource. When you define a resource,you need to:

Step Action1 Name the resource, using up to 8 alphanumeric characters, the first

of which must be a letter.2 Use the ADD keyword 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.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 onequantity. You can specify either maximum (MAX) or available(AVAIL). For renewable resources, there are maximum andavailable quantities. Maximum is the total quantity of the resourcethat exists; available is the current quantity.

Indicate whether or not the resource has gravity. This allows a job to be routedto another node if the resource is not available on the node on which the jobwas submitted.

Example:Defining arenewableresource

This example defines a resource called ‘DATABASE’. It is a global,renewable resource with maximum and available quantities of 1.

RESDEF DATABASE ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)


400

Defining Resources, Continued

Example:Defining athresholdresource

This example defines a resource called ‘CICSUP’. It is a local, thresholdresource on SYSA with an availability count of 1.

RESDEF CICSUP ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)

Defining a realresource

A real resource is one that is associated with an actual hardware device. Thisis normally a tape transport. ESP looks at the number of online, unallocateddevices to satisfy a job’s real resource requirement.

DEVICEparameter

To define a real resource, use the DEVICE parameter, on the RESDEFcommand, to specify a valid MVS device name (i.e., legal value for theUNIT= keyword in JCL). The unit name can be a generic, such as 3480, or aninstallation-defined esoteric such as TAPE. Real resources should be definedas local and renewable. Use the MAX parameter to identify the number ofdevices available to ESP submitted jobs.

RESREFRcommand

ESP supplies the RESREFR command to refresh resource status. This may berequired when you change the environment. For example, if a job is waitingfor tape drive resources and you vary more online, ESP is not immediatelyaware of this. The RESREFR command causes ESP to look at theenvironment and refresh the status of real resources.

Example:Defining a realresource

This example defines a resource called ‘T3480’. It is a local, renewable, realresource that represents a device type of 3480. There is a maximum of 20 ofthese devices.

RESDEF T3480 ADD LOCAL RENEWABLE DEVICE(3480) MAX(20)

401

Setting Resources

Changing aresource

Use the SET keyword on the RESDEF command to change the scope or thequantity of a resource. You cannot change the type of a resource withoutdeleting and redefining it.

For depletable and threshold resources, there is only one quantity. You canspecify either maximum (MAX) or available (AVAIL). For renewableresources, there are maximum and available quantities. If you set themaximum, the available count changes. Setting the available count has noeffect on the maximum count.

Example This example sets the available quantity of the resource ‘LOWPRIO’ to ‘1’.

RESDEF LOWPRIO SET AVAIL(1)

Settingquantitiesautomatically

For some resources you might want ESP to set the quantity for youautomatically. For example, you might have a resource called CICSUP torepresent that a started task called CICS is active. You can use ESP toautomatically set the quantity of the resource to indicate the availability. Referto Job Monitoring and Alert Processing in the Advanced User’s Guide formore information.

402

Deleting Resources

Deleting aresource

Use the DELETE keyword on the RESDEF command to delete a resource.This example deletes the resource ‘LOWPRIO’.

RESDEF LOWPRIO DELETE

Note:You cannot delete a resource while any job is using the resource.

403

Displaying Resource Information

CSF and ESPcommands

You can display information about a resource using the Consolidated StatusFacility and ESP commands.

Using theConsolidatedStatus Facility

Using CSF, you can use the LR command for a job to display the resourcesassociated with that job, and determine what jobs have resources allocated. Ifa job is awaiting resources, the status field in CSF states ‘waiting forresources’, and the PNODE field in CSF states ‘RESWAIT’.

In the following example, the LOCKOUT resource is displayed to determinewhat 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.

Using theRESDEFcommand

Use the LIST keyword on the RESDEF command to display one or moreresources. The display shows the name of the resource, the type of resource,and the quantities associated with the resource. You can also display the jobsusing the resource and the jobs needing the resource.

This example displays the CICSUP resource. It is a local, threshold resourcewith an available count of 1 on CPU1 and an available count of 0 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


404

Displaying Resource Information, Continued

Using theLISTAPPLcommand

The LISTAPPL (LAP) command displays resource requirements for jobs notyet submitted in an active Application. Sample output might look like this:

LAP TURNOVER.14 ALLAPPL TURNOVER GEN 14 CREATED AT 13.43 ON TUESDAY AUGUST 4TH, 1998 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

405

Step-level Resource Release

Introduction Step-level resource release allows you to return resources back to the resourcepool at job step-end. Previously, resources would remain allocated to a job forthe duration of the job.

Description Step-level resource release is achieved by the use of a new STEPENDstatement. STEPEND is coded within the scope of the job statement. Youmay release part or all of the resources back to the resource pool. You canhave more than one STEPEND statement in one job.

Types ofresources

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

Parameter Descriptionstepname Indicates the name of the job step.procstep Indicates the name of the proc step.n1,resname Indicates the quantity and name of the resource to be

released.


406

Step-level Resource Release, Continued

Example –Stependstatement

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 resourcelater in the same job:

APPL ONEJCLLIB ‘CYBER.JCLLIB.CNTL’JOB JOBA RUN DAILY RESOURCE (5,T3480) STEPEND STEPNAME(STEP3) PROCSTEP(PROCB) RELRES(2,T3480)ENDJOB

Ensure the stepnames and procsteps you specify match your JCL exactly. Youcan release resources by specifying just a procstep and not a stepname, if thatis how your JCL is tailored.

Note Step-level Resource Release only works if USERMOD 11 is off. WhenUSERMOD 11 is on, the Application Manager does not get step-endnotification.

407

Resource Absorption

Introduction In ESP Workload Manager Version 5 Release 1, jobs that required a largeresource count would encounter processing delays as jobs with low resourcerequirements would continually grab the resource, thus keeping the overallavailable resource count low.

In ESP Workload Manager Version 5 Release 2, Resource Absorptionreserves the resources that are available at the time the job is next in the queueand holds them while waiting to accumulate the remainder of resourcesrequired for that job. Jobs with smaller resource requirements can not use thereserved resource.

Description The ABSORB statement will only ABSORB resources if the request is forless than or equal to the maximum resource defined. An ABSORB statementis coded within the scope of the job, above the RESOURCE statement, whereAbsorption is to occur. ABSORB can also be used at the Application level.

Priority jobs A job with a higher priority and the same resource requirements will take theresources and run before the lower priority job with the ABSORB statement.

Once the higher priority job completes, or has the resources it needs, theprocess of gathering resources starts again.


408

Resource Absorption, Continued

Example –Absorbstatement

The following example shows coding an ABSORB statement within the scopeof 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 ofreserving the required resources, 4 units of T3480. Jobs that follow JOBX inthe queue that require less than or equal to the same resource, and are thesame job priority, will not be submitted before JOBX.

Types ofresources

Absorption is available for the following types of resources:

• Renewable• Depletable.

Example –ApplicationwithAbsorption

The following example shows an Application with an Absorb statement:

APPL ABSRESJCLLIB ‘CYBER.JCLLIB.CNTL’

JOB A RESOURCE (1,T3480)JOB B RESOURCE (1,T3480)JOB C RESOURCE (1,T3480)JOB D ABSORB RESOURCE (3,T3480)JOB E RESOURCE (1,T3480)JOB F RESOURCE (1,T3480)ENDJOBSELECT (A,B,C,D,E,F)


409

Resource Absorption, Continued

Examplecontinued -ApplicationwithAbsorption

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

Examplecontinued –ApplicationwithAbsorption

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

410

Example: Controlling Mutually Exclusive Jobs

Introduction In this example, a renewable resource controls the execution of two jobs sothat they do not execute at the same time.The criteria for this example are:

• Job A and Job B cannot execute at the same time.• Each job requires one unit of a resource called DB2TAB1.

Resource DB2TAB1

Job A Job BWaiting for Resource

Setting -upmutuallyexclusive jobs

Take the following steps to set this up:

Step Action1 Define a global, renewable resource with maximum and available

quantities of 1.

RESDEF DB2TAB1 ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)

2 Specify, in the Application in which each job is defined, arequirement of 1 unit of the resource. For example:

JOB A RESOURCE (1,DB2TAB1)

JOB B RESOURCE (1,DB2TAB1)


411

Example: Controlling Mutually Exclusive Jobs, Continued

Result At any time there is either 1 unit of the resource available, or no units of theresource available. If, for example, job A is executing, the available count ofthe resource is 0 and ESP prevents job B from executing. ESP returns theresource to the system upon completion (successful or not) of job A.

Extending thisexample

You can extend this example to any number of jobs.If you need to control mutually exclusive groups of jobs, see the example laterin this chapter.

412

Example: Controlling Access to an Online System

Introduction This example uses a renewable resource to control the maximum number ofconcurrent job executions.

The criteria for this example are:

• Access to an IMS region is limited to a small number of jobs at any onetime

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

IMS 3

1,IMS

2,IMS

2,IMS

A

B

C

Take the following steps:

Step Action1 Define a local, renewable resource with maximum and available

quantities of 3. The name of the resource is ‘IMS’.

RESDEF IMS ADD LOCAL RENEWABLE MAX(3) AVAIL(3)


413

Example: Controlling Access to an Online System, Continued

(continued)

Step Action2 In an Application, specify the number of units each job requires.

For example,

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

Result ESP processes the jobs as follows:

• Job A is able to run concurrently with either job B or job C.• Jobs B and C can not execute at the same time because they require a total

count of 4 units of the IMS resource.

414

Example: Time Periods for Low Priority Jobs

Introduction This example uses a threshold resource to control when low priority jobs run.The criteria for this example are:

• Low priority jobs can execute between 9 a.m. and 4 p.m. on workdays• At other times, ESP puts low priority jobs into a ‘waiting for resources’

status.

To set this up:

Step Action1 Define a threshold resource with an available quantity of 1. 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 1 unitof the resource, like this:

JOB ABC RESOURCE (1,LOWPRIO)

3 Set up two Events: one to set the quantity of the resource to 0, andthe other to set the quantity of the resource to 1. The Events looklike this:

EVENT ID(OPER.SET_LOWPRIO_ON)SCHEDULE 9AM WORKDAYSVS 'F ESP,RESDEF LOWPRIO SET AVAIL(1)'ENDDEF

EVENT ID(OPER.SET_LOWPRIO_OFF)SCHEDULE 4PM WORKDAYSVS 'F ESP,RESDEF LOWPRIO SET AVAIL(0)'ENDDEF

Result ESP turns the LOWPRIO resource on and off automatically. Any jobrequiring one unit of the LOWPRIO resource can only execute between 9 a.m.and 4 p.m. on workdays.


415

Example: Time Periods for Low Priority Jobs, Continued



Allow low priority jobs

Disallow low priority jobs

9 a.m. to 4 p.m.

4 p.m. to 9 a.m.

In a multiple CPU environment, you might have different time periods to runlow priority jobs on different systems. You can define different localresources and set them independently.

416

Example: Using a Resource for a Self-completing Task

Introduction A link cannot have a resource requirement because a link is marked completeas soon as it becomes ready. Instead, you can use a self-completing task thatrequires a resource.

Self -completing task

This example uses a task called WAIT4.LOWPRIO that requires one unit of aresource 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 readies the task andissues an ESP AJ command to complete itself. This command uses an ESPsymbolic variable (%ESPAPGEN) for the Application generation number toensure the task is marked complete in the correct generation.

417

Example: Controlling Access to a Database

Introduction In this example, a renewable resource controls access to a database.The criteria for this example are:

• Any job that updates the database requires exclusive use of the database.In this example, jobs A and Z update the database.

• Any number of jobs that read the database can execute at the same time.In this example, jobs B and C read the database.


Step Action1 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 unitsrequired. A job that updates the database requires 999 units; a jobthat reads the database requires 1 unit. For example,

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

Result ESP processes the jobs as follows:

• Neither job A or job Z can run concurrently with any of the other jobs,since each of these jobs requires the maximum count for the resource.

• Jobs B and C can run together because they require a total count of 2 unitsof the DBASE1 resource.

418

Example: Running Jobs on a Particular System

Introduction This example uses threshold resources to control on which system a job runs.In a master-slave environment, you may have the requirement for jobs to runon a particular system. Instead of hard coding this requirement in JCL, ESPcan add, at submit time, the JCL required to route a job to a system.

CPU definitions Prior to using the resource feature, CPU definitions are added to the ESPInitialization Parameters that assign names to your master and slave ESPsystems and identify routing JCL for routing jobs to each system. Thesedefinitions 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 theresources

You can represent each system by a local, threshold resource. The name of theCPU must be the same as that identified in your ESP InitializationParameters. For example, the following defines two local, threshold resourcescalled SYSA and SYSB, each with an available count of 1.

RESDEF SYSA ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)RESDEF SYSB ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(1)

Requesting theresource

To specify a job must run on SYSB, request 1 unit of the SYSB resource. Forexample,

JOB XYZ RESOURCE (1,SYSB)

A job may request other resources, which may be either local or global. ESPtries to find all the resources a job needs on one system.


419

Example: Running Jobs on a Particular System, Continued

Result When the SYSB resource is available, ESP submits the job and adds a systemaffinity card for SYSB. For example, ESP adds the following card:

/*JOBPARM SYSAFF=SYSB

420

Example: Controlling Mutually Exclusive Groups of Jobs

Introduction In this example, ESP controls resources such that one group of jobs does notexecute while another group is running. The technique illustrated here can beused whether or not both groups of jobs are in the same Application.

Criteria for thisexample

The criteria for this example are:

• One group of jobs consists of jobs B and D.• The other group of jobs consists of jobs C and E.• All jobs in one group must complete successfully before processing any

jobs in the other group.

Take the following steps to set this up:

Step Action1 Define a global, depletable resource with a maximum quantity of

1.

RESDEF MUTUAL ADD GLOBAL DEPLETABLE MAX(1)

2 Use a different task as a predecessor to each group of jobs. Eachtask requires one unit of the depletable resource and completesitself when the resource requirement is met.

3 Use a link at the end of each group of jobs to reset the availablecount of the depletable resource to 1.


421

Example: Controlling Mutually Exclusive Groups of Jobs,Continued

Visualperspective

Visually, the dependencies look like this:

B

START.2(task)

(job)

A(job)

START.1(task)

C(job)

D(job)

E(job)

RESET.2(link)

RESET.1(link)

A sample Application is shown on the next page.


422


SampleApplication

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


423


Result ESP produces the following results:

• When job A ends successfully, ESP completes one of the tasks and startsprocessing one group of jobs.

• The predecessor task for the other group of jobs requires the MUTUALresource, which is not available.

• When the first group of jobs is done, a link sets the available quantity ofthe MUTUAL resource to 1. This allows the other group of jobs toprocess.

424

Example: Planning for a System Shutdown - Part 1

Introduction You can use the ELAPSED default resource to prevent long running jobsfrom starting prior to a system shutdown. ESP uses historical information toassign elapsed time resource requirements to each job in an Application whenit creates a generation of that Application.

Setting-up thisexample

To set up this example:

• Define the ESP resource representing elapsed time. The name of theresource in this example is RUN_TIME.

• Turn on the default resource called ELAPSED.• Optionally, set up a countdown procedure that you can use prior to a

system shutdown.

Defining theresourcerepresentingelapsed time

The following ESP command defines the RUN_TIME resource as a local,threshold resource, with an available quantity of 9999. If you are running amaster-slave environment, you should define a local resource for each CPUand use the same name for the resource.

RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(9999)

Turning on theELAPSEDresource

The following ESP initialization statement causes ESP to use a defaultresource for elapsed time.

RESDFLT ELAPSED(RUN_TIME)

When ESP creates an Application, each job is assigned a RUN_TIMErequirement, unless you have specified ‘RESOURCE (0,RUN_TIME)’ inyour Application.


425

Example: Planning for a System Shutdown - Part 1, Continued

Setting up acountdownprocedure

The following example uses an Event called OPER.SHUTDOWN thatinvokes an ESP Procedure. When you trigger this Event, specify the numberof minutes until shutdown in the USER1 field.

Actions carriedout by the ESPprocedure

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 threshold resource called

RUN_TIME to the number of minutes until shutdown• Decrements the TIME variable by 1• If the amount of time now left until shutdown is greater than or equal to

zero, ESP re-triggers the Event in 1 minute (the amount of time left ispassed 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')

426

Example: Planning for a System Shutdown - Part 2

Introduction In a master-slave environment, a default resource representing elapsed time(e.g. RUN_TIME) can be used to prevent jobs from being submitted if there isnot enough elapsed time available. If the RUN_TIME resource is defined as alocal resource for each CPU then each CPU can have its own counter. ESPonly submits a job to JES if there is enough of the RUN_TIME resourceavailable on any CPU. Even though JES controls where the job executes, ESPcan automatically insert a system affinity card to control routing.

Resource check When a job’s predecessor and time requirements have been met, ESP checksto see if the required resources are available. For example, ESP checks to seeif enough of the RUN_TIME resource is available for job XYZ on each of theCPUs. If no ORDER has been specified on the CPU definitions in the ESPInitialization Parameters for the master, ESP checks each CPU in the order inwhich they are defined.

Suppose ESP doesn’t find enough of the resource on SYSA but does findenough of the resource available on SYSB, ESP submits the job and adds asystem affinity card to route the job to SYSB. If no JCL has been specified forthe ROUTEJCL parameter in the CPU Initialization Parameter, ESP submitsthe job and JES determines where the job runs.

Multipleresourcerequirements

If a job needs the RUN_TIME resource and must execute on a particularsystem, on SYSA for example, you have two resource requirements. Youshould specify a resource requirement of 1 unit of SYSA in yourApplications. This is a local, threshold resource with quantity of 1. ESP willnot submit a job until enough of the RUN_TIME resource is available and theSYSA resource is available; each of these local resources needs to beavailable on the same system.


427

Example: Planning for a System Shutdown - Part 2, Continued

Defining thesystemresources

Define a local resource that represents the CPU. For example, the followingdefines two local, threshold resources called SYSA and SYSB, each with anavailable count of 1.

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 1 unit of the SYSA resource. Forexample,

JOB XYZ RESOURCE (1,SYSA)

Defining thedefaultresources

The following example defines two local RUN_TIME resources, one forSYSA and one for SYSB.

RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(99999999)RESDEF RUN_TIME ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(99999999)

Setting theresources

You can set the available count of your RUN_TIME resources using theprocedure explained in Part 1 of this example. Use the CPU parameter on theRESDEF command to specify the system on which you are setting theresource. For example,

RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)

The system resources, SYSA and SYSB, may be always available. You maychoose to turn them off when the system is coming down and turn them onwhen the system comes up using ESP or some other form of automation.

Result When enough of the RUN_TIME resource is available and the systemresource (i.e. SYSA or SYSB) is available, ESP submits the job and adds asystem affinity card for the appropriate system.

428

Example: Schedule Dependency

Introduction This example uses a threshold resource to represent the completion of a job.For example, you might have a job that is dependent on an on-request jobwith an unpredictable frequency.In this example, PAYJOB2 requires that the previous run of PAYJOB1 hascompleted successfully.


Step Action1 Define a threshold resource with an available quantity of 0. In this

example, the name of the resource is the same as the name of thepredecessor job, PAYJOB1.

RESDEF PAYJOB1 ADD GLOBAL THRESHOLD AVAIL(0)

2 For the successor job, define the first job as a resourcerequirement.

JOB PAYJOB2 RESOURCE (1,PAYJOB1)

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

JOB END.PAYJOB1 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(1)

• When PAYJOB2 completes successfully, use a link to set theavailable quantity of the PAYJOB1 resource to 0. Thisprevents PAYJOB2 from running without its dependency thenext time it is scheduled.

JOB END.PAYJOB2 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(0)


429

Example: Schedule Dependency, Continued

Visually, the dependencies look like this:

PAYJOB1

END.PAYJOB1

PAYJOB2(job)

(link)

(job)

END.PAYJOB2(link)

Result ESP produces the following results:

• When PAYJOB1 ends successfully, ESP processes a link calledEND.PAYJOB1. The link sets the available count of the PAYJOB1resource to 1.

• ESP does not submit PAYJOB2 until the PAYJOB1 resource is available.• When PAYJOB2 completes successfully, ESP processes a link called

END.PAYJOB2. The link sets the available count of the PAYJOB1resource to 0.

431

Using XCF with ESP

Overview

Introduction ESP Workload Manager Version 5 Release 2 has been enhanced to use theCross-System Coupling Facility (XCF) component of MVS/ESA or OS/390.There is new functionality and commands added to ESP Workload Manager.


Topic See PageCommands 432 XCF Services 433 State Awareness 437 Trace 438

432

Commands

Description All the ESP XCF commands may be issued via:

• ESP page mode, option G from the ESP main menu• ESP line mode• ESP Workstation• MVS MODIFY command.

Commands To display the list of ESP XCF commands available, enter XCF HELP.

The following is the response from the XCF HELP command:

Long Form Short Form

DELETE MEMBER member DEL M|MEM memberDISPLAY ACTIVE|ACTIVITY D A|ACTDISPLAY GROUP|GROUPS D G|GRDISPLAY SERVICE|SERVICES D S|SERVDISPLAY SYSTEM|SYSTEMS D SYSDISPLAY TRACE D TRFORCE MEMBER member FORCE M|MEM memberHELP H|?PURGE CONNECTION connection PG CON connectionPURGE SERVICE service PG S|SERV serviceSET TERMOPT LEAVE|QUIESCE T TO L|QSET TRACE SYSOUT(class) T TR S(class)SPIN TRACE SP TRSTART SERVICE service S S|SERV serviceSTART TRACE S TRSTOP GROUP P G|GRSTOP MEMBER member P M|MEM memberSTOP SERVICE service P S|SERV serviceSTOP TRACE P TRVERIFY MEMBER member VER M|MEM member

Commandreference

For detailed information on all the ESP XCF commands, see the ESPWorkload Manager Command Reference.

433

XCF Services

Introduction XCF Services are functions of ESP that use Sysplex architecture. ESPcurrently registers these two XCF Services:

• Data set triggering (dstrig)• Job tracking (tracking).

Enabling XCFServices

XCF Services are registered and started via the XCF START SERVICE xxxxcommand. This command must be coded in the Initialization Parameter dataset. XCF Services must be coded in all the ESP subsystems in the XCFgroup.

When an XCF Service is coded and started on the ESP Master, a listener isactivated. When an XCF Service is started on the ESP Slave(s), it willconnect to the ESP Master’s listener for that Service.

Job trackingand data settriggering

In ESP Workload Manager Version 5 Release 1, an ESP Slave subsystemwrites Job tracking and data set triggering records to a QUEUE file and theESP Master subsystem reads those records from the QUEUE file.

In ESP Workload Manager Version 5 Release 2, you have the option to useXCF for Job tracking and data set triggering. When XCF is used, the ESPSlave transmits Job tracking and data set triggering records to the ESP Mastervia XCF. This provides a quicker vehicle for communicating, thus reducingcontention on the QUEUE file.

If XCF Services are not enabled, ESP Workload Manager Version 5 Release2 will continue to write Job tracking and data set triggering records to theQUEUE file.

QUEUE file The QUEUE file is still required in ESP Workload Manager Version 5Release 2.

The QUEUE file has a record of Abended Job information (available via theDAB command) and also information on jobs in the Input, Execute andOutput pnodes.


434

XCF Services, Continued

QUEUE file toXCF Migrationconsiderations

The ESP Master will always check the QUEUE file for Job tracking and dataset triggering records written by ESP Slaves. To migrate from the QUEUEfile to an XCF connection, add the XCF START SERVICE xxxx commandsin the ESP Master and ESP Slave Initialization Parameter data set at the sametime. If you are going to add the XCF START SERVICE xxxx commandsseparately, put them in the ESP Master first.

If the ESP Slave has the XCF START SERVICE xxxx commands in theInitialization Parameters and the ESP Master does not, Job tracking and dataset triggering records cannot be sent from the ESP Slave to the ESP Master.

Starting XCFServices

The following is the syntax for the XCF START SERVICE commands in theInitialization Parameter data set:

XCF START SERVICE DSTRIGXCF START SERVICE TRACKING

DisplayingXCF Services

To display XCF Services, enter the following command:

XCF DISPLAY SERVICES

The following is an example of a response to the above command:

Service Status Group MemberDSTRIG Active P520 P521TRACKING Active P520 P521


435


Displayingactive XCFServiceconnections

To display active XCF Service connections, enter the following commandfrom an ESP 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

Stopping anXCF Service

To stop an XCF Service, enter the following command:

XCF STOP SERVICE DSTRIG

Restarting anXCF Service

To restart an XCF Service “on the fly” after it has been stopped, enter thefollowing command:

XCF START SERVICE DSTRIG

Purging XCFServices

When you purge a Service on an ESP Master, the Service gets purged andrestarted. ESP stops and starts the listener. This should only be used insituations when XCF STOP SERVICE does not appear to be working.

Example ofPurging aService

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


436


Example of arestartedService

Display the active XCF connections from an ESP Master:

XCF DISPLAY ACTIVE

The following example shows the Service DSTRIG connected on a newlistener 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

437

State Awareness

Introduction In an XCF group, State Awareness exists between all the ESP subsystems inthe group. Each ESP is a unique member of a common group, but they allknow the operating status of each other.

Description Each ESP subsystem knows which other ESPs are active, quiesced or failed inthe XCF group. Each ESP member also knows the XCF Services that areavailable on the ESP Master.

Displaying themembers

To display the members in the XCF group and their respective states, use theXCF DISPLAY GROUP command.

XCF DISPLAY GROUP

Group=P520, Member=P521, TermOpt=QuiesceGroup Member System ASID Jobname SSID ESP StatusP520 P521 SYSA 0081 P521 P521 Master ActiveP520 P522 SYSA 007D P522 P522 Slave Active

Stopping amember

To stop an ESP XCF member, use the XCF STOP MEMBER command.

XCF STOP MEMBER member

Stopping thegroup

To stop all the ESP XCF members in the XCF group simultaneously, use theXCF STOP GROUP command.

XCF STOP GROUP

438

Trace

Introduction The XCF Trace facility is a debug tool. XCF Trace captures data and spoolsthe output to a preset sysout class. This should not be used unless instructedby Cybermation technical support.

Commands The following shows how to activate and capture data using XCF Trace:

Step Action1. Define a sysout class by entering:

XCF SET TRACE SYSOUT(x)2. Activate the trace by entering:

XCF START TRACE3. 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 is used to spool the current XCF trace fileto output and start a new XCF trace file. It can be used when the trace file isstarted upon initialization of the ESP subsystem and kept running for theduration of the subsystem session.

Usage notes The XCF SET TRACE SYSOUT(x) and XCF START TRACE commandscan be specified in the Initialization Parameter data set, but XCF STOPTRACE and XCF SPIN TRACE cannot. It is recommended to put XCF SETTRACE SYSOUT(x) in the Initialization Parameter data set because then onlyXCF START TRACE is required to start it on the fly.

439

Optimizing ESP Applications to Use Distributed Manager

Overview

Introduction When your ESP network contains one or more Distributed Managers, youmay be required to create ESP Applications that run workload on one or moreESP Agents controlled by a Distributed Manager. You should consider certainguidelines when defining Applications that run workload managed by aDistributed Manager.

The structure of the ESP Applications that require management by aDistributed Manager can be tailored to make the most efficient use of theDistributed Manager's ability to manage previously scheduled workload whenthe mainframe is unavailable.

This chapter describes the guidelines you may want to follow when definingdistributed Applications, and those ESP features that are not currentlysupported by the Distributed Manager.

If this is a new installation of ESP Workload Manager that does or willinclude one or more Distributed Managers, you should read this chapterbefore you begin coding ESP Applications.


Subtask See PagePlanning Applications to Optimize DM 440Establishing Ownership of a Workload Object 446Creating Distributed Applications for use with DistributedManager

447

Defining Manager Ownership of an Application 448Changing Manager Ownership of an Application 450Changing Manager Ownership of an Application Dynamically 451

440

Planning Applications to Optimize DM

Introduction Before you define a new distributed ESP Application, or update an existingdistributed Application, you should consider the features and limitations ofthe Distributed Manager. Creating Applications that optimize the abilities ofthe Distributed Manager ensure the completion of the Application when themainframe is unavailable, either due to scheduled maintenance or a plannedor unplanned outage.

Steps Follow these steps to plan optimal Applications:

Step Action1 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:

1. The owning Manager of each workload object. SeeEstablishing Ownership of a Workload Object on page 446.

2. The number of times the owning Manager changes from aDistributed Manager to the central ESP Workload Manager orvice versa.

See Example 2 - not recommended structure on page 443.4 Group the workload objects wherever possible, to minimize the

number of changes in owning Manager:• Group MVS 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 Managertogether, reducing the communication required betweenDistributed Managers.

See Example 1 - recommended structure on page 442.


441

Planning Applications to Optimize DM, Continued

Steps (continued)

Step Action5 Review the list of ESP functions not supported by the current

release of DM. Eliminate the use of the following functions in anyESP Application that runs workload managed by a DistributedManager.• Resolution of runtime symbolic variables• Resolution of runtime CLANG or REXX statements• Workload objects containing EXTERNAL or MANUAL

keywords• ESP Alerts.

For more detailed information, refer to Unsupported functions onpage 445.

6 Create a set of rules for defining distributed Applications at yoursite.

Features andlimitations

The primary purpose of a Distributed Manager is to track scheduled workloadthat is running on ESP Agents. As status is returned from an Agent, theDistributed Manager passes the status to the central ESP Workload Manageror any other interested Distributed Managers. If the mainframe is down orcommunications to the mainframe is unavailable, the Distributed Managercontinues to track workload, releasing workload objects under its control astheir dependencies are met. When the mainframe becomes available again, theDistributed Manager sends all status updates to the ESP Workload Manager atthat time.

The Distributed Manager can release workload under its control, or sendstatus to another Distributed Manager that is interested in the completion of aworkload object. It cannot, however, determine that a workload object hascompleted if information from the owning Manager (such as the central ESPWorkload Manager) is unavailable. Refer to the following examples thatgraphically describe the optimal way to design the interrelationships within anESP Application.


442


Example 1 -recommendedstructure

The following example shows an ESP Application that runs MVS, UNIX andWindows NT workload, controlled by a central ESP Workload Manager andtwo Distributed Managers. Note that the workload is grouped to limit thenumber of changes of owning Manager and the number of interdependenciesbetween Managers.

UNIX_JOB F

JOB A

UNIX_JOB G

JOB B

NT_JOB S

NT_JOB T

NT_JOB V

UNIX_JOB H

Distributed Manager 1 Distributed Manager 2

Central ESPWorkload Manager

Change

Change

In this example, the dependency on the availability of the mainframe islimited to the beginning of the Application: ESP Workload Managerschedules the Application and manages the first two workload objects. Afterthey complete, the connection to the mainframe may be lost, or the mainframetaken down for maintenance and the workload continues to run because itdoes not rely on intervention from the mainframe. Ideally, remove alldependencies on the mainframe entirely, or limit them to the beginning or endof the Application.


443


Example 2 - notrecommendedstructure

The following example shows an ESP Application that runs MVS, UNIX andWindows NT workload, controlled by a central ESP Workload Manager andtwo Distributed Managers. Distributed Manager 1 controls the UNIXworkload and Distributed Manager 2 controls the Windows NT workload.Note that the workload objects have many inter-platform dependencies, andthe owning Manager changes five times within the Application. In thisexample, if the mainframe becomes unavailable after JOB A completes,workload cannot continue to run after UNIX_JOB F and NT_JOB Scomplete.

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 ESPManager

Change

Change

Change

Change

Change

Change


444


Example 2 - notrecommendedstructure,continued

In the above example, each Distributed Manager has a dependency on theavailability of the mainframe throughout the entire Application. If themainframe or communication to it becomes unavailable at any point duringthe execution of the Application, the work cannot continue to run. A workloadobject may complete, but the next workload object may not be released untilthe mainframe becomes available again. This Application structure defeats thepurpose of the Distributed Manager in this case.


445


Unsupportedfunctions

Some ESP functions are not yet supported by ESP Distributed Managers.While your workload objects will not cause errors in the Distributed Managerif they contain statements the Distributed Manager does not recognize, yourworkload may not perform as expected. The following ESP functions are notsupported by Distributed Managers:

• Resolution of runtime symbolic variables• Resolution of runtime CLANG or REXX statements• Workload objects containing EXTERNAL or MANUAL keywords• ESP Alerts.

Support of these functions varies depending on the owning Manager of theApplication or workload object. Refer to the following to determine when afunction is unavailable:

State of central ESPWorkload Manager

Owned by ESPWorkload Manager

Owned by aDistributed Manager

ESP Workload Manageravailable

• Runtime symbolicvariables

• Runtime scriptingof CLANG andREXX

• EXTERNAL• MANUAL• Alerts

ESP Workload Managerunavailable







446

Establishing Ownership of a Workload Object

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

Owner of anApplication

The owning Manager of an Application is defined on the APPL statement orin the Application definition on ESP Workstation. If no owner is specified,the owner defaults to the central ESP Workload Manager. The ownerspecified at the Application level also applies to all Links and Tasks withinthe Application, unless the owner is specified in the Link or Task definition.

The owning Manager determines the status of the Application, and is the onlyManager that can complete the Application. Therefore, if you are running adistributed Application that must be able to complete when the mainframe isunavailable, a Distributed Manager must be the owner.

Owner of aLink or Task

The owner of a Link or Task is defined either at the Application level, withthe OWNER keyword on the APPL statement, or in the Link or Taskdefinition with the OWNER keyword. Specifying the OWNER keyword inthe Link or Task definition overrides any specified at the Application level.

Specifying a Distributed Manager as the owning Manager of a Link or Taskallows you to define the Link or Task as non-MVS workload. The DistributedManager determines if the conditions of the Link or Task are met.

Owner of anMVS job

The owner of an MVS job is always the central ESP Workload Manager.

Owner of adistributedworkloadobject

The owner of a distributed workload object is not determined by an OWNERkeyword - it is determined by the network topology defined in theAGENTDEF file. A Manager - either a Distributed Manager or the centralESP Workload Manager, owns each Agent. The Manager that owns the Agentrunning the workload object owns the distributed workload object.

447

Creating Distributed Applications for use with DistributedManager

Introduction You can optimize your ESP Applications for use with a Distributed Managerby keeping some simple rules in mind when designing the Application. Also,consider if the Application will run most efficiently under the ownership of aDistributed Manager or the central ESP Workload Manager.

Steps Follow these steps to create an ESP Application that optimizes DistributedManager's capabilities:

Step Action1 If this Application must be able to complete when ESP Workload

Manager is unavailable, specify a Distributed Manager as theowner. Specify an OWNER keyword on the APPL statement orspecify an owner in the Owner field in ESP Workstation.

2 Structure the Application to minimize embedded dependencies onMVS workload. If dependencies on MVS workload are requiredwithin the Application, try to place them at the beginning or end ofthe Application.

3 Ensure you do not include External or Manual jobs within theApplication.

4 Ensure any symbolic variables can be resolved at the time theEvent is triggered. A Distributed Manager cannot resolve runtimesymbolic variables.

5 Ensure any CLANG or REXX used within the Application can beresolved at the time the Event is triggered. A Distributed Managercannot resolve runtime-scripting requirements.

6 Ensure you do not use ESP Alerts in the Application.7 Group workload by Distributed Manager, where possible.

448

Defining Manager Ownership of an Application

Introduction The owning Manager of an Application is the only Manager that can start orcomplete an Application, change the status of an Application, or sendnotifications to the other Managers regarding the status of an Application. Theowner of an Application is also the owner of all Links and Tasks within theApplication, unless the owner is specified within the Link or Task definition.

The owning Manager of an Application is defined on the APPL statement orin 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 completewhen the mainframe is unavailable, specify a Distributed Manager as theowner.

Steps Follow these steps to define the owner of an Application:

1 Create a new Application or edit an existing Application.2 If you are using ESP Workstation proceed to step 4. Otherwise

continue.

If you want to specify an owner that changes based on a schedule,proceed to step 3. Otherwise continue.

1. On the APPL statement, specify an OWNER parameter. Entera valid Distributed Manager name, up to 16 alphanumericcharacters in length. The first character must be alphabetic or anational character, as follows:

APPL PAYROLL OWNER(DMTOR)

2. Proceed to step 5.


449

Defining Manager Ownership of an Application, Continued

Steps (continued)

Step Action3 1. On the APPL statement, specify an OWNER parameter. Enter

a valid Distributed Manager name, up to 16 alphanumericcharacters in length. The first character must be alphabetic or anational character. Define the circumstances under which youwant ownership of the Application determined. Specify theexceptions first. Specify the normal ‘business as usualcircumstances next. For example, the following exampledefines a Distributed Manager as the owner of the Applicationon weekends:

IF TODAY ('WEEKEND') THEN APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL ENDDO

2. Proceed to step 5.4 1. In the Workload Editor, bring up Workload Definition Defaults

2. On the Application tab, find the Owner field3. Enter a valid Distributed Manager name, up to 16

alphanumeric characters in length. The first character must bealphabetic or a national character.

5 Simulate the Event that runs this Application for eachcircumstance. Ensure the results are as expected.

6 Save the Application.7 If you are using ESP Workstation, upload the Procedure to the

mainframe.

450

Changing Manager Ownership of an Application

Introduction Depending on how ownership is specified in your Application, there may betimes when you want to change the ownership, such as you expect themainframe to be shut down for maintenance.

You need to change the ownership in the Application and trigger the Eventprior to shutting down ESP Workload Manager.

Steps Follow these steps to change the ownership of an Application:

Step Action1 Edit the Application.2 If an owner is currently defined for the Application, change the

owner to the new name. Otherwise, add an owner name in theOwner field on ESP Workstation, or add an OWNER statement asfollows:

APPL PAYROLL OWNER(DMTOR)

3 Simulate the Event that runs this Application to ensure nounforeseen problems.


mainframe.6 When the Event is triggered, the new owner controls the status of

the Application.

451

Changing Manager Ownership of an Application Dynamically

Introduction Depending on how ownership is specified in your Application, there may betimes when you want to change the ownership dynamically. For example, ifthe mainframe is shut down for maintenance on a certain schedule, you canuse ESP to change the ownership of the Application to a Distributed Managerduring those scheduled times. This is especially important if your Applicationmust be able to complete (and perhaps run additional generations of theApplication) even if the mainframe is unavailable.

Ensure the Event is triggered prior to shutting down ESP Workload Manager.

Steps Follow these steps to change the ownership of the Application dynamically:

Step Action1 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 thenormal ‘business as usual’ circumstances next. For example:

IF TODAY FRIDAY THEN APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLLENDDO

3 Simulate the Event that runs this Application for eachcircumstance. Ensure the results are as expected.


mainframe.

453

Glossary of Terms

Glossary

Term ExplanationAlert A mechanism you define to ESP to trigger

ESP activity when specific actions take placein your Application. For example, you can useESP to trigger an Event when a job fails.

Application See ESP Application.Application Wait A status in which the execution of an

Application has to wait until a previousgeneration of the Application completes.

Audit log An audit trail of ESP activity. It storesinformation on administration activities,operator commands, and Application andEvent processing.

Authorization string One of four job related fields that is used toidentify the ownership of a job.

Authorization table A table ESP may use to control access to jobtracking data.

AUTOVAR Automatic variable; a variable used torepresent an initial or trailer job step, or DJCnet card.

Calendar A collection of definitions of holidays, specialdays and special periods that are unique toyour installation.

CCFAIL Abbreviation for “condition code fail”.CCFAIL statements define conditions, which,if met, should cause the job to fail.

CLANG Control language. This is a high levelprogramming language developed for ESP.

Condition code A code indicating the results of processing ajob step.

Consolidated Status Facility An ESP facility for displaying andmanipulating the workload.


454

Glossary, Continued

Term ExplanationCOPYJCL Location of a copy of the submitted JCL.Descriptor code A one or more digit code used to describe the

characteristics of a message to an MVSconsole.

DJC Dependent Job Control; a Cybermationproduct used to control resources and jobnetworks at the initiator level.

DJC job network A group of related jobs where dependenciesare controlled at the initiator level.

ESP Application A group of related jobs and tasks.ESP Procedure A collection of stored instructions to be

executed by ESP when invoked by an Event.External job A job defined in an ESP Procedure that ESP

submits from another Procedure.Event A basic unit of work to ESP. An Event starts

an active function such as sending a messageor invoking an ESP Procedure.

Event data set A VSAM data set where ESP stores Eventdefinitions.

Event group Group of ESP Events with the same Eventprefix (first name).

EVENTSET Event data set.


455

Glossary, Continued

Term ExplanationGroup A high-level index, to which specific users

are allowed access. Normally a group is acollection of users with common accessrequirements.

HISTFILE History file.History file A VSAM data set used to store historical

information.Job index data set A VSAM data set used to store an index to

the most recent executions of a job.Job monitor An ESP facility for monitoring a job’s

progress at any stage of processing and fortaking action at significant points.

Job tracking An ESP facility to track job data in real timeas jobs are processed.

Job tracking definition table A table used to specify the characteristics ofjobs, STCs and TSUs you want to track.

Link A task in an Application that does not requiremanual completion.

Manual job A job which ESP does not submit as part ofeither an ESP Application or a DJC/JES3 jobnetwork.

Model A definition of your environment (e.g. CPUs,initiators, resources).

Page mode A method to communicate with ESP usingISPF, producing scrollable output from ESP.

P-Node Processing node. A processing stage throughwhich a job must pass during its time on thesystem.

Post To mark complete. For example, you can posta job complete.

Predecessor job Any job that must complete before anotherjob can be released.


456

Glossary, Continued

Term ExplanationQualifier An addition to the job’s name, used to

uniquely identify similar jobs.Resource An item of hardware, a software resource or

an abstract condition.REXX Restructured eXtended eXecutor. This is a

high level, procedural language developed byIBM. You can invoke the REXX languageinterpreter from ESP to extend ESP’scapabilities.

Route code A one or more digit code used to route amessage to an MVS console.

SAD file Scheduled activity data set file; a sequentialdata set ESP uses to store scheduled activityinformation on jobs.

SAF System Authorization Facility; a generic setof operating system interfaces that allows asecurity product to implement access controlagainst the components of the operatingsystem. Also used to refer to the use of theinterface.

Schedule A list of Events to execute, sorted in timesequence.

Signal A manual or automated task used forscheduling.

Special day A day with special significance for schedulingat your installation.

Special period A period of processing with specialsignificance for scheduling at yourinstallation. An example is a fiscal month.

SubApplication A group of jobs within an Application.Subsystem An MVS facility that ESP uses to manage and

control requests among its components.Successor job Any job that depends on the completion of

another job before it can be released.


457

Glossary, Continued

Term ExplanationSymbolic variable An integer or a character string whose value

ESP substitutes at processing time.SYMLIB Symbolic variable library; data set(s) or data

set members used to store symbolic variables.Sysplex The term Sysplex is derived from SYStems

comPLEX. Sysplex is a platform for anevolving, large system computingenvironment.

System message interception A facility used to intercept system messagesas they are written to the system message dataset.

System security product A product installed to implement systemsecurity. Also known as the host securitysystem or product.

Task An element of an Application that requirescompletion. For example, a task mayrepresent the checking of a report.

Tracking model A centralized definition of the attributes andprocessing phases of a group of jobs.

TRAKFILE Tracking file; a non-VSAM data set used tostore job tracking data.

userid A short (8 bytes or less) field used to identifya system user. It can represent an actualperson or an active program, job or routine.

XCF XCF (Cross System Coupling Facilitycomponent of MVS/ESA or OS/390) servicesallow authorized programs to communicatewith programs on the same or different MVSimages.

459

/

//* FROM statement .............................................. 187//* UNTIL statement ............................................. 187

4

4-4-5 periodexample ............................................................ 134

A

ABANDON DEPENDENCIES statement ............ 203ABANDON RESOURCES statement................... 205ABANDON SUBMISSION statement.................. 203Absolute day ......................................................... 110Access

to calendars....................................................... 124to Events............................................................. 63

Accessing ESPas a program ....................................................... 55as a TSO command processor ............................ 56in batch............................................................... 54ISPF option ........................................................ 45

ACTIVE function.................................................. 159Adding

job dependency using CSF ............................... 278job relationship using CSF ............................... 280relationship between 2 jobs .............................. 251resource requirements....................................... 388scheduled Event execution ................................. 96

Advancing Event processing ................................... 69Advancing job based on holiday ........................... 128AFTER statement.................................................. 206AJ command ......................................................... 251Altering Event ....................................................... 101ALTEVENT command ......................................... 101Anticipated end times............................................ 199APPL statement..................................................... 184Application

changing owner of ............................................ 446changing the definition ..................................... 253command processing ........................................ 196creating for use with DM.................................. 443CSF commands................................................. 270defining owner of ............................................. 444description........................................................ 177displaying ......................................................... 249distributed......................................................... 436dynamically changing owner of........................ 447generating......................................................... 179manipulating..................................................... 251naming.............................................................. 184optimizing for Distributed Manager ................. 435owning Manager of........................................... 442

planning, for use with DM................................ 436reommended structure for DM ......................... 438working with..................................................... 248

Application generationsconcurrent processing....................................... 184number ESP assigns ......................................... 181

Application phases ................................................ 179APPLJOB command ............................................. 251Arithmetic expression ........................................... 147Arithmetic operations............................................ 148Attributes, of a job ................................................ 227Authorization string

External jobs..................................................... 214Manual jobs...................................................... 218

B

Batch, invocation of ESP ........................................ 54Blank lines,history report ...................................... 308BREAK command ................................................ 308Built-in functions

ACTIVE ........................................................... 159combining......................................................... 164DAYS_BETWEEN.......................................... 152DAYS_FROM.................................................. 152DAYS_TO........................................................ 152DEFINED......................................................... 157ESP Procedure.................................................. 150JOBONQ.......................................................... 159LENGTH.......................................................... 157SELECTED...................................................... 156SUBSTR........................................................... 158TAPES ............................................................. 162TODAY............................................................ 153TOMORROW .................................................. 154YESTERDAY .................................................. 154

Built-in symbolic variables ................................... 145Bypassing

a job.................................................................. 251a job based on time........................................... 203a scheduled Event execution .............................. 97Event,specific day .............................................. 69

Bypassing a job ..................................................... 277

C

Calendaraccess ............................................................... 125contents ............................................................ 124deletion of entries ............................................. 125specifying in Event ............................................. 86SYSTEM.......................................................... 125

CALENDAR command .......................................... 86CALENDAR statement......................................... 125Canceling an Event

460

for specific day................................................... 69next execution .................................................... 97

Changing Application definition ........................... 253changing ownership of Application....................... 446

dynamically ...................................................... 447CLANG,language elements................................... 141CLIST,to access ESP .............................................. 56Commands

CSF................................................................... 270processing in an Application ............................ 196

CommentsESP Procedure.................................................. 140Event .................................................................. 86

Comparing expressions ......................................... 148Comparison operators ........................................... 148Completing a job................................... 252, 255, 277Concurrent access to online system....................... 408Concurrent processing,Applications ..................... 184Conditional jobs,defining...................................... 195CONDITIONAL keyword .................................... 196Conditions,freeform filtering................................. 289Consolidated Status Facility.......................... See CSFContinuation character,ESP Procedure ................. 140Control information,using ..................................... 365Controlling access to database,using resource ...... 413CONVERT.EXE utility......................................... 348Converting job documentation .............................. 374COPY command ................................................... 306Copying JCL ........................................................... 82COPYJCL command............................................... 82COPYJCL statement ............................................. 188COREQ statement................................................. 206Countdown procedure ........................................... 421Creating reports..................................................... 293CRITERIA command............................................ 303Critical jobs

default............................................................... 240defining ............................................................ 195

CRITICAL keyword ..................................... 195, 240Critical path........................................................... 238

displaying ......................................................... 242External jobs..................................................... 240historical elapsed times .................................... 241identifying critical jobs..................................... 240multiple ............................................................ 241

Critical path analysisturning off......................................................... 240turning on ......................................................... 239

Cross-System Coupling Facility............................ 427CSF

add dependency................................................ 278add job relationship .......................................... 280add LINK PROCESS ....................................... 281freeform filtering .............................................. 285inserting job...................................................... 273

installation written commands.......................... 284presentation fields ............................................ 264presentation titles.............................................. 264reset time .......................................................... 276set User Status .................................................. 282Status fields ...................................................... 292views ................................................................ 256

CSF commands ..................................................... 270Application....................................................... 270ESP definitions................................................. 272jobs................................................................... 271subApplication ................................................. 270

CSF Extensions ..................................................... 284

D

Data set names in ESP Procedure ......................... 140Data set trigger objects.......................................... 228

controlling ........................................................ 232displaying ......................................................... 233ready status....................................................... 232setting up .......................................................... 229

Data set triggering................................................... 74any closure.................................................. 74, 230data set creation.................................................. 74

job-level....................................................... 230displaying Events ............................................... 77job level............................................................ 228multiple closures................................................. 76

job-level....................................................... 231multiple data sets ................................................ 75

job-level....................................................... 231Data set,job mapping............................................. 328DATASET statement ............................................ 189Date fields,history reporting.................................. 299Date format,history report ..................................... 306DATEFORM command ........................................ 306DAYS_BETWEEN function ................................ 152DAYS_FROM function ........................................ 152DAYS_TO function .............................................. 152Default resources................................................... 392

dropping ........................................................... 393DEFHOL command .............................................. 126DEFINED function ............................................... 157Defining

a job.................................................................. 191Event using a link ............................................. 243function of Event ................................................ 78holiday.............................................................. 126resource ............................................................ 395special day........................................................ 129special period ................................................... 131when Event executes .......................................... 66

DEFSPEC command............................................. 129Delayed submission time....................................... 198Delaying

461

Event processing ................................................ 69job based on holiday......................................... 128

Delaying submission ............................................. 198DELAYSUB statement ......................................... 198DELETE command............................................... 102Deleting

calendar entries................................................. 125CSF view.......................................................... 267Event ................................................................ 102resource ............................................................ 398

Depletable resource............................................... 382DESELECT statement .......................................... 209Deselecting jobs .................................................... 209DEVICE resource ................................................. 396DISPLAY command ............................................. 307Displaying

Application....................................................... 249critical path....................................................... 242data set trigger objects...................................... 233data set triggered Events..................................... 77data sets for triggering Events ............................ 77Events................................................................. 93External jobs..................................................... 212history report fields .......................................... 307scheduled activity data ..................................... 322scheduled Events ................................................ 88

Distant Application ............................................... 212Distributed Manager

functions of....................................................... 437limitations of .................................................... 437unsupported functions ...................................... 441

DO statement......................................................... 142DOCMEM keyword.............................................. 366Documentation,for jobs......................................... 353Dropping

default resources............................................... 393resource requirements....................................... 389

DSNAME statement.............................................. 229DSTRIG command,Event ....................................... 74DSTRIG statement ................................................ 229DUEOUT EXEC statement................................... 200DUEOUT INPUT statement ................................. 200Dueout times

job end.............................................................. 200job start............................................................. 200propagating....................................................... 201

DURATION statement.......................................... 241

E

Early submission time ........................................... 198EARLYSUB statement ......................................... 198Elapsed time resource ........................................... 420

multi-CPU ........................................................ 422ELSE statement..................................................... 141ENDDEF command ................................................ 62

ENDDO statement ................................................ 142Ending

job definition .................................................... 191report definition................................................ 309

ENDJOB statement ............................................... 191ENDR command ................................................... 309Enterprise resource................................................ 383ESP commands

from CSF.......................................................... 283issuing from an Application ............................. 243loading................................................................ 58

ESP FLOWDOC................................................... 337components....................................................... 338data generation ................................................. 338database generation .......................................... 339examples........................................................... 343overview........................................................... 337report generation .............................................. 340report headings ................................................. 342

ESP Procedurebuilt-in functions .............................................. 150comments ......................................................... 140continuing a line ............................................... 140data set names................................................... 140expressions ....................................................... 147indentation........................................................ 140invoking............................................................ 139label.................................................................. 140name ................................................................. 140overriding ......................................................... 174re-executing...................................................... 165syntax ............................................................... 140terminating with EXIT ..................................... 142terminating with QUIT ..................................... 143using CLANG................................................... 141using Event commands..................................... 171

ESP statement ....................................................... 243ESPNOMSG statement ......................................... 243Event

access ................................................................. 63altering.............................................................. 101bypassing............................................................ 99bypassing one execution..................................... 97comments ........................................................... 86concept ............................................................... 16data set triggered ................................................ 74deleting............................................................. 102description.......................................................... 61displaying ........................................................... 93expected time...................................................... 89function .............................................................. 78

issuing operator command............................. 84sending message ............................................ 78submitting job................................................ 78

invoking ESP Procedure..................................... 81

462

missed................................................................. 69name ................................................................... 63next execution times ........................................... 90overdue............................................................... 69pending execution............................................... 71postponing .......................................................... 98resuming ............................................................. 99scheduling........................................................... 67setting calendars ................................................. 86setting symbol libraries....................................... 85simulating ........................................................... 94to invoke an Application .................................. 254trigger ................................................................. 66triggered in error ................................................ 97triggering ............................................................ 96

EVENT command................................................... 62Event commands

using in ESP Procedure .................................... 171Event processing

advancing ........................................................... 69delaying .............................................................. 69ignoring .............................................................. 69

Exceptions,Event scheduling................................... 68EXIT statement ..................................................... 142EXPECT statement ................................................. 89Expected time of Event ........................................... 89Expression............................................................. 147External job

Application....................................................... 212critical path....................................................... 240tagging.............................................................. 234

EXTERNAL keyword........................................... 212

F

Field formats,history reporting.............................. 297Field lengths,history report ................................... 307Fields

for history reporting.......................................... 311history reporting ............................................... 296

Filter Specifications panel..................................... 263First day of week................................................... 110FLOW command................................................... 350Flowcharting ......................................................... 346

MS Project........................................................ 347TIMELINE....................................................... 350

FLOWDOC........................................................... 337components....................................................... 338data generation ................................................. 338database generation .......................................... 339examples........................................................... 343overview........................................................... 337report generation .............................................. 340report headings ................................................. 342

Freeform filteringconditions ......................................................... 289

CSF................................................................... 285examples........................................................... 291keywords .......................................................... 286

FROM command................................................... 302functions not supported by DM............................. 441Functions of ESP..................................................... 14

not supported by DM........................................ 441

G

Generation phase,Application ............................... 179Generations of an Application............................... 181GENFLOW command........................................... 350GENPROJ command ............................................ 348Global resource ..................................................... 383Gravity attribute .................................................... 385

H

Held jobs,defining................................................. 195HELP facility .......................................................... 46Help panels.............................................................. 50HISTFILE command............................................. 302History file

for reporting ..................................................... 302History report

blank lines ........................................................ 308date format ....................................................... 306display fields .................................................... 307ending............................................................... 309field lengths ...................................................... 307history file ........................................................ 302list of fields....................................................... 311output data set .................................................. 306page break ........................................................ 308reporting fields ................................................. 296sample .............................................................. 309selection criteria ............................................... 303sort criteria ....................................................... 307structure............................................................ 295subtotals............................................................ 308time range......................................................... 302titles.................................................................. 307width................................................................. 309

History reporting ................................................... 294HOLD command..................................................... 98

in Event .............................................................. 71Hold count............................................................. 179

job in an Application ........................................ 179Holding an Event .................................................... 98Holiday

defining ............................................................ 126defining with a template ................................... 168using to schedule .............................................. 128

Home Application ................................................. 212Hyphen,using in batch........................................... 310

463

I

IF statement........................................................... 141Ignoring

Event processing ................................................ 69Indentation

ESP Procedure.................................................. 140Index for job activity report .................................. 332INFOMSG command .............................................. 53Informational messages

displaying ........................................................... 53Inheriting relationships.......................................... 209INPUT command .................................................. 302Input criteria,history report ................................... 302INPUTDS statement ............................................. 326Inserting a job

CSF................................................................... 273resource requirements....................................... 387

Inserting LINK PROCESS.................................... 281INVOKE command,in Event .................................. 81Invoking

Application....................................................... 254ESP Procedure,using Event ................................ 81

ISPF panels ............................................................. 45Issuing commands

using a link ....................................................... 221Issuing operator command

using Event ......................................................... 84

J

JCLcreating a copy ................................................... 82for routing jobs................................................. 385

JCL library ............................................................ 185temporary ......................................................... 186

JCLLIB statement ................................................. 185JES queue

using JOBONQ function .................................. 159Job Activity Report ............................................... 330

customizing ...................................................... 331Job ancestor wait................................................... 184Job dependency

adding, using CSF ............................................ 278Job Descendent Report.......................................... 334Job documentation ................................................ 353

converting......................................................... 374example-storing phone numbers....................... 377links and tasks .................................................. 370member............................................................. 366other uses.......................................................... 377qualified jobs.................................................... 368user description ................................................ 356using control information ................................. 365

Job mapping .......................................................... 327setting up .......................................................... 327

Job priority............................................................ 390Job qualifier .......................................................... 191

External job ...................................................... 212Job relationships

adding, using CSF ............................................ 280Application....................................................... 206inheriting .......................................................... 209using resources ................................................. 424

JOB statement ....................................................... 191Job types ............................................................... 211JOBATTR statement............................................. 227JOBDOC file......................................................... 372JOBMAP command .............................................. 330JOBONQ function................................................. 159

generated variables........................................... 160Jobs

attributes........................................................... 227bypassing.......................................................... 277completing........................................................ 277CSF commands................................................. 271on-request ......................................................... 193ownership of..................................................... 442qualifying ......................................................... 191requirements ..................................................... 197specifying owner .............................................. 442submitting without dependencies...................... 203

JOBTREE command............................................. 334JUMPTO statement............................................... 143

K

Keywordsfreeform filtering .............................................. 286

L

LabelESP Procedure.................................................. 140job documentation ............................................ 356

LAP command ...................................................... 249Late Submission time ............................................ 200LATESUB statement ............................................ 200LAX command...................................................... 212LDTE command...................................................... 77LDXE command ............................................. 77, 233LENGTH function ................................................ 157Length of a variable .............................................. 157Librarian data sets

as input ............................................................... 60ESP Procedure.................................................. 140submitting a job.................................................. 80

LIBSUB command.................................................. 80limitations of Distributed Manager ...................... 437Line mode ............................................................... 55Link

owning Manager of........................................... 442specifying owner .............................................. 442

464

LINK keyword ...................................................... 219LINK PROCESS,inserting, using CSF.................. 281Links

common uses .................................................... 221definition .......................................................... 219job documentation ............................................ 370resource limitation............................................ 412triggering an Event ........................................... 243using for notification ........................................ 222using to add job relationship ............................ 280using to define an Event ................................... 243using to issue commands .................................. 221using to keep Application active ...................... 222

LIST command ....................................................... 93LISTAPPL command............................................ 249LISTSCH command................................................ 88LOAD command..................................................... 58Local resource....................................................... 383Logical day............................................................ 110Logical expression ................................................ 147Logical operators .......................................... 148, 149LSAR command.................................................... 322

M

Main Menu........................................................ 45, 47Manager

changing owner of Application ........................ 446dynamically changing owner of Application .... 447

Manager of an Application.................................... 444Manual job,Application ........................................ 216MANUAL keyword .............................................. 216MAPGEN.............................................................. 329MEMBER statement

JCLLIB............................................................. 185TEMPLIB......................................................... 186

MS Project,flowcharts........................................... 347Multiple runs of a job............................................ 192Mutliple critical paths ........................................... 241Mutually exclusive

groups of jobs................................................... 416jobs................................................................... 406

N

Naming an Application ......................................... 184NEXT command ..................................................... 90Next execution times

Event .................................................................. 90Non-MVS workload................................................ 25Non-MVS workload,reporting .............................. 311NORUN statement ................................................ 209NOSCHED command ............................................. 68Notification

job status .......................................................... 236using a link ....................................................... 222

NOTIFY statement................................................ 236

NOW,scheduling term........................................... 114Numeric fields,history reporting ........................... 297

O

One time Event........................................................ 68Operator commands

from Events ........................................................ 84Operator console

retrieving job documentation............................ 372Operator precedence ............................................. 148Operators

arithmetic.......................................................... 148comparison ....................................................... 148logical....................................................... 148, 149

Optional jobs,defining........................................... 195Overdue Event................................................. 69, 100OVERDUE status, jobs......................................... 199Overriding

elapsed times for critical path........................... 241ESP Procedure.................................................. 174JCL library ....................................................... 186

Ownerof Application, changing .................................. 446of Application, changing dynamically.............. 447of Application, defining.................................... 444of distributed workload .................................... 442

Owning Manager................................................... 442of Application................................................... 442of distributed workload object.......................... 442of Link.............................................................. 442of MVS job....................................................... 442of Task.............................................................. 442

P

Page breakshistory report .................................................... 308

Page mode............................................................... 50displaying informational messages ..................... 53

PANSUB command ................................................ 80Panvalet datasets

as input ............................................................... 60ESP Procedures ................................................ 140submitting a job.................................................. 80

Pending executionEvent .................................................................. 71

Postponing an Event................................................ 98POSTREQ statement............................................. 206Postrequisite job.................................................... 206PREREQ statement ............................................... 206Prerequisite job ..................................................... 206Presentation fields,changing order ........................ 264Presentation titles,CSF .......................................... 264Primed data set triggers........................................... 76Prioritizing work

using resources ................................................. 410

465

Priority of a jobbased on resources............................................ 390

PRIORITY statement ............................................ 390Process phase,Application..................................... 180Projected versus actual report ............................... 325Propagating dueout times ...................................... 201

Q

Qualified jobs,job documentation ......................... 368Qualifying

a job.................................................................. 191job names ......................................................... 191

QUIT statement..................................................... 143

R

Real device types,resource .................................... 384Real resources ....................................................... 384

limitations......................................................... 384REALNOW, scheduling term ............................... 115REEXEC statement............................................... 165Re-executing an ESP Procedure............................ 165Refreshing resource status..................................... 396RELDELAY statement.......................................... 198RELEASE command,in Event ................................ 71RELEASE statement ............................................. 206Removing job dependencies,CSF.......................... 275Renewable resource .............................................. 382Repetitive information........................................... 167Replacing

scheduled Event execution ................................. 97Report balancing

using a task ....................................................... 226Reporting............................................................... 293

history............................................................... 294invoking............................................................ 301non-MVS workload.......................................... 311projected versus actual ..................................... 325scheduled versus actual .................................... 323

Reporting fields..................................................... 296character ........................................................... 297CPU time.......................................................... 299dates ......................................................... 299, 300elapsed time...................................................... 298format ............................................................... 297numeric............................................................. 298

Request jobs .......................................................... 193REQUEST keyword.............................................. 193Requesting

a job.................................................................. 194subApplication ................................................. 247

Requestinga job.................................................................. 251

RESDEF command ............................................... 395RESDFLT statement ............................................. 392Resetting time dependency

using CSF ......................................................... 276Resetting User Status field .................................... 282Resource

ABSORB statement.......................................... 404Absorption........................................................ 403counts ............................................................... 395STEPEND statement ........................................ 401Step-level release.............................................. 401

RESOURCE statement.......................................... 387Resource types ...................................................... 382Resources

changing quantitiy ............................................ 397default requirements ......................................... 392defining ............................................................ 395deleting............................................................. 398feature............................................................... 379for

resubmitted job ............................................ 386for inserted jobs................................................ 387real device ........................................................ 384removing dependency....................................... 205setting ............................................................... 397specifying dependency ..................................... 387types ................................................................. 382

RESREFR command............................................. 396Resubmitted job,resource requirement.................. 386RESUME command................................................ 99

in Event .............................................................. 72Retrieving job documentation ............................... 372REXX extensions

CSF................................................................... 284ROSCOE datasets

as input ............................................................... 60ESP Procedure.................................................. 140submitting a job.................................................. 79

ROSSUB command ................................................ 79Routing jobs

resource availability ......................................... 385using a resource................................................ 414

RUN statement ...................................................... 208

S

SADGEN command.............................................. 320SADGEN,ESPSADG variable .............................. 320SADUPD command .............................................. 323SCHEDULE command ........................................... 67Schedule criteria.................................................... 103

examples........................................................... 119testing ............................................................... 123using CLANG................................................... 122using GENTIME .............................................. 122where you can use .................................... 103, 104

Scheduled activity dataset ..................................... 320updating............................................................ 323

Scheduled activity reporting.................................. 318

466

limiting scope ................................................... 320setting up .......................................................... 318

Scheduled vs actual report .................................... 323Scheduling

Event .................................................................. 67one-time Event ................................................... 68

Scheduling terms................................................... 111first day of week ............................................... 110NOW ................................................................ 114REALNOW...................................................... 115workday............................................................ 110

Scope of job statement .......................................... 196Screens

ISPF interface..................................................... 48Security,based on Event prefix................................ 63SELECT statement................................................ 208SELECTED function ............................................ 156Selecting

CSF view.......................................................... 268Selection criteria

history report .................................................... 303Self-completing task.............................................. 412SEND command,in Event ....................................... 78Sending a message

in an Application .............................................. 196using Event ......................................................... 78

Settingresource ............................................................ 397User Status field ............................................... 282

SETWIDTH command ......................................... 309Simplifying code,using templates.......................... 167SIMULATE command............................................ 94Simulating an Event ................................................ 94SORT command.................................................... 307Sort criteria,history report ..................................... 307Sorting,date fields in a history report .................... 300Special day

defining ............................................................ 129using to schedule .............................................. 130

Special perioddefining ............................................................ 131intervals ............................................................ 131using to schedule .............................................. 133

Started taskdependency....................................................... 223

State Awareness .................................................... 433SUBAPPL statement.............................................. 244subApplication ...................................................... 244

controlling ........................................................ 247CSF commands................................................. 270displaying ......................................................... 246naming.............................................................. 244requesting ......................................................... 247SELECT statement ........................................... 246WAIT option .................................................... 244

SUBDELAY PNODE ........................................... 258SUBERROR PNODE ........................................... 259Submission delay .................................................. 258Submission error ................................................... 258SUBMIT command,in Event................................... 78Submitting a job

from Librarian .................................................... 80from ROSCOE ................................................... 79Panvalet .............................................................. 80using Event ......................................................... 78without dependencies ....................................... 203without resources.............................................. 205

SUBSTR function ................................................. 158Subtotals

history report .................................................... 308Suppressing messages ........................................... 243SUSPEND command .............................................. 99

in Event .............................................................. 72Suspending an Event ............................................... 99Symbol introducer character ................................. 145Symbol Library

specifying in Event ............................................. 85Symbolic variables

determining length............................................ 157in ESP Procedures ............................................ 145substring ........................................................... 157

SYMLIB command................................................. 85Synchronizing Applications .................................. 214Syntax,ESP Procedure .......................................... 140System affinity ...................................................... 415SYSTEM calendar ................................................ 125System identifier

Event .................................................................. 65System shutdown

multi-CPU ........................................................ 422planning............................................................ 420

System Status fieldCSF................................................................... 260

System,for Event execution..................................... 65

T

TAG statement ...................................................... 234Tagging jobs.......................................................... 234

day of week ...................................................... 234high priority...................................................... 234

Tape information,extracting .................................. 326Tape pull program................................................. 326TAPES function .................................................... 162Task

common uses .................................................... 226dueout time....................................................... 201job documentation ............................................ 370owning Manager of........................................... 442specifying owner .............................................. 442

TASK keyword ..................................................... 225

467

Templates.............................................................. 167purpose ............................................................. 167

TEMPLIB statement ............................................. 186Temporary JCL ..................................................... 186

limited use ........................................................ 187options.............................................................. 186

TEST command .................................................... 123Testing

schedule criteria................................................ 123THEN statement.................................................... 141Threshold resource................................................ 382Time and date scheduling........................................ 15

due-out time...................................................... 200early submit time .............................................. 198job end.............................................................. 200job start............................................................. 200job submission.................................................. 203late submission time ......................................... 200predecessor....................................................... 203resetting using CSF........................................... 276resource ............................................................ 205

Time periodsprioritizing work............................................... 410

Time rangehistory report .................................................... 302

TIMELINEflowcharts ......................................................... 350

Titleshistory report .................................................... 307

TODAY function .................................................. 153TOMORROW function......................................... 154TRIGGER command............................................... 96Triggering an Event................................................. 96

using a link ....................................................... 243Types of jobs......................................................... 211Types of resource .................................................. 382

U

UpdatingCSF view.......................................................... 266scheduled activity dataset ................................. 323

Usage meter............................................................. 49USE command ........................................................ 49User description .................................................... 356

labels ................................................................ 356

User Status fieldCSF................................................................... 260setting and resetting.......................................... 282

USERDESC keyword ........................................... 356

V

V commandCSF................................................................... 261

ViewCSF................................................................... 256customizing ...................................................... 262deleting............................................................. 267selecting............................................................ 268updating............................................................ 266

View Definitions panel.......................................... 261VS command........................................................... 84

W

Wait optionApplication....................................................... 184jobs................................................................... 184

WAIT optionsubApplication ................................................. 244

Width,history report .............................................. 309Workday................................................................ 110Workload object

owning Manager of........................................... 442Workstation............................................................. 28

X

XCFcommands......................................................... 428State Awareness ............................................... 433Trace ................................................................ 434

XCF Servicedisplaying ......................................................... 431stopping............................................................ 431

XCF Servicesdata set triggering ............................................. 429job tracking....................................................... 429starting.............................................................. 430

Y

YESTERDAY function......................................... 154

469

Reader’s Comment FormESP v.5.2 UG-02

We want tohear from you!

Please use this form to communicate your comments about this publication,its organization or subject matter with the understanding that Cybermationmay use or distribute whatever information you supply in any way itbelieves appropriate without incurring any obligation to you.

If your comment does not need a reply (for example, pointing out a typingerror), check this box and do not include your name and address below. Ifyour comment is applicable, we will include it in the next revision of themanual.

If you would like a reply, check this box. Be sure to print your name andaddress below.

Page Number(s) Comment(s)

Name _______________________________________________Company _____________________________________________Address ______________________________________________Fax: _________________________

470

Mail this form to:Cybermation Inc.80 Tiverton CourtMarkham, OntarioL3R 0G4Attn: Documentation Dept.

or Fax it to:Documentation Dept.(905) 479-4614

471

Reader’s Comment FormESP v.5.2 UG-02

We want tohear from you!

Please use this form to communicate your comments about this publication,its organization or subject matter with the understanding that Cybermationmay use or distribute whatever information you supply in any way itbelieves appropriate without incurring any obligation to you.

If your comment does not need a reply (for example, pointing out a typingerror), check this box and do not include your name and address below. Ifyour comment is applicable, we will include it in the next revision of themanual.

If you would like a reply, check this box. Be sure to print your name andaddress below.

Page Number(s) Comment(s)

Name _______________________________________________Company _____________________________________________Address ______________________________________________Fax: _________________________

472

Mail this form to:Cybermation Inc.80 Tiverton CourtMarkham, OntarioL3R 0G4Attn: Documentation Dept.

or Fax it to:Documentation Dept.(905) 479-4614

esp user guide

Documents