ESP User Guide

ESP Workload Manager
Version 5.2
User's Guide
ESP-UG-02
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 in any 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 by GSA 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 respective companies.
Table of Contents
About this Guide ................................................................................................................. 9 Conventions Used in this Guide........................................................................................ 10 Summary of Changes ........................................................................................................ 11 Introduction to ESP Concepts................................................................................................ 13 Overview ........................................................................................................................... 13 Functions of ESP............................................................................................................... 14 Time and Date Scheduling ................................................................................................ 15 ESP Events ........................................................................................................................ 16 Data Set Triggering ........................................................................................................... 17 ESP Procedures ................................................................................................................. 18 Applications ...................................................................................................................... 19 Inheriting Job Relationships.............................................................................................. 21 On Request Jobs ................................................................................................................ 22 Links.................................................................................................................................. 23 Tasks.................................................................................................................................. 24 Distributed Workload Objects........................................................................................... 25 Job Documentation............................................................................................................ 26 Consolidated Status Facility (CSF) ................................................................................... 27 Graphical User Interface.................................................................................................... 28 Symbolic Variables ........................................................................................................... 29 Tailoring Job Control Language........................................................................................ 30 Resources .......................................................................................................................... 32 Tracking Jobs .................................................................................................................... 34 Job Monitoring and Alert Processing................................................................................ 35 System Message Interception ............................................................................................ 36 REXX Interface................................................................................................................. 37 Reporting........................................................................................................................... 38 Modeling ........................................................................................................................... 41 Security.............................................................................................................................. 42 Getting Started ........................................................................................................................ 43 Overview ........................................................................................................................... 43 Accessing ESP................................................................................................................... 44 Accessing ESP as an ISPF Option .................................................................................... 45 Accessing ESP as a Batch Program .................................................................................. 54 Accessing ESP as a Program in TSO ................................................................................ 55 Accessing ESP as a TSO Command Processor................................................................. 56 Exiting ESP ....................................................................................................................... 57 Loading Commands .......................................................................................................... 58 Alternative Input Data Sets ............................................................................................... 60 Processing ESP Events............................................................................................................ 61
Overview ........................................................................................................................... 61 Defining an ESP Event...................................................................................................... 62 Naming an Event ............................................................................................................... 63 Defining Where an Event Will Execute............................................................................ 65 Defining When an Event Will Execute ............................................................................. 66 Specifying Scheduled Events ............................................................................................ 67 Controlling Event Scheduling ........................................................................................... 71 Specifying Data Set Triggered Events............................................................................... 74 Specifying the Function of an Event ................................................................................. 78 Issuing Operator Commands ............................................................................................. 84 Specifying Other Requirements ........................................................................................ 85 Displaying the Schedule.................................................................................................... 88 Expected Execution........................................................................................................... 89 Displaying when an Event will Execute............................................................................ 90 Working with Defined Events........................................................................................... 91 Listing Event Names or Definitions.................................................................................. 93 Simulating an Event .......................................................................................................... 94 Triggering an Event Manually........................................................................................... 96 Postponing Execution of an Event .................................................................................... 98 Bypassing Execution of an Event...................................................................................... 99 Overdue Events ............................................................................................................... 100 Altering Events................................................................................................................ 101 Deleting Events ............................................................................................................... 102 Schedule Criteria................................................................................................................... 103 Overview ......................................................................................................................... 103 Where You Can Use Schedule Criteria........................................................................... 104 Specifying Schedule Criteria........................................................................................... 105 Schedule Terms ............................................................................................................... 111 Using Other Techniques for Schedule Criteria ............................................................... 122 Testing Schedule Criteria ................................................................................................ 123 Using Calendars .............................................................................................................. 124 Using Calendar Terms..................................................................................................... 125 Defining Holidays ........................................................................................................... 126 Using Holidays ................................................................................................................ 128 Defining Special Days..................................................................................................... 129 Using Special Days ......................................................................................................... 130 Special Periods ................................................................................................................ 131 Using Special Periods...................................................................................................... 133 Working with Periods...................................................................................................... 134 Working with ESP Procedures ............................................................................................ 137 Overview ......................................................................................................................... 137 Overview of ESP Procedures .......................................................................................... 138 Invoking an ESP Procedure............................................................................................. 139 ESP Procedure Syntax..................................................................................................... 140 Using ESPs Control Language in Procedures................................................................ 141
Using Symbolic Variables in Procedures ........................................................................ 145 Using Expressions and Strings in Procedures ................................................................. 147 Built-in Functions............................................................................................................ 150 Using Calendaring Functions .......................................................................................... 152 Using Functions For Job Selection.................................................................................. 156 Using Functions For Symbolic Variables........................................................................ 158 Using System Activity Functions.................................................................................... 160 Combining Functions ...................................................................................................... 165 Re-executing an ESP Procedure...................................................................................... 166 Using Templates.............................................................................................................. 168 Using Event Definition Commands in Procedures ......................................................... 172 Examples ......................................................................................................................... 173 Using Applications ................................................................................................................ 178 Overview ......................................................................................................................... 178 Introducing Applications................................................................................................. 180 Identifying the Application.............................................................................................. 185 Identifying JCL Libraries ................................................................................................ 186 Identifying Jobs ............................................................................................................... 192 Defining Job Requirements............................................................................................. 199 Specifying Time Dependencies....................................................................................... 200 Specifying Job Relationships .......................................................................................... 208 Selecting Jobs for Submission ........................................................................................ 210 Using Different Job Types .............................................................................................. 213 Defining External Jobs .................................................................................................... 214 Defining Manual Jobs ..................................................................................................... 218 Using Links ..................................................................................................................... 221 Using Tasks ..................................................................................................................... 227 Changing Job Attributes.................................................................................................. 229 Using Data Set Trigger Workload Objects...................................................................... 230 Tagging Jobs ................................................................................................................... 236 Providing Notification on Job Status .............................................................................. 238 Using Critical Path Analysis ........................................................................................... 241 Issuing ESP Commands .................................................................................................. 246 Using subApplications .................................................................................................... 247 Working with Applications ............................................................................................. 251 Displaying an Application............................................................................................... 252 Controlling an Application.............................................................................................. 254 Changing an Application Definition ............................................................................... 256 Invoking an ESP Application .......................................................................................... 257 Consolidated Status Facility................................................................................................. 258 Overview ......................................................................................................................... 258 Setting up CSF Views ..................................................................................................... 259 CSF Fields ....................................................................................................................... 260 Defining a View .............................................................................................................. 264 Customizing a View ........................................................................................................ 265
Updating a View.............................................................................................................. 269 Deleting a View............................................................................................................... 270 Selecting Views............................................................................................................... 271 Working with CSF .......................................................................................................... 272 Commands....................................................................................................................... 273 Inserting a Job ................................................................................................................. 276 Resubmitting a Job.......................................................................................................... 277 Removing Job Dependencies .......................................................................................... 278 Resetting a Time Dependency......................................................................................... 279 Bypassing and Completing Jobs...................................................................................... 280 Adding Job Dependencies ............................................................................................... 281 Adding a Job with a Time Dependency .......................................................................... 282 Adding a Job Relationship in an Application.................................................................. 283 Adding a LINK Process................................................................................................... 284 Setting and Resetting the User Status Field .................................................................... 285 Using Other Commands .................................................................................................. 286 Extensions to CSF ........................................................................................................... 287 Freeform Filtering ........................................................................................................... 288 Specifying Boolean Operators......................................................................................... 294 Creating Reports ................................................................................................................... 296 Overview ......................................................................................................................... 296 History Reporting ............................................................................................................ 297 Structuring the Report ..................................................................................................... 298 Reporting Fields .............................................................................................................. 299 Field Formats................................................................................................................... 300 Invoking the Report Function.......................................................................................... 304 Specifying Input Criteria ................................................................................................. 305 Specifying Output Criteria .............................................................................................. 309 Ending the Report Definition .......................................................................................... 312 ESPs History Reporting Fields ...................................................................................... 314 Accumulating Fields ....................................................................................................... 320 Reporting on Scheduled Activity .................................................................................... 321 Allocating a Sequential Data Set..................................................................................... 322 Generating Data............................................................................................................... 323 Extracting Data................................................................................................................ 325 Generating Scheduled Versus Actual Report .................................................................. 326 Generating Projected Versus Actual Data....................................................................... 328 Extracting Tape Information ........................................................................................... 329 Using Job Mapping ......................................................................................................... 330 Job Mapping Data Set ..................................................................................................... 331 Generating Data for the Report ....................................................................................... 332 Producing a Job Activity Report ..................................................................................... 333 Producing a Job Descendent Report................................................................................ 338 Putting it All Together..................................................................................................... 340 ESP FLOWDOC ............................................................................................................. 341
Flowcharting.................................................................................................................... 350 Generating Flowcharts Using MS Project....................................................................... 351 Generating Flowcharts with ESP and Timeline .............................................................. 354 Job Documentation ............................................................................................................... 357 Overview ......................................................................................................................... 357 Contents of Job Documentation ...................................................................................... 358 Control Information......................................................................................................... 359 User Description.............................................................................................................. 360 Creating Job Documentation........................................................................................... 362 Using The Jobs Option.................................................................................................... 363 Updating Job Documentation.......................................................................................... 366 Using Job Documentation ............................................................................................... 367 Using the Control Information ........................................................................................ 368 Referencing Job Documentation Members ..................................................................... 370 Overriding Job Documentation ....................................................................................... 371 Using Job Documentation for Qualified Jobs ................................................................. 372 Using Job Documentation for Links and Tasks .............................................................. 374 Retrieving Information .................................................................................................... 376 Converting Existing Job Documentation ........................................................................ 378 Other Uses of Job Documentation .................................................................................. 381 Using Resources..................................................................................................................... 383 Overview ......................................................................................................................... 383 What is a Resource? ........................................................................................................ 385 Types of Resources ......................................................................................................... 386 Scope of Resources ......................................................................................................... 387 Using Real Devices ......................................................................................................... 388 Routing Jobs to Other Systems ....................................................................................... 389 Managing Jobs................................................................................................................. 390 Requesting Resources ..................................................................................................... 391 Default Resources ........................................................................................................... 396 Working with Resources ................................................................................................. 398 Defining Resources ......................................................................................................... 399 Setting Resources ............................................................................................................ 401 Deleting Resources.......................................................................................................... 402 Displaying Resource Information.................................................................................... 403 Step-level Resource Release ........................................................................................... 405 Resource Absorption ....................................................................................................... 407 Example: Controlling Mutually Exclusive Jobs.............................................................. 410 Example: Controlling Access to an Online System ........................................................ 412 Example: Time Periods for Low Priority Jobs................................................................ 414 Example: Using a Resource for a Self-completing Task ................................................ 416 Example: Controlling Access to a Database ................................................................... 417 Example: Running Jobs on a Particular System.............................................................. 418 Example: Controlling Mutually Exclusive Groups of Jobs ............................................ 420 Example: Planning for a System Shutdown - Part 1 ....................................................... 424
Example: Planning for a System Shutdown - Part 2 ....................................................... 426 Example: Schedule Dependency..................................................................................... 428 Using XCF with ESP............................................................................................................. 431 Overview ......................................................................................................................... 431 Commands....................................................................................................................... 432 XCF Services................................................................................................................... 433 State Awareness .............................................................................................................. 437 Trace................................................................................................................................ 438 Optimizing ESP Applications to Use Distributed Manager .............................................. 439 Overview ......................................................................................................................... 439 Planning Applications to Optimize DM.......................................................................... 440 Establishing Ownership of a Workload Object............................................................... 446 Creating Distributed Applications for use with Distributed Manager ........................... 447 Defining Manager Ownership of an Application ............................................................ 448 Changing Manager Ownership of an Application........................................................... 450 Changing Manager Ownership of an Application Dynamically ..................................... 451 Glossary of Terms ................................................................................................................. 453 Glossary........................................................................................................................... 453
About this Guide
Introduction
This guide provides you with an intermediate level of instruction for using Enterprise Systems Platform (ESP) Workload Manager, a very powerful and versatile system for scheduling jobs and managing workload.
Who should read this guide
If your job involves scheduling and managing jobs, you should find this guide useful. 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 this Guide
The preliminary chapters, Introduction to ESP Concepts on page 13 and Getting Started on page 43, provide important background information as a starting point. These sections, along with the glossary and index, are useful reference tools both now and when you are more familiar with the aspects of ESP discussed in this guide. The other chapters, Processing ESP Events to Using Resources, explain ESP in more detail.
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 the command in uppercase letters.
Syntax conventions
The Syntax diagrams in this guide use the following conventions:
Notation Apostrophes or Comma , Ellipsis Lower Case Italics parameter Uppercase parameter OR-bar ( | )
Underline ______ Parentheses ( ) and special characters Single parameter in square brackets [ ] Stacked parameters in braces { } { } Stacked parameters in square brackets [ ] [ ] Stacked parameters with OR-bars ( | ) and square brackets [ ] |[ ] Stacked parameters in square brackets within braces {[ ]}
Meaning Must be entered as shown. Must be entered as shown. The parameter can be repeated. Do not enter ellipsis. A parameter must be substituted. User supplied variable or character string. The parameter must be spelled as shown. You can enter the command and the parameter in either upper or lower case. Indicates an exclusive value on left or right of bar. You must enter one of the items. You cannot enter more than one. If you do not enter one of the parameters, the system supplies the underlined parameter, which is the default. Parameter enclosed in parentheses is mandatory and must be entered as shown. Optional parameter, do not type the brackets. Mandatory, you must enter one of the parameters. You cannot enter more than one. Optional parameter, you can enter one value, or none.
Optional, mutually exclusive parameters. Enter one or none.
Mandatory, you must enter one of these parameters. You can enter more than one.
10
Summary of Changes
Introduction
This guide contains information previously presented in ESP-UG-01, which supports ESP Workload Manager version 5 release 1.
Changed Information
This guide contains terminology, maintenance and editorial changes. A vertical line to the left of the text indicates technical changes or additions to the text.
New Information
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
11
12
Introduction to ESP Concepts Overview
Introduction
ESP Workload Manager is a very flexible and versatile job scheduling and workload-management system. Many of ESPs basic features are outlined in this guide. Other, more complex and lesser- used functions are covered in the Advanced Users Guide.
In this chapter
This chapter contains the following topics: Topic Functions of ESP Time and Date Scheduling ESP Events Data Set Triggering ESP Procedures Applications Inheriting Job Relationships On Request Jobs Links Tasks Distributed Workload Objects Job Documentation Consolidated Status Facility (CSF) Graphical User Interface Symbolic Variables Tailoring Job Control Language Resources Tracking Jobs Job Monitoring and Alert Processing System Message Interception REXX Interface Reporting Modeling Security See Page 14 15 16 17 18 19 21 22 23 24 25 26 27 28 29 30 32 34 35 36 37 38 41 42
13
Functions of ESP
Introduction
ESP helps you automate and manage workload in your installation through a variety 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
14
Time and Date Scheduling
Introduction
With ESP, you use simple, everyday English to schedule. ESP has a built-in understanding of common scheduling terms. ESP handles any variety and combination 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 require scheduling terms that are specific to your installation. To define your own customized set of scheduling terms, you can define one or more calendars. A calendar may contain: A list of holidays. Holidays can span one day, several days or just parts of a day. Lists of special processing dates. Descriptions of periods, such as fiscal months, fiscal years, 4-4-5 periods, 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 criteria like 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.
Additional information
For more information on time and date scheduling, refer to Schedule Criteria on page 103.
15
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 an Event
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.
Performing tasks
ESP can perform a variety of tasks through the Events you define. An Event must do one of the following: Send a message to you, other users, or operator consoles Submit JCL Invoke an ESP Procedure Issue an operating system command.
Example
An example of an Event appears below. It is an Event scheduled at 8 a.m. each day that submits a job.
EVENT ID(USER.MESSAGE) SCHEDULE 8AM DAILY SUBMIT 'SYS1.JCLLIB(PAYJOB1)' ENDDEF
For more information on Events refer to Processing ESP Events on page 61.
16
Data Set Triggering
Introduction
You can tell ESP when to process your Events depending on a date, or you can tell ESP to process your Events depending on data set activity. This feature of ESP is called data set triggering, and you can use it in conjunction with, or instead of, time and date scheduling.
Triggers for a data set
An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of jobnames. Events can also be made to wait for triggers from activity in more than one data set.
Example
An example of a data set triggered Event appears below. This Event sends a message to a user each time the data set CYB.APPL.BASKET closes.
EVENT ID (USER.APPL_RECEIVE) DSTRIG CYB.APPL.BASKET ANYCLOSE SEND 'APPLICATION RECEIVED FROM ESP WORKSTATION' USER(BP) ENDDEF
You can also use data set triggering for establishing individual job dependencies within your ESP Applications.
For more information on data set triggering refer to Processing ESP Events on page 61, and Using Applications on page 178.
17
ESP Procedures
Introduction
An ESP Procedure is a set of stored instructions that ESP invokes. Part or all of these instructions may define a group of jobs and tasks as an ESP Application. While you use an ESP Procedure to define all ESP Applications, not all ESP Procedures contain an ESP Application definition.
Controlling processing requirements
Using a combination of CLANG (ESPs Control LANGuage), ESP built-in functions, job specification statements, templates, and symbolic variables in a Procedure, you can control any processing requirements.
Uses of an ESP procedure
The main uses of an ESP Procedure are to: Define processing requirements for a group of jobs and tasks in an ESP Application Define and work with symbolic variables Take different actions based on other criteria, such as a job failure.
Example
The following is an example of using CLANG. In this example, ESP: Sends a message on workdays Submits job PAYJOB on the last workday of each month.
IF TODAY('WORKDAY') THEN SEND 'ANOTHER DAY OF HARD LABOR' U(BOSS) IF TODAY('LAST WORKDAY OF MONTH') THEN SUBMIT 'SYS1.JCLLIB(PAYJOB)'
For more information on Procedures, see Working with ESP Procedures on page 137.
18
Applications
Introduction
An ESP Application consists of one or more workload objects (e.g. job, message, command, script, manual task). An ESP Procedure describes an Application 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
Daily
Friday
Last workday of month

Continued on next page
19
Applications, Continued
Application definition
The corresponding Application definition might look like this:

APPL PAYROLL JCLLIB 'CYBER.ESP.JCL' JOB A RUN DAILY RELEASE (B,C) JOB B RUN DAILY RELEASE D JOB C RUN DAILY RELEASE D JOB D RUN DAILY RELEASE E JOB E RUN FRIDAY RELEASE F JOB F RUN LAST WORKDAY OF THE MONTH ENDJOB
Streamlining Applications
ESP lets you streamline the way you schedule and manage entire Applications. When ESP creates an Application it assigns a generation number to the Application. One generation does not need to complete before the next one starts. Several generations of the Application can run concurrently. ESP manages dependencies within the Application as well as between different Applications.
For more information on Applications refer to Using Applications on page 178.
20
Inheriting Job Relationships
Introduction
All jobs in an Application do not require the same frequency. When ESP selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited. Once you pre-specify your job relationships, ESPs advanced decision making skills determine the relationships required under different processing conditions.
Example
Consider the following three jobs and their schedule frequencies.

J1 Daily
J2
Friday
J3
Daily
On Fridays all three jobs execute in order, but on any other day of the week job J2 does not run. On these days, ESP selects J1 and J3 and inherits their relationships with J2. When J1 completes successfully, it releases J3.
For more information on how ESP inherits job relationships, refer to Using Applications on page 178.
21
On Request Jobs
Introduction
An on-request job is a job normally run on demand; it is not a regularly scheduled job. With Applications, you can identify certain jobs as on-request and define their relationships to other jobs. The on-request jobs take their place in the schedule. You can request a job anytime, from the time you generate the Application up to the time ESP submits the job. If you have not explicitly requested the job using a command, ESP bypasses it and treats it as a normal completion.
For more information on request jobs, refer to Using Applications on page 178.
22
Links
Introduction
A link is a task that does not require completion. You can use a link to process 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 could send a message, issue an operator command, or simply link two groups of jobs together.
LINK
For more information on using links, refer to Using Applications on page 178.
23
Tasks
Introduction
You can define tasks in an Application and establish dependencies between them and other tasks and jobs. You must mark a task complete before its successors become eligible for submission.
Task
A task may represent a manual process which requires intervention or it may represent 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 completes successfully. A task called CHECKRPT.J1 represents the task of checking the report.
(Job)
J1
CHECKRPT.J1
(Task)
J2
(Job)
For more information on using tasks, refer to Using Applications on page 178.
24
Distributed Workload Objects
Introduction
ESP Workload Manager Extensions extend the functionality of ESP Workload Manager to other platforms. Workload is scheduled by ESP Workload Manager and run on Agents. From a single point of control, your workload can be automatically managed on various platforms throughout your enterprise.
ESP Distributed Manager
ESP Distributed Manager manages UNIX and Windows NT workload after it is scheduled by ESP Workload Manager. Once the workload is scheduled, if the mainframe becomes unavailable, the workload can continue processing.
For information on scheduling workload on non-MVS platforms, refer to the ESP Workload Manager Extension documentation for the platform in which you are interested.
25
Job Documentation
Introduction
You can use ESPs job documentation facility to create a complete and centralized definition of all or any of your jobs. This powerful feature allows you to document the entire requirements of a job at the individual job level, including a jobs predecessors and successors, schedule criteria, due out time from various processing phases, resources required by the job, and more.
Scope of job documentation
As an extension to ESP Procedures, job documentation is much more than a list of processing requirements for a job. ESP can use the information you define and ensure that the job is processed as specified in the job documentation entry. If-then-else statements within the job documentation entry allow the job definition to fit with a variety of conditional or complex requirements.
For more information on job documentation see Job Documentation on page 357.
26
Consolidated Status Facility (CSF)
Introduction
The Consolidated Status Facility (CSF) is a focal point that provides a realtime view of the current workload. The CSF allows you to see which jobs have executed, which ones are currently on the system, and which jobs have yet to execute. CSF allows you to zoom in on any job or workload object to find out more information. You can also manipulate jobs, edit JCL, and restart jobs while in CSF. With CSF you can create customized views where you choose what you want to see and how you want it displayed. You may want to focus on one particular Application, or view all jobs that have failed.
Example
This example demonstrates the kind of job information that CSF can provide:
Customizing CSF
Through the use of CSF Extensions, you can further customize your use of CSF by writing your own commands, or by replacing existing commands. For example, you can launch other ISPF Applications, provide additional panels, and force the use of certain fields.
For more information on CSF see Consolidated Status Facility on page 258.
27
Graphical User Interface
Introduction
Schedulers and operators sometimes find graphical presentation of the workload helpful. Graphic flows make it easier to see job dependencies and to monitor the progression of work.
ESP Workstation
ESP Workstation is a graphical user interface for ESP Workload Manager. From a single point, ESP Workstation allows you to define, monitor and control your entire workload across multiple platforms. ESP Workstation users can: Use graphics to create ESP Applications Manage workload in real time.
For more information on ESPs graphical user interface, refer to the ESP Workstation User's Guide.
28
Symbolic Variables
Introduction
A symbolic variable is an object whose value may be changed during ESP processing. ESP provides powerful substitution capabilities through the use of symbolic variables. When ESP encounters a symbolic variable, it substitutes the current value of that variable. With symbolic variable you have all the flexibility you need to define date parameters, specify job names, and define job dependencies.
Using variables
ESP provides you with several built-in variables (such as times and dates) that can be substituted in Events, ESP Procedures and the JCL input stream. Also, you can define as many of your own symbolic variables as you need.
Example
The following are some examples of variables:

NAME=PATRICK DATE=%ESPSMM%ESPSDD%ESPSYEAR INTEGER X X=293
Attributes of symbolic variables
Each symbolic variable has a name and a value, and starts with a symbolic introducer character. The percent sign (%) is the default introducer character, although you can change this symbol at installation to suit your requirements. There are many operations that you can perform on symbols such as concatenation and using sub-strings.
For more information on symbolic variables and symbol libraries, refer to the Symbolic Variables chapter of the Advanced Users Guide.
29
Tailoring Job Control Language
Introduction
You can selectively tailor the JCL that ESP submits to the JES internal reader by 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 a job step every Monday. You can also use ESP to add a restart step, route a job to 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 to dates and times. The following example shows how to represent the scheduled date of a job in the format MM/DD/YY using built-in symbols. In this example, a user requests date information as data; you can use also symbolic variable as part of JCL.
//SYSIN DD * %ESPSMM%ESPSDD%ESPSYEAR
Example 2
When ESP submits this JCL for an Event scheduled on June 9,2000, ESP substitutes the built-in symbolic variable as shown below.
Original JCL //SYSIN DD %ESPSMM%ESPSDD%ESPSYEAR Substituted JCL on June 9, 2000 //SYSIN DD 06092000
You could generate another set of symbols to complement the built-in set of date and time variables for any date in the future or in the past.
Additional tailoring
In addition to using symbolic variables to insert different parameters such as time, date, day of week, and data set name into JCL, you can further tailor your JCL by using: Selective inclusion and exclusion of JCL and data JCL exclusion symbols Different symbol introducers Secured symbols Automatic variable insertion.
30
Tailoring Job Control Language, Continued
For more information on tailoring JCL, refer to the Advanced Users Guide.
31
Resources
Introduction
A resource is an item of hardware or software, or an abstract condition. There is no limit to what you can define as a resource.
Examples
Common examples of resources include: Disk space Scratch tapes Execution time An entity to control mutually exclusive jobs Online system availability DASD space Time periods Tape drives.
Resources
ESP supports the three following types of resources: Type of resource ... Renewable Explanation A renewable resource is a borrowed resource. When ESP submits a job, the job removes the resource from the resource pool and returns it upon completion. Some examples of renewable resources include tape drives, a database, or sort work space. A depletable resource is a consumed resource. When ESP submits a job, it removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP command. A depletable resource could refer to the number of scratch tapes available or to permanent DASD space.
Depletable
32
Resources, Continued
Resources (continued)
Type of resource ... Threshold
Explanation A threshold resource is a sizing resource. You can think of a threshold resource as a variable height doorway into the system. If the resource quantity is set to 2, any number of jobs requiring 2 or less units are able to be submitted. However, any job requiring 3 or more units are too high to pass through the door and so is not submitted. In other words, ESP sizes the job against the current level of the threshold resource. This type of resource could be used to prevent certain jobs from executing until a NITESHFT period begins, for example.
Resource Requirement
You can define resource requirements for any job. You can also use default resources where ESP automatically determines resource requirements for a job based on historical data.
For more information on resources see Using Resources on page 383.
33
Tracking Jobs
Introduction
ESPs job tracking facility tracks job data in real time as jobs are being processed. You can use ESPs job tracking facility to tell ESP to track your jobs and keep information on the progress of these jobs. You can ask ESP to track both jobs that it submits and jobs that it does not submit. Also, you can tell ESP to track Started Tasks (STCs) and TSO users (TSUs). ESP provides detailed step-level statistics in real-time. ESP maintains completion codes for each job step, and provides data such as CPU time, elapsed time, disk and tape I/O counts, number of tape mounts, tape drives and so on.
Example
The following example shows a sample output from a command to display tracking data for job PAYD008A.
LJ PAY008A(6308) PAYD008A JO6308, COMPLETED, CC SOC1, NODE CYBJES SUBMITTED BY ESP AT 10.06 ON TUE 13APR, EVENT CYBBP01.PAY JCL FROM CYBBP01.ESP.DEMO.JCL(PAYD008A) JCL COPIED TO CYBBP01.ESP.DEMO.COPYJCL(PAYD08A) PROGRAMMER BOB, ACCOUNT CYBTEST JOB IS IN APPL PAY INFORMATION/MANAGEMENT RECORD 0000053 CREATED FOR THIS JOB STEPNAME-PROCSTEP-PROGNAMEEXCEP-#T-S-N-CPU-TIME-SUNITS-REGION-CMPC ENCORE ESPRM CYBRM000 30 0 0 0 0:00.48 2635 320K 0 STEP01 IEFBR14 0 0 0 0 0:00.00 0 4K 0 STEP02 IEBGENER 0 0 0 0 0:00.00 0 72K 0 STEP03 SOC1 1 0 0 0 0:00.13 428 8K SOC1 STEP04 IEFBR14 0 0 0 0 0:00.00 0 0K STEP05 IEBGENER 0 0 0 0 0:00.00 0 0K ESPCCFCK IEFBR14 0 0 0 0 0:00.00 0 0K PNODE----OUT---QTIME-POST_BYSYS-|PNODE----OUT---QTIME-POST_BYSYS INPUT 10.06 5 CYB1|EXEC 10.06 12 SYSTEM CYB1 OUTPUT 10.06 13 SYSTEM CYB1
Tracking models
ESP allows you to define a tracking model to track a group of jobs with similar characteristics. This tracking model has the advantage of enabling you to define and modify the tracking characteristics of multiple jobs at the same time. You can, for example, use a tracking model to identify jobs for which you want to keep long term historical data and then use the data with ESPs history reporting facility. For more information on setting up your job tracking environment, see the Administrators Guide.
34
Job Monitoring and Alert Processing
Introduction
ESPs Job Monitor facility and Alert Processing facility can automatically take action at different processing points, for example, stepend, jobend, and overdue.
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 either facility.
For more information on Job Monitoring and Alert Processing, see the Advanced Users Guide.
35
System Message Interception
Introduction
ESP can intercept any message while it is being written to the system messages data set. This happens in real-time and can be used to detect conditions such as NOT CATLGD and other important message portions or message identifiers. ESP may cancel the job, fail the job with a JCL error or Condition code failure, trigger an Event, or rebroadcast the message as a WTO (write-to-operator).
Example
The following example requests the cancellation of a job whenever a NOT CATLGD message starting anywhere between column 50 and 60 is generated for that job. It also specifies that this message be routed to consoles with route code 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 Advanced Users Guide.
36
REXX Interface
Introduction
You can use IBMs high level, procedural language called REstructured EXtended eXecutor language (REXX) with ESP. REXX extends ESPs capabilities by providing it with another powerful command language. You can use REXX anywhere you use ESPs Command Language (CLANG), or you can mix the two languages together to provide powerful functions in an easy-to-use fashion.
Uses of REXX
You can use REXX with ESP 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 Users Guide.
37
Reporting
Introduction
ESPs reporting facilities can give you up-to-date information about scheduled jobs that executed in the past or will execute in the future. Reporting facilities include: History Scheduled activity Job mapping.
History reporting
ESP has a powerful and versatile generalized reporting facility which provides detail about the progress of your jobs at any time up to the present. This facility extracts and formats data from the ESP history files to meet a variety of requirements. The reports specified can be as detailed or as simple as you require. You can include a variety of job aspects such as jobname, status, tape allocation, and so on. The report formats you define can be named and used repeatedly. In addition, reports are available online and in hardcopy.
Fields to use as selection criteria
ESP retains over 60 items of history data for each tracked job. The fields you can use as selection criteria and for display in your reports include, but are not limited to: Execution queue time Print time Start and end dates Start and end times Overdue times EXCP counts Number of job steps.
38
Reporting, Continued
Example
The following is an example of a report on all PAY- jobs which executed on March 3,1998:
JOBNAME JOB NO PAYD001A 2221 PAYD002A 2227 PAYD003A 2226 PAYD004A 2229 PAYD100A 2232 PAYD006A 2233 PAYD008A 2234 PAYD008A 2270 PAYD008A 2271 PAYD009A 2272 PAYD010A 2273 PAYD010A 2275 PAYD011A 2276 SUBTOTAL (13) TOTAL (13) COMP CODE 0 0 0 0 0 0 SOC1 SOC1 0 0 SOC1 0 0 EXEC START 11.56 12.02 12.02 12.02 12.07 12.08 12.08 12.57 12.58 12.58 12.59 12.59 12.59 START EXEC END DATE END DATE TUE 03MAR98 12.02 TUE TUE 03MAR98 12.02 TUE TUE 03MAR98 12.02 TUE TUE 03MAR98 12.07 TUE TUE 03MAR98 12.07 TUE TUE 03MAR98 12.08 TUE TUE 03MAR98 12.08 TUE TUE 03MAR98 12.57 TUE TUE 03MAR98 12.58 TUE TUE 03MAR98 12.58 TUE TUE 03MAR98 12.59 TUE TUE 03MAR98 12.59 TUE TUE 03MAR98 13.04 TUE CPU TIME 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 03MAR98 0:01 0:00 0:00 0:04 0:00 0:00 0:00 0:00 0:00 0:00 0:00 0:00 0:01 0:06 0:06
For more information on history reporting, refer to Creating Reports on page 296.
Scheduled activity reporting
The scheduled activity reporting facility forecasts, at the job level, the system workload for a future time period. This reporting facility allows you to generate both hardcopy and online reports displaying a variety of statistics about jobs that ESP scheduled, including: Execution time CPU time Print lines Tape requirements Application name.
For more information on scheduled activity reporting, refer to Creating Reports on page 296.
39
Reporting, Continued
Job mapping
Job mapping is a reporting facility that allows you to produce detailed job information. You can generate the following reports: Job activity report. This report contains detailed information on jobs including job name, Application name, job type, Event name, ESP Procedure name, JCL library, execution time, CPU time, and predecessor and successor jobs. Job descendent report. This report shows a job and its successors.
For more information on scheduled activity reporting, refer to Creating Reports on page 296.
40
Modeling
Introduction
ESP has a modeling feature that forecasts how ESP processes a group of jobs in your particular systems environment. Scheduled activity reporting provides you with information based on what ESP schedules. Modeling takes this one step further. ESP combines the schedule with what it knows about the scheduling environment to predict future activity. You define your environment and then ESP creates a picture showing how a future schedule period looks. Modeling allows ESP to forecast the influence of factors such as CPUs, initiators and resources.
Modeling Reports
Modeling generates reports on jobs, resources and exceptions. For example, you can generate a report that shows you all jobs that will not meet their scheduled due out time. 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.
Use of modeling reports
For more information on modeling, see the Advanced Users Guide.
41
Security
Introduction
Whether you have schedulers and operators scheduling all of the work or end users submitting their work, ESP provides you with the security flexibility to ensure the integrity of your system. ESP performs work based on the security attributes of the user, not on the attributes of ESP itself. Because ESP uses a client/server design, it requests work to be done on behalf of the user. Before the ESP server executes the requested routines, it checks to see if the user is authorized for the requested work. This method of security works for any type of user: individuals, production groups, or service bureau customers.
Host security programs
ESP supports RACF, CA-ACF2 and CA-TOP SECRET. It manages support for these host security programs without the need to use exits or modify JCL. ESP offers further security measures through a SAF interface. ESPs SAF interface provides granular security over all functions and resources.
For more information on security, see the ESP Administrators Guide.
42
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 commands into ESP, and how to use different data set types as input for ESP.
In this chapter
This chapter contains the following topics: Topic Accessing ESP Accessing ESP as an ISPF Option Accessing ESP as a Batch Program Accessing ESP as a Program in TSO Accessing ESP as a TSO Command Processor Exiting ESP Loading Commands Alternative Input Data Sets See Page 44 45 54 55 56 57 58 60
43
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
44
Accessing ESP as an ISPF Option
Introduction
If your MVS system has ISPF you can use ESPs menus and panels. ESP has panels that step you through the definition of Events, Applications, calendars, and jobs. Other panels allow you to display job tracking information and for reporting scheduled activity. ESPs ISPF interface uses the dialog manager. It allows the use of ISPF functions such as split screen, edit, and multiple sessions. As well as menus and panels, ESPs Page mode provides scrollable data, and the ability to edit and save any portion of an ESP session. The method for accessing ESP from ISPF differs with each installation. Check with your system administrator for the method that your site uses.
Screens for ISPF interface
The layout of each screen is designed as similar as possible to the panels you are already accustomed to seeing when using ISPF. The Command or Option field is always at the left of the second panel line. Short messages are displayed top right, while long messages occupy line three, which is otherwise blank. The maximum length of most panels is 23 lines. This facilitates the use of split-screen mode where it is available. Panels with scrollable data will extend to the entire screen capacity. When you invoke ESP, the Main Menu appears. It displays the available options: Events, Calendars, Consolidated Status Facility, and so on. Many ESP commands are available through menu mode. There is a wide choice of menus, entry panels and help screens.
45
Accessing ESP as an ISPF Option, Continued
Main Menu Screen
The screen below shows the ESP Main Menu.
ESP's menu panels
To use a command, first select an option from any menu or selection panel. Then specify your requirements by entering appropriate data in labeled fields on the entry panel. All entry fields are labeled with an arrow (===>). ESPs menu panels are easy to use. Required fields are indicated, and you are prompted if you omit required information or make a recognized error in any of your entries. If a short message prompt is insufficient to clarify an error or omission, display a long message by entering the HELP command (PF1) to provide more information.
46
ESP Main Menu Options
The ESP Main Menu is the first ISPF panel. It provides the following options:
Option Set your ESP defaults
Events
Applications
Calendars
Use this option to ... 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 ISPF sessions. ESP automatically transfers your input to the appropriate panels. For example, ESP can use a default ESP Procedure Library when you define an Event. You can override information in any field. Test schedule criteria Add a new Event definition Display the next execution times of an Event Alter, browse, delete, edit, simulate, hold, release, suspend, resume, or trigger an Event you have already defined Obtain a list of Events by prefix. Get information on the status of your Application Create an Application definition using panels. Define and display calendar information including holidays, special days, and special periods.
47
ESP Main Menu Options (continued)
Option Jobs
Job Tracking
Scheduled Activity
Consolidated Status Facility (CSF)
Use this option to ... Set up job documentation. You can specify processing requirements for any job as well as user information such as ABEND codes and messages. Display job status Access commands to display job tracking information Display tracking models Use P-Nodes Display the number of jobs on each PNode queue Display the names of jobs on P-Node queues Display jobs on the ABEND queue. View information on the scheduled activities you want ESP to perform. This information gives you a snapshot of which jobs will be on the schedule during a specified future time. It also provides some additional information about the jobs, such as estimates on: Execution time CPU time Print lines Tape specifications CPU absorption. View information on jobs and Applications that ESP tracks. Once you have chosen a display, you can use commands to manipulate jobs, Applications, subApplications, or any of the related ESP definitions.
48
ESP Main Menu Options (continued)
Option ESP Utilities
Page Mode
ESP Administration
ESP Encore
USE Command
Use this option to ... Load a series of ESP commands Display information on key ESP data sets, tracking cells, data set triggers and system attributes. Switch directly into the Page mode method of communicating with ESP. In this mode you can use the command line for input, while receiving scrollable output in return. Refer to the section Using ESPs Page Mode ON PAGE for detailed information on using this option. This option is only available to the ESP Administrator and departmental administrators. The administrator can use this option to define and update users, groups, and calendars, and to test and modify job tracking definition tables. If your installation uses your host security system for ESP security, you do not use this option to define users and groups. Take you to the Job List Panel of ESP Encore, Cybermations rerun/restart product. This option only appears on your menu if you have ESP Encore installed. Enter the USE command on the OPTION line, from the ESP main menu, to display ESP statistics on various activities. These statistics are reset to zero following an ESP cold start.
49
USE command sample
ESP ------------ Usage ------------ ROW 1 TO 4 OF 4 Command ==> Scroll ===> CSR This This This Since Last Activity Year Month Day ESP Start ------------------------------------------------------------Applications completed 2930 430 25 75 Applications created 2994 450 32 100 Events executed 3232 472 41 115 Jobs submitted 65678 8250 563 1694
Using ESPs Help Option
While you work with ESP you can access the online, panel-specific Help screens at any time. By pressing the Help key (PF1/PF13) you access Help about the particular screen on which you are working.
Using ESPs Page mode
To use Page mode, type the information in free format, line by line, on the command entry line. After entering data, the data and resultant output appear in a scrollable field below the command line.
50
Example: Page mode screen
The following is an example of using Page mode:
Input line entry
Each time you complete an input line, press Enter. ESP adds the line, highlighted, to the bottom of the input display. To re-enter a previous line follow the steps below: Step 1 2 3 4 Action Move the cursor to that line using the arrow keys. Press Enter. The line appears on the command line. Edit the line. Press Enter.
Similarities to ISPF Browse
Page mode appears very similar to ISPF Browse. However, not all Browse commands are available. If you want to use the delete and find features, you must type EDIT on the command line. The EDIT command lets you delete or change the Page mode output and store it. When you use the EDIT command, ESP automatically copies all the sessions data into a temporary work file that it displays immediately. You can write the data into a more permanent existing data set or a new member of a PDS using the CREATE or REPLACE commands.
51
Writing session data
Follow these steps when writing session data to a data set:
Step 1 2
3 4
Action Use the CC or MM block commands to select the lines you want to copy to the data set. Type either CREATE or REPLACE on the command line. CREATE makes a new member for the data. REPLACE overwrites an existing data set with the new information. Press Enter. Respond to the prompt for a data set name: If you used the CREATE command, enter the name for your new member and the existing data set to which it will belong. OR If you use the REPLACE command, enter the name of the existing data set that you want to overwrite.
WARNING
Do not use the SAVE command. The SAVE command writes the data back to the temporary work file which ESP discards at the end of your session.
Using The Page mode screen
In Page mode, ESP retains your entire session on the screen. As you enter more data, the screen scrolls up to make room. You can scroll the screen up or down to view all of the data. If any headings are attached to your input, the headings remain in view at the top of your screen while the data scrolls below them. Also, any informational, warning, and error messages appear in the short message fields at the top of the screen, as in ISPF.
Notes
A few notes about using the Page mode: To scroll use the standard scroll keys: PF7 to move up, and PF8 to move down. To scroll more quickly you can enter TOP or BOTTOM in the command line. To access a specific line number quickly use the LOCATE command.
52
Displaying Informational Messages
To display informational messages where they occur in the input instead of at the top of the screen, enter on the command line:
INFOMSG SET
You can prefix these messages with a string of your choice by entering on the command line:
INFOMSG SET PR('STRING')
To return informational messages to the top of the screen, type on the command line:
INFOMSG RESET
53
Accessing ESP as a Batch Program
Introduction
Although many of ESPs 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 series of commands.
ESP in Batch
To execute ESP commands in batch, use the following JCL after your jobcard:
//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 continuation character. If you are using a hyphen as a mask, you should follow it with a semi-colon. For example, LTJ -;
Subsystem name
If the subsystem name for ESP is not ESP, you need to type the subsystem name. For example, if the subsystem name is ESPA, type:
//EXEC PGM=ESP,PARM='SUBSYS(ESPA)',REGION=4000K
Steplib
If the TSO command processor is not in a LINKLIST library, you will need a STEPLIB or JOBLIB statement in your JCL. Your statement may look like:
//STEPLIB DD DSN=CYB.ESP.LOAD,DISP=SHR
54
Accessing ESP as a Program in TSO
Invoking ESP as a program in TSO
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 the subsystem 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 an arrow: ==> TSO refers to this prompt as a MODE message. To turn on the TSO mode message, at the TSO prompt, type:
PROFILE MODE
You are now in ESP 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 their syntax. You can find the ESP commands and syntax in the ESP Command Reference manual.
Example: Invoking the ESP Command from a CLIST
The following is an example of a CLIST that invokes the ESP command processor directly. The CLIST: Prompts a user for the name of a job to be submitted Accepts the name of the job Invokes the ESP command processor Triggers an Event, passing the name of the job as a user parameter.
PROC 0 WRITE Enter the name of the job you want to run READ &J ESP SUB(ESPX) TRIGGER &USER.ADDJOB USER1("&J") END
55
Accessing ESP as a TSO Command Processor
Calling ESP from a CLIST
You can also access ESP as a TSO command processor by using a CALL instruction to the ESP load library.
Note
Using this method, you may be limited by the size of the parameter list you pass on the CALL instruction.
Example: Calling ESP from a CLIST
The following is an example of a CLIST using a CALL instruction. In this example the subsystem name for ESP is ESPX. The CLIST: Prompts a user for the name of a job to be submitted Accepts the name of the job Calls the ESP TSO command processor Triggers an Event, passing the name of the job as a user parameter.
PROC 0 WRITE Enter the name of the job you want to run READ &J CALL 'CYB1.ESP510E.LOAD(ESP)' SUB(ESPX);TRIGGER &USER.ADDJOB USER1("&J");END'
56
Exiting ESP
Methods of exiting ESP
To exit ESP at any time follow the instructions below:
If you are... using the ISPF panels...
in Line mode... in Page mode...
Action Press the END key (PF3/15) until you return to the ISPF Primary Option Menu Type END Press PF3/15
57
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 of commands.
Example: Loading diagnostic commands from a data set
Suppose you have a member DIAG of a data set called CYB.ESP.DATA that contains a number of ESP diagnostic commands, like this:
SMFSTATS LISTRAK OPER LISTAPTF LISTCKPT LISTQ
You can process all of these commands by issuing the following command in Page mode:
LOAD 'CYB.ESP.DATA(DIAG)'
58
Loading Commands, Continued
Sample output
SMFSTATS ESP SUBSYSTEM INITIALIZED AT 12.43.58 ON MONDAY JUNE 27TH, 1994 9213 ENTRIES TO SMFWTM, 1592 BY BRANCH ENTRY AND 7621 BY SVC 4863 ENTRIES TO ESP PHASE 2 7272 JOB STARTS, 595 STC STARTS, 645 TSU STARTS, 9051 STEP ENDS LISTTRAK TRAKFILECYB3.ESP430NV.TRAKFILE FORMATTED AT 16.15.17 ON MONDAY SEPTEMBER 27TH, 1993 9296 SLOTS TOTAL, 8857 AVAILABLE, NEXT IS 6223 OPER LISTAPTF DATASET CYB3.ESP430NV.APPLFILE FORMATTED AT 15.00.54 ON MONDAY OCTOBER 18TH, 1993 6000 SLOTS TOTAL, 5735 AVAILABLE, NEXT IS 2504 ---1 ENTRY DISPLAYED LISTCKPT PRIMARY CHECKPOINT CTB3.ESP430NV,CKPT MAX CHECKPOINT SIZE 614400 HIGHEST ADDRESS USED 4032 80 BYTES IMBEDDED FREE SPACE LISTQ QUEUE DATASET CYB3.ESP430NV.QUEUE FORMATTED AT 13.44.57 ON MONDAY JUNE 13TH, 1994 MAXIMUM SIZE 614400 BYTES HIGHEST ADDRESS USED 3888, 480 BYTES IMBEDDED FREE SPACE
59
Alternative Input Data Sets
Introduction
In addition to standard O/S and VSAM data sets, ESP lets you input commands from ROSCOE, Librarian and Panvalet data sets. Each of these data set types has specific conventions.
Prefixes for data sets
You can use the following prefixes when you need to use one of these types of data sets: Prefix ROSLIBPANROSCOE Librarian Panvalet Type of Data set
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.
60
Processing ESP Events Overview
Introduction
In ESP, an Event is a basic unit of work. Information in an Event defines when ESP must perform the work and the actions it must take to do so.
In this chapter
This chapter contains the following topics: Topic Defining an ESP Event Naming an Event Defining Where an Event Will Execute Defining When an Event Will Execute Specifying Scheduled Events Controlling Event Scheduling Specifying Data Set Triggered Events Specifying the Function of an Event Issuing Operator Commands Specifying Other Requirements Displaying the Schedule Expected Execution Displaying when an Event will Execute Working with Defined Events Listing Event Names or Definitions Simulating an Event Triggering an Event Manually Postponing Execution of an Event Bypassing Execution of an Event Overdue Events Altering Events Deleting Events See Page 62 63 65 66 67 71 74 78 84 85 88 89 90 91 93 94 96 98 99 100 101 102
61
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 the schedule criteria, if any, and decides when to first schedule it. ESP saves Events in an EVENTSET, which is a VSAM data set defined to ESP. You can later display or manipulate your Event if you need to look at or change it. You can also add or delete Events at any time.
Defining an Event
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 Events 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 MONTH SUBMIT 'TEST.JCL.CNTL(JOB1)' ENDDEF
When ESP encounters the ENDDEF command, it sends the Event to the ESP subsystem for processing. It also sends a message to the user who defined it, telling the date and time on which the Event will first execute, or warning the user that no schedule elements exist.
62
Naming an Event
Introduction
The first step in defining the Event is naming. Naming an Event establishes its ownership, which is important for security. Not all users have the same authority or access to functions and resources. A security system such as RACF, CA-ACF2, or CA-Top Secret, as well as ESPs internal security, can control the authority and access users have.
Event name
An Event name has two parts: Part of Event name Prefix Explanation The name of a user or group containing up to eight alphanumeric characters, including the national characters. This prefix must be a prefix you are allowed to use. Your ESP administrator controls which prefixes you are allowed to use. A description that can contain up to 16 characters, including the national characters and the underscore. The first character must be alphabetic.
Descriptive name
Duplicate Events
When an Event with the same name already exists, ESP ignores your new definition. To replace the old definition with the new one, use the REPLACE keyword.
Use of the prefix
When ESP triggers an Event, it must verify the security requirements of the actions the Event performs. The security identifier ESP uses is determined by a number of settings. For more information on security, refer to the Administrators Guide.
63
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
DOROTHY.PHONE_BILL
PROD.TRAINING PROD.PAYROLL
Example: Naming an Event
A production scheduling group might use a prefix of PROD. They might use the descriptive name PAYROLL_PROCESSING to describe an ESP Event:
PROD.PAYROLL_PROCESSING
64
Defining Where an Event Will Execute
Introduction
In a multiple CPU environment you should use the SYSTEM keyword on the EVENT command to identify the system on which the Event is to activate. This applies to Events that are not manually triggered. This is the name by which ESP knows the system and may not necessarily be the same as the SMF identifier. Check with your system administrator or use the LSYS command for the correct name to use.
Systems
All Events that create ESP Applications should point to the ESP system designated as the Master system. Other Events may need to execute on a specific system as they need to process commands for that system. If the system does not matter, you can specify SYSTEM(-). Note: This does not affect where jobs run; JES controls this.
Example
This example identifies a system identifier of ESPM for the Event PROD.BILLING.
EVENT ID(PROD.BILLING) SYSTEM(ESPM)
65
Defining When an Event Will Execute
Trigger for an Event
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 triggering in Events, and how to manually trigger an Event. For information on other types of Events, including signalled, job monitor, and Alert Events, refer to the Advanced Users Guide.
66
Specifying Scheduled Events
Introduction
The schedule criteria you enter tells ESP when to execute your Event. You can use the SCHEDULE command to specify this criteria, which generally includes a time and a frequency.
SCHEDULE command
Each command, or scheduling statement, begins with SCHEDULE followed by the time period for execution. For example:
SCHEDULE 10AM DAILY
You can specify as many SCHEDULE commands as you need. For example, you might want to schedule an Event at different times during a week.
SCHEDULE 4PM WEEKDAYS SCHEDULE 2PM WEEKENDS
Overlapping Criteria
If the times in more than one SCHEDULE command coincide, the Event only executes once. The following example only executes once at midnight, even though the second statement also schedules an execution at midnight every fourth execution.
SCHEDULE MIDNIGHT DAILY SCHEDULE EVERY 6 HOURS ROUND WEEKDAYS
Examples: SCHEDULE statements
Here are examples of schedule statements:

SCHEDULE SCHEDULE SCHEDULE SCHEDULE SCHEDULE 7PM DAILY 10:00 LAST WORKDAY OF MONTH 16:00 3RD 13TH 23RD DAY OF MONTH 9AM 2ND LAST DAY OF MONTH EVERY 4 HOURS ROUND
For more information on schedule criteria, see Schedule Criteria on page 103.
67
Specifying Scheduled Events, Continued
Scheduling an Event once
If you want a SCHEDULE command to execute only once, followed by a deletion of the Event, use the ONCE keyword. This keyword might be useful if 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 of the ONCE keyword, the Event deletes itself 24 hours later.
EVENT ID(USER1.SPECIAL) SCHEDULE 8AM AUG29,2000 ONCE SEND '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.
Handling exceptions
An Event executes once at every time and date you specified in your SCHEDULE statements. You can use the NOSCHED command to handle exceptions. If your SCHEDULE statement has a time, then you must use the same time on the NOSCHED statement.
Example: Schedule exception
This example schedules an Event at 8 a.m. each workday, except at 8 a.m. on the last workday of each month:
SCHEDULE 8AM WORKDAYS NOSCHED 8AM LAST WORKDAY OF MONTH
68
Example: Schedule exception-once
This example schedules an Event at 8 a.m. each workday, except on February 13, 2000. The use of the keyword ONCE causes the Event not be scheduled on this date only.
SCHEDULE 8AM WORKDAYS NOSCHED 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 Events 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 its execution, it considers the Event overdue. When the Event becomes eligible, for example after an outage, ESP checks the Event definition to determine how to process the Event. The overdue count specifies how many overdue occurrences of the Event ESP must process.
Advance/Delay/ Ignore/ Processing
Your scheduling criteria for Event execution may create conflicts. For example, 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 or weekdays Delay the event (run it later than usual) by any number of days or weekdays Ignore the Event (do not run it at all). You can use the ON command with a SCHEDULE command to advance, delay, or ignore Event processing if the Event falls on a holiday, weekday, weekend, or particular day of the week. You can use multiple ON commands in an Event.
69
Example: Changing processing
If you schedule your Event to run on the 12th day of every month, but do not want it to run if the 12th falls on a weekend or holiday, you can delay the Events processing using the ON command. Type ON followed by the criteria you do not want the Event to run. Then type your DELAY keyword and the amount of time you want the Event delayed. Your Event might look like this:
EVENT ID(CYBER.TWELVE) SCHEDULE 12TH DAY OF MONTH ON WEEKEND DELAY 1 WEEKDAY ON HOLIDAY DELAY 1 WEEKDAY INVOKE 'TEST.ESP.PROC(MYAPPL)' ENDDEF
By indicating a delay of one weekday, you ensure that even if the 12th falls on a Saturday, Sunday, or a Holiday, it runs during the week.
70
Controlling Event Scheduling
Introduction
There are five commands you can use when you define an Event to control the processing of that Event. For example, you can schedule a deletion of an Event or schedule an Event to be suspended at some time in the future. These commands are: DELETE, HOLD and RELEASE, SUSPEND and RESUME.
DELETE command
Use the DELETE command to schedule the deletion of an Event. You might use the DELETE command if, for example, you want to delete an Event that is only temporary. Perhaps you want to delete a daily Event after a particular date.
DELETE 10AM AUG 23, 2000
HOLD and RELEASE commands
Use the HOLD command in an Event if you want to hold an Event from being processed by ESP at a particular time. When ESP encounters a HOLD command in an Event, it increases the Events hold count by one at the time and date specified in the command. As long as the hold count has a value of at least one, ESP delays the Events execution. This way you can use the HOLD command to postpone an Event. Conversely, the RELEASE command decreases the Events hold count at the time and date specified in the command. When the hold count equals zero, the Event is eligible for execution. If the Events scheduled time comes up while it is being held, ESP marks the Event as overdue. ESP adds a comment to a held Event if it misses its scheduled time, indicating that execution is pending and the time it should have executed. For example:
//*EXECPEND AT('9:30 2000 JUN7')
Refer to Missed Events earlier in this chapter for a further explanation of the overdue count. After you release the Event, ESP checks the overdue count. If you specified a number other than zero, or let the count default to one, the Event executes immediately for every occurrence it missed while on hold, up to the value of the overdue count.
71
Controlling Event Scheduling, Continued
Example: Holding a data set triggered Event
You have an Event, PROD.PAYROLL, that is triggered by the close of the data set PAYROLL.INPUT, but you do not want it to run between 6 a.m. and 10 p.m. To prevent the Event from executing in that time period, you can use the HOLD command to delay PROD.PAYROLL if the data set PAYROLL.INPUT closes between 6 a.m. and 10 p.m. The RELEASE command reduces the Events hold count back to zero at 10 p.m., letting the Event trigger if the data set was created:
EVENT ID(PROD.PAYROLL) DSTRIG PAYROLL.INPUT HOLD DAILY AT 6AM RELEASE DAILY AT 10PM INVOKE 'ESP.PROCS(PAYJOBS)' ENDDEF
SUSPEND and RESUME commands
The SUSPEND command works similarly to HOLD, but has a slightly different purpose. If an Event misses its scheduled execution time while suspended, ESP ignores the Event and does not execute it at all or mark it overdue. Each time ESP encounters SUSPEND it increases the Event suspend count by one at the specified time and date. While the suspend count is greater than zero, ESP bypasses the Event without executing it. The RESUME command reduces the suspend count by one at each occurrence. When the suspend count is zero, ESP can execute the Event at the next scheduled time.
72
Controlling Event Scheduling, Continued
Example: Scheduling an hourly Event during a time range
In the following example, an Event notifies the user of the time (%ESPATIME is a symbolic variable) once an hour, on the hour, workdays, from 8 a.m. to 4 p.m. The SUSPEND command stops ESP from sending the message after 4:01 p.m. and the RESUME command restarts the message again at 7:59 a.m.:
EVENT ID(CYBER.HOUR_MESSAGE) SCHEDULE WORKDAYS HOURLY ROUND STARTING TODAY SEND 'TIME IS %ESPATIME' U(*) SUSPEND 16:01 WORKDAYS RESUME 7:59 WORKDAYS ENDDEF
Suspended and Held Event
If an Event is both suspended and held at its scheduled execution time, ESP ignores the hold state and considers the Event suspended
73
Specifying Data Set Triggered Events
Introduction
An Event can be triggered automatically by the creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. Triggering can be restricted to data sets created by a specific job or group of jobnames. Events can also be made to wait for triggers from activity in more than one data set. Refer to the section Using Applications for techniques on setting up data set triggering for individual jobs in an ESP Application. You can use data set activity to trigger an Event through the DSTRIG command.
Data set Triggered and Scheduled Events
You can use this command in addition to an Events time and date schedule, or instead of it. When your Event contains both SCHEDULE commands as well as DSTRIG commands, executions caused by the time schedule do not affect the DSTRIG conditions. The Event executes at both the scheduled times and, in addition, when the DSTRIG conditions are satisfied.
Abnormal Closures
ESP does not trigger a data set triggered Event when the data set closes during an abnormal termination of a task or job step. When more than one DD (data definition) statement in a step references the data set, the Event is only triggered if the DD being closed is the one that specifies DISP=NEW
Waiting for any closure of a data set
You can use the ANYCLOSE keyword to trigger an Event at closure of a data set. This means the creation of a new data set or the updating of an existing data set. If you do not specify ANYCLOSE, ESP triggers the Event only when the applicable data set is created.
Example: Any Closure
If you want any closure of data set PROD.CICS.FILE1602 to trigger your Event, type:
EVENT ID(PROD.NIGHTLY) DSTRIG PROD.CICS.FILE1602 ANYCLOSE INVOKE 'CYB.ESP.PROCS(NIGHTLY)' ENDDEF Continued on next page
74
Specifying Data Set Triggered Events, Continued
Process flow
Visually, the flow looks like this:
PROD.CICS.FILE1602
(data set)
PROD.NIGHTLY
(Event)
Limiting data set activity to a job
You can restrict the trigger to only specific data sets created by a particular job. Use the JOB keyword followed by the full name or jobname prefix of the job.
Example: Job specific creation
The following Event triggers when job ABC creates a generation of the data set USER1.PAYROLL.
EVENT ID(PROD.PAY_DATA) DSTRIG 'USER1.PAYROLL.G-' JOB(ABC) INVOKE 'PROD.ESP.PROCS(PAYJOBS)' ENDDEF
Waiting on multiple data sets
You may have an Event that needs multiple data sets to close before it is triggered. You can indicate each of the multiple data sets with the MULTIPLE keyword. When ESP encounters the MULTIPLE keyword it notes the individual closures of data sets, but it does not trigger the Event until all the DSTRIG commands containing a MULTIPLE keyword have been satisfied by a data set closure.
75
Example: Waiting on multiple data sets
When both of the following criteria have been met, the following Event triggers: 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 MULTIPLE DSTRIG '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 on multiple closures of the same data set
It is possible that a data set will be closed several times. You can use the COUNT keyword to specify how often this closure will actually trigger the Event. With each closure, ESP increases its internal counter by one. When the counter reaches the number you set in your COUNT statement, the Event triggers and the counter resets to zero. You can display the Event at any time to see the current value of the counter. You can specify several DSTRIG commands for one Event and each can maintain its own separate counters.
Example: Running a compress job after 100 closures of a data set
If you want a job to submit automatically after every 100 closures of a data set, you could use the COUNT keyword followed by 100 as below. This example Event submits a COMPRESS job for a COPYJCL data set after every 100 closures of that data set:
EVENT ID(CYBER.COPYJCL_COMPRESS) DSTRIG CYBER.COPY.JCL COUNT(100) SUBMIT PROD.JCL.CNTL(COMPRESS) ENDDEF
76
Displaying data set triggering information
Below are commands that relate to data set triggering. They are useful for displaying data set trigger information.
Command LDXE LDTE
Use this command to ... display data set triggered Events. display data sets being checked for closures, creations, or renames.
Output from these commands might look like this:

Ldte THE FOLLOWING DATASET(S) ARE BEING CHECKED FOR DATASET TRIGGERS CYBER.PAYROLL.DATA1 ANYCLOSE USER.INPUT.CYCLE CREATE-CLOSE
Ldxe EVENT/APPL (WOB)----------DATASET CYBER.PAYROLL(WAIT4.DS) CYBER.PAYROLL.DATA1,ANYCLOSE CYBER.CYCLES USER.INPUT.CYCLE
77
Specifying the Function of an Event
Introduction
ESP can perform a variety of tasks through the Events you define. An Event must do one of the following: Send a message to you, other users, or operator consoles Submit JCL Invoke an ESP Procedure Issue an operating system command.
This section describes these tasks and the commands associated with each.
Sending messages
You may want to use an Event to send a message to yourself, another user, a group of users, or an operator console. To send a message, enter the SEND command followed by the message in single quotes, and the userid or console identifier to which the message is being sent. You can include several SEND commands in any single Event.
Example: Sending a message
The following Event is scheduled at 8 a.m. each day and sends a message to USER1.
EVENT ID(USER1.MESSAGE) SCHEDULE 8AM DAILY SEND 'SCHEDULING IS EASY WITH ESP' USER(USER1) ENDDEF
Submitting JCL
You can use an ESP Event to submit JCL from a data set to the internal reader using the SUBMIT command. A single Event can submit more than one job. If there are relationships between the jobs you are submitting, you must use an ESP Procedure, not an Event, to submit them. For more information on submitting related jobs refer to Chapter 6, Using Applications. You can also use ESP to submit jobs from ROSCOE, Librarian, and Panvalet data sets using different statements as outlined in the next section. Note: You cannot use the Consolidated Status Facility to monitor and control jobs submitted from an Event.
78
Specifying the Function of an Event, Continued
Example: Submitting a job
You can create an Event PROD.INVENTORY that, at 7 a.m. on the last workday of every month, submits member BACKUP1 of data set PROD.JCL.CNTL. The Event looks like this:
EVENT ID(PROD.INVENTORY) SCHEDULE 7AM LAST WORKDAY OF MONTH SUBMIT 'PROD.JCL.CNTL(BACKUP1)' ENDDEF
Example: Submitting multiple jobs
The following Event submits two jobs at 7 a.m. on the last workday of each month. The jobs can run in any order. The Event looks like this:
EVENT ID(PROD.INVENTORY) SCHEDULE 7AM LAST WORKDAY OF MONTH SUBMIT 'PROD.JCL.CNTL(BACKUP1)' SUBMIT 'PROD.JCL.CNTL(BACKUP2)' ENDDEF
Submitting JCL from ROSCOE, Librarian and Panvalet data sets
In addition to the SUBMIT command, there are special commands to submit jobs directly from ROSCOE, Librarian, and Panvalet data sets. You can use multiple commands in an Event. ESP effectively concatenates the input data to form one or more jobs.
ROSCOE data sets
To submit a job directly from a ROSCOE data set, enter the ROSSUB command 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 the ROSCOE 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 the ROSSUB command implies a ROSCOE data set.
79
Librarian data sets
To submit a job directly from a Librarian data set, enter the LIBSUB command followed by the data set name and the name of the data set member you want to submit, like this:
LIBSUB LIB1.DATA(PRODCNTL)
ESP supports multiple LIBSUB commands. Note: You do not need to specify the LIB- data set identifier because the LIBSUB command implies a Librarian data set.
Panvalet data sets
There are two methods you can use to submit a job directly from a Panvalet data set. You can either enter the PANSUB command followed by the data set name and the name of the member you want to submit:
PANSUB PANDS.DATA MEMBER(DLYPAYROLL)
OR If 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 the PANSUB command implies a Panvalet data set.
80
Invoking ESP Procedures
You can create an Event to invoke an ESP Procedure. An ESP Procedure is a set of instructions for ESP. The most common use of an ESP Procedure is to define 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 the Procedure. To invoke any Procedure, you must first create the Procedure and then define an Event to invoke that Procedure. The INVOKE command invokes an ESP Procedure by specifying where the ESP Procedure is stored. In the following example, the ESP Procedure is stored in the PAYROLL member of the data set PROCS.ESP.PAY :
EVENT ID(PROD.PAYJOBS) SCHEDULE 17:00 DAILY INVOKE 'PROCS.ESP.PAY(PAYROLL)' ENDDEF
Note: ESP allows multiple INVOKE commands. However, an Event can only generate one Application. To invoke more than one Application requires one Event per Application.
For information on using ESP Procedures, refer to Working with ESP Procedures on page 137.
81
Copying JCL
The COPYJCL command lets you generate a copy of the JCL for every job, as ESP submits it. You can specify COPYJCL in the Event definition of any Event that submits jobs. This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved and NET cards (for DJC/JES3) included. This JCL can be used for job re-submission. ESP keeps track of where the job was submitted from and the JCL that was used. You can also specify COPYJCL within an Application definition to identify one or more jobs for which you want to use COPYJCL. This gives you the advantage of using COPYJCL for specific jobs. When you use the COPYJCL command you must also specify the library that is to receive the copy, followed by either the JOBNAME or JOBID keyword. The keywords you use influence the member name ESP assigns to the JCL copy.
Using the JOBNAME keyword
The JOBNAME keyword requests that the member name used for storing the JCL for a job is the same as the jobname. This is the default. Each submission of a particular job overwrites the previous copy of that jobs JCL.
Using the JOBID keyword
Use the JOBID keyword when you want ESP to store the copy of the JCL by job number. ESP creates a member name starting with JOB, followed by a five-digit JES job number. The system assigns this number sequentially. A member is not overwritten until its five-digit number reoccurs.
Example: Using COPYJCL
This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by jobname.
EVENT ID(EMP.MYJOBS) SCHEDULE 5PM WORKDAYS INVOKE 'EMP.ESP.PROC(WKJOBS)' COPYJCL 'CYBER.JCL.COPY' GEN(0) JOBNAME ENDDEF
82
Using a GDG for COPYJCL
With either the JOBID or the JOBNAME method, you can write the JCL to a PDS GDG. A new generation can be created each day to maintain several generations of JCL. Schedule an Event each day to submit a job that creates the next generation.
Compressing COPYJCL
If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You could use a data set triggered Event to submit the compress job automatically after a number of closures.
Changing the copy
Your original JCL may contain data that you do not want to copy. ESP has a JCL Tailoring facility that automatically changes certain aspects of the original JCL when it copies the JCL to a COPYJCL data set. Refer to the Advanced Users Guide for more information on tailoring JCL.
83
Issuing Operator Commands
Issuing an operator command
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 VS command in your definition, as shown below. The commands will be issued on the SYSB system.
EVENT ID(OPER1.START_IMS) SYSTEM(SYSB) SCHEDULE 6AM DAILY VS 'S IMS10' VS 'S IMS20' ENDDEF
There are restrictions on which users can issue operator commands. Contact your system administrator to find out if you are authorized to issue any operator commands.
84
Specifying Other Requirements
Options
When you define an Event, you can also specify: Symbol library names Calendar names Comments.
Setting symbol libraries
ESP has a set of built-in symbolic variables. Your ESP administrator may define symbol libraries to store user-defined symbolic variables. A symbol library consists of one or more data sets or data set members. Variables may include date formats, control cards, and other information ESP can use when processing the workload. You can use the SYMLIB command in an Event to specify symbol libraries. If a variable is assigned more than one value, ESP uses the last assigned value.
Example
This example references the symbol library called DATES. When ESP processes the Event, it opens each data set associated with this symbol library and uses this information to perform substitution of symbolic variables.
EVENT ID(CYBER.PAYROLL) SYMLIB DATES INVOKE 'CYB.ESP.PROCS(PAYROLL)' ENDDEF
You can also define and work with symbols as part of an ESP Procedure. Refer to the Advanced Users Guide for detailed information on creating and using symbolic variables.
85
Specifying Other Requirements, Continued
Setting special calendars
ESP lets you define dates that might be unique to your organization. If, for example, Labor Day is a regular holiday at your installation, you can define it as such in your calendar. ESP contains an installation defined SYSTEM calendar based on the 12month Gregorian calendar. You can use the CALENDAR command to specify up to two additional calendars for the Event, so that you can schedule Events in terms that might be unique to your calendar. If you do not specify a calendar, ESP uses the calendar(s) assigned by default to the group or user that owns the Event. For more information on calendars, refer to the next chapter, 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, ESP uses the first definition it finds. ESP searches in this order: Calendar First calendar you define for the Event, or first default calendar. Second calendar you define for the Event, or second default calendar. The SYSTEM calendar.
1 2 3
Example: Specifying a calendar in an Event
If you want your Event to execute on the second day of your fiscal month, you must first set the calendar so that ESP knows where to look for the definition of what a fiscal month is. In the Event below, the CALENDAR command tells ESP which previously defined calendar (i.e. FISCAL) to refer to when scheduling the Event:
EVENT ID(CYBER.FISCAL_JOBS) CALENDAR FISCAL SCHEDULE 2ND DAY OF FISCAL_MONTH SUBMIT 'PROD.JCL.CNTL(FISJOB1)' ENDDEF
Adding comments
You can use the COM command to add any number of comments, anywhere in an Event. ESP ignores them when it executes the Event.
86
Specifying Other Requirements, Continued
Example: Using comments in an Event
If you want to include a comment in your Event that tells you the Event is a manually triggered Event to submit JOBX, you could use the COM command, like this:
EVENT ID(PROD.JOBX) COM MANUALLY TRIGGERED EVENT TO SUBMIT JOBX SUBMIT 'PROD.JCL.CNTL(JOBX)' ENDDEF
87
Displaying the Schedule
Introduction
You can use the LISTSCH command to display the Event names and times of the current schedule cycle (normally 24 hours). These elements include the names and execution times of all the Events in the schedule, and the overdue, held, or deferred queues. The LISTSCH command does not display the names or submission times for individual jobs within Events. To display the schedule for jobs refer to the section on scheduled activity reporting in Chapter 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 instance of the Event and does not calculate the next execution time until it has executed the Event.
88
Expected Execution
Introduction
The LISTSCH command can only display scheduled Events. If you want to display Events that do not have SCHEDULE commands, such as Events triggered by data set activity you can use the EXPECT command. The EXPECT command uses the same format as the SCHEDULE command, but it does not cause an Event to execute.
Example: Expected time of an Event
If your Event is usually triggered by the creation of a data set every morning at approximately 11 a.m., you could insert an EXPECT command in your Event definition to tell ESP when to expect the Event, like this:
EVENT ID(USER01.MY_EVENT) SUBMIT 'USER01.JCL.CNTL(MYJOB)' EXPECT 11AM DAILY DSTRIG MY.DATA.SET ANYCLOSE ENDDEF
Triggering Expected Events
The EXPECT command normally does not affect the schedule. If the data set that triggers the Event, in the above example, has not been created by the expected time, the Event continues to wait. However, if you trigger an Event that has an EXPECT statement and you keep the REPLACE option, ESP treats the EXPECT statement the same as a SCHEDULE statement. ESP selects jobs and substitutes variables based on the expected time and date.
89
Displaying when an Event will Execute
Introduction
Using the NEXT command, you can display the next scheduled executions of an Event. The NEXT command lets you specify the number of execution times you want to test, up to a maximum of 99. As long as your Event contains at least one SCHEDULE command, ESP computes the execution times and dates for the number of executions you specify.
Example: Displaying the next execution times of an Event
If you would like to know the next five execution dates and times for the Event PROD.LWD, you could use the NEXT command. The following shows the NEXT command and sample output from the command. ESP displays the next five scheduled times and dates:
NEXT 5 PROD.LWD SCHED AT 19.00.00 SCHED AT 19.00.00 SCHED AT 19.00.00 SCHED AT 19.00.00 SCHED AT 19.00.00 ON ON ON ON ON SATURDAY JANUARY 31ST, 2000 SATURDAY FEBRUARY 28TH, 2000 TUESDAY MARCH 31ST, 2000 THURSDAY APRIL 30TH, 2000 SUNDAY MAY 31ST, 2000
90
Working with Defined Events
Introduction
The section Controlling Event Scheduling earlier in this chapter describes five commands for controlling an Event during definition. You can use ESP commands in Line mode, Page mode, batch and through the ISPF interface, to control an Event after you define it.
Commands and their function
The following table summarizes the available commands and their function:
Command ALTER CLASS DELETE HOLD LIST RELEASE RESUME SIMULATE SUSPEND TRIGGER
Function Alters the characteristics of an Event. Controls the classes of Events (requires OPER authority; not available through panels). Deletes an Event. Holds an Event from processing. Lists an Event name or definition. Releases a held Event for processing. Resumes processing of a suspended Event. Simulates the functions of an Event. Suspends an Event from processing. Triggers execution of an Event.
91
Working with Defined Events, Continued
For ISPF users
To access the ISPF panels: Step 1 2 3 Action Select Option E on the Main Menu. Select Option 3 on the Event Management Menu. Type the appropriate code letter for the action you want to take and the Events name (prefix and descriptive name).
OR, you can: Step 1 2 3 4 5 Action Select Option E on the Main Menu. Select Option 3 on the Event Management Menu. Type the prefix of the Event in the PREFIX field for Multiple Events. Press Enter. A list of Events appears. 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.
92
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 Events starting with the prefix PROD, type the command below. The LEVEL parameter identifies the Event prefix.
LIST LEVEL(PROD)
Note: In ISPF you must abbreviate the LIST command to simply the letter L.
93
Simulating an Event
Introduction
You should simulate the functions of any defined Event using the SIMULATE command. For the Event you select, the SIMULATE command tells you which jobs ESP submits, any messages it sends, how it substitutes symbolic variables, and so on. This command is particularly useful with ESP Procedures because you can use it to see how the complex and conditional components of your Procedure will run at a particular date and time. ESP also displays error messages if it encounters problems, such as syntax errors or successor loops in an ESP Procedure. You can simulate an Event for a day on which it is not normally scheduled; ESP simulates what would happen if the Event was triggered on that particular day.
Options
There are a number of other options available with the SIMULATE command. For example, you can: Suppress the printing of the ESP Procedure listing. Simulate data set triggers, signal processing and job monitor Events. Simulate procedures invoked by the simulated procedure as well as monitor Events and other directly invoked Events. Invoke a JCL scan exit during simulation. An indicator will be passed to this exit indicating that this is a simulation rather than real Event execution. Perform full syntax checking on all ESP commands invoked. Direct the JCL output to a data set. Suppress the execution of REXX code within an ESP Procedure. Display all successors that were inherited because a job was not selected for some reason on the job selection report. Display jobs that were not selected for any reason on the job selection report.
Specifying the options
You specify these options using the SIMULATE command or on the Simulate Event Execution panel. On the SIMULATE command, specify the Event name and any schedule parameters. If you do not enter any parameters ESP either simulates the next occurrence of the Event, or, if the Event has no schedule execution, it assumes an execution time NOW.
94
Simulating an Event, Continued
Example: Simulating an Event
You might want to simulate the results of executing an Event named CYBER.TEST1 on the last workday of the current month. Enter the following command in Page mode:
SIMULATE EVENT(CYBER.TEST1) SCHED('LAST WORKDAY OF MONTH')
95
Triggering an Event Manually
Triggering an Event
You can manually trigger an Event at any time through the TRIGGER command. Enter the command TRIGGER, followed by the Events name and the time at which you want it to execute. (The default time is now.) If you specify a time in the past, ESP triggers the Event immediately and processes the Event as if it was this prior date. ESP selects jobs and resolves symbolic variables as if it were this date in the past. DELAYSUB/EARLYSUB statements are ignored unless they use the term REALNOW that reflects the actual time of Event trigger. The Event execution either replaces the next scheduled execution, or it can be a temporary addition to the schedule.
Adding Executions
You can use the ADD option to schedule executions of the Event that you would like to add to the Events normal schedule. ESP processes the ADD keyword in the same way it processes a SCHEDULE command. A TRIGGER ADD always causes the Event to execute. If there is a HOLD or SUSPEND, ESP does not execute the Event and produces an error message. For example, if you need to run an Event now in addition to its scheduled time of 7 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 or REPLACE.
96
Triggering an Event Manually, Continued
Replacing scheduled executions
When you want to process an Event at a time different than its next scheduled time, you can use the REPLACE option. REPLACE advances the execution time for an Event. For example, if you need to run an Event now instead of at 7 p.m., trigger the Event with the REPLACE option. When you use the REPLACE option, ESP selects jobs and resolves symbolic variables based on the replaced time and date. For example, if you have an Event that runs every Saturday and this week you want to run the Event on Friday instead, you can trigger the Event with the REPLACE option. ESP selects the jobs and resolves symbolic variables based on Saturdays date. The following example uses REPLACE to replace the next scheduled execution of an Event called PROD.PAYROLL.
TRIGGER PROD.PAYROLL REPLACE
Bypassing a scheduled Event
If you want to bypass the next execution of a scheduled Event, you can trigger the Event and specify NOXEQ. This might be used when you trigger an Event in error, and you need to undo this operation, or when you want to cancel one execution of an Event. The following example bypasses the next scheduled execution of the Event called PROD.BAD_EVENT.
TRIGGER PROD.BAD_EVENT NOXEQ
97
Postponing Execution of an Event
Introduction
When you use the HOLD command outside the Event definition process, ESP increments the Events hold count immediately. When you use the HOLD command within a definition (explained in Controlling Event Scheduling earlier in this chapter) ESP does not increment the count until the scheduled date and time.
Holding and releasing an Event
By issuing the HOLD command followed by an Event name, you postpone execution of that Event until its hold count is reduced to zero. Every HOLD increases the count by one; every RELEASE command reduces it by one. When a held Event is released and it has missed a scheduled execution, ESP executes the Event once for each scheduled execution that the Event missed, up to the number of times in the overdue count. This count is specified by the OVERDUE parameter on a SCHEDULE statement and defaults to 1.
Example: Holding an Event
If you have an Event with the name PROD.MYEVENT, you can place it on hold (increasing its hold count by one) by typing the following:
HOLD PROD.MYEVENT
98
Bypassing Execution of an Event
Introduction
Outside of an Event definition, the SUSPEND command immediately increases the suspend count by one, telling ESP to bypass the Event you name. A suspended Event remains in that state until it is resumed. All scheduled executions and manual triggers of the Event are bypassed.
Suspending and Resuming an Event
By issuing the SUSPEND command followed by an Event name, you bypass the execution of that Event until its suspend count is reduced to zero. Every SUSPEND increases the count by one; every RESUME command decreases it by one. When the suspend count reaches zero, the Event is eligible for execution. If the Event misses any execution times while suspended, ESP ignores them and does not consider the Event overdue.
Example: Suspending an Event
If you have an Event with the name PROD.MYEVENT, you can suspend it by typing the following:
SUSPEND PROD.MYEVENT
Note: If the Event is both held and suspended at a scheduled execution time, ESP treats the Event as suspended and therefore does not consider it overdue.
99
Overdue Events
Event classes
After a long system outage, ESP makes it easy for you to manipulate classes of Events so that the system can process high priority work first. For more information on manipulating classes of Events refer to the ESP Operators Guide.
Overdue Events
Add OVERDUE to the end of your SCHEDULE command, then a number in brackets indicating how often the Event should execute if it misses its scheduled time. The default is 1.
Example: Overdue Events
If you do not want an Event to run, even if it misses its 10 a.m. scheduled execution 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)
100
Altering Events
ALTEVENT command
Use the ALTEVENT command to change certain characteristics of one or more Events. Specify any number of parameters to cause multiple changes to a single Event or group of Events. When the name contains asterisks or a hyphen, ESP alters all matching entries. If you are unsure of which Events a particular command will affect, use a LIST command to display the Events. Use the ALTEVENT command to change calendars, classes, symbol libraries, and system identifiers, in addition to adding or subtracting hours or minutes to compute a new set of time and date schedules.
Example: Altering system identifier
The example below alters all Events prefixed by MYGROUP, with SYSTEM identifiers beginning with OLDA, to execute on the system NEWA. The SYSTEM identifier corresponds to the ESP system identifier, defined by ESPs SYSID Initialization Parameter.
ALTEVENT MYGROUP.- SYSTEM(NEWA OLDA)
101
Deleting Events
DELETE command
Use the DELETE command to delete an existing Event. This removes the Event from the Event data set.
Example: Deleting an Event
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 unable to continue processing that Application.
102
Schedule Criteria Overview
Introduction
ESP allows you to use free format, everyday English to specify schedule criteria when scheduling Events and jobs. ESP has a built-in understanding of general scheduling terms. You may also add your own unique scheduling terms to ESP. This may include special processing periods, holidays, and other special days. You can specify schedule criteria up to the year 2042.
In this chapter
This chapter contains the following topics: Topic Where You Can Use Schedule Criteria Specifying Schedule Criteria Schedule Terms Using Other Techniques for Schedule Criteria Testing Schedule Criteria Using Calendars Using Calendar Terms Defining Holidays Using Holidays Defining Special Days Using Special Days Special Periods Using Special Periods Working with Periods See Page 104 105 111 122 123 124 125 126 128 129 130 131 133 134
103
Where You Can Use Schedule Criteria
Schedule criteria
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.
104
Specifying Schedule Criteria
Days of the week
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 can shorten the names such as: sun, thu, fri. The minimum number of characters for days of the week is 3. You can specify multiple days of the week too. For example, monday wednesday friday.
Specify
If you specify a day and a date that do not match each other, ESP automatically calculates the first specified day of the week on or after the date you 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 April July October February May August November March June September December
You can abbreviate any month specification to a minimum of 3 letters, for example: APR AUG
105
Specifying Schedule Criteria, Continued
Time Zones
You can use the following time zone abbreviations for scheduling in ESP: LT ADT EDT CDT MDT PDT BST Local time Atlantic Daylight Time Eastern Daylight Time Central Daylight Time Mountain Daylight Time Pacific Daylight Time British Summer Time LOCAL AST EST CST MST PST GMT Local time Atlantic Standard Time Eastern Standard Time Central Standard Time Mountain Standard Time Pacific Standard Time Greenwich Mean Time
You should not need to specify your own time zone in your schedule criteria. These are set in ESPs Initialization Parameters. Note: ESP assumes that any number preceding a time zone abbreviation is a time specification.
Time of Day
The following table shows time-of-day formats that ESP accepts, where hh = hours, mm = minutes and ss = seconds. Format hh.mm hh:mm hh.mm.ss hh:mm:ss 12.30 01:25 10.47.30 11:00:01 Example
Note
ESP assumes that any number preceding the letters AM or PM is a time specification, for example: 3AM 6PM
106
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 are also used with a month name. For example, january21st, august29th.
Julian date
A Julian date is recognized in the following formats, where yy or yyyy = year number and ddd = day number. Format yy.ddd yyyy.ddd 99.056 1999.056 Example
Date format
ESP recognizes the date format xx/xx/xx. The DATEFORM Initialization Parameter instructs ESP how to interpret this format. The following table shows the different formats (yy=year number, mm=month number, dd=day number) and how to express January 2, 2000 using them. Format yy/mm/dd dd/mm/yy mm/dd/yy 00/01/02 02/01/00 01/02/00 Example
Note: Only one of these formats is valid at your installation. Check with your systems programmer or issue the DATEFORM operator command to determine which format you can use.
107
Ordinal numbers
Use ordinal numbers (1st, 5th, etc.) to refer to scheduling terms other than just day of month. For example, 2nd monday of year. You may use more than one ordinal, as in 3rd and 4th month of year. The following examples specify the first Monday of each month.
1ST MONDAY OF MONTH 1ST MONDAY MONTHLY
The following example requests activity at 10 a.m. on the third day of each month.
10AM 3RD MONTHLY
The next example requests activity at 10 a.m. on the first Monday after the third day of each month.
10AM MONDAY 3RD MONTHLY
Date range
Use a hyphen (-) to designate a range of dates. For example, 3rd - 6th day of month 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 MONTH 3RD DAY OF LAST WEEK OF YEAR 5TH WORKDAY OF 2ND WEEK OF YEAR
108
Specifying a time and frequency
A schedule specification in an Event may consist of two parts. One part gives a starting date and time, while the other part describes an algorithm for computing subsequent dates and times. In an ESP Application, you must use separate statements to specify the time and the frequency of a job. Starting Date and Time 9AM JANUARY 1ST MIDNIGHT 9 DECEMBER 2000 3PM Subsequent Times DAILY EVERY 2 WEEKS MONTHLY 4 TIMES
Matching Criteria
Normally, you do not need to specify a starting time and date when you define a schedule. The first time and date that match the criteria you have entered is automatically selected. DAILY AT 19.00 WEDNESDAYS AT 3PM WORKDAYS
Specifying an Algorithm and date / time
To specify both an algorithm and a starting date and time, separate the two parts of the schedule specification with the keyword STARTING. 3PM DAILY STARTING JAN 1 WEEKDAYS EXCEPT WEDNESDAYS STARTING 2ND JUNE
109
Spaces
Spaces between words are not necessary if there are other delimiting factors in your date and time specification. SAT25JUN EVERY5MINUTES
Using the first day of the week
Each calendar identifies the day that ESP considers the first day of the week. By default ESP considers Sunday to be the first day of each week. If you specify 1st day of week, ESP uses the calendar to determine what day this is.
Using Workdays
Each calendar has its own workdays. By default workdays are Monday through Friday excluding holidays. If you specify 2nd workday of month, ESP looks for the second day of the month which is not a weekend or holiday.
workday 1 weekend X weekend X holiday X workday 2 Workday 3 workday 4
Absolute vs. logical days
By default a day is considered to be an absolute day beginning at midnight (00:00). To override the default, you can define a calendar as logical and identify the start time of your logical day. For example, if your logical day begins at 08:00 and you schedule an Event to execute Monday at 2 a.m., the Event actually executes Tuesday morning at 2 a.m.
Absolute Calendar
SCHEDULE 2AM MONDAY
Logical Calendar
SCHEDULE 2AM MONDAY
Event scheduled at 2 a.m. Monday
Event scheduled at 2 a.m. Tuesday
Caution: Cybermation recommends you use absolute calendars because of their ease of use.
110
Schedule Terms
Terms
You may use words and phrases other than specific dates and times to define schedule criteria. The following is a list of other terms recognized by ESP. Term recognized by ESP Explanation ABSOLUTE Specifies that you are using an absolute day (i.e. beginning at 00:00). This is only required when your calendar is a logical calendar, with a start time other than 00:00. AND Used to specify multiple similar scheduling terms (e.g. days of the month, months of the year) and ordinal numbers. For example, monday and tuesday, 1st 4th and 9th, Monday of June July and August. AND cannot be used with times of day; separate schedule statements are required. ANYDAY Specifies that there is no day of the week restriction. You can abbreviate this term to ANY. COMPLETE Used only with the LAST keyword. Ensures that the schedule only occurs during a complete period. For example you can specify last complete week of year or last complete week of quarter If a fiscal week starts in one quarter but finishes in the next quarter, ESP provides a schedule for the previous complete fiscal week. DAILY Means every one day. ENDING Allows you to specify the end date for any schedule interval, for example, daily at 9am starting tomorrow ending 1jul2000. You cannot use this qualifier in a RUN/NORUN statement.
111
Schedule Terms, Continued
Term recognized by ESP Explanation EACH Means every occurrence of. EVERY n units Requests a recurrence of the Event at every n units of time. The units can be any of SECONDS, MINUTES, HOURS, WORKDAYS, DAYS, WEEKS, MONTHS or YEARS, while n can be any number from 1 to 32767. For example, every 1 hour round less 5 minutes requests an Event at five minutes before the hour, every hour. Note that five minutes are subtracted from the base time (every hour on the hour). You cannot use this qualifier in a RUN/NORUN statement. EXCEPT Used to exclude a day of the week or holidays. For example weekdays except wednesdays limits activity to Monday, Tuesday, Thursday and Friday. daily except holidays limits activity to days which are not holidays. You cannot specify more than one day of the week with EXCEPT. You cannot use EXCEPT with a term other than a day of the week or the term HOLIDAYS. FIRST To specify the first occurrence of a particular day or period. For example, you can specify first monday of month, first fiscal_month of fiscal_year. You can also use the ordinal number 1st. HOURLY Means every one hour. You cannot use this term in a RUN/NORUN statement. HOLIDAYS Refers to all holidays. You can refer to specific holidays by name.
112
Term recognized by ESP Explanation LAST Specify the last (i.e. final) occurrence of a particular day or period. For example you can specify last holiday of year, last workday of fiscal_month, first and last tuesday of month. LESS n units Specifies a value to be subtracted from the base time to produce a time/date execution time. n must be a whole number. For example, you can specify less 2 weekdays, less 1 month, less 0 workdays. LOGICAL Specifies that you are using a logical as opposed to an absolute day (i.e. beginning at 00:00). The start time of your logical day must be specified in a calendar. For example, you can specify 2am logical tuesday, 7am first logical workday of month. LOGICAL can be set as a default at calendar definition time. MIDDAY 12.00, noon MIDNIGHT 24.00, midnight. 24.00 is normally recognized as being the same as 00.00. Thus, if you specify monday at 24.00 it will be stored as 00.00 tuesday. However, specifying midnight ensures that the time associated with the previous day - midnight monday is considered to be the end of Monday and not the start of Tuesday. MONTHLY Means every one month. You cannot use this qualifier by itself in a RUN/NORUN statement (i.e. you can use RUN 15TH MONTHLY but you cannot use RUN MONTHLY).
113
Term recognized by ESP Explanation n TIMES Allows you to specify the number of times you want a schedule to occur, such as daily at 9am 6 times starting tomorrow. You cannot use this qualifier in a RUN/NORUN statement. NOW Refers to the scheduled time. This is useful when you need up-to-the minute information, as when obtaining a report for example. You could request a report from any time in the past until NOW. You cannot use this qualifier in an Event definition on its own. See note at the end of this section. ONCE Means that a scheduled command will be processed once only, at the time specified. If you specify a date in an Event without ONCE, the default frequency is DAILY. You cannot use this qualifier in a RUN/NORUN statement. OR Allows you to specify either of two similar scheduling terms, such as monday or tuesday. OR implies whichever happens first, and as such can only be used where it is meaningful and does not lead to ambiguity. A statement such as 1st january or 2nd february is meaningless to ESP. OVERDUE(n) Specifies how many overdue occurrences of an Event are to be initiated should an Event miss its scheduled time. ESP schedules the Event once for each missed occurrence, up to the number specified. You can only use this on a SCHEDULE statement in an Event definition.
114
Term recognized by ESP Explanation PLUS n units Specifies a value to be added to the base time to produce a time/date execution time. n must be a whole number. For example, you can specify plus 2 weekdays, plus 0 workdays, plus 1 week. QUIT Used to quit an entire process and the Event that invoked it. ESP does not process any pending requests from this or any other Procedure invoked by the same Event. REALNOW Refers to the actual time. You cannot use this term in an Event definition on its own. See note at the end of this section. ROUND This word can be used together with the EVERY n UNITS phrase. It specifies that the computed time is an integral multiple of the units parameter. For example, specifying every 1 hour round requests every hour at the hour mark. every 6 hours round requests the times 00.00, 06.00, 12.00 and 18.00. every 5 hours round provides the next hour that is an integral multiple of five hours from 00.00 on 1st January 1900. STARTING Allows you to split the schedule specification into two parts. The first part is an algorithm and the second part is the starting time or date. The time or date to the left of STARTING is when you want the Event to execute. The time or date to the right of STARTING is when you want the first execution to occur. Use an actual date or time after STARTING. A repetition, such as every 5 minutes, is not valid. You cannot use this qualifier in a RUN/NORUN statement. TODAY Today TOMORROW Tomorrow. You cannot use this term in a RUN/NORUN statement.
115
Term recognized by ESP Explanation UNTIL Allows you to specify the end date for any schedule interval, for example, daily at 9am starting tomorrow until 1jul1995. You cannot use this qualifier in a RUN/NORUN statement. WEEKDAYS Requests that the schedule actions occur only on weekdays (Monday through Friday). WEEKENDS Requests that the scheduled actions occur only on Saturday and Sunday. WORKDAYS Each calendar identifies workdays. Workdays exclude holidays. Default workdays are Monday through Friday. YEARLY Means every 1 year. You cannot use this qualifier in a RUN/NORUN statement. YESTERDAY Yesterday. This term is useful in reporting. You cannot use YESTERDAY in an Event definition or in a RUN/NORUN statement. Note: When working with jobs in an ESP Application, NOW refers to the scheduled time of the Event which triggered the ESP Application; REALNOW refers to the actual time the Event was triggered.
116
Using ordinal numbers
If you use an ordinal number as part of the STARTING parameter with a special period or special day, and without using nested levels, ESP assumes that you are implying from today. For example, 10pm daily starting 5th payroll_day provides the fifth payroll day from now. If you use an ordinal number with a schedule term (other than with the STARTING parameter) without stating what the schedule term refers to, ESP assumes the following defaults: Schedule Term date, day name or workday week or month holiday special day or period ESP Default of month of year of year 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 a schedule 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 of schedule criteria
Here are some examples of schedule criteria, each of which can be handled with one statement. Refer to the next section Other Techniques for Schedule Criteria for information on handling more complex criteria.
Daily or multiple times a 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
117
Multiple times a week
Monday, Wednesday and Friday: MON WED FRI Everyday except Mondays: DAILY EXCEPT MONDAYS 19:00 on Saturdays and Sundays: 19.00 WEEKENDS Every other workday beginning this Friday: EVERY 2 WORKDAYS STARTING FRIDAY
Weekly
Last workday of each week: LAST WORKDAY OF WEEK Every Saturday in June: SATURDAY OF JUNE
118
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 next workday 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 the month: 15TH DAY OF MONTH PLUS 0 WEEKDAYS Friday after the 1st Sunday of the month: 1ST SUNDAY OF MONTH PLUS 5 DAYS
119
Monthly continued
1st Saturday of the month. If this is also the first day of the month then run on 2nd Saturday of month: SATURDAY 2ND MONTHLY ESP interprets the above expression as the first Saturday on or after the 2nd day of the month. Multiple Times a Month 10 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

120
One-time Examples
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 is 00:00).
121
Using Other Techniques for Schedule Criteria
CLANG and GENTIME
For some criteria you may need to use ESPs CLANG (Control Language) or the GENTIME command. ESP Command CLANG Explanation Provides you with IF-THEN-ELSE logic and some built-in functions (e.g. DAYS_TO). Refer to ESP Procedures on page 137, for more information. Allows you to generate date and time symbolic variables for any date/time.
GENTIME
The Advanced Users Guide contains some examples of schedule criteria that use the above techniques. For instance, it describes how to: Run a job every two weeks in an Application Run a job based on what day of the week a particular criteria falls on Use symbolic variables for schedule criteria Schedule on even days of the month.
122
Testing Schedule Criteria
Process
You can test schedule criteria, prior to actually using them, with the TEST command. This tests any date or schedule specification. ESP responds with the actual date and time. If you specify a number in parentheses after the command, ESP displays as many subsequent dates and times as you indicated. This facility is also available through option E.4 from ESPs 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 00.00.00 00.00.00 00.00.00 00.00.00 MONDAY JANUARY 31ST, 1998, DAY 031 MONDAY FEBRUARY 28TH, 1998, DAY 059 THURSDAY MARCH 31ST, 1998, DAY 090 FRIDAY APRIL 29TH, 1998, DAY 120 TUESDAY MAY 31ST, 1998, DAY 151
123
Using Calendars
Introduction
You do not need to define calendar terms to ESP in order to use them. ESP already recognizes general scheduling terms. Administrators may create calendars to store definitions of scheduling elements unique to your installation - your holidays, special days and special processing periods. A calendar also identifies workdays, the first day of the week, and the start time for a day. Your administrator defines calendars and controls access to them.
Special days and Periods
A special day is useful when a particular schedule criteria is difficult to describe with an algorithm. Special periods are defined the same way as special days. A set of periods with the same name can occur at regular intervals, such as fiscal year, or a trading period. You can also define periods which have irregular intervals and refer to these special periods when specifying a schedule. A single calendar can contain many different special days and periods.
124
Using Calendar Terms
Introduction
Different groups of users can have their own set of unique holidays, special days and periods. Even if they choose the same names for a set of special days or periods, the reference only applies to the special day or period in the calendar named in an Event.
CALENDAR statement
Use a CALENDAR statement in an Event to refer to a maximum of two calendars. If you do not refer to a calendar in the Event, ESP automatically uses the default calendars your administrator assigned to you or your group. ESP merges holiday definitions in all calendars associated with an Event. For special days, workdays, and the first day of the week, ESP uses the first definition it encounters.
Default calendar
When defining holidays, special days and special periods, specify which calendar will be used to store the definition. If you do not specify a calendar name, your first default calendar as defined in your userid entry will be used. If you do not have a first default calendar, your second default calendar is used. If you do not have any default calendars defined, the entry automatically goes into the SYSTEM calendar.
SYSTEM calendar
Only global holidays and special days should be stored in the SYSTEM calendar. Department-specific holidays and special days can be stored in as many calendars as required.
Retaining entries
ESP checks for and deletes old entries only when a calendar is updated for other define and delete requests. When more than two days have gone by since holiday and special day entries have occurred, they are automatically deleted unless you specify otherwise using the RETAIN parameter at definition time.
125
Defining Holidays
Process
To define holidays, use the DEFHOL command or use Option L of the Main Menu. You can use up to 16 characters to name each holiday, and you must give a start date in each holiday definition. The time duration for a holiday is 24 hours, unless you specify otherwise. You can define multiple holidays with the same name, 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 terms even if stored in a LOGICAL calendar.
Example: Defining a Holiday
This example defines a 24-hour holiday, called BANK_HOLIDAY, on the next occurrence of the 1st Monday of August:
DEFHOL BANK_HOLIDAY START('1ST MONDAY OF AUGUST') FOR(24)
Example: Defining a holiday using a panel
This example uses Option L to define a holiday.
126
Defining Holidays, Continued
Example: Defining a repetitive holiday
This example shows how a batch job defines a 24-hour holiday called CHRISTMAS for 3 years. The subsystem name for ESP in this example is ESPM:
//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)
127
Using Holidays
Introduction
Once holidays are defined, you can use them as you would any other scheduling terms. Some examples are shown below. 16:00 every holiday: 16:00 HOLIDAY 10 p.m. on Christmas: 10PM CHRISTMAS One workday before BANK_HOLIDAY: BANK_HOLIDAY LESS 1 WORKDAY
Holiday processing of Events
In an Event definition, you can schedule on holidays or use an ON command such as on holiday. This allows you to bypass, delay or advance the schedule if it normally falls on a holiday or a particular day of the week. The calendars associated with the Event and the SYSTEM calendar are searched for holiday entries. If there are no calendars specified in the Event, the owning groups or users default calendars and the SYSTEM calendar are used.
Holiday processing of jobs
The RUN statement identifies schedule criteria for a job in an ESP Application. For more information, refer to Using Applications on page 178. Run every holiday: RUN HOLIDAY Run on Christmas: RUN CHRISTMAS Run on workdays: RUN WORKDAYS
Example: Advancing / Delaying a Job
When specifying the frequency of a job in an ESP Application, you might need 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 a holiday, run the job on the following workday. The second statement instructs ESP to run a job on Friday. If this is a holiday, run the job on the previous workday.
RUN FRIDAY PLUS 0 WORKDAYS RUN FRIDAY LESS 0 WORKDAYS
128
Defining Special Days
Process
To define special days, use the DEFSPEC command or use Option L of the Main Menu.
Example
The following example defines April 20, 2000 as a special day called BALANCE_DAY:
DEFSPEC BALANCE_DAY ON('APR20,2000')
You can define more than one day as BALANCE_DAY. For example:
DEFSPEC BALANCE_DAY ON('AUG23,2000') DEFSPEC BALANCE_DAY ON('OCT17,2000')
129
Using Special Days
Using a special day as a special term
Once you define a special day, you can then use it as a scheduling term. Some examples are shown below. 17:00 on BALANCE_DAY: 17:00 BALANCE_DAY 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 REPEAT parameter to define multiple special days using a single command. The following example shows how to define the next 10 fiscal years on February 1. Each FISCAL_YEAR definition will be retained in the calendar called FISCAL for 2 years.
DEFSPEC FISCAL_YEAR REPEAT('10 TIMES FEB1 YEARLY') CALENDAR(FISCAL) RETAIN(2,YEARS)
130
Special Periods
Defining special Use the DEFSPEC command to define the first day of each period. When Periods defining multiple regular periods, you can use the REPEAT parameter of the
DEFSPEC 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 give ESP a final reference point. For example, define the first day of at least two consecutive fiscal years, so that ESP can calculate the start and finish of the first year. Use an alphanumeric name of up to 16 characters for the name of your special period. The first character must be alphabetic, and you should not use blanks. You can also specify the name of a particular calendar to which the period definitions apply.
Example
This example defines fiscal years:

DEFSPEC FISCAL_YEAR ON(1APRIL97) RETAIN(2,YEARS) DEFSPEC FISCAL_YEAR ON(1APRIL98) RETAIN(2,YEARS) DEFSPEC FISCAL_YEAR ON(1APRIL99) RETAIN(2,YEARS)
Period intervals Period intervals do not have to be regular. One trading period, for example,
may start three weeks after the beginning of the previous trading period, and five weeks before the beginning of the next. Simply tell ESP when each period starts. When two special days of the same names are defined in a calendar, you have essentially defined a period from the first special day up to the second special day. In the above example, ESP knows that the last day of each FISCAL_YEAR is 31st March. Use this method for any special period you want to define, regardless of the intervals between the start of each period: every five days, three weeks, or four months, etc.
Example
This example shows how to define payroll periods every 2 weeks for the next year using the REPEAT parameter. Each PAYROLL_PERIOD is retained on the PAYCAL calendar for 1 year after it occurs.
DEFSPEC PAYROLL_PERIOD REPEAT('26 TIMES EVERY 2 WEEKS STARTING THURSDAY') CALENDAR(PAYCAL) RETAIN(1,YEAR)
131
Special Periods, Continued
Using ISPF panels
Achieve the same result using ESPs ISPF panels as follows:
Step 1 2 3
Action Select Option L (Calendars) from the Main Selection Menu. Select Option 4 (Define a Special Day) from the Calendar Control Menu. Proceed as illustrated below:
132
Using Special Periods
Example special periods
Once you define a special period, you can use criteria as illustrated below. Last day of PAYROLL_PERIOD: LAST DAY OF PAYROLL_PERIOD 2nd, 3rd and 4th day of PAYROLL_PERIOD: 2ND-4TH DAY OF PAYROLL_PERIOD 1st day of the current PAYROLL_PERIOD: FIRST DAY OF PAYROLL_PERIOD STARTING TODAY 1st day of the next PAYROLL_PERIOD: PAYROLL_PERIOD
133
Working with Periods
This example illustrates the use of 4-4-5 periods, where there is a 4-week period, 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:
134
Working with Periods, Continued
Quarters and fiscal years
You can also define quarters and fiscal years, if you need to. Once this is done, you can use such criteria as shown below. You do not need to know the day of the week or the date to which each statement refers. ESP calculates this for you. First workday of PERIOD445: 1ST WORKDAY OF PERIOD445 First workday of the current PERIOD445: 1ST WORKDAY OF PERIOD445 STARTING TODAY Last workday of the 2nd week of PERIOD445: LAST WORKDAY OF 2ND WEEK OF PERIOD445 4th workday of the 3rd PERIOD445 of FISCAL_YEAR: 4TH WORKDAY OF 3RD PERIOD445 OF FISCAL_YEAR
135
136
Working with ESP Procedures Overview
Introduction
An ESP Procedure is a set of stored instructions that ESP invokes. When you create an ESP Procedure you use CLANG, a high level programming language. You can also use IBMs REXX language in ESP Procedures. The main use of an ESP Procedure is to provide a framework for an ESP Application. ESPs Procedure capability lets you control an Application from one Event definition, regardless of the Applications complexity or number of conditional requirements. You can use a single ESP Procedure to control a complete batch run or even multiple batch runs. The Procedure automatically accounts for any daily changes, or month-end processing. For more information on using ESP Procedures to define Applications, refer to Using Applications, in this guide.
In this chapter
This chapter contains the following topics: Topic Overview of ESP Procedures Invoking an ESP Procedure ESP Procedure Syntax Using ESPs Control Language in Procedures Using Symbolic Variables in Procedures Using Expressions and Strings in Procedures Built-in Functions Using Calendaring Functions Using Functions For Job Selection Using Functions For Symbolic Variables Using System Activity Functions Combining Functions Re-executing an ESP Procedure Using Templates Using Event Definition Commands in Procedures Examples See Page 138 139 140 141 145 147 150 152 156 158 160 165 166 168 172 173
137
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 the Procedure.
138
Invoking an ESP Procedure
INVOKE command
To invoke an ESP Procedure, use the INVOKE command in an Event or in another 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: An Event invokes an ESP Procedure
The following example demonstrates how to use an Event to invoke an ESP Procedure. The Event appearing below runs each weekday at 4 p.m. and invokes an ESP Procedure. The Event looks like this:
EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE 'CYBER.ESP.PROC(PAYDAILY)' ENDDEF
139
ESP Procedure Syntax
Introduction
ESP Procedures have a specific syntax that you must follow for each of the components listed below: Syntax Rules Explanation Name 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 by the 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 + sign strips 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 denote character strings and literal data in expressions, in assignment statements, and in built-in functions. You must include single quotation marks around a string that contains blanks. 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 left hand side of an assignment statement. Labels Use labels in a Procedure to denote different sections. Labels can be up to 16 characters. The first character must be a letter and you must type a colon after the last character. In addition to identifying sections for editing purposes, labels can also act as targets in JUMPTO statements, where they control logical flow. Examples of using the above syntax rules are presented throughout this chapter.
140
Using ESPs Control Language in Procedures
Introduction
CLANG is an integral component of ESP Procedures and provides great power and flexibility. Its several language elements listed below allow you to specify conditional processing requirements.
IF
IF conditionally processes an instruction or group of instructions depending on the evaluation of an expression. When you use an IF statement, the expression that follows it must return a true or false value. You can use any number of nested IF statements. Example:
IF logical-expression THEN ...
THEN
The Procedure processes the statement after THEN only if the expression that follows the IF statement returns a true value. If a THEN statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP ignores the THEN statement. You must begin and end a set of instructions with DO and ENDDO language elements. Example:
THEN statement
ELSE
Use an ELSE statement only in conjunction with an IF statement when the expression that follows the IF statement returns a false value. If you do not include an ELSE statement after an expression returning a false value, ESP passes control on to the next line. You must begin and end a group of instructions with DO and ENDDO language elements. If an ELSE statement continues to another line, use a line continuation character (- or +). If there is no continuation character, ESP ignores the ELSE statement. Example:
ELSE statement
141
Using ESPs Control Language in Procedures, Continued
DO
Use the DO statement in conjunction with THEN and ELSE statements to indicate the start of a set of statements. Use this statement to group a number of instructions together. You do not require a DO statement if you only have one instruction. DO must follow immediately after THEN or ELSE, or begin the continuation line. Do not use a continuation character (- or +) on a DO statement. Example:
DO statement statement
ENDDO
Use the ENDDO statement in conjunction with the DO statement to indicate the end of a set of statements. The following example shows how you should use DO and ENDDO. Example:
DO statement statement ENDDO
EXIT
Use EXIT to quit from your current point in a Procedure. ESP continues to process pending requests up to the point at which you use EXIT. ESP also processes any action statements in the calling Event, or other ESP Procedures invoked in the same Event. ESP ignores EXIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, EXIT within the scope of a JOB statement causes ESP to process all statements up to the EXIT and submit the job. Example:
EXIT Continued on next page
142
QUIT
Use QUIT to quit an entire process and the Event that invoked it. If you use QUIT, ESP does not process any pending requests from this or any other Procedure invoked by the same Event. ESP ignores QUIT statements within the scope of a JOB statement during the generation of an ESP Application. During Application processing, QUIT within the scope of a JOB statement causes ESP not to process any statements for that job and does not submit the job, causing the job to fail with a SUBERROR. Therefore, any of the jobs dependencies are not released. Example:
QUIT
JUMPTO
Use JUMPTO to search forward through the existing Procedure to find the next label of the name given in the JUMPTO statement. Use JUMPTO to skip over whole sections of a Procedure. You can use JUMPTO with or without an IF statement. Example:
JUMPTO error_handler
Note: After you specify DO, ENDDO, EXIT or QUIT you must specify your next statement on the next line. You cannot continue these statements.
Example: Using IF-THENELSE
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 example might look like this:
IF A=B THEN SEND 'A AND B ARE EQUAL' U(*) ELSE SEND 'A AND B ARE NOT EQUAL' U(*)
143
Example: Grouping with DO-ENDDO
This example groups instructions together using DO and ENDDO:

DO SUBMIT 'CYB.ESP.JCL(PAYJOB1)' SEND 'PAYROLL IS RUNNING' CN(01) ENDDO
Example: Using QUIT and EXIT
This example uses the QUIT and EXIT instructions, as follows: If today is CHRISTMAS ESP quits the ESP Procedure and no instructions are processed. If today is not CHRISTMAS but it is a holiday, ESP sends a message and exits the Procedure at that point. If none of the above conditions are true, ESP sends a message indicating it will continue processing.
IF TODAY('CHRISTMAS') THEN QUIT IF TODAY('HOLIDAY') THEN DO SEND 'NO WORK TODAY' U(BOSS) EXIT ENDDO SEND 'LET US CONTINUE PROCESSING' U(USER01)
For more examples of using CLANG, refer to the Examples section at the end of this chapter.
144
Using Symbolic Variables in Procedures
Introduction
You can use symbolic variables in an ESP Procedure. The different types of variables are: Type of Variable Built-in Variables Explanation ESP provides a set of built-in variables for such information as the current date, time, and Event name. You can use these variables in an ESP Procedure but their values cannot be changed. Refer to the Advanced Users Guide for a complete list of these variables. These are alphanumeric strings or integers that you can use in an ESP Procedure to represent character strings, literal data, and numbers. When using an integer variable, you must first define the variable with an INTEGER statement before you use it.
User Defined Variables
When you want to use the value of a symbolic variable, you use the symbol introducer character (default is the per cent sign (%)) followed by the symbol name. For example: %NAME. Note: Your installation may use a different symbol introducer character. Check with your system administrator to find out what symbol introducer character is used at your site.
Example: Using Symbolics
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 NUMBER NUMBER=52 NAME='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
145
Using Symbolic Variables in Procedures, Continued
Refer to the Advanced Users Guide for a detailed discussion of symbolic variables.
146
Using Expressions and Strings in Procedures
Introduction
You can also use strings, expressions, and operators in your Procedures. This section outlines the syntax and use for each of these.
Using literal strings
A literal string is a group of characters enclosed in single quotes. You can embed symbolic variables in a string. ESP later substitutes the actual value of the 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, such as the time (%ESPATIME), you could type:
'THE TIME IS %ESPATIME'
ESP substitutes the actual system time in place of the symbolic variable name %ESPATIME.
Using expressions
An expression is a variable, number, or character string connected by operators. Expression evaluation is from left to right; this is overridden by operator precedence. You can modify this order using parentheses. A logical expression resolves to the value 1 if true, or 0 if false. Conversely, if an arithmetic expression resolves to 1, it is false. For any other value, the expression is true. If you do not enclose a logical expression in parentheses when you use an IF statement, ESP understands the THEN statement to be the terminator. 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 ...
147
Using Expressions and Strings in Procedures, Continued
Using operators
You can use arithmetic operators, comparison operators, and logical operators in an expression.
Arithmetic operators
Numbers may be combined using the following arithmetic operators:

+ Add Subtract * Multiply / Divide // Integer Divide ** Power Prefix Negate the following term. Same as 0-term Prefix + Take following term as if it was 0+term
If you use / for division, ESP performs the division internally using floating- point arithmetic but the resulting value is an integer. If you use // for division, ESP disregards any remainder. For example, if A is an integer then A = A/2*2 is always true, but A = A//2*2 is true only if A is even.
Comparison operators
The comparison operators return the value 1 if the result of the comparison is true or 0 otherwise. You can use the following operators, in either their symbol or letterform in an expression.
>= <= < > = = GE LE LT GT EQ NE greater than or equal to less than or equal to less than greater than equal to not equal to
Logical operators
You can use the following logical operators in an expression: AND OR

148
Using Expressions and Strings in Procedures, Continued
Order of precedence
The order of precedence of the operators is (highest at the top):

(not), prefix + (prefix plus), prefix - (prefix minus) **(power) /(divide), // (integer divide), * (multiply) +(plus), -(minus) >= (GE), <= (LE), < (LT), > (GT),= (EQ), = (NE) AND OR
In the statement below (A = B or C > D) is a valid expression and GO is a valid character string that ESP assigns to the variable E. ESP assigns the value GO to the variable E if either A = B or C > D.
IF (A=B OR C > D) THEN E = 'GO'
Note: If the expression A = B is true, the entire logical expression is also true. This means that ESP does not have to evaluate C > D. This order of precedence is useful for expressions such as IF I = 0 AND J/I > 4. This expression does not cause an error since J is divided by I only if I is non-zero.
149
Built-in Functions
Introduction
A function is a sequence of instructions that can receive data, process that data, and return a value. ESP provides a set of built-in functions. To use a function, type the function name directly followed by one or more arguments within parentheses, like this:
function(arguments)
Note: There can be no space between the function name and the left parenthesis.
Built-in functions
The built-in functions fall into the following categories:
Category Calendaring Job Selection Symbolics System Activity
Explanation Test schedule criteria and calculate time periods. Check if a job has already been selected for submission. Perform operations on symbolic variables. Check the status of activity on the system, including jobs and tape drives.
Summary by function
The following table summarizes the functions by category: Category Calendaring Function Description DAYS_BETWEEN Calculates the number of units (days, weekdays, workdays, etc.) between two dates. DAYS_FROM Calculates the number of days from a date. DAYS_TO Calculates the number of days away from a date in the future. TODAY Tests to see if today matches a specified schedule expression. TOMORROW Tests to see if tomorrow matches a specified schedule expression. YESTERDAY Test to see if yesterday matches a specified schedule expression.
Calendaring Calendaring Calendaring Calendaring Calendaring
150
Built-in Functions, Continued
Summary by function (continued)
Category Job Selection Symbolics Symbolics Symbolics System Activity
Function SELECTED DEFINED LENGTH SUBSTR ACTIVE
System Activity
JOBONQ
System Activity
TAPES
Description Checks to see if a job has been selected. Checks to see if a symbolic variable has been defined. Returns the length of a symbolic variable. Returns a partial string of a symbolic variable. Checks to see if a job or address space is active on the current system. Checks to see if a job or address space is active on any system in the shared spool environment. Checks the status of tape drives.
Testing for a true condition
Each one of the SELECTED, TODAY, TOMORROW, and YESTERDAY built-in functions returns a true value (1) or a false value (0). To test for a true condition you do not have to specify the true value, since this is the default. If you want to test for a false value, you must specify either =0, EQ 0, or use the word NOT. In the following example, both statements have the same effect. Each checks to see if today is not Monday.
IF TODAY('MONDAY') EQ 0 THEN ... IF TODAY('NOT MONDAY') THEN ...
The following sections describe ESPs built-in functions in detail and contain some examples of using these functions. For more examples, refer to the Examples section at the end of this chapter.
151
Using Calendaring Functions
DAYS_TO
The DAYS_TO function returns a positive number representing the number of days from a specified special day, holiday, or any defined schedule criteria. If you do not use a year and the day you specified has passed, DAYS_TO assumes the next year and returns a positive number. If the date is in the past, ESP returns a negative number.
Example: DAYS_TO
If you want to determine the number of days to December 25 from the current day, and assign that number to an integer variable called X, type:
INTEGER X X=DAYS_TO('DEC 25')
DAYS_FROM
The DAYS_FROM function returns a positive number representing the number of days from a date in the past. DAYS_FROM assumes the current year if you do not specify one. If the date is in the future, ESP returns a negative number.
Example: DAYS_FROM
The following is an example of an expression containing the DAYS_FROM built-in function:

IF DAYS_FROM('AUGUST 1ST') GT 0 THEN
DAYS_BETWEEN
The DAYS_BETWEEN function returns a whole number representing the number of a specified unit of time between two given dates. You do not have to specify the dates explicitly; you can use a schedule expression instead.
DAYS_BETWEEN('first date','second date','restrictor')
The restrictor is an optional qualifier that defaults to DAYS. The following are other possible restrictors; HOURLY, DAILY, WORKDAYS, WEEKDAYS, WEEKLY, SATURDAYS, WEEKENDS, MONTHLY, YEARLY. Your restrictor cannot be any unit of time less than hourly. The value that this function returns is the number of occurrences of the restrictor between the first date and the second date. If the first date is not prior to the second date, the function returns a negative number. The maximum value the function returns is 50,000 for any restrictor other than 'DAYS'.
152
Using Calendaring Functions, Continued
Example:
Days_Between to Calculate Workdays
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 to Calculate Weeks
You could also determine the number of Saturdays from the 6th workday of the current month, up to but not including tomorrow, by typing:
DAYS_BETWEEN('6TH WORKDAY OF MONTH STARTING + TODAY','TOMORROW','SAT')
TODAY
The TODAY function compares the schedule expression that you specify to todays schedule date. It returns a true or a false value, depending on whether the expression matches today. ESP returns a number code indicating the result:
1 = true 0 = false
In the following example, ESP only processes the instructions following the THEN statement if today is a Friday.
IF TODAY('FRIDAY') THEN ...
When the statement is false, ESP skips to the next ELSE statement or to the following line. You can check if today is not Friday like this:
IF TODAY('NOT FRIDAY') THEN ...
Example: TODAY
The following are examples of the TODAY function: 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 ...
153
TOMORROW
The TOMORROW function compares the expression following the TOMORROW keyword to tomorrows date (i.e. the day after the schedule date). ESP returns a true or false value, depending on whether the expression matches tomorrow. ESP returns a number code indicating the result:
1 = true 0 = 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 the following line.
YESTERDAY
The YESTERDAY function compares the schedule expression that you specify to yesterdays date (i.e. the day before the schedule date). ESP returns a true or false value, depending on whether the expression matches yesterday. ESP returns a number code indicating the result:
1 = true 0 = false
Example: YESTERDAY
In the following example, ESP only processes the instructions following the THEN statement when yesterday is the first workday of the month:
IF YESTERDAY('FIRST WORKDAY OF MONTH') THEN ...
When the statement is false, ESP skips to the ELSE statement or to the following line.
154
Example: YESTERDAY
In the following example, ESP only processes the instructions following the THEN statement when yesterday is a holiday:
IF YESTERDAY('HOLIDAY') THEN ...
When the statement is false, ESP skips to the ELSE statement or to the following line.
155
Using Functions For Job Selection
SELECTED
The SELECTED function returns a true or false value that indicates whether a jobname has been selected as a result of a previously processed SELECT or RUN statement. To return a true value, ESP must have selected the job in this ESP Procedure, or in another ESP Procedure invoked by the same Event, prior to evaluating the function. This function does not return a true value for a job selected via a POSTREQ, PREREQ or COREQ statement. ESP 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 to include the qualifier, like this:
SELECTED('jobname.qualifier')
This function is useful for scheduling jobs with the same frequency as it can eliminate the need to specify complicated criteria multiple times. The function is also useful when you want to schedule a job whenever another job is not scheduled.
Example: Selecting one job based on another
You could use the SELECTED function to select Job B whenever ESP selects another job, Job A.
IF SELECTED('A') THEN SELECT B
Example: Selecting a job when another is not selected
In this example, ESP selects Job Z whenever it does not select Job X. ESP selects Z on all days except for the 3rd, 13th and 23rd day of the month.
JOB X RUN 3RD 13TH 23RD DAY OF MONTH ENDJOB JOB Z IF NOT SELECTED('X') THEN RUN TODAY ENDJOB
The above results are valid only at Application generation time and not at Application process time.
156
157
Using Functions For Symbolic Variables
DEFINED
The DEFINED function checks to see if a symbolic variable has been defined and returns the following values:
1 = true 0 = false
The syntax is:

DEFINED(variable)
Example: Defining an undefined variable
This example defines an integer variable called COUNT if it has not been defined.
IF NOT DEFINED(COUNT) THEN INTEGER COUNT
LENGTH
The LENGTH function returns a number equal to the length of the variable following the LENGTH keyword in parentheses. The syntax is:
LENGTH(variable)
This function does not return a true or false value. Instead, it resolves to a whole number equal to the length of the named variables value.
Example: Calculating the length of a symbol
In this example, the LENGTH function assigns the length of a user-defined variable called LETTER to the integer variable SIZE. As a result, SIZE has a value of 7.
INTEGER SIZE LETTER='OMICRON' SIZE=LENGTH(LETTER)
SUBSTR
The SUBSTR function resolves to a partial string from the variable string that follows the SUBSTR keyword in parentheses. The syntax is:
SUBSTR(start,length,variable_name)
158
Using Functions For Symbolic Variables, Continued
Example: Using a substring of a time variable
The ESPATIME built-in variable represents the actual time, 19.35.42, for example. This example assigns the number of minutes in the ESPATIME symbolic variable to the symbol MIN.
MIN=SUBSTR(4,2,ESPATIME)
Example: Extracting the last character of a variable length symbol
This example uses the LENGTH and SUBSTR functions to extract the last character of the scheduled month name. The LENGTH function calculates the length of the month name. The SUBSTR function extracts the last character.
INTEGER X X=LENGTH(ESPSMONTH) LAST_CHAR=SUBSTR(%X,1,ESPSMONTH)
For example, if the scheduled month is December: X=8, because there are 8 characters in the word December LAST_CHAR=SUBSTR(8,1,DECEMBER), which resolves to R, the last character in the word December.
159
Using System Activity Functions
ACTIVE
The ACTIVE function tests to see if a job or any address space is active on the current system and returns a value based on that test. ESP returns a number representing the result:
address space identifier = true 0 = false.
Note: If you want to verify that a job or any address space is active on any system (within the same JES node), use the JOBONQ built-in function.
Example: Checking if CICSPROD is active
This example sends a message to console identifier 01 if CICSPROD is active on the current system.
IF ACTIVE('CICSPROD') THEN + SEND 'CICSPROD IS STILL ACTIVE' CN(01)
JOBONQ
Use the JOBONQ function to determine, by checking JES, whether a job or group of jobs is currently on any JES queue. To use the JOBONQ function, use the following syntax:
JOBONQ('jobname','prefix','criteria')
This function requires three parameters: a jobname, a prefix and search criteria. Parameter jobname prefix Explanation The name of the job or jobname prefix. You can only use a jobname prefix with the U criteria. 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(*)
160
Using System Activity Functions, Continued
Parameter criteria
Explanation The search criteria consist of any combination of the letter codes below. If this parameter is omitted, ESP looks in all queues.
Returning Values
The following list contains all the acceptable search criteria codes:
Search Criteria Codes I E O H U
Explanation Examine the input queue Examine the execution queue Examine the output queue Examine held jobs only Treat the jobname as a userid. The search includes any job with a name consisting of the jobname plus one character.
JOBONQ Variables
The JOBONQ function returns the count of jobs that meet the criteria. For each job it generates a series of four variables beginning with the specified prefix (the second 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 the number of jobs found.
Example: JOBONQ
The JOBONQ function in the following example verifies the existence of any job in the input queue (I) in hold status (H). ESP assigns the number of jobs that meet this criteria to the integer variable JOBCOUNT.
INTEGER JOBCOUNT JOBCOUNT = JOBONQ('PAYROLL','Z','IH')
If JOBCOUNT is not equal to zero, meaning that at least one job called PAYROLL is in the input queue in hold status, ESP generates a set of variables for each job it finds. These variables all begin with the prefix Z.
161
Example
For example, for the first job it finds the variables are: Variable ZJOBID1 ZJOBNO1 ZJOBH1 ZJOBQ1 Explanation JES job identifier. This is JOB followed by the 5-digit job number (e.g. JOB01234). JES job number (e.g. 1234). Equal to 0 if JES is not holding the job, or equal to 1 if JES is holding the job. 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 second job are: ZJOBID2, ZJOBNO2, ZJOBH2, and ZJOBQ2. ESP repeats this series with the last digit incrementing by one for additional jobs it finds. If you use the U criteria, the JOBONQ function also returns the JOBN variable, with the appropriate prefix and suffix.
Using JOBONQ with REEXEC
You can also use the JOBONQ function in conjunction with the REEXEC statement to allow you to re-execute an ESP Procedure at a specified time or after a certain time interval. In the following example, ESP re-executes the Procedure if MYJOB is found on any queue.
IF JOBONQ('MYJOB') THEN REEXEC IN(5)
162
TAPES
ESP evaluates the TAPES function to check the status of tape drives on the system and compares the status to the resources required by the job. When you use the TAPES function at the job level for a job in an Application, you can verify the status of the tape drives before you submit a job. Note: To check the status of tape drives, Cybermation recommends you use resources. Resources provide you with easier, more efficient ways of defining tape requirements. For more information, refer to Using Resources, in this guide.
Example: TAPES
To use this function enter TAPES followed by two parameters from the lists below:
TAPES('xy')
ESP evaluates both parameters (x and y) of the function and returns a whole number. You can choose one of the following three options as the first parameter: Option C R T Explanation Cartridge drives Reel-to-reel drives Total drives
You can choose one of the following as the second parameter: Option A O D The default is CA.
Explanation Available Online Defined
163
Example: If a job in an Application requires two cartridge drives, you can use the Checking TAPES function to check that two cartridge drives are available before you available submit the job. If they are not, ESP can check again after two minutes: cartridge drives
JOB TAPEJOB1 IF TAPES('CA') < 2 THEN REEXEC IN(2)
164
Combining Functions
Introduction
You can combine built-in functions using the AND and OR logical operators. Specify the built-in function name each time you need to use it.
Examples
Some examples are shown below: Today is Friday and today is not the last workday of the year:
IF TODAY('FRIDAY') AND TODAY('NOT LAST WORKDAY OF YEAR') THEN
Today is the last workday of the month and CICS is active on the current system:
IF TODAY('LAST WORKDAY OF MONTH') AND ACTIVE('CICS') THEN
Yesterday was a holiday, tomorrow is Friday, and today is a workday:

IF YESTERDAY('HOLIDAY') AND TOMORROW('FRIDAY') AND + TODAY('WORKDAY') THEN
Today is Monday, Wednesday, or Friday and either yesterday was a holiday or tomorrow is a holiday:
IF TODAY('MON WED FRI') AND (YESTERDAY('HOLIDAY') OR + TOMORROW('HOLIDAY')) THEN
165
Re-executing an ESP Procedure
Introduction
Use the REEXEC statement to request re-execution of an ESP Procedure at a specific time or after a certain time interval. ESP stores the number of reexecutions in a symbolic variable called ESPREEXEC#. If you use REEXEC within the scope of a JOB statement in an Application, ESP re-executes only the code associated with that job, and maintains a separate ESPREEXEC# for each job.
Example: Checking if CICS is active
This ESP Procedure checks to see if a job or address space called CICS is active on the current system. If CICS is active, ESP sends a non-deletable message to console id 01 and re-executes the Procedure in 5 minutes. If CICS is not active, ESP submits the member CICSBKUP from the library 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) ENDDO ELSE SUBMIT 'PROD.JCL.CNTL(CICSBKUP)'
Note: If you want to set up a dependency with an online region, such as CICS, for a job in an ESP Application, the preferred method is to use ESPs resource feature. For information on using resources, refer to Using Resources.
166
Re-executing an ESP Procedure, Continued
Example: Waiting for a job
This ESP Procedure checks to see if a job called RMTJOB is on the input queue. 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 reexecutes the Procedure in 30 minutes. Otherwise, ESP sends a message.

INTEGER COUNT COUNT=JOBONQ('RMTJOB','X','IH') IF COUNT=1 THEN VS '$AJ%XJOBNO1' ELSE DO IF ESPREEXEC#<5 THEN REEXEC IN(30) ELSE SEND 'I GIVE UP ON RMTJOB' U(USER01) ENDDO
167
Using Templates
Introduction
A template is an element of CLANG that allows you to specify repetitious commands or statements once, such as those you use to define holidays or jobs. This section contains a brief introduction to templates. For more information on using templates, refer to the Advanced Users Guide.
Defining a template
To define a template, you: Use a TEMPLATE statement to give your template a name and identify parameters you want to pass through the template Define the statements that make up your template End the template definition with the ENDTEMPL statement.
Using a template
To use a template you have defined, you specify the name of the template followed by any parameters you want to pass through the template.
168
Using Templates, Continued
Example Defining a static 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 and supply the template with different years. In this example: The name of the template is XMAS and it accepts 1 positional parameter represented by the variable YEAR. The body of the template consists of one statement that defines CHRISTMAS as a 24 hour holiday, on Dec. 25 each year, in the SYSTEM calendar. The year is represented by the variable YEAR. The ENDTEMPL statement ends the template definition. The template XMAS is then used with the years 1998 through 2003. Each of these years is passed to the template and substituted for the variable YEAR within the template.
TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START('DEC 25, %YEAR') + FOR(24) CAL(SYSTEM) ENDTEMPL XMAS 1998 XMAS 1999 XMAS 2000 XMAS 2001 XMAS 2002 XMAS 2003
Set up an Event to invoke this ESP Procedure and trigger it manually to define your holidays.
169
Example Defining similar jobs
In this example, an Application contains a number of print jobs. These jobs: Run daily Belong to a subApplication called PRTJOBS Run independently.
The following is a sample definition of this Application:

APPL PAYROLL JCLLIB 'CYB.JOBS.CNTL' JOB USERA SUBAPPL PRTJOBS RUN DAILY ENDJOB JOB USERB SUBAPPL PRTJOBS RUN DAILY ENDJOB JOB USERC SUBAPPL PRTJOBS RUN DAILY ENDJOB JOB USERD SUBAPPL PRTJOBS RUN DAILY ENDJOB
Because of the similarity of the jobs, you can define a print job template and pass 1 parameter for the name of each job. The template contains details for the print job, such as SUBAPPL PRTJOBS and RUN DAILY.
170
Example Defining similar jobs
APPL PAYROLL JCLLIB 'CYB.JOBS.CNTL' TEMPLATE PRTJOBS (1,NAME) JOB %NAME SUBAPPL PRTJOBS RUN DAILY ENDJOB ENDTEMPL PRTJOBS USERA PRTJOBS USERB PRTJOBS USERC PRTJOBS USERD
The template is used for jobs USERA, USERB, USERC and USERD. ESP substitutes the jobname for the %NAME variable within the template.
171
Using Event Definition Commands in Procedures
Commands
You can use the following commands in an ESP Procedure:
Command INVOKE LIBSUB PANSUB ROSSUB SEND SIGPOST SIGCYCLE SUBMIT VS
Explanation Invokes another ESP Procedure Submits JCL from a Librarian data set Submits JCL from a Panvalet data set Submits JCL from a Roscoe data set Sends messages to a TSO user or console Posts a complete signal Cycles a new generation of a signal Submits JCL from a PO, PS, or VSAM ESDS data set Issues an operator command (restricted use).
172
Examples
Introduction
This section contains some additional examples of using CLANG.
Example: Scheduling a job on the last day of the month
In this example, ESP selects a job if it is the last day of the month and the month has 31 days in it. The Procedure uses the ESPSDD built-in symbolic variable that represents the number of the scheduled day of the month. The ESP Procedure looks like this:
IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN SELECT MONTHEND
Alternatively, if you normally use RUN statements for your jobs, the ESP Procedure looks like this:
JOB MONTHEND IF TODAY('LAST DAY OF MONTH') AND ESPSDD='31' + THEN RUN TODAY ENDJOB
Example: Taking different action on a weekday
In this example, ESP takes different actions based on whether or not the scheduled day is a weekday. If the scheduled day is a weekday, ESP sends a message and submits JOB1. If the scheduled day is not a weekday, ESP sends a different message and submits JOB2.

IF TODAY('WEEKDAY') THEN DO SEND 'TODAY IS A WEEKDAY' U(*) SUBMIT 'CYB.ESP.JCL(JOB1)' ENDDO ELSE DO SEND 'TODAY IS A WEEKEND' U(*) SUBMIT 'CYB.ESP.JCL(JOB2)' ENDDO
173
Examples, Continued
Example: Taking different actions based on the status of CICS
In this example, ESP takes different actions based on whether or not CICS is active. If CICS is active on the current system, ESP jumps to a label called STOP. ESP issues an operator command, schedules a re-execution in 5 minutes, and exits this Procedure. If CICS is not active on the current system, ESP jumps to a label called GO and issues a command to trigger an Event.

IF ACTIVE('CICS') THEN JUMPTO STOP ELSE JUMPTO GO STOP: VS 'F CICS SHUTDOWN' REEXEC IN(5) EXIT GO: VS 'F ESP,TRIGGER PROD.NIGHTLY'
Example: Using calendaring functions
This example uses different CLANG functions. It accomplishes the following: Assigns the number of days to December 25 to the integer variable X Assigns the number of 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,Z X=DAYS_TO('DEC25') Y=DAYS_BETWEEN('TODAY','DEC25','WORKDAYS') Z=DAYS_FROM('JUL20,1969') SEND 'THERE ARE %X DAYS TO CHRISTMAS' U(*) SEND 'THERE ARE %Y WORKDAYS TO CHRISTMAS' U(*) SEND 'THERE HAVE BEEN %Z DAYS SINCE THE FIRST MOON WALK' U(*) IF TODAY('WORKDAY') THEN SEND 'ANOTHER DAY OF HARD LABOR' U(*)
174
Examples, Continued
Example: Calculating time periods
This example calculates the number of days, from a specific time and date in the past. ESP sends the results back to your terminal. The ESP Procedure looks like this:
INTEGER X,Y X=DAYS_BETWEEN('1PM JAN1,1994','NOW','HOURLY') Y=DAYS_BETWEEN('JAN1,1994','TODAY','DAILY') SEND 'ITS BEEN %X HOURS SINCE STOP HOUR' U(*) SEND 'ITS BEEN %Y DAYS SINCE STOP DAY' U(*)
Example: Overriding an ESP procedure on a particular date
There may be occasions where you need to use an alternate ESP Procedure for a specific date. One method is illustrated below:
DAILY:ESPPROC IF TODAY('specific date') THEN DO INVOKE 'PROD.ALT.ESPPROC(DAILYEX)' EXIT ENDDO /*REGULAR PROCEDURE*/ . . .
The first statement checks to see if today is a specific date. If so, ESP invokes an alternate ESP Procedure. Otherwise, ESP processes the statements in the regular procedure.
175
Examples, Continued
Example: Taking different action based on time
In this example, ESP takes different actions based on when a job becomes eligible for submission. The criteria are: If Job THISJOB becomes ready for submission between 3 a.m. and 3:59 a.m., ESP submits the job and sends a message indicating it is almost too late to run the job. If THISJOB becomes ready for submission at 4 a.m. or later, ESP does not submit 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 variable represents 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
176
177
Using Applications Overview
Introduction
An Application consists of one or more jobs, or other workload objects. A workload object can be a job, a manual task, a command you want processed, or a non-MVS object, such as a Unix script. For example, an Application may consist of all of your payroll jobs. You can define an Application using the Application Definition panels, ESP Workstation, or by editing a member of a PDS. All Application definitions are stored in ESP Procedures.
In this chapter
This chapter contains the following topics: Topic Introducing Applications Identifying the Application Identifying JCL Libraries Identifying Jobs Defining Job Requirements Specifying Time Dependencies Specifying Job Relationships Selecting Jobs for Submission Using Different Job Types Defining External Jobs Defining Manual Jobs Using Links Using Tasks Changing Job Attributes Using Data Set Trigger Workload Objects Tagging Jobs Providing Notification on Job Status See Page 180 185 186 192 199 200 208 210 213 214 218 221 227 229 230 236 238
178
Overview, Continued
In this chapter (continued)
Topic Using Critical Path Analysis Issuing ESP Commands Using subApplications Working with Applications Displaying an Application Controlling an Application Changing an Application Definition Invoking an ESP Application
See Page 241 246 247 251 252 254 256 257
179
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 an Application
ESP performs the following processing steps for jobs in an Application:
Step 1 2
Action When a jobs submission time arrives, ESP checks for any remaining dependencies. Each job has a hold count. The hold count is a number corresponding to the number of immediate predecessors for the job. A job in an Application is not eligible for submission if the hold count exceeds zero. When a predecessor job terminates successfully, ESP subtracts 1 from the successor jobs hold count. For instance, if the hold count for a job is 3 and a predecessor job terminates successfully, the hold count decreases to 2. When the hold count reduces to zero, ESP readies the job for submission, unless the job is in another type of hold status such as Manual hold or Resource Wait. ESP submits the job when all required resources are available.
Types of phases
An Application passes through the following two phases: Generation Process.
Generation phase
When an Event is triggered that invokes an ESP Application definition, ESP must first generate the Application. ESP reads the definition and creates a record in a file known as the APPLFILE. This record includes the information ESP needs in order to process the jobs in the Application. The record describes the Application and all the jobs within it.
180
Introducing Applications, Continued
Process phase
Once ESP generates an Application, it then begins to process that Application as follows: A component of ESP called the Application Manager has a queue of jobs awaiting submission. Jobs can be in a waiting state due to such things as time, predecessors, and resources. The Application Manager looks at the jobs and assesses whether any time dependencies have been met. If so, the job goes into a job dependency state and waits until the last predecessor dependency has been met. The job then enters a resource wait state, which allows ESPs resource manager to verify that the jobs resource dependencies are met. ESP re-drives the Event to submit the job when the required resources are available. The Application manager uses real-time SMF data to update the execution status of each job.
Phase status
You can find out the phase status of an Application by using the ESP_APPL_PROC and ESP_APPL_GEN symbolic variables in an Application definition. ESP 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 the generation phase of an Application.
IF ESP_APPL_GEN=1 THEN SE ESP IS GENERATING THE PAYROLL APPLICATION U(TAXMAN)
181
Application Generations
Each Application has a generation number assigned by ESP when the Application is generated. This number increments with each generation of an Application. Using the generation number, ESP can identify the particular generation of an Application to which a job belongs. A generation of an Application does not have to complete within any 24 hour period; an Application can span many days or weeks, or you can schedule an Application many times in one day. Different generations of an Application can process at the same time.
Defining an Application
You must use an ESP Procedure to describe an Application to ESP. Refer to Working with ESP Procedures on page 137 for detailed information on ESP Procedures.
182
ESP Procedure statements
An ESP Procedure that defines an Application consists of a series of statements 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 documentation library is used, or specify what condition codes cause a job to fail. Visually, an Application might look like this:
A
Daily
Friday
Last workday of month
183
Application definition
The corresponding Application definition might look like this:

APPL PAYROLL JCLLIB CYBER.ESP.JCL JOB A RUN DAILY RELEASE (B,C) ENDJOB JOB B RUN DAILY RELEASE D ENDJOB JOB C RUN DAILY RELEASE D ENDJOB JOB D RUN DAILY RELEASE E ENDJOB JOB E RUN FRIDAY RELEASE F ENDJOB JOB F RUN LAST WORKDAY OF MONTH ENDJOB
The following sections discuss how to define an Application.
184
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 national characters. Your security administrator may require you to code other information on the APPL statement, such as the SAF_PROF_APPL keyword, to provide more granular security for the Application.
Controlling concurrent processing
Normally, if two generations of an Application are active on the system at the same time, they execute at the same time. You can control concurrent processing at different levels, as follows: Explanation A generation of an Application must wait until its previous generation is complete The subApplication must wait until the same subApplication in the previous generation is complete Indicates that a job is not eligible for submission if the same job in any previous generation of the Application has not completed successfully Indicates that a job is not eligible for submission if the same job in the previous generation of the Application has not completed successfully. ESP only looks at the -1 generation. Applications can process at the same time. Example
APPL PAYROLL WAIT SUBAPPL PAYREQ WAIT
Parameter WAIT parameter on APPL statement WAIT parameter on the SUBAPPL statement JOB_ANCESTOR_ WAIT(ANY) parameter on the APPL statement JOB_ANCESTOR_ WAIT(LAST) parameter on the APPL statement None of the above parameters
APPL PAYROLL + JOB_ANCESTOR_WAIT(LAST)
APPL PAYROLL + JOB_ANCESTOR_WAIT(ANY)
APPL PAYROLL
For more information on subApplications, refer to Using subApplications on page 247.
185
Identifying JCL Libraries
Introduction
Use global statements in your Application to specify the default JCL libraries you want to use throughout an Application. This saves you the task of repeatedly specifying the same information as part of each jobs definition. The scope of a global statement extends from the point at which you specify it to either the end of the Application, or to the point at which you specify a corresponding global statement. This way you can change or override job defaults several times during an Application, if necessary. You can specify any of the following: a JCL library, a temporary JCL library and a COPYJCL library at a global level. You can override the JCL library, member name, or COPYJCL library at a job level.
Example
The following example identifies three libraries in the BILLJOBS Application. These global statements are specified prior to any JOB statements.
APPL BILLJOBS JCLLIB PROD.JCL.CNTL TEMPLIB PROD.OVERRIDE.JCL. COPYJCL CYBER.JCL.COPY GEN(0)
Each of these statements is described in the following sections.
Specifying a JCL library
Use the JCLLIB statement to specify the JCL library you want to use for all jobs following this statement. For example,
JCLLIB PROD.JCL.CNTL
When ESP encounters a JOB statement for a job, it uses the JCL member in the JCLLIB with the same name as the job. You can use the MEMBER statement to override this action. The JCLLIB statement cannot be used at the job level. If you code a JCLLIB statement within the scope of a JOB statement, it affects all jobs after it, or until another JCLLIB statement is specified. To override the JCL library for a particular job, use the DATASET statement.
186
Identifying JCL Libraries, Continued
Specifying a temporary JCL library
Use the TEMPLIB statement to specify the temporary, or override JCL library you want to use as the default for all jobs following this statement. ESP uses JCL from this library for job submission if it exists. Otherwise, it uses JCL from the most recent JCLLIB statement. By default, the member name is the same as the job name. You can use the MEMBER statement to override this action. For example:
TEMPLIB PROD.OVERRIDE.JCL
As long as JCL exists for a job in the temporary library, and you specified a TEMPLIB statement in your Application, ESP submits the job from there. ESP does not automatically delete the member from the TEMPLIB data set when a job completes.
Controlling the use of temporary 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. This technique is described later in this section. Use ESPs automatic variable insertion facility (AUTOVARS) to insert a trailer step that deletes the TEMPLIB member. For information on using AUTOVARS, refer to the Advanced Users Guide. Use another method for cleaning out the TEMPLIB members. For example, on a daily basis, delete the members. Instead of using TEMPLIB, use IF logic with the DATA SET statement to override the JCL library for a particular job. This technique is described later in this section. Instead of using TEMPLIB, use %INCLUDE/%EXCLUDE statements within the JCL. This may be practical if the differences in JCL are minimal. For information on using these statements, refer to the Advanced Users Guide. Use different data sets. For example, you could use a different data set each day.
187
Example: Using a different TEMPLIB based on year and day
In the following example, ESP symbolic variables are used as part of the TEMPLIB data set name. %ESPSYEAR resolves to the 4-digit year; %ESPSDDD resolves to the Julian day. For example, on February 28, 1998 this resolves to: ESP.OVERRIDE.1998059.
TEMPLIB ESP.OVERRIDE.%ESPSYEAR%ESPSDDD
Limiting the use of temporary JCL
A job may need to run from a temporary JCL library for a period of time. If you want to limit the time period in which temporary JCL is to be used for a job, you can: Use a //*FROM statement in the jobs JCL to identify the beginning date and time. The default is NOW. Use a //*UNTIL statement in the jobs JCL to identify the ending date and time. There is no default. ESP uses the TEMPLIB JCL up to, but not including, the date and time specified.
You can use either one of these statements or you can use both. Place these statements before the job card in a JCL member of the temporary library (TEMPLIB). You can use any ESP scheduling term that resolves to a single date and time.
Example
In the following example, ESP uses the temporary JCL from midnight on February 1, 1998 up to, but not including, February 14, 1998. At any time after February 13, ESP uses the default JCL library. Note these dates are based on the scheduled date of the Event, which may not be the actual date of job submission.
//* FROM FEB 1,1998 //* UNTIL FEB 14,1998 //BILLJOBA JOB . . .
188
Specifying a COPYJCL library
Use the COPYJCL statement to generate a copy of the JCL for every job, as ESP submits it. This copy is written to a member of a PDS, providing a working copy of the JCL with, where applicable, all symbolic variables resolved. This JCL can be used for job re-submission. ESP keeps track of where the job was submitted from and the JCL that was used. ESP can store the copy of the JCL either by jobname (JOBNAME keyword) or by JES job number (JOBID keyword).
Using the JOBNAME keyword
The JOBNAME keyword requests the member name used for storing the JCL for a job is the same as the jobname. This is the default. Each submission of a particular job overwrites the previous copy of that jobs JCL.
Using the JOBID keyword
Use the JOBID keyword when you want ESP to store the copy of the JCL by job number. ESP creates a member name starting with JOB, followed by a five-digit JES job number. The system assigns this number sequentially. A member is not overwritten until its five-digit number reoccurs.
Writing the JCL to a PDS GDG
With either the JOBID or the JOBNAME method, you can write the JCL to a PDS GDG. A new generation can be created each day to maintain several generations of JCL. Schedule an Event each day to submit a job that creates the next generation.
Example: Using COPYJCL
This example requests that a copy of submitted JCL be written to the current generation of the data set CYBER.JCL.COPY and stored by jobname (by default).
COPYJCL CYBER.JCL.COPY GEN(0)
Suppressing COPYJCL
If you do not want to create COPYJCL for a particular job, you can specify the following:
JOB MISC COPYJCL NONE
189
Compressing COPYJCL
If you re-use the same data set continually, submit a compress job frequently to ensure the data set does not run out of space. You can use a data set triggered Event to submit the compress job automatically after a number of closures.
Overriding the member for a job
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 MEMBER statement and specify the name of the member that contains the JCL for the job. The jobname must match the name specified on the job card.
Example
For example, the following specifies that the JCL for job PAY123A is in member PAYA of the JCL library CYBER.JCL.CNTL:
JCLLIB CYBER.JCL.CNTL JOB PAY123A MEMBER PAYA
Overriding the JCL library for a job
In addition to using the JCLLIB and TEMPLIB default specifications statements, you can identify the JCL library and optional member name that a particular job requires using the DATASET job statement. For this particular job only, the DATASET statement overrides.
190
Example: Using a different JCL library for a job
In the following example, jobs J1 and J3 use the CYBER.JCL.CNTL library for job submission, as this is the global JCL library specification. Job J2 uses the CYBER.ALT.JCL library for submission because of the presence of the DATASET statement.
APPL J123 JCLLIB CYBER.JCL.CNTL' JOB J1 RUN DAILY RELEASE J2 JOB J2 DATASET CYBER.ALT.JCL' RUN DAILY RELEASE J3 JOB J3 RUN DAILY ENDJOB
Example: Temporarily using a different JCL library for a job
In the following example, ESP uses the JCL from CYBER.ALT.JCL for job J2 only on February 14, 2000.
JOB J2 IF TODAY(FEB 14,2000) THEN DATASET CYBER.ALT.JCL RUN DAILY RELEASE J3 ENDJOB
191
Identifying Jobs
Introduction
An ESP Application is made up of a group of related jobs and other tasks. The jobs and tasks have jobnames assigned to them. Before identifying job requirements, you must use a JOB statement to identify the name of the job in an Application. You can define jobs in any order. ESP submits the jobs based on how you define the job relationships.
JOB statement
Once the JOB statement has been used to introduce a job to an Application, use other related job statements to: Define a jobs processing requirements Override any default specifications Specify the relationships between the named job and others included in this Application or outside this Application.
The JOB statement defines the beginning of the job definition. The ENDJOB statement or another JOB statement signifies the end of a job definition. You must use an ENDJOB statement after defining all of your jobs. Although optional, it is recommended you use an ENDJOB for each job definition. The following is a sample job definition:
JOB PATJOB1 RUN DAILY RELEASE PATJOB2 ENDJOB
Qualifying jobs
ESP lets you qualify jobnames with a qualifier consisting of up to 8 alphanumeric characters, and separated from the jobname by a period,. You can qualify jobs, links and tasks but you cannot qualify Manual jobs. Use qualification 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 jobs JCL.
192
Identifying Jobs, Continued
Symbolics as qualifiers
You should not use %ESPA (actual) variables as time qualifiers for jobs since the actual time differs from Application generation to the time ESP submits a job as part of the Application. You can use %ESPS (scheduled) variables as time qualifiers as these refer to the scheduled time of the Event.
Examples: Qualified Jobs
The following are some examples of qualified jobs. The last example uses a qualifier that consists of the first 3 characters of the symbolic variable %ESPSDAY. This is the scheduled day name. For example, on Monday this resolves to MON.
JOB JOB JOB JOB MYJOB.RUN1 STILL.RUNNING BACKUP.SYSRES PAYJOB.%ESPSDAY(1:3)
Duplicate jobnames
Duplicate jobnames are not allowed in an Application. You can define the same jobname more than once in an Application by using a unique qualifier for each job.
Example: Multiple runs of a job
This example shows how you can define a job more than once in an Application using a job qualifier. Job A appears twice in the Application. The qualifier of the first run is THIS; the qualifier of the second run is THAT.
APPL TESTQUAL JCLLIB CYB.TESTJOBS.CNTL JOB A.THIS RUN ANY RELEASE A.THAT ENDJOB JOB A.THAT RUN ANY ENDJOB
193
Identifying a job as Onrequest
With Applications, you can identify certain jobs as on-request and define their relationships to other jobs. The on-request jobs take their place in the schedule when they are selected. From the time you generate the Application up to the time of job submission, you can use CSF or the APPLJOB command to request the job. If you have not explicitly requested the job, ESP bypasses it and treats it as a normal completion, releasing its successor jobs. To mark a job 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 only making it eligible for explicit request via CSF or the APPLJOB command. You must first generate the Application before you can request any of the Applications jobs. To allow users to request jobs, you may want to generate the Application containing these jobs early in the morning and use submit time dependencies (i.e. DELAYSUB statements) on the jobs with no predecessors so they are not submitted at the time ESP generates the Application.
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 Users Guide.
194
Example
In the following example, if job J2 is not requested at the time it is scheduled for submission, ESP bypasses it and submits job J3.
The Application looks like this:

APPL APPL1 JCLLIB... JOB J1 RUN DAILY RELEASE J2 ENDJOB JOB J2 REQUEST RELEASE J3 RUN DAILY ENDJOB JOB J3 RUN DAILY ENDJOB
Requesting the job
To request the job, use the RQ command from the Consolidated Status Facility, or use the APPLJOB (abbreviated AJ) Command. The following example shows requesting job J2 in the current generation of APPL1, with the abbreviated APPLJOB command:
AJ J2 REQUEST APPL(APPL1.0)
195
Defining critical jobs
Use the CRITICAL keyword on the JOB statement to identify a critical job In your 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 using CSF or the LISTAPPL command. The following statement defines Job XYZ as critical.
JOB XYZ CRITICAL
For information on critical path analysis, see Using Critical Path Analysis on page 241.
Defining held jobs
Use the HOLD keyword on the JOB statement to identify a job that you want to hold from submission until you release it. This places the job on manual hold when ESP generates the Application. You can display jobs that are on manual hold using CSF or the LISTAPPL command. The following statement defines Job ABC on hold.
JOB ABC HOLD
It is not a common practice to define jobs on hold. If a job needs to wait for a manual process, it is better to use a task in the Application as a predecessor. For information on using tasks, see Using Tasks on page 227.
Defining conditional jobs
Normally, all jobs in an Application must complete, or be bypassed, in order for the Application to complete. In some situations, you could have some optional jobs (other than on-request jobs) which may or may not run as part of the Application. These jobs are referred to as conditional jobs. ESP completes an Application when all non-conditional jobs are complete and bypasses any incomplete conditional jobs. For example, you might have a recovery job that only runs when another job in the Application abends. In this case, the recovery job is a conditional job. The recovery job may or may not run. If all other jobs in the Application are complete then you want ESP to complete the Application.
196
Conditional Job
Use the CONDITIONAL keyword on the JOB statement to identify a job that may or may not run as part of an Application. The following statement defines Job RECOVER as a conditional job.
JOB RECOVER CONDITIONAL
For examples of using conditional jobs, see Advanced Users Guide.
Scope of a JOB statement
The scope of a JOB statement includes all statements up to an ENDJOB statement or the next JOB statement. ESP processes commands based on where they are placed, as follows: ESP processes commands outside the scope of JOB statements when the Application is generated and every time a job becomes eligible (i.e. all dependencies met). ESP processes commands within the scope of a JOB statement only when the job becomes eligible (i.e. all dependencies met).
Example: Sending messages at different stages
The following Application contains three SEND commands. ESP sends the following messages at the following points: MESSAGE1, when ESP generates the Application and each time it submits a job in the Application. MESSAGE2, when ESP submits job A. MESSAGE3, when ESP submits job B.

APPL ABC JCLLIB . . . SEND MESSAGE1 U(*) JOB A SEND MESSAGE2 U(*) RUN DAILY RELEASE B ENDJOB JOB B SEND MESSAGE3 U(*) RUN DAILY ENDJOB
197
198
Defining Job Requirements
Introduction
Once you name a job, you can use different statements to define the jobs requirements. These requirements generally fall into the following three areas:
Dependency
Timing
Selection
199
Specifying Time Dependencies
Types of time dependencies
A job can have different types of time dependencies. These include the following: Delayed, or early, submission time Late submission time Due-out times for different stages in processing Cut-off time for submission Cut-off time for job dependencies Cut-off time for resources. You can refer to different times to compensate for varying conditions using CLANG.
Delaying submission of a job
Use the EARLYSUB (early submit time) or DELAYSUB (delayed submit time) statements to mark a job for delayed submission relative to the scheduled time of the Event. Both statements achieve the same results. Since you can specify any valid schedule criteria that resolves to a single date and time when the Application builds, you can use the EARLYSUB (or DELAYSUB) statement to allow an Application to span many days or weeks.
Example: Identifying a delayed submission time
This example specifies that job J2 should not be submitted prior to 9 p.m.:
JOB J2 DELAYSUB 9PM
Example: Using different submission times
This example uses CLANG to specify different DELAYSUB times for a job. The second DELAYSUB statement overrides the first on weekends only. The different times are: 9 p.m. on weekdays 5 p.m. on weekends.
JOB J2 RUN DAILY DELAYSUB 9PM IF TODAY(WEEKEND) THEN DELAYSUB 5PM Continued on next page
200
Specifying Time Dependencies, Continued
Delaying the Release of a job
You can also use the RELDELAY statement to delay job submission at the time a job becomes eligible (i.e. ready). This statement uses minutes as its unit of measure. You can delay submission up to 255 minutes.
Example: Delaying submission of a job from Ready time
This example delays submission of job J2 by 5 minutes when it becomes ready for submission.
JOB J2 RELDELAY 5
Introducing Anticipated End Times
When ESP generates an Application, it calculates anticipated end times for all jobs in the Application. ESP adjusts anticipated end times automatically as the Application processes; for example, when a job is submitted or a job ends. This allows you to review the Application, at any stage, and determine when any job is expected to finish. This information is displayed to you whenever you list the Application (e.g. LISTAPPL command).
Introducing Dueout Times
If a job is not complete by its anticipated end time, ESP continues to adjust this time. There is no indication that a job has missed its original anticipated end time. If you need to provide some awareness when jobs are late, you can identify any of the following: A late submission time A late start time A late end time.
If the job has not completed the specified stage in processing by the due-out time, the status field shows OVERDUE in the Consolidated Status Facility (CSF) display of the job. ESP can also send a message or trigger an Event when a job becomes overdue by using a NOTIFY statement. For more information, refer to Providing Notification on Job Status later in this chapter. ESP also provides critical path analysis. For information on using critical path, refer to the Using Critical Path Analysis on page 241.
201
Specifying dueout times
You can use any of the following statements to identify dueout times for a job: Statement LATESUB Explanation Specifies a late submission for a job. This identifies a time by which ESP should submit a job. The LATESUB time for a link, task or data set trigger object represents the time by which all of its predecessor and time dependencies should be met (i.e. the READY time). LATESUB does not force, or bypass, submission of the job. Use the ABANDON DEPENDENCIES statement to force submission of the job, regardless of dependencies; use the ABANDON SUBMISSION statement to bypass submission of the job. Specifies a due-out time from the INPUT processing node. This refers to the start time. Specifies a due-out time from the EXEC processing node. This refers to the successful end time. For a link, task, or data set trigger object, this represents the time by which it should complete.
DUEOUT INPUT DUEOUT EXEC
Statements for different job types
The following table indicates the statements you can use for different job types. For more information on job types, refer to Using Different Job Types on page 213. Job Type Job External Job Manual Job Link Task Data set Trigger Object LATESUB X X X X X X DUEOUT INPUT X X X DUEOUT EXEC X X X X X X
202
Example: Specifying a late submission time for a job
In the following example, Job X has a late submission time of 9 p.m.

JOB X LATESUB 9PM
Example: Specifying a due-out time for 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 a due-out time for a task
This example specifies that the task called WAIT4.TAPE should be marked complete no later than two hours after the trigger time of the corresponding Event.
JOB WAIT4.TAPE TASK DUEOUT EXEC REALNOW PLUS 2 HOURS
Propagating dueout times
ESP propagates dueout times, up-stream, to all predecessors of a selected job where you specified a LATESUB or DUEOUT statement. This reduces the need for you to code a lot of LATESUB or DUEOUT statements in an Application. ESP sets these dueout times based on historical average elapsed times. When ESP propagates a time to a predecessor, it sets the DUEOUT EXEC time and adjusts this time if it is already specified. ESP provides notification when this time is not met, just as it does when you specifically code a DUEOUT time. If you need to reset the time, you can use CSF or the APPLJOB command. Note: Your system administrator may have turned this propagation feature off.
203
Example: Propagating dueout times
In the following example, PAYJOB6 should be submitted by 7am.

PAYJOB1
PAYJOB2
PAYJOB3
PAYJOB4
PAYJOB5
PAYJOB6
By specifying a LATESUB time for PAYJOB6, ESP automatically sets dueout execution times for all predecessors to this job. If any job in the PAYROLL Application is late, ESP highlights it on CSF. Further notification can take place using the NOTIFY statement. A sample Application is:
APPL PAYROLL JCLLIB CYBER.JCL.CNTL JOB PAYJOB1 RELEASE PAYJOB2 JOB PAYJOB2 RELEASE (PAYJOB3,PAYJOB4,PAYJOB5) JOB PAYJOB3 RELEASE PAYJOB6 JOB PAYJOB4 RELEASE PAYJOB6 JOB PAYJOB5 RELEASE PAYJOB6 JOB PAYJOB6 LATESUB 7AM ENDJOB SELECT (PAYJOB1,PAYJOB2,PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)
204
Bypassing job dependencies
Use the ABANDON DEPENDENCIES job statement to drop a jobs predecessor dependencies once it meets a specified time. This does not override a manual hold, a time dependency, or a resource dependency for a job. An example of this statement is:
ABANDON DEPENDENCIES 10PM
Bypassing Jobs
Use the ABANDON SUBMISSION job statement to bypass a job after a specified time. An example of this statement is:
ABANDON SUBMISSION 11PM
Example: Bypassing jobs and dependencies
The following example submits Job J2 when Job J1 completes successfully, or at 10 p.m., whichever comes first. When J2 completes successfully, ESP checks that the time is before 11 p.m. If it is, ESP submits Job J3; otherwise, it bypasses J3 and submits Job J4.
APPL APPL3 JCLLIB... JOB J1 RUN DAILY RELEASE J2 JOB J2 RUN DAILY ABANDON DEPENDENCIES 10PM RELEASE J3 JOB J3 RUN DAILY ABANDON SUBMISSION 11PM RELEASE J4 ENDJOB JOB J4 RUN DAILY ENDJOB
205
Example: Bypassing a job and wait for predecessor
Jobs A, B and C are 3 sequential, daily jobs. Job B has a submission time of 9 a.m. If job B is not submitted within an hour (10 a.m.), then job B should not run but job C should wait for job A to complete. The following part of an Application identifies a delayed submission time of 9 a.m., and an abandon submission time of 10 a.m. for job B. Job Bs execution is abandoned if it is not submitted by 10 a.m. Job B is not actually bypassed until job A completes successfully and job C waits until this happens.
JOB A RUN DAILY RELEASE B JOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AM JOB C RUN DAILY ENDJOB
206
Example: Bypassing a job without waiting for predecessor
Jobs A, B and C are 3 sequential, daily jobs. Job B has a submission time of 9 a.m. If job B has not been submitted within an hour (10 a.m.), job C should start (even if job A is running) and job B should not run. The following part of an Application identifies a delayed submission time of 9 a.m. and an abandon submission time of 10AM for job B. Job B waits for job A to complete successfully prior to being bypassed. By coding an abandon dependencies time of just after 10 a.m., job B does not wait for job A to complete before it is bypassed and job C starts.
JOB A RUN DAILY RELEASE B JOB B RUN DAILY RELEASE C DELAYSUB 9AM ABANDON SUBMISSION 10AM ABANDON DEPENDENCIES 10:01AM JOB C RUN DAILY ENDJOB
Removing resource dependencies
Use the ABANDON RESOURCES job statement to submit a job without its resource dependencies, once it meets a specified time. An example of this statement is:
ABANDON RESOURCES 8AM
This example indicates ESP should not wait for resources for the job after 6 p.m.
JOB PREPJOB RESOURCE (1,NITESHFT) ABANDON RESOURCES 6PM
207
Specifying Job Relationships
Introduction
To specify predecessor and successor job relationships, include the appropriate job dependency parameters. A list of job dependency parameters appears below: Job Dependency Parameter AFTER Explanation
RELEASE PREREQ
COREQ
POSTREQ
Specifies any job that is a predecessor to this job and should indicate a release to this job upon its completion. (The default is successful completion). Specifies successors to a job that are released upon its completion. (The default is successful completion). Specifies the names of any other jobs that must be complete before this job can be allowed to execute. These are prerequisite jobs. ESP automatically selects the prerequisite jobs for submission whenever this job is selected for processing. Specifies the names of any other jobs which must be selected automatically whenever this job is selected for processing. The named job and all of its co-requisites are allowed to execute simultaneously; there is no relationship between a job and its co-requisites. Specifies the names of any other jobs which must run after this job has executed. These are post-requisite jobs. ESP automatically selects the post-requisite jobs for submission whenever this job is selected for processing.
208
Specifying Job Relationships, Continued
Specifying Multiple jobs
If you need to specify more than one jobname, enclose the jobnames in parenthesis. For example:
RELEASE (PAYJOB2,PAYJOB3,PAYJOB4)
If you need to continue to another line, use either a + or a - as a line continuation character. For example:
RELEASE (PAYJOB2,PAYJOB3,PAYJOB4,PAYJOB5,PAYJOB6)
Two methods of coding a job dependency relationship
The following are two ways of coding a job dependency relationship. With either method, there is no difference in the way ESP generates or processes the Application. Method 1 2 Code
JOB A RELEASE B JOB B AFTER A
209
Selecting Jobs for Submission
Selecting a job for 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 same Application. This Guide contains more information on the schedule frequencies you can use.
Examplemethod 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 each time the Procedure is invoked; ESP selects job B if the scheduled day is Friday.
JOB A RUN DAILY RELEASE B JOB B RUN FRIDAY ENDJOB
Examplemethod 2
This method uses SELECT statements after identifying specific job requirements. ESP selects job A each time the Procedure is invoked; ESP selects job B if the scheduled day is Friday.
JOB A RELEASE B JOB B ENDJOB SELECT A IF TODAY(FRIDAY) THEN SELECT B
Submit time
If a job has a time dependency for submission, you must use either an EARLYSUB or a DELAYSUB statement. The statement RUN 5PM DAILY is not valid.
210
Selecting Jobs for Submission, Continued
Using SELECT vs. RUN statements
Some users prefer to use RUN statements; other users prefer SELECT statements. The following are some reasons for choosing either method: RUN statements are used within the scope of a JOB statement. This allows you 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 for using IF TODAY type logic. SELECT statements allow you to easily see all the jobs with the same criteria. Changing the criteria for these jobs requires a change to a single SELECT statement. You can also select a subApplication.
Deselecting jobs
Use the NORUN and DESELECT statements to handle exceptions to a jobs regular schedule criteria. These statements tell ESP when not to select a job. ESP allows multiple RUN and NORUN statements for the same job. You should normally code your NORUN statements after your RUN statements. If you specify a job with a NORUN statement and without a RUN statement, ESP schedules the job each time the Event executes except when it manages to satisfy the NORUN schedule criteria.
Example 1
In the following example Job X runs daily except on the first Monday of the month.
JOB X RUN DAILY NORUN FIRST MONDAY OF MONTH ENDJOB
Example 2
This example uses a DESELECT statement to achieve the same results.

SELECT X IF TODAY(FIRST MONDAY OF MONTH) THEN DESELECT X
Inheriting job relationships
Jobs in an Application may not require the same run frequency. When ESP selects jobs for submission, it automatically checks to see if any relationships among jobs should be inherited.
211
Selecting Jobs for Submission, Continued
Example
Consider the following three jobs and their schedule frequencies.

J1 Daily
J2
Friday
J3
Daily
On Fridays all three jobs execute in order, but on any other day of the week Job J2 does not run. On these days, ESP selects Jobs J1 and J3 and inherits their relationships with job J2. When job J1 completes successfully it releases job J3.
For information on overriding the inheritance of job relationships, refer to the Advanced Users Guide.
212
Using Different Job Types
Introduction
An Application may consist of different types of jobs. You can define the following job types in an Application by using different keywords on a JOB statement or different job-like statements. Type Job External job Manual job Link Task Dataset Trigger Object Description JCL submitted by ESP (default) JCL submitted by another Application JCL submitted outside an ESP Application Task that does not require manual completion Task that requires manual completion Object that completes based on data set trigger activity Identification Blank EXTERNAL keyword MANUAL keyword LINK keyword TASK keyword DSTRIG statement
The next few sections describe the job types other than Job. You can also define non-MVS workload, such as Unix scripts, in your ESP Application. For information on defining this type of workload, refer to the ESP Agents for UNIX Operating Systems, User Guide.
213
Defining External Jobs
EXTERNAL keyword
Use the EXTERNAL keyword as part of a JOB statement to identify to ESP that the job is part of another Application. This allows you to establish relationships between jobs in different Applications. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied. The Application that submits the job is known as the home Application. The Application where the job is defined as External is known as the distant Application. When you define an External job: You can use different frequencies in the home and distant Application You must use the same qualifier in each Application. You can use the LAX command in Page mode to display External jobs in active Applications.
Example: InterApplication dependency
In this example, ESP submits Job X on Fridays, as part of Application APPL1. Job Z in the Application APPL2 waits for Job X. The home Application for Job X is APPL1; the distant Application for Job X is APPL2. Visually, the dependencies look like this:
APPL1 A
(job)
APPL2 X
(External job)
X
(job)
Z
(job)
214
Defining External Jobs, Continued
The Application definition for APPL1 looks like this:

APPL APPL1 JCLLIB.... JOB A RUN DAILY RELEASE X ENDJOB JOB X RUN FRIDAY ENDJOB
The Application definition for APPL2 looks like this:

APPL APPL2 JCLLIB.... JOB X EXTERNAL RUN FRIDAY RELEASE Z ENDJOB JOB Z RUN DAILY ENDJOB
When ESP generates APPL2 on Fridays, job Z waits until job X completes in its home Application, APPL1.
Controlling External jobs
Under different situations, ESP must decide whether or not it should mark an EXTERNAL job complete. The following are some general rules ESP uses: A job defined as EXTERNAL in an Application is normally marked complete by ESP if the job is run manually. If more than one generation of an Application is active when an External job ends, ESP posts the job as complete in all active Applications.
Some of the ways you can control the posting complete of External jobs are described below.
215
Specifying an Application
When you define an External job, you can use the APPLID parameter to specify the name of the Application that submits the job. ESP does not mark the External job complete unless it was submitted by the Application specified. For example, ESP only marks the following job as complete when the job is submitted from the Application called ANOTHER.
JOB ABC EXTERNAL APPLID(ANOTHER)
SCHEDULED parameter
You can specify a SCHEDULED parameter on a JOB statement to reflect when an External job is scheduled. The Application containing the External does not have to be active when the job in the home Application ends. ESP automatically looks back to see if the dependency has been satisfied. The job in the example below only gets marked complete when run from another Application with the same scheduled date. This provides synchronization of Applications. Refer to the Advanced Users Guide for more information.
JOB ABC EXTERNAL SCHEDULED(TODAY)
The following example shows specifying a range:

JOB ABC EXTERNAL SCHEDULED(NOW LESS 2 HOURS ENDING NOW PLUS 2 HOURS)
Job qualifiers
In order for ESP to mark an External job complete, the job qualifier must match what was defined in the home Application. You can use job qualifiers to ensure that an External job does not get marked complete when it is run manually. You might want to qualify External jobs with the home Application name. For example:
JOB ABC.BILLING EXTERNAL
Authorization string
You can specify that ESP checks an authorization string for External jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a userid or an account field. For example, ESP only marks the following job as complete when the job is run with an authorization string of CYBER.
JOB ABC EXTERNAL AUTHSTR(CYBER)
216
Posting options
Different posting options are available on the APPL statement. For example, you can select different options to control the posting of External jobs when multiple generations of an Application are active. Refer to the Advanced Users Guide for more information.
Forced complete
When an External job is forced complete in a distant application, this will have no effect on the status of the same job in any other distant application, or in the jobs home application. When an External job is forced complete in its home application, this change will be transmitted to every distant application in which the job is defined as external.
USERMOD 30
Prior to release 5.1.0, if a job defined as EXTERNAL in an Application is forced complete in the home Application, the job in the remote Application (where it is EXTERNAL) is marked complete only if the job in the home Application has actually been submitted. With release 5.1.0 and 5.2.0, the remote Application job is now marked complete even if the home Application job was forced complete prior to submission. This USERMOD disables the new functionality, for those users who rely on the previous behavior.
217
Defining Manual Jobs
MANUAL keyword
Use the MANUAL keyword as part of a JOB statement to identify to ESP that a job is submitted outside of an ESP Application. As a result, ESP does not look for JCL, nor does it try to submit the job. The job may be submitted by a person, an operator command, an Event, or another scheduling product. You can use Manual jobs as predecessor or successor jobs within an Application. As long as the Application containing the successor is active at the time the predecessor completes successfully, the required dependency is satisfied.
Notes
When defining a MANUAL job in an Application, keep the following in mind: You must define a manual job as a tracked job if you want to use it in an Application. Check with your system administrator to find out about tracked jobs. You cannot use a job qualifier for a manual job.
Example 1
In the example below, Job ZZ runs after the manually submitted Job YY on Mondays, Wednesdays, and Fridays. On other days Job ZZ does not wait for Job YY.
JCLLIB... APPL SMALL JOB ZZ AFTER YY RUN DAILY JOB YY MANUAL RUN MON WED FRI ENDJOB
218
Defining Manual Jobs, Continued
Example
In this example, Job B is a Manual job that should not complete until Job A runs successfully. After Job A is submitted, ESP has no control over the submission time for Job B, since Job B is a manual job. However, ESP can remind someone to submit the job at the time it should be submitted. Visually, the flow of jobs looks like this:
A
MANUALLY SUBMITTED
The Application is shown below. The PROCESS keyword on the manual job causes ESP to process the SEND command when job B is eligible for submission.
JCLLIB... APPL ABC JOB A RELEASE B RUN DAILY JOB B MANUAL PROCESS SEND TIME TO SUBMIT JOB B USER(SW) RUN DAILY RELEASE C JOB C RUN DAILY ENDJOB
219
Defining Manual Jobs, Continued
Controlling Manual jobs
Under different situations, ESP must decide whether or not it should mark a MANUAL job complete. The following are some general rules ESP uses: A job defined as MANUAL in an Application is normally marked complete if the job is run as part of another Application. If more than one generation of an Application is active when a Manual job ends, ESP posts the job as complete in all active Applications.
Some of the ways you can control the posting complete of Manual jobs are described below.
Authorization string
You can specify that ESP checks an authorization string for Manual jobs so that it tracks and posts the correct job. The authorization string is the field you use at your site to identify job ownership, such as a userid or an account field. For example, ESP only marks the following job as complete when the job is run with an authorization string of CYBER.
JOB ABC MANUAL AUTHSTR(CYBER)
Posting options
Different posting options are available on the APPL statement. For example, you can select different options to control the posting of Manual jobs when multiple generations of an Application are active. Refer to the Advanced Users Guide for more information.
Forced complete
When a Manual job is forced complete in one application, this will have no effect on Manual jobs in other applications that just happen to refer to the same physical job instance. If it is desired to modify the status of a specific manually submitted job in multiple applications that define this job as Manual, the modification will have to be performed explicitly in each of the dependent applications.
220
Using Links
Using links
A link is a task that does not require manual completion. Use a link when you need to take an action (for example, issue a command or send a message) but the Application does not need to wait for you to notify ESP that the action has been completed. A link can also be used as a dependency node to simplify complex dependencies.
LINK keyword
The LINK keyword on the JOB statement identifies a link. ESP does not try and submit JCL for it. You define relationships and other dependencies for a link the same way you do for a job that ESP would submit. A link usually has a schedule frequency and it can have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application. If you want to use a link to process commands, you must specify LINK PROCESS, as shown in the next example.
Example
In the following example, a link is used to send a message to user BP01 after MYJOB1 and MYJOB2 complete successfully.
JOB LETME.KNOW LINK PROCESS AFTER (MYJOB1,MYJOB2) RUN DAILY SEND MYJOBS ARE DONE USER(BP01) ENDJOB
Link vs task
A link is the same as a task, except that ESP automatically marks a link as complete as soon as its dependencies are met, while a task requires an action. Note: A link cannot have a resource dependency. If this is a requirement, you need to use a self-completing task.
221
Using Links, Continued
Example: Simplifying job relationships
You have an Application that contains two groups of three jobs. The second group of jobs cannot run until all jobs in the first group have completed.
To create this dependency configuration without using a link means that dependencies must be created from all three jobs in the first group to all three jobs in the second group. While ESP can create an Application that includes many inter-linked dependencies like this, the Application may be hard to read and maintain. Visually, you need to define the dependencies like this:
222
Solution
A better approach is to create a link that represents the completion of the first three jobs, and releases the second group of three jobs. This simplifies the definition of job relationships and makes it easier to add or delete jobs in each group. Visually, the dependencies look like this:
A B C
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 a command
This example uses a link to start some initiators.

JOB OPEN.INITS LINK PROCESS VS $SI1-10 RUN DAILY ENDJOB
223
Example: Keeping an Application active
This example uses a link called KEEPOPEN to keep an Application active until 23:59. This technique is useful when you need an Application active to insert on-request jobs.
JOB KEEPOPEN LINK DELAYSUB 23:59 RUN DAILY ENDJOB
Example: Notification when an Application completes
This example sends a message at the end of an Application. The message includes the following symbolic variables: %ESPAPPL - Represents the name of the Application %ESPATIME - Represents the actual time the Application completes
JOB ENDAPPL LINK PROCESS AFTER LASTJOB RUN DAILY SEND %ESPAPPL HAS COMPLETED at %ESPATIME USER(BP01) ENDJOB
For detailed information on symbolic variables, refer to the Advanced Users Guide.
224
Example: Starting a task, taking action after completion
You may have a started task that you wish ESP to start, monitor, and then run a job when it comes down. This example shows how you can set up these dependencies. Visually the dependencies look like this:
START.STC1
(Link)
STC1
(Manual)
BATCHJOB
(Job)
Setting-up this Application
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.
225
Application

APPL MYAPPL JCLLIB SYS1.JCL JOB START.STC1 LINK PROCESS RUN DAILY VS S STC1 ENDJOB JOB STC1 MANUAL RUN DAILY RELEASE BATCHJOB ENDJOB JOB BATCHJOB RUN DAILY ENDJOB
226
Using Tasks
Identifying Tasks
You can define tasks in an Application and establish dependencies between them and other tasks and jobs. A task may represent a manual process such as balancing a report, or an automated process such as a step in a job completing. You identify a task using the TASK keyword on a JOB statement. ESP does not try and submit JCL for it. You define relationships and other dependencies for a task the same way you do for a job that ESP would submit. A task usually has a schedule frequency and may have a time dependency. It can be on-request, conditional, defined on hold, and can be inserted into an active Application. When you mark a job as a TASK and select it for execution, ESP builds it as part of the Application. The AJ command, or the C command from CSF, can be used to mark a task complete.
Example: Checking a report
In this example, a report needs to be checked on workdays after Job J1 completes successfully. Visually, the dependencies look like this:
J1
(Job)
CHECKRPT.J
(Task)
J2
(Job)
227
Using Tasks, Continued
Identifying
CHECKRPT.J
as a TASK
The following Application identifies CHECKRPT.J1 as a TASK. When J1 completes successfully on a workday, ESP issues the SEND command to user BP01, indicating the actions to be taken. ESP submits Job J2 only when CHECKRPT.J1 is marked complete. On non-workdays, J2 inherits the relationship with J1, and ESP submits J2 after J1 completes successfully.
JCLLIB CYBB.JOBS.CNTL APPL ABC WAIT JOB J1 RUN DAILY RELEASE CHECKRPT.J ENDJOB JOB CHECKRPT.J TASK RUN WORKDAYS SEND JOB J1 HAS COMPLETED SUCCESSFULLY USER(BP01) SEND COMPLETE THE CHECKRPT.J TASK USER(BP01) RELEASE J2 ENDJOB JOB J2 RUN DAILY ENDJOB
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 Users Guide.
228
Changing Job Attributes
Introduction
In ESP, you can define a job with a number of different attributes using different keywords on the JOB statement. Some examples of attributes are CRITICAL, 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 job has different attributes based on schedule criteria.
Defining a job with different attributes
To define a job with different attributes, use the JOBATTR statement. This statement lets you change any attributes of a job within the scope of the JOB statement or in job documentation. Attributes include the keywords you can use on the JOB statement.
Example Changing a job attribute
In the following example, Job ABC runs daily. On December 9, 1998, it needs to be defined on hold.
JOB ABC RUN DAILY IF TODAY(DEC9,1998) THEN JOBATTR HOLD ENDJOB
For more examples of changing job attributes, refer to the Advanced Users Guide.
229
Using Data Set Trigger Workload Objects
Introduction
You can use ESPs data set triggering facility at the Event level or at the job level. This section describes how to use this facility at the job level. For information on using data set triggering at the Event level, refer to Processing ESP Events on page 61.
Data set trigger workload object
You can define a data set trigger workload object as part of an ESP Application. This allows you to set up data set dependencies at the job level. A data set trigger workload object can be completed by the successful creation, closure, or renaming of a data set by another job, by a started task, or by a TSO user. This activity can be restricted to data sets created by a specific job or group of jobnames.
The next sections describe how to set up data set trigger objects. For more examples using these objects, and for other techniques on handling data set dependencies, refer to the Advanced Users Guide.
Preparing to use data set trigger objects
In order to use a data set trigger object, the Systems Programmer responsible for ESP must add a Workload Object Module (WOBDEF) statement to the ESP Initialization Parameters (i.e. WOBDEF LOAD CYBESODT).
230
Using Data Set Trigger Workload Objects, Continued
Setting-up data set trigger objects
To set up a data set trigger object in an Application: Step 1 Action Use the DSTRIG statement to assign a name to the data set trigger workload object. You can use some of the same keywords you use on a JOB statement. These include REQUEST, HOLD and CONDITIONAL. Use the DSNAME statement to identify the name of the data set. Quotation marks are optional. You can use a hyphen at the end of the data set name as a wildcard and you can use keywords such as COUNT, ANYCLOSE, JOBNAME, and RENAME to handle different requirements. Only one DSNAME statement is supported per workload object. Use a RUN or SELECT statement to identify when you want this object to build as part of the Application. Use other statements, such as DELAYSUB, DUEOUT, RELEASE, etc. to identify other requirements.
3 4
Example: Waiting for a data set creation
In this example: The DSTRIG statement identifies a data set trigger object called BIGFILE. The DSNAME statement identifies PROD.CICS.FILE1602 as the data set. Because no other parameters are specified, ESP waits for this data set to be created. The frequency is DAILY. The successor job is ABCJOB.
DSTRIG BIGFILE DSNAME PROD.FILE.CICS1602 RUN DAILY RELEASE ABCJOB ENDJOB
Once the Application containing this object is active, ESP watches for the PROD.CICS.FILE1602 data set to be created. When it is created, the BIGFILE object completes and releases the successor job ABCJOB.
231
Visual perspective
Visually, the flow looks like this:

PROD.CICS.FILE1602
(data set)
ABCJOB
(Job)
Waiting for any closure of a data 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 existing data set. If you do not specify ANYCLOSE, ESP waits for the data set to be created.
Example
The following example uses a data set trigger workload object (WAIT4.DS) to build a dependency between any closure of a data set (PROD.WEEKLY.ACCNTS) and a job (PAYJOB1).
APPL PAYROLL JCLLIB CYB.JCL.CNTL DSTRIG WAIT4.DS DSNAME PROD.WEEKLY.ACCNTS ANYCLOSE RUN DAILY RELEASE PAYJOB1 JOB PAYJOB1 RUN DAILY ENDJOB
Limiting data set activity to a job
You can restrict the trigger to only specific data sets created by a particular job. Use the JOB keyword followed by the full name or jobname prefix of the job.
Example: Job specific creation
The following example indicates a data set trigger occurs when job ABC creates a generation of the data set USER1.PAYROLL.
DSTRIG USERDATA DSNAME USER1.PAYROLL.G- JOB(ABC)
232
Waiting on multiple data sets
To set up a dependency on multiple data sets, you need to use a separate data set trigger object for each.
Example: Waiting on more than one data set
In this example, job XYZ waits for two data set trigger objects, FILEA and FILEB. FILEA completes when CYBER.DATA111.CNTL closes. FILEB completes when CYBER.DATA999.CNTL closes.
APPL PAYROLL JCLLIB CYB.JCL.CNTL DSTRIG FILEA DSNAME CYBER.DATA111.CNTL ANYCLOSE RUN DAILY RELEASE XYZ DSTRIG FILEB DSNAME CYBER.DATA999.CNTL ANYCLOSE RUN DAILY RELEASE XYZ JOB XYZ RUN DAILY ENDJOB
Waiting on multiple closures of the same data set
It is possible for a data set to be closed several times. You can use the COUNT keyword to specify how often this closure is required before the data set trigger object completes. The count begins when the data set trigger object becomes ready (i.e. any time and predecessor dependencies have been met). The CSF STATUS field displays the counter and its current value once the data set trigger object becomes ready. With each closure, ESP increases its internal counter by one. When the counter reaches the number you set in your COUNT keyword, ESP completes the data set trigger object. The next time the Application gets generated, the count is set to zero.
233
Example: Waiting on multiple closures of a data set
In the following example, the data set trigger object completes after two creations of a data set:
DSTRIG DOUBLE.INPUT DSNAME SITE1.BILLING.FILE COUNT(2)
Controlling data set trigger objects
A data set trigger object must be ready before ESP looks for the activity specified on the DSNAME statement. It is possible for a data set trigger object 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 take against it is complete it.
Example: Data In the following example, the data set trigger object INPUT.DATA has a set trigger has a delayed submission time of 6 p.m. If the CYBER.BILLING data set is created dependency prior to this time, the data set trigger object does not complete. At 6 p.m., ESP
sends a message to BOB indicating it is waiting for some data.

DSTRIG INPUT.DATA DSNAME CYBER.BILLING RUN DAILY DELAYSUB 6PM SEND WAITING FOR INPUT DATA NOW U(BOB) RELEASE BILLJOB1 ENDJOB
234
Displaying data set triggering information
While DSTRIG workload objects are active, you can use the LDXE command to display them. The LDXE command differentiates between Event level and Application level data set triggers. The following is an example of the output produced by the LDXE command, where: Application PAYROLL.1 contains a job level data set trigger called WAIT4.DS. It is waiting for a data set closure on a data set called CYBER.PAYROLL.DATA1. Event CYBER.CYCLES is waiting for data set USER.INPUT.CYCLE to be created.
LDXE EVENT/APPL (WOB)-------DATASET PAYROLL.1 (WAIT4.DS) CYBER.PAYROLL.DATA1, ANYCLOSE CYBER.CYCLES USER.INPUT.CYCLE 2 ENTRIES DISPLAYED
235
Tagging Jobs
TAG statement
You can use the TAG statement to tag jobs in an Application with a character string up to 16 characters in length. The tag can apply to all jobs in an Application or to individual jobs depending on where you place it. You may 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 jobs with the scheduled day of week
The following example uses a symbolic variable to tag all jobs in an Application with the 3-character day of the week:
TAG %ESPSDAY(1:3) APPL BILLING
Example: Tagging high priority jobs
This example tags PAYJOB as a high priority job:

JOB PAYJOB TAG HIGH_PRIORITY
Example: Tagging jobs with Application name
This example uses the TAG statement to specify the name of the Application that submits the job. This is useful when you have an Application containing External jobs. Construct the Application like this: Use a global TAG statement to identify the name of the Application Use a job-specific TAG statement for each External job to specify the name of the Application submitting each External job.
236
Tagging Jobs, Continued
Sample Application
A sample Application looks like this:

APPL PAYROLL JCLLIB . . . TAG PAYROLL JOB A RUN DAILY RELEASE B JOB B RUN DAILY RELEASE C JOB C RUN DAILY AFTER X JOB X EXTERNAL TAG BILLING RUN DAILY ENDJOB
237
Providing Notification on Job Status
Introduction
You can use the NOTIFY statement within an Application to keep yourself or other users informed about the progress of jobs in an ESP Application. The NOTIFY statement can inform you when: A job is submitted A job starts A job becomes overdue from different processing points A job 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 External jobs, Manual jobs, data set trigger objects, links, and tasks are overdue. This is based on the LATESUB and DUEOUT statements.
Example: Notification on submit and abend
For example, suppose that you know that a programmer has modified the JCL for Job D and you want to find out: When ESP 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 DAILY ENDJOB
Example: Overdue notification
This example notifies user USER02 when job LONGJOB becomes overdue. ESP sends a message to USER02 if LONGJOB does not complete execution successfully by 5 a.m.
JOB LONGJOB NOTIFY OVERDUE USER(USER02) DUEOUT EXEC 5AM RUN DAILY ENDJOB
238
239
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 Monitoring and Alert Processing, in the Advanced Users Guide.
240
Using Critical Path Analysis
Introduction
Critical path analysis, combined with the ability to set time dependencies and trigger Events automatically, provides the framework for advanced due out notification when mission critical workload does not complete within the designated time frame or window. ESP allows you to identify a job within an Application that represents a critical point of that Application. The longest path to that job, based on historical execution time, is a critical path.
Example of a critical path
In the following diagram, job Z is identified as the critical point in an Application. The longest path to job Z, based on historical execution time, represents the critical path. If all jobs are selected, the critical path consists of jobs A, B, X, Y and Z.
A B
10 Mins
15 Mins
15 Mins
E F
X Y
10 Mins
60 Mins
C D
30 Mins
20 Mins
30 Mins
15 Mins
CRITICAL
241
Using Critical Path Analysis, Continued
Example of a critical path (Cont'd.)
ESP determines the critical path when it generates an Application. The critical path for an Application may vary depending on which jobs are selected. Based on the previous example, the critical path may vary as follows: Jobs Not Selected X, Y X, Z X,Y, D Z Critical Path A, B, C, D, Z A, B, C, D A, B, E, F, Z and A, B, C, Z A, B, X, Y - defaults to longest path
Preparing to use critical path
Prior to using critical path, check with your system administrator to ensure the critical path feature is enabled. Through the CRITPATH ESP Initialization Parameter or command, an installation can disable critical path analysis for all Applications, enable critical path analysis for selected Applications, or turn on critical path analysis for all Applications. To use the critical path feature: Step 1 2 Action Turn on critical path analysis for an Application. Identify one or more critical jobs.
Turning On/Off critical path for an Application
To turn on critical path analysis for an Application, use the CRITPATH ON statement as a global statement before your job definitions. For example,
APPL BILLING JCLLIB CYBER.JCL CRITPATH ON JOB A . . .
242
Critical path analysis for all Applications
Some installations may turn on critical path analysis for all Applications using an ESP Initialization Parameter or command. If critical path analysis is on for all Applications: You do not need the CRITPATH ON statement to use critical path analysis for an Application. You must use the CRITPATH OFF statement as a global statement, to turn off critical path analysis for an Application.
Identifying critical jobs
Use the CRITICAL keyword on a job that represents a critical point in the Application, as follows:
JOB Z CRITICAL
If critical path analysis is turned on for an Application, but no selected jobs are coded with the CRITICAL keyword, ESP calculates the path to the job that will finish last and identifies that path as the critical path.
External jobs on critical path
Jobs defined as External jobs in an Application may be part of the critical path. However, if those external jobs have predecessors, the predecessors in the home Application are not defined as part of the critical path.
243
Multiple critical paths
An Application may have more than one critical path. In the following diagram, four jobs (represented by grayed boxes) are critical jobs. The longest paths to each of these jobs, based on historical execution time, are identified as critical paths.
A B C D E F
J K L M
Overriding elapsed 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 run longer than normal. Or maybe there is no historical information for a job on the critical path, because this is the first run of the job. In these situations, you can override historical elapsed time defaults using the DURATION statement to specify an estimated duration for the job. The following example sets the elapsed time estimate for job A to 120 (minutes) on the last day of the month:
JOB A RUN WORKDAYS IF TODAY(LAST DAY OF MONTH) THEN DURATION 120 ENDJOB
244
Displaying the critical path
After ESP generates an Application, you can display the critical path using CSF freeform filtering or the List Application (LAP) command.
Using the consolidated status facility
You can use CSFs freeform filtering feature to filter jobs in an Application that are on the critical path, or not on the critical path. The following freeform filter results in a display of all critical path jobs in the PAYROLL Application.
CRITICAL_PATH AND APPL EQ PAYROLL
For more information on freeform filtering, refer to the Consolidated Status Facility on page 258.
Using the list Application command
The LISTAPPL (LAP) command displays information about your Application. All jobs on the critical path are identified with a label of CRITICAL PATH. Any job in the Application coded with the CRITICAL keyword is identified with a label of CRITICAL. You can limit your display to jobs on the critical path, or jobs not on the critical path. The following LAP command uses the CRITPATH keyword to display only those jobs on the critical path for the current generation of the PAYROLL Application:
LAP PAYROLL.0 ALL CRITPATH
245
Issuing ESP Commands
Introduction
As part of an Application you may want to issue ESP commands. This is useful, for example, when you want to issue commands to manipulate jobs, trigger Events, and perform displays. Use the ESP or ESPNOMSG statement in an Application to issue an ESP command. ESPNOMSG suppresses responses from the command.
Example: Triggering an Event
This example uses a link called MORE.WORK. It issues an ESP command to trigger an Event called CYB.OTHER in addition to its regular schedule. ESP suppresses the response ( i.e. EVENT TRIGGERED) from the trigger command.
JOB MORE.WORK LINK PROCESS RUN ANY ESPNOMSG TRIGGER CYB.OTHER ADD ENDJOB
Example: Creating an Event, triggering an Event
This example issues a series of ESP commands to: Define a new Event called CYB.NEW_EVENT Trigger the new Event.
JOB CREATE.EVENT LINK PROCESS RUN ANY ESP EVENT ID(CYB.NEW_EVENT) SYSTEM(ESPA) REPLACE ESP SEND THIS IS A NEW EVENT USER(CYB01) ESP ENDDEF ESP TRIGGER CYB.NEW_EVENT ENDJOB
246
Using subApplications
Introduction
An Application can consist of one or more subApplications. This is useful, for example, when you have a large Application you would like to break up into smaller, easier to manage, groups of jobs. You can display, manipulate, and report on subApplications. This lets you control a group of jobs belonging to the same subApplication by using a single command. Use CSF or the LISTAPPL (LAP) and APPLJOB (AJ) commands to display and control subApplications respectively.
Identifying a subApplication
Use the SUBAPPL statement in an Application to identify a subApplication and choose a name different from any jobname in the Application. You can use the SUBAPPL statement within the scope of a JOB statement to associate a job with a subApplication, or outside the scope of a JOB statement to apply to multiple jobs. Use the WAIT keyword if you have not used it on the APPL statement and you want a subApplication to wait on the previous generation of the subApplication.
247
Using subApplications, Continued
Example
The following example shows two subApplications defined within the Application called ACJOBS. The criteria are: Jobs in CYB1 and CYB2 belong to the subApplication called PREPJOBS. Jobs CYB3 and CYB4 belong to the subApplication called NIGHTLY. The PREPJOBS subApplication can process even if the previous PREPJOBS subApplication is not complete; the NIGHTLY subApplication must wait until the previous generation of the corresponding subApplication completes execution.
APPL ACJOBS SUBAPPL PREPJOBS JOB CYB1 RELEASE CYB3 ENDJOB JOB CYB2 RELEASE CYB3 ENDJOB SUBAPPL NIGHTLY WAIT JOB CYB3 RELEASE CYB4 ENDJOB JOB CYB4 ENDJOB SELECT (CYB1,CYB2,CYB3,CYB4)
248
Selecting a subApplication
If your jobs within a subApplication have the same frequency, you may choose to use a SELECT statement to select all jobs within a subApplication. This eliminates the need to use a RUN statement for each job or a SELECT statement that specifies the name of each job. To select a subApplication, use the SELECT statement to specify one or more subApplication names, followed by the keyword SUBAPPL. In the following example, subApplications PREPJOBS and NIGHTLY are selected.
APPL ACJOBS SUBAPPL PREPJOBS JOB CYB1 RELEASE CYB3 ENDJOB JOB CYB2 RELEASE CYB3 ENDJOB SUBAPPL NIGHTLY WAIT JOB CYB3 RELEASE CYB4 ENDJOB JOB CYB4 ENDJOB SELECT (PREPJOBS,NIGHTLY) SUBAPPL
Similarly, you can use the DESELECT statement to deselect all jobs within a subApplication.
Displaying a subApplication
Use the LS command from CSF or use the LISTAPPL (LAP) command with the SUBAPPL parameter to display subApplications. For example, the following results in a structured view of the subApplication PREPJOBS within the Application called ACJOBS.
LAP ACJOBS SUBAPPL(PREPJOBS) ALL
249
Controlling a subApplication
You can use either CSF or different keywords on the APPLJOB command to control subApplications similar to the way in which you control jobs. You can: 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 a subApplication
In the example below, ESP requests, the subApplication called REQJOBS in the Application MYAPPL. The system requests each selected job marked as REQUEST in this subApplication. This eliminates the need to request each job individually.
AJ REQJOBS REQUEST APPL(MYAPPL.0)
Note: Requesting a subApplication is not the same as selecting each job in the subApplication.
250
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 these tasks 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 page 258. For more information on Workstation, refer to the ESP Workstation Users Guide.
251
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 ALL keyword to give a structured view of an active Application or with other keywords to give a summary of active or completed Applications. You can limit the display to specific generations of an Application and to specific jobs within an Application.
Sample output
Sample output from an LAP command looks like this:

LAP PAYROLL.23 ALL APPL PAYROLL GEN 23 CREATED AT 09.54 ON MONDAY MAY 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, PREDECESSORS: PAYD003A SUCCESSORS: PAYD100A PAYD100A, HC=1 ANTICIPATED END TIME: 10.29 ON MONDAY MAY 11TH, 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, EXTERNAL PREDECESSORS: NONE SUCCESSORS: PAYD006A PAYD006A, HC=2 ANTICIPATED END TIME: 11.12 ON MONDAY MAY 11TH, PREDECESSORS: PAYD100A, ABCJOB SUCCESSORS: ENDAPPL RESOURCES: 1,CICSUP ENDAPPL, HC=1 ANTICIPATED END TIME: 11.29 ON MONDAY MAY 11TH, PREDECESSORS: PAYD006A SUCCESSORS: (NONE) ----- 1 ENTRY DISPLAYED
1998
1998
1998
1998
1998
252
Displaying an Application, Continued
Other
Other options are available on the LISTAPPL command. For example, you can display particular jobs, a previous generation of an Application, or a subApplication.
253
Controlling an Application
APPLJOB command
The APPLJOB command controls jobs, subApplications, and Applications. The short form of this command name is AJ.
Options on APPLJOB command
There are many different options available on this command. Some of these options allow you to: Insert a job Add or reset dependencies for a job Drop dependencies for a job Bypass a job Complete a job, subApplication, or Application Request a job.
Examples
Here are some examples of using the APPLJOB command with the current generation (.0) of an Application called PAYROLL.
Example: Requesting a job
This example requests MYJOB.

AJ MYJOB REQUEST APPL(PAYROLL.0)
Example: Bypassing a job
This example bypasses PAYJOB3. ESP bypasses the job at the time it would normally submit it.
AJ PAYJOB3 BYPASS APPL(PAYROLL.0)
Example: Inserting a link to add a job relationship
This example inserts a link called LINKME. It has a predecessor of PAYJOB1 and a successor of PAYJOB2, which means that PAYJOB1 must complete successfully prior to submitting PAYJOB2.
AJ LINKME INSERT PRED(PAYJOB1) SUCC(PAYJOB2) ATTRIBUTES(LINK) APPL(PAYROLL.0)
254
Controlling an Application, Continued
Example: Completing an Application
This example completes the entire Application.

AJ ALL COMPLETE APPL(PAYROLL.0)
You will likely use the Consolidated Status Facility to perform many of these tasks. More information on controlling jobs, subApplications and Applications, see the Consolidated Status Facility section, in this guide.
255
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 Application definition resides while the Application is processing. Some changes you make take effect immediately (i.e. next job submission); others do not take effect until the next time the Application is created.
Changes that take effect immediately
You can make changes to any of the following commands and statements listed below. Global changes, outside the scope of any JOB statements, apply to all subsequent submissions. Job specific changes, within the scope of a JOB statement, apply to the next submission of that job. CCFAIL, CCCHK, NOTIFY, MEMBER, DATASET COPYJCL, DOCMEM, MODEL, PNODES, MONITOR, TEMPLIB, JCLLIB, DOCLIB, ESP, VS, SEND, SUBMIT, INVOKE commands and statements.
Changes that do not take effect until next generation
You can drop dependencies and change time dependencies for an active Application through CSF. However, any of the changes listed below to the coded Application definition do not take effect until the next generation. Job relationships (AFTER, 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 or bypassing a job, use the Consolidated Status Facility, or the AJ command.
256
Invoking an ESP Application
Invoking via an ESP Event
Use an ESP Event to invoke an ESP Application. The trigger for the Event can be: A scheduled date and time A data set trigger A job monitor trigger A signal with a scheduled date and time A manual trigger.
An Event can invoke more than one ESP Procedure, but it can only process one Application per Event. Normally, you should not change an Event to invoke another Application while it is still processing an active Application.
Example: An Event invokes an ESP procedure to create an Application
The following example demonstrates how to use an Event to invoke an ESP Application. The Event below runs each weekday at 4 p.m. It invokes an ESP Procedure that defines the Application and job relationships. The Event looks like this:
EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE CYBER.ESP.PROC(PAYDAILY) ENDDEF
257
Consolidated Status Facility Overview
Introduction
The Consolidated Status Facility provides a focal point for monitoring and controlling the workload. You will see which jobs have recently executed, are currently running and are scheduled to execute. You can zoom in on any job to get greater detail, edit JCL, and restart jobs. Note: You can use CSF for jobs in an Application, but not for jobs submitted directly from an Event.
In this chapter
This chapter contains the following topics: Topic Setting up CSF Views CSF Fields Defining a View Customizing a View Updating a View Deleting a View Selecting Views Working with CSF Commands Inserting a Job Resubmitting a Job Removing Job Dependencies Resetting a Time Dependency Bypassing and Completing Jobs Adding Job Dependencies Adding a Job with a Time Dependency Adding a Job Relationship in an Application Adding a LINK Process Setting and Resetting the User Status Field Using Other Commands Extensions to CSF Freeform Filtering Specifying Boolean Operators See Page 259 260 264 265 269 270 271 272 273 276 277 278 279 280 281 282 283 284 285 286 287 288 294
258
Setting up CSF Views
Introduction
ESP may handle a large workload at your installation. Different people are interested in different aspects of this workload. One person may be interested in a particular Application, whereas someone else may only be interested in jobs that have failed regardless of the Application to which they belong.
Displaying data
Using the Consolidated Status Facility, you can display only relevant data in the format you want. You do this using views. A view is a customized way of looking at ESPs workload. Think of CSF as a kind of scoreboard where: Each row represents a workload object, such as a job, link or task Each column represents an attribute of a workload object, such as job number and status.
Example
For example, one row can represent a job. Each column represents some attribute of the job, such as the job name, Application generation number, PNODE (processing node), job number, and status. An example of what the CSF might look like is shown below. Here the CSF presents the current status of an Application:
259
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. These stages are known as PNODES. Using CSF you can filter and sort your view by PNODE, and display PNODE information. The following table describes the PNODE fields: PNODE APPLHOLD APPLWAIT BYPASSED COMPLETE EXEC EXTERNAL FAIL INPUT JANCWAIT MANHOLD MANSUB PREDWAIT READY RESWAIT SANCWAIT SUBDELAY SUBERROR SYSERROR TASK WAITING Description Application hold Application waiting on previous generation Bypassed Completed successfully Executing External job submitted by another Application Completed unsuccessfully Input queue - JES number assigned Job ancestor wait Manual hold Manual submission Predecessor wait Eligible Resource wait SubApplication ancestor wait Submission delayed Submission error System error Task requiring completion Delayed submission time
Note: The term PNODE is also used to describe the phases through which ESP tracks a job. The PNODES described here apply only to jobs in an ESP Application and do not include post-execution phases.
260
CSF Fields, Continued
SUBDELAY PNODE
The following table provides more information on what you might see in the Status field if a job is in the SUBDELAY PNODE. PNODE SUBDELAY SUBDELAY Status Submit delayed by REEXEC n Submit delayed, Eventset closed Description The submission of the job has been delayed. The Eventset in which the Event is stored is currently closed. As soon as it is opened, the Event will be scheduled. Submit Delay, DS The execution of the Event Contention was delayed due to data set contention. It will be retried at 5 minute intervals. Submit Delay, DS Offline The execution of the Event was delayed due to a data set being offline. It will be retried at 5 minute intervals. Submit Delay, DS The execution of the Event Recalled was delayed due to a data set that was in a migrated state. A recall has been requested, and the Event will be retried at 5 minute intervals.
SUBDELAY
SUBDELAY
SUBDELAY
261
SUBERROR PNODE
This table provides more information on what you might see in the Status field if a job is in the SUBERROR PNODE.
PNODE Status Description
SUBERROR
SUBERROR
SUBERROR
SUBERROR
SUBERROR
SUBERROR
SUBERROR SUBERROR
Submit Eventset I/O error An I/O error has occurred in the Eventset. The Event cannot be processed. Submit error, Event not The Event needed by the found Application has been deleted. It will need to be redefined. Submit error, Group not The ESP Group definition for defined the Event has been deleted. It will need to be redefined. Submit error, Applfile not The APPLFILE in which the found APPL resides could not be found. Submit error, Applfile I/O An I/O error occurred while reading the ATR (Application Tracking Record) from the APPLFILE. Submit Failed, Event error An error occurred processing the Event. This would normally be due to a syntax error in the ESP Procedure. An error message would have been sent to the Events owner. This may also occur when the master ESP comes down while trying to submit a job. Submit error, Invalid Job ESP encountered an invalid name jobname Submit Error, JCL The JCL for the job to be missing submitted was not found in the specified data set, or a data set was not specified for the job.
262
SUBERROR PNODE (continued) PNODE Status Description
SUBERROR
Submit Error, Member missing Re-execution count exhausted Submit error, Quit
SUBERROR SUBERROR
The PDS member in which a JOBs JCL resides was not found. The maximum re-execution count has been reached QUIT statement encountered
Status Fields
You can display the following status fields on CSF: Status Field User Status System Status Description Displays information set by the user. Displays the system state of a workload object. This is the system state that ESP continues to change during job processing. You cannot change the values in this field. Displays the user status, if set. If the user status is set to null, it displays the system status.
Status
Setting the User You can set the User Status field when you use either of the following: Status field
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 notify others of the reason for this action. The User Status field for a job might look like this:
JOBNAME TAPEJOB PNODE BYPASSED USER STATUS 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.
263
Defining a View
Introduction
The process of defining a view involves replicating an existing view and customizing the new view to your requirements.
Define a View
To define a view, take the following steps: Step 1 2 Action Select option C from the ESP Main Menu to access CSF. Type V at the Command Line. ESP takes you to the View Definitions panel which lists any existing views, as shown below.
3 4
5
Storing views
Enter R to the left of a view name to copy an existing view under a new name. ESP takes you to the Replicate View panel. Type the name, an applicable description, and the message you want displayed when there are no items matching the view criteria. The view you selected appears, showing all the jobs that fall within that view definition. Customize the view as described in the next section
ESP stores your view definitions in the ESPCSFA member of your ISPF profile data set. This allows you to use the same view on different systems.
264
Customizing a View
Introduction
Once you select a view, you can customize the information presented. Some examples of types of views are: Application specific Exception monitoring. For example, you 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 the characteristics of a view: Command FI PR PT PL SO CO Characteristic Filter information Presentation information Presentation titles Presentation lengths Sort the information presented Define color options based on job status. You can use colors to distinguish workload states.
The following sections describe each of these areas.

265
Customizing a View, Continued
Filtering information
When you filter information, you are describing the criteria for displaying a job as part of a view. For example, you can filter by Application name to select only those jobs in a particular Application. This information defines the rows in your display. To filter information, type FI on the CSF Command Line. This takes you to the Filter Specification panel where you can adjust which characteristics of your jobs ESP filters into the display. You can filter based on different conditions (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.
Freeform Filtering
Freeform filtering is an extension to the CSF filtering capabilities that allows you a more versatile and customizable method of filtering your ESP Applications. If you cannot use the standard filter panel for your requirements, refer to the Freeform Filtering section on page 288 for information on using this feature.
266
Presenting information
Once you have filtered the information you want, you can specify the attributes of the filtered jobs you want presented. For example, you may want to see the job number, PNODE (processing node), and status information for each job. This information defines the columns in your display. Note: Option O.5 (Set CSF Options) allows you to set different options for CSF. This determines the types of entries displayed when you enter any Presentation command from CSF. To present information, type PR on the CSF Command Line. This takes you to the Presentation Fields panel. On this panel, indicate which fields you want displayed by entering a number or letter beside each desired field. The numbers and letters also represent the order you want them to appear across the screen. You can alter the presentation order easily by using numeric and alphabetic characters.
Example
The following example positions the Appl Generation column between the Application and Completion Code columns.
Appl Generation ! 2A Application ! 2 Completion Code ! 3
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 presentation column lengths and titles.
Presentation titles
The PT command takes you to the Presentation Fields panel. On this panel, you can define the titles that ESP presents for each of the fields listed. This is useful for long titles you want to abbreviate. For example, you may want to shorten the field title Account number. You can type an abbreviation such as ACCT in the area to the right of the field name Account number. Or you could change the TAG title to reflect how you are using tags in an Application.
267
Presentation column length
The PL command takes you to the Presentation Fields panel. On this panel ESP lists all the columns used in the CSF view. You can override the default display length of these columns by entering the number of characters you want in the display.
Sorting information
Sorting information defines the order in which ESP presents the rows of information. To define your sorting requirements, type SO on the CSF Command Line. The Presentation Fields panel lets you identify the fields by which you want to sort your view, and the order in which you want ESP to sort them. You can select one or more fields to sort on by typing a 1 or 2 character string 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 the displayed data. Note: If a field contains multiple words (e.g. STATUS field), the sort occurs only on the first word.
Sort Sequence
A Sort Sequence field allows you to specify an ascending or descending sort sequence for a field. Specify an A, or leave the field blank, for ascending order; specify a D for descending order.
Color options
Color screens allow you to use different colors and highlighting options to indicate job status. You may choose different colored and highlighted options to represent different job status conditions, including: Submitted Overdue Task awaiting post Executing Failed.
Selecting colors
To select color options, follow the steps below: Step 1 2 Action Type CO on the COMMAND line. Complete the fields as required.
268
Updating a View
Introduction
You can update a view at any time by selecting the different options for customization, such as FI, PR and SO.
Update a view
To update a view, follow the steps below: Step 1 2 Action Enter U to the left of the view name you want to update. Type the name, an applicable description, and the message you want displayed when there are no items matching your view criteria in the respective fields. Press Enter. ESP returns you to the View Definitions panel.
269
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 1 2 Action Enter D to the left of the view name you want to delete. Press Enter. ESP removes the View from the View Definitions panel.
270
Selecting Views
Methods employed
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 these steps: Step 1 2 Action Type V on the COMMAND line of the Consolidated Status View panel. ESP presents you with a list of Views. 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 on the COMMAND line.
271
Working with CSF
Introduction
This section describes the generally available commands and procedures you can use to work with the Consolidated Status Facility.
272
Commands
Introduction
When ESP displays a view, it precedes each jobname with an entry field. The codes below represent commands that are valid in CSF. To use one of these commands, type the letter code in the entry field preceding the jobname you want 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 with Applications
The following table lists the available commands for working with Applications. Command AA CA HA LA LAD UWA Description Release an Application held by ESP Complete an entire Application Place Application into ESP hold status List Application Dump Application data Remove Application from wait status
Working with subApplications
The following table lists the available commands for working with subApplications. Command AS BYS CS HS LS RDS RQS UBS URS UWS Description Release a subApplication held by ESP Bypass a subApplication Complete an entire subApplication Place subApplication into ESP hold status List subApplication Ready a subApplication Request a subApplication Un-bypass a subApplication Un-request a subApplication Remove subApplication from wait status
273
Commands, Continued
Working with jobs
The following table lists the available commands for working with jobs.
Command A BC BJ BY C DD DIN DR EC EJ H HR IJ IJA IJB L L/D LI LJ LR R RD RP RQ RR RT SUS UB UIN UR UW
Description Release a job held by ESP Browse COPYJCL Browse last executed JCL Bypass a job Complete a job and reduce hold count of successors Drop all job predecessor dependencies Display Info/System record Drop all resource dependencies Edit COPYJCL Edit last executed JCL Place a job into ESP hold status Place a job into ESP hold status with a reason Insert a job Insert a job after the selected job Insert a job before the selected job List job dependencies Drop individual job dependencies (first enter L on CSF and then D on next panel) List job index entries List step-level statistics List job resource waits Resubmit or restart job Ready a job, removing all dependencies except resources Reply to AS/400 message Request job View ESP Encore panels Reset a time dependency Set User Status field for a job Un-bypass a bypassed job Update Info/System record Un-request a requested job Un-wait a job from JANCWAIT
274
Commands, Continued
Working with other ESP definitions
The following table lists the available commands for working with other ESP definitions. Command BD BE BP ED EE EP Description Browse Job Documentation Browse Event Browse ESP Procedure Edit Job Documentation Edit Event Edit ESP Procedure
275
Inserting a Job
Introduction
Using CSF, you can insert different job types into an active Application. The inserted job runs immediately unless you define a predecessor or insert the job on hold.
Example
For example, to add job NEWJOB to an Application with a predecessor of Job PAYD006A and a successor of Job PAYD008A, take the following steps: Step 1 2 3 Action Type IJ beside any job in the Application. Type NEWJOB as the Object name on the Insert an Object panel. Type Y for Predecessors, Y for Successors, and press Enter.
3 4 5
Enter PAYD006A as the Predecessor Job name and press Enter. Enter PAYD008A as the Successor Job name and press Enter. Your job, NEWJOB, should now appear as part of your CSF display.
276
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 panel illustrated below: If an override member name is specified (in the Member field), but no override JCL library name is specified (in the Dsname field), then the specified member name is used together with the original JCL library. If the JCL library name is specified but the member name is blank, then the specified JCL library is used with the original member name. If both fields are blank, the original library name and original member name are used. If both fields are filled in, then the specified library name and specified member name are used.
Resubmitting more than one job
Once an override library name has been specified on this panel, the Dsname field will always be pre-filled with the latest override library name used, for the remainder of the CSF session. Once you exit from CSF, this default value is lost.
277
Removing Job Dependencies
Introduction
Using CSF you can remove different dependencies from a job in an Application.
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 yet completed, to drop a dependency. JOB PAYD008A PREDECESSORS PAY006A NEWJOB SUCCESSORS PAYR009A
Use the RD command to ready a job - remove all dependencies except resources Use the DR command to remove all resource dependencies.
278
Resetting a Time Dependency
Introduction
A job in an Application can have different types of time dependencies. Using CSF, you can reset any of these dependencies.
Process
To change a time dependency for a job, type RT beside the job. This takes you to the Reset Object Times panel. The following table associates each field on the Reset Object Times panel with the corresponding Application statement. Field Earliest submit time Late submit time Overdue time for job start Overdue time for job end Abandon execution at Abandon dependencies at Abandon resources at ESP Procedure Statement DELAYSUB or EARLYSUB LATESUB DUEOUT INPUT DUEOUT EXEC ABANDON SUBMISSION ABANDON DEPENDENCIES ABANDON RESOURCES
Example
Suppose a job has an early submission time of 5 p.m. To remove this dependency 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.
279
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 by typing BY next to the job. ESP updates the status field to BYPREQ indicating that a bypass has been requested. When the jobs predecessors are complete, the job is bypassed and the successor jobs released. You can unbypass a job by typing UB next to the job anytime before the job actually becomes bypassed.
Completing a job
When you complete a job, you are telling ESP 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 can insert another occurrence of the job (qualified for uniqueness) with the required dependencies but successor jobs may have already been released.
280
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.
281
Adding a Job with a Time Dependency
Process
Follow these steps to add a job with a delayed submission time: Step 1 2 3 Action Insert the job on hold (IJ command, Job on HOLD? ==> Y). Reset the submission time for the job (RT command, Earliest submit time ==> time). Release the job from hold (A command).
282
Adding a Job Relationship in an Application
Unrelated jobs
To add a relationship between two unrelated jobs in an Application, simply insert 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 to wait for Job A to complete successfully. Visually, the dependencies look like this:
A B
LINKME
Steps
Follow these steps: Step 1 2 3 4 5 Action Type the IJ command beside any job in the Application. Enter the name of the link in the Jobname field. Type A in the predecessor field. Type B in the successor field. Specify the Job Type as L (link).
When Job A completes successfully, ESP completes the link and submits Job B.
283
Adding a LINK Process
Process
Follow these steps to add a link that processes commands. Step 1 Action Edit the Application definition to define the link and specify the commands you want processed. For example:
JOB EXTRA LINK PROCESS SEND 'THIS IS AN INSERTED LINK PROCESS' U(*) ENDJOB
Insert a link with the same name into the Application - specify jobname, job type, and dependencies.
When the link becomes ready, ESP processes the commands.
284
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 notify others of the reason for this action. The User Status field for a job might look like this:
JOBNAME TAPEJOB PNODE BYPASSED USER STATUS 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.
285
Using Other Commands
Process
You can also enter the following commands on the COMMAND line of the Consolidated Status View panel: Command ESP ESPPM Invokes ESP in ... Line mode Page mode
Another way of processing ESP commands is to type ESP followed by the command you want processed. The following example issues a TRIGGER command from the command line.
ESP TRIGGER PROD.MORE_WORK ADD
For more information on using these modes, refer to Getting Started on page 43.
286
Extensions to CSF
Introduction
The Consolidated Status Facility can have extensions written in REXX. Your installation may want to add its own commands and enhance or replace the standard commands.
Example
For example, your installation can write commands to: Trigger an Event Edit JCL prior to job submission Provide confirmation panels Force user status information Access SDSF.
Check with your system administrator to see if any customized commands are available to you.
287
Freeform Filtering
Introduction
Freeform filtering is an extension to the CSF filtering capabilities that allows you a more versatile and customizable method of filtering your ESP Applications. You have the option to filter your Applications using the standard filter panel or to use the Freeform filter panel for scenarios that cannot 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 optionally Boolean Operator. The keyword identifies the kind of workload objects on which you want to filter, such as Applications or workload object names. The logical operator specifies the operation, such as filter on Application name, when it is equal to some specified character string. Value is what you want Application name to be equal to, such as PAYROLL. If you want to see all Applications that are incomplete, filter on the condition INCOMPLETE. Boolean operators are used to AND or OR one or more keyword and value sets.
Entering a freeform filter
To enter a freeform filter:
Step 1 2
Action Type FI on the CSF command line. This displays the Filter Specification panel. 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)
288
Freeform Filtering, Continued
Specifying Keywords
The following keywords are valid entries for filtering: Keyword ACCOUNT Description Account number Keyword JSBYTE Description Job status byte: C-completed D-dependency E-executing F-failed I-input P-post-process R-resources S-scheduled T-time W-wait Job status flag DJC/JES3 network id Non-specific cart mounts Non-specific reel mounts Processing node Qualifier SAD flags Scoreboard cycle Scoreboard entry # Scoreboard token Scheduled time Status Job start time SubApplication name
AGENT APPL APPLFILE APPLGEN APPLSEQ
Agent name Application name Application file
JSFLAG NETID NSCM
Application generation NSRM PNODE QUAL SADFLAG SCBCYCLE SCBENTRY SCBTOKEN SCHED STATUS STIME SUBAPPL
Application definition sequence APSLOT Application file slot # ASFLAG Application status flag AUTH Authorization string CMPC Completion code DMANAGER Distributed manager name ETIME Job end time EVENT Event name HC Hold count HWCM High water cart mounts
289
Specifying Keywords (continued)
Keyword HWRM JAFLAG JOBNAME JOBNO
Description High water reel mounts Job attribute flag Job name Job number
Keyword TAG TRSLOT USTATUS WOBTYPE
Description Tag Trkfile slot # User status 2-character workload object type for nonMVS
Note: For any of the time fields, (i.e. ETIME, SCHED, and STIME), you need to use the TIME function in a comparison. For example, STIME > TIME(11AM TODAY). You can compare against any time in a format that ESP recognizes.
Specifying relational operators
Relational operators include the following standard operators: >= GE greater than or equal <= LE less than or equal > GT greater than < LT less than = EQ equal = NE not equal to
290
Using Substrings
You may need to refer to portions of a value, rather than its full contents. The filter string uses substring notation to allow you to specify which characters of a value you need. Substring notation consists of specifying 1 or 2 numbers in parentheses 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. The following table demonstrates the outcome that results when you specify certain substring notations:
Specification Result
JOBNAME JOBNAME(1,4) JOBNAME(5) JOBNAME(5,1) JOBNAME(-1,1) JOBNAME(1,7) JOBNAME(1,-3)
PRODJOB PROD JOB J B PRODJOB PROD

291
Specifying Conditions
You can use the following conditions in your filter string: Condition ALL APPL_COMPLETE BYPASSED COMPLETE CRITICAL_PATH EXTERNAL INCOMPLETE INTERVENTION_REQUIRED INTVRQ LINK MANUAL_TASK NOT_APPL_COMPLETE NOT_BYPASSED NOT_CRITICAL_PATH NOT_EXTERNAL Description All objects Application execution is complete Object execution has been bypassed Object execution is complete Object is on a critical path Object is External to an Application Object execution is not complete Object execution requires manual intervention Object execution requires manual intervention Object is a LINK Object is a manual task Application execution is not complete Object execution has not been bypassed Object is not on a critical path Object is not an External
292
Specifying Conditions (continued)
Condition Description NOT_INTERVENTION_REQUIRED Object execution does not require manual intervention NOT_INTVRQ Object execution does not require manual intervention NOT_LINK Object is not a LINK NOT_ON_REQUEST Object is not defined as REQUEST NOT_OVERDUE_END Object execution end time has not been exceeded NOT_OVERDUE_START Object execution start time has not been exceeded NOT_REQUESTED Object has not been specifically requested NOT_RESTART_STEP_PRESENT Object does not have a restart step NOT_TASK Object is not a TASK ON_REQUEST Object is defined as REQUEST OVERDUE_END Object execution end time has been exceeded OVERDUE_START Object execution start time has been exceeded REQUESTED Object has been specifically requested RESTART_STEP_PRESENT Object has a restart step TASK Object is a TASK Note: Common conditions are available on the Filter Specifications screen and may not require a freeform filter.
293
Specifying Boolean Operators
Introduction
When you specify your filter string, you can connect 2 or more keyword and value sets with the logical operators AND and OR. Use AND when all conditions must be met. Use OR when any of the conditions meet your criteria. The AND operator takes precedence over the OR operator. You can nest expressions within parentheses to force precedence.
Example Filter Strings
The following table lists filter strings and what they reveal:
Enter the following filter

CRITICAL_PATH ON_REQUEST AND REQUESTED APPL EQ 'PAYROLL' AND RESTART_STEP_PRESENT JOBNAME(1,1) EQ 'P' AND JSBYTE EQ 'F' CMPC EQ 'S222' AND SUBAPPL EQ 'PAYJOBS' JOBNAME(1,3) EQ 'PAY' OR JOBNAME(1,3) EQ 'ACC'AND APPL EQ 'FINANCE' JOBNAME(1,4) EQ 'TEST' OR APPL EQ 'TESTAPPL' AND INCOMPLETE APPL EQ 'CYBER' AND OVERDUE_START AND REQUEST JOBNAME(1,3) EQ 'CYB' AND STIME> TIME(11AM TODAY) WOBTYPE EQ 'HP' AND APPL EQ 'BILLING'
To see... Critical path jobs On-request jobs that have been requested Jobs in the PAYROLL Application that have a restart step Failed objects that start with P Jobs with a completion code of S222 in the PAYJOBS subApplication Objects that start with PAY or ACC and belong to an Application called FINANCE Objects in Application TESTAPPL that start with TEST and are not complete Objects in Application CYBER whose execution start time is overdue Objects whose names start with CYB that started later than 11 a.m. today All HP jobs in the BILLING Application
294
Specifying Boolean Operators, Continued
Example Filter Strings (continued)
Enter the following filter

JOBNAME(1,1) EQ 'X' AND APPL EQ 'MYAPPL' AND NOT_REQUESTED (JOBNAME EQ 'TESTJOB' OR JOBNAME(1,2) EQ 'A' OR JOBNAME(1,2) EQ 'BC') AND (APPL EQ 'MYAPPL' OR APPL (1,2) EQ 'PA') AND OVERDUE_START
To see ... Objects that start with X in Application MYAPPL that have not been requested Objects called TESTJOB and whose names start with the characters A or BC and are contained within Application MYAPPL or any Application whose name starts with PA and whose execution start time is overdue
295
Creating Reports Overview
Introduction
ESP allows you to get information about your jobs in several ways. You may generate a report, flowchart a jobstream, view CSF, or use tracking commands to give you the job information you require.
In this chapter
This chapter contains the following topics: Topic History Reporting Structuring the Report Reporting Fields Field Formats Invoking the Report Function Specifying Input Criteria Specifying Output Criteria Ending the Report Definition ESPs History Reporting Fields Accumulating Fields Reporting on Scheduled Activity Allocating a Sequential Data Set Generating Data Extracting Data Generating Scheduled Versus Actual Report Generating Projected Versus Actual Data Extracting Tape Information Using Job Mapping Job Mapping Data Set Generating Data for the Report Producing a Job Activity Report Producing a Job Descendent Report Putting it All Together ESP FLOWDOC Flowcharting Generating Flowcharts Using MS Project Generating Flowcharts with ESP and Timeline See Page 297 298 299 300 304 305 309 312 314 320 321 322 323 325 326 328 329 330 331 332 333 338 340 341 350 351 354
296
History Reporting
Overview
ESP has a powerful and versatile reporting facility that you can use at any time to generate details about the progress of jobs. Information in the job history files, defined by the administrator or installer, provide the basis for the reports. You can generate reports online or in batch. Note: You can report only on jobs, started tasks, and TSO users that the ESP administrator requests ESP to track.
For more information on how to specify which of these ESP will track, refer to the ESP Administrators Guide.
297
Structuring the Report
Introduction
You can structure a report definition in several sections, some of which are optional. Start each section of a report definition by a command, then code each section in free format and in any sequence.
Sections of a report
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 the report
For most reports, you usually specify input source selection, selection criteria, and display format. You can make reports as detailed as you want, describing such aspects as: Jobname Completion date Application name CPU time Number of print lines.
298
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 a report containing as much detail as you want.
History reporting fields
A list of ESPs history reporting fields and their definitions appears later in this chapter under the heading ESPs History Reporting Fields.
299
Field Formats
Field categories
Using ESP you can display or base selection criteria on the following field categories: Character Numeral Time Elapsed time CPU times Dates.
Character fields
These include JOBNAME, ACCOUNT, CLASSID, and PGMR. These fields are always left justified. In the CRITERIA section, you can select character fields by specifying the full field value or part of it. If you specify a part of the field, you must include wildcard characters. The asterisk matches with any single character, while a hyphen specifies that any remaining characters match.
Example: Character fields
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 also select any occurrences of the job ABC.
CRITERIA JOBNAME EQ ZA*B OR JOBNAME EQ ABC
Numeric fields
These fields include APPLGEN, EXCP, EXEC#, JOBNO, RC, RRJOBNO, STEPS, SUBJOBNO, TRANSACT and TRANSRES. ESP displays them right justified with leading zeros translated into blanks. You can increase the default length for these fields by specifying whatever length you want on the DISPLAY statement or by defining a longer title.
Example: Numeric fields
The following example displays DASD EXCP counts to nine digits because the title length (DISK-EXCP) is nine characters. The title for the tape EXCP counts is TAPE I/O but ESP displays the counts to a length of nine, as specified. Blanks on the left fill the field. ESP justifies title and numeric fields on the right.
DISPLAY DEXCP 'DISK_EXCP' TEXCP 9 'TAPE I/O'
300
Field Formats, Continued
Comparisons
You can also make comparisons against numeric fields in the CRITERIA section. 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 than 1000 tape EXCPs.
CRITERIA TEXCP>0 AND TEXCP<1000
Time fields
Time appears in the 24-hour clock format. The default is hh.mm.ss, but you can omit the seconds by specifying a display size of five. The RDRON, EXECST, ENDT, and COMPT fields fall into this category. You can use any date and time format valid on a SCHEDULE statement when you want to select these fields.
Example: Time fields
The following example selects all jobs submitted since March 3rd, 1998.
CRITERIA RDRON GT MARCH 3RD 1998
Elapsed time fields
OVDSTART, INPUT, TOTALQT, and OVDCOMPT are examples of elapsed times. ESP displays them in the following forms: ESP Form Explanation ss 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-three seconds). hhHmm Hours and minutes, when the elapsed time is less than 99 hours. For example: 16H14 (16 hours and 14 minutes). hhhHm Hours and first digit of minutes, when the elapsed time is greater than 99 hours but less than 999 hours. hhhH Hours, when the elapsed time is more than 999 hours. You can select elapsed times by requesting them in the same formats as those that appear above.
301
Example: Elapsed time fields
The following example selects jobs that were in execution for one or more minutes, yet completed execution within five hours.
CRITERIA EXECQT GE 1M00 AND EXECQT LT 5H00
CPU time fields
This includes CPUTIME, SRBTIME, and TCBTIME. They appear in the form mm:ss.th, where mm is the number of minutes, ss is the number of seconds, and th are the tenths of a second.
Example: CPU time fields
The following example selects all jobs that consumed between ten seconds and 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 in the form xxxddmmmyy, where: Field Symbol xxx dd mmm yy Explanation first three characters of the day of the week. day of month number. first three characters of the month name. last two digits of the year.
You can change the way date fields are displayed in a report using the DATEFORM command within the report, as described in the Specifying Output Criteria section of this chapter. You can use any date and time format valid on a SCHEDULE statement when you want to select these fields as input criteria to your report.
302
Example: Date fields
The following example selects all jobs that were submitted since 9 a.m. on March 29th, 2000.
CRITERIA RDRONDATE GT 9AM MARCH 29TH 1999
The date fields also allow for some sorting by storing time information. When you request sorting by a date field, ESP sorts by date and time. If you specify the following, ESP reports only on those jobs with a reader-on time and date of midnight, August 23, 2000.
CRITERIA RDRONDATE EQ AUGUST 23RD 1999
303
Invoking the Report Function
Methods used to invoke the reporting function
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 now structure your report.
304
Specifying Input Criteria
Input for a report
The input for a report consists of: A history file A time range Selection criteria. This section describes each of these areas.
Identifying the History file
Use the HISTFILE command to specify which history files you want to use as the input source. If you omit the history file you want to use, ESP scans all the history files you can access. Your ESP Administrator determines history file access. The following specifies a history file called HIST1:
HISTFILE HIST1
Using History file other than current
Use the INPUT command to request that ESP read in other records from a data set other than an active history file. You can use any VSAM KSDS, ESDS or non-VSAM sequential data set as input. The data records must have the exact format of the ESP history file records. You will find this option most 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-system does not have to be active in order to use the INPUT statement.
Specifying the time range
Use the FROM and TO commands to specify a time range for the history file search. In this way you can limit your search based on the job submission time in the history file. If you do not specify an end time, ESP uses the current time. You can use any valid schedule statement that resolves to a date and time, for example:
FROM 10AM TODAY FROM 8AM YESTERDAY TO 8AM TODAY FROM 9AM TODAY LESS 1 WEEK TO 9AM YESTERDAY
305
Specifying Input Criteria, Continued
Specifying the selection criteria
Use the CRITERIA command to specify selection criteria. The syntax is:
CRITERIA field operator value
To view all the values possible for field, see the topic entitled ESPs History Reporting Fields, starting on page 314. You can specify several field, operator, and value groups. To be selected, all criteria elements must be matched. Use the OR connective to provide alternatives. If you do not specify a CRITERIA command, ESP reports on all records that meet the time range criteria. You can use the following operators in either their symbol or letter form in a CRITERIA command. You cannot use the equal sign (=). Symbol Form >= <= < > = Letter Form GE LE LT GT NE EQ Explanation Greater than or equal Less than or equal Less than Greater than Not equal to Equal
If you want to compare a field to a null string, use a blank enclosed in single quotes, as in . Note: You can specify several criteria sections in a single report, using multiple CRITERIA commands; ESP selects a job if it satisfies any criteria section.
Example
The following example selects only those jobs that belong to the PAYROLL Application:
CRITERIA APPLSYS EQ PAYROLL
Example
The following example selects only those jobs that have been restarted:
CRITERIA RRJOBNO NE 0
306
Example
The following example selects a job if it belongs to the PAYROLL Application 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 PAYROLL Application or the jobname starts with P.
CRITERIA APPLSYS EQ PAYROLL CRITERIA JOBNAME EQ P-
Or you could use OR to separate the requirements:

CRITERIA APPLSYS EQ PAYROLL OR JOBNAME EQ P-
Example
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 of an 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 10000 CRITERIA JOBNAME EQ ABC- OR JOBNAME EQ A*
307
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 10000 CRITERIA CPUTIME GT 1:00
308
Specifying Output Criteria
Specifying an output data set
Use the COPY command if you want to specify an output data set or file to receive all or subsets of the job history records read in from the input source. ESP writes to any format sequential data set. If a data set is new and you have not yet specified a record format for it, ESP uses the following default: LRECL=4096, RECFM=VBS, BLKSIZE=6144.
Separating data into different files
You may find the COPY option useful when you want to separate data in a history file into one or more files. The example below sends records to tape after they are 12 weeks old:
REPORT HISTFILE HIST1 CRITERIA RDRON GT TODAY LESS 12 WEEKS COPY SELECT FILE(DISK1) COPY REJECT FILE(TAPE1)
Specifying the date format
History reporting displays date fields in DDMMMYY format. You can change this default using the DATEFORM command. The options are as follows DATEFORM DMY This is the default. JULIAN YM YMD MDY Results Day DDMMMYY Day DDDYY Day YYYYMMM Day YYYYMMMDD Day MMMDDYY Example MON21JUN99 MON17299 MON199906 MON19990621 MON062199
Notes
This setting only affects the date format you use to display fields in a history report; it does not affect the date format you use on a CRITERIA command and it does not affect the date format used in schedule criteria.
309
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 in YYYYMMMDD format.
DATEFORM YMD
Specifying fields to display
Use the DISPLAY command to specify which fields you want to display. Then you have the option to define titles.
Entering field names
Once you start the DISPLAY section, you can enter several field names one after the other. Separate each by a blank or a comma, along with optional lengths and titles. ESP places the fields you specify on the report detail line in the order you specified them. To view all the values possible for field, see the topic entitled ESPs 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 their default titles Restricts the reader-on date to five characters Displays the tape and disk EXCP count to five and six digits respectively Includes special title segments for the last two fields.
DISPLAY JOBNAME, RDRON, RDRONDATE 5, TEXCP 'TAPE' 'EXCPS' DEXCP 6 'DISK' 'EXCPS'
Specifying sort criteria
Use the SORT option to specify which fields you want to sort and whether you want the sort sequence to be ascending or descending. The default is ascending. The following example sorts data by decreasing use of CPU time. ESP displays the data in sequence of ascending DASD EXCP counts.
SORT CPUTIME D DEXCP
310
Specifying Output Criteria, Continued
Specifying other 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 only meaningful fields such as CPUTIME and DEXCP, but not JOBNO. The subtotal detail line has the same format as the normal detail line, except that it always has the word subtotal starting in column one. The next column displays the number of items ESP sub-totaled. The preceding information occupies the first 14 character positions on the line. When you create a detail line, do not place any fields you want ESP to subtotal in the first two columns.
Example: Specifying a format
In the following example: When the first three characters of the first account number change, ESP prints a subtotal and starts a new page When the first two characters of the jobname change, ESP leaves one blank line.
DISPLAY JOBNAME JOBNO ACCOUNT RDRON DEXCP TEXCP SORT ACCOUNT JOBNAME BREAK ACCOUNT 3 EJECT SUBTOTAL BREAK JOBNAME 2 SPACE 1
311
Ending the Report Definition
Introduction
Use the ENDR command to mark the end of a report definition and initiate the report generation.
Example: Reporting on an Application
This example reports on all jobs in an ESP Application called PAYROLL that have changed status since 8 a.m. today. The SETWIDTH command sets the width of the report to 80 characters.
REPORT SETWIDTH 80 FROM 8:00AM TODAY CRITERIA APPLSYS EQ PAYROLL DISPLAY JOBNAME CMPC EXECST EXECSDATE ENDT ENDDATE CPUTIME ENDR
Sample output from the above commands is shown below.

JOBNAME JOB NO PAYD001A 2221 PAYD002A 2227 PAYD003A 2226 PAYD004A 2229 PAYD100A 2232 PAYD006A 2233 PAYD008A 2234 PAYD008A 2270 PAYD008A 2271 PAYD009A 2272 PAYD010A 2273 PAYD010A 2275 PAYD011A 2276 SUBTOTAL (13) TOTAL (13) COMP CODE 0 0 0 0 0 0 SOC1 SOC1 0 0 SOC1 0 0 EXEC START 11.56 12.02 12.02 12.02 12.07 12.08 12.08 12.57 12.58 12.58 12.59 12.59 12.59 START EXEC DATE END MON 13APR98 12.02 MON 13APR98 12.02 MON 13APR98 12.02 MON 13APR98 12.07 MON 13APR98 12.07 MON 13APR98 12.08 MON 13APR98 12.08 MON 13APR98 12.57 MON 13APR98 12.58 MON 13APR98 12.58 MON 13APR98 12.59 MON 13APR98 12.59 MON 13APR98 13.04 END CPU DATE MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 MON 13APR98 TIME 0:01 0:00 0:00 0:04 0:00 0:00 0:00 0:00 0:00 0:00 0:00 0:00 0:01 0:06 0:06
312
Ending the Report Definition, Continued
Example: Reporting in batch
In the example below the first four lines represent JCL statements and the remaining lines define a report. The report includes information on jobs whose first account number begins with PAY that ESP has tracked from 6 p.m. yesterday until 8 a.m. today.
//REPORT JOB ... //EXEC PGM=ESP,REGION=4000K //SYSPRINT DD SYSOUT=X //SYSIN DD * REPORT HISTFILE HIST1 FROM 6PM YESTERDAY TO 8AM TODAY CRITERIA ACCOUNT EQ PAY-; DISPLAY JOBNAME, JOBNO, ACCOUNT, DEXCP, TEXCP SORT ACCOUNT 4 EJECT SUBTOTAL ENDR
Note: When reporting in batch, a hyphen at the end of a line indicates a continuation. If you are using a hyphen as a mask, follow it with a semi-colon (e.g. PAY-;).
Example: Writing report output to a data set
The following example writes a history report to a new data set. The report includes information on jobs with names beginning with CYB that ESP has tracked 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 * REPORT HISTFILE HIST1 CRITERIA JOBNAME EQ CYB-; FROM 4PM TODAY DISPLAY JOBNAME JOBNO CMPC MXCMPC EXECST EXECQT CPUTIME SORT JOBNAME D BREAK JOBNAME 4 EJECT SUBTOTAL ENDR
313
ESPs History Reporting Fields
Introduction
The following are history reporting fields. An asterisk beside a field indicates you can use the field for non-MVS workload. Field ACCOUNT Explanation Jobs first account parameter, can also be specified as ACCOUNT1. ACCOUNT2 Jobs second account parameter. ACCOUNT3 Jobs third account parameter. ACCOUNT4 Jobs fourth account parameter ALLOCQT 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 jobs 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 a condition 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 different completion codes, go to the last page of the History Reporting Field topic. COMPDATE Job completion date, which is the date on which the job completed its last post-processing phase. If the job has no postprocessing phases, the completion date is the same as the purge date. (See note at the end of the table.) COMPT Job completion time, which is the time at which the job completed its last post-processing phase. If the job has no postprocessing phases, it is the same as the purge time. (See note at the 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.
314
ESPs History Reporting Fields, Continued
Field ESPSUB
EXCP EXEC# EXECNODE EXECQT EXECSDATE EXECST* EXECSYS GROUP* INFOREC INPUTQT INSYS JOBCLASS JOBNAME* JOBNO* JOBQUAL* LINES MSGFAIL
MXCMPC MXRC
NCI NETID
Explanation Indicates whether or not the job was submitted by ESP. It has a value of YES if the job was submitted by ESP (either through an Event or as part of an Application), otherwise it has a value of NO. Total EXCP count for the job during the execution phase. Number of times the job has executed as part of a particular generation of an Application. Node the job executed on. This refers to a JES node and not the name given to an ESP node (i.e. LOCAPPL parameter). Elapsed time for the job during the execution. Date at the start of the execution. Execution start time. For example, 08:26. System the job executed on. This does not get set until the job is purged regardless of your tracking options. Prefix of the Event associated with the job, if ESP submitted. Info/System record number. Length of time the job was in the input queue. System the job was submitted on. This does not get set until the job is purged regardless of your tracking options. JES execution class. Name of the job. Job number. ESP job qualifier. Number of print lines. Indicates whether or not the job failed due to an ESP SYSMSGS command. The field has a value of YES if the job terminated due to the ESP SYSMSGS facility, and the value NO otherwise. Maximum completion code for the job. The highest return code from any step in the job. This is a numeric field, for more information, go to the last page of the History Reporting Field topic. Number of card images submitted to the internal reader. Network identifier for a job belonging to a DJC/JES3 job network.
315
Field NSTM
Explanation 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 the DUEOUT OUTPUT statement in an ESP Procedure or in a jobs tracking model. OVDEND Amount of time by which the job was late in ending execution. The criteria for being late is defined by the DUEOUT EXEC statement in an ESP Procedure or in a jobs tracking model. OVDSTART Amount of time by which the job was late in starting execution. The criteria for being late is defined by the DUEOUT INPUT statement in an ESP Procedure or in a jobs 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 of the History Reporting Field topic. RDRON Time at which ESP read the job into the system. If you are using RDRONDATE, you do not require this field. RDRONDATE Date at job submit time. This field also includes the time ESP 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 rerun by ESP (i.e. a job that has been resubmitted via an explicit AJ command or the R line command in CSF. If the job is not a rerun, this field is set to 0 (zero). SCHEDDATE Scheduled date. SCHEDT Scheduled time.
316
Field SPTM SRBTIME STATUS
Explanation Number of specific (i.e. non-scratch) tape mounts for the job. CPU time consumed while in SRB mode. Job status. There are four possible values: INPUT: defines submitted jobs not yet started STARTED: defines jobs currently in execution COMPLETED: defines jobs that completed all phases of processing ENDED: defines jobs that completed execution but did not finish all phases of processing. Number of job steps. Submission number for a job in an Application. SubApplication identifier. Job number on the system that submits the job. This is useful when a job is submitted on one system and routed to another system where a different JES job number is assigned. Job service units, as defined by the SRM. System abend code or null. Number of tape mounts for the job. Maximum number of tape drives allocated to a job at one time. Note that SPTM and NSTM may not add up to TAPEW. SPTM and NSTM represent numbers of tape mounts. TAPEW counts the number of different tape drives that were used at one time. For example, if a jobstep calls for 3 specific tapes, one at a time, on the same drive then TAPEW will be 1 but SPTM will be 3. CPU time consumed while in TCB mode. Total EXCP count to tape drives. Name of the ESP tracking model that was used to track the job. Total elapsed time for the job.
STEPS SUB# SUBAPPL* SUBJOBNO
SUNITS SYSABD TAPEM TAPEW
TCBTIME TEXCP TMODEL TOTALQT
317
Field TRANSACT
TRANSRES
TRUSER UABEND WDFAIL
Explanation Total time for which a transaction is active. In the case of a batch job, this is approximately equal to the total execution times for the programs contained in the job. It is measured in units of 1024 microseconds. Total time during which a transaction was resident in real memory. This is often identical to the transaction active time (TRANSACT), but may differ since it does not include any time during which the task was swapped out of real memory. It is measured in units of approximately 1 millisecond, or more precisely, units of 1024 microseconds. Userid that triggered the Event. It resolves to the userid that manually triggered an Event, and is blank otherwise. User abend code or null. Indicates whether or not there was a WTO detected JCL error. The field has a value of YES if the job terminated prior to starting execution, and the value NO otherwise. These errors are caused by such activities as an early (pre-execution) JCL error, certain security system verification errors, and a cancellation of a job while it is on the JES input queue.
Note:
ESP may not track jobs through to the output stage at your installation. For such jobs: The times specified in the COMPDATE and COMPT fields refer to when the jobs complete successfully. The LINES, POSTQT, PRINTQT, PURGDATE and PURGT fields are not applicable.
318
Numeric fields
The RC and MXRC fields contain strictly numeric values. For cases where a completion code is non-numeric (e.g. JCL errors, system or user abends, CCFAIL), special values are inserted in these fields as an indication of the actual completion status. The following table lists the completion codes: Type of Error System ABEND User ABEND SYSERROR CCFAIL JCLERROR RUNNING Value Abend code + 10000 (abend code converted to decimal first) Abend code + 20000 30000 (actual completion status unavailable) 30001 (terminated by CCFAIL or CCCHK logic) 30002 32767 (job still executing)
Field length change
All fields that represent Time previously displayed the minutes and hours. As of ESP 5.1, these displays now include seconds. This causes an increase in the field length for coding purposes. This is important if you produce a history report and use another program (e.g. SAS) to pull data out of the report.
319
Accumulating Fields
Description
The following reporting fields are accumulated, totals will be produced for you: EXCP DEXCP TEXCP TAPEM SPTM NSTM STEPS SUNITS NCI LINES OVDSTART OVDEND OVDCOMP INPUTQT EXECQT PRINTQT TOTALQT POSTQT ALLOCQT TCBTIME SRBTIME CPUTIME TRANSRES TRANSACT
320
Reporting on Scheduled Activity
Introduction
The scheduled activity facility reports on the scheduled workload for a time period in the future. It lets you generate online and hardcopy reports about scheduled jobs, links, tasks, and manual jobs. The reports provide a variety of job statistics that indicate processing requirements. The data the report generates uses average execution results from tracked jobs to provide a true picture of what you can expect during the next scheduled occurrence of the jobs. Note: This facility reports on job workload that is not yet active. This excludes jobs in an active Application, for example.
Set up schedule forecasting
To set up schedule forecasting:
Step 1 2 3 4
Action Allocate a sequential data set to store scheduled activity data. Generate data on scheduled jobs. Extract data to create a report. Update data to obtain a scheduled versus actual report. (This is an optional procedure).
321
Allocating a Sequential Data Set
Optional attributes
Allocate a sequential data set to store the data. The following attributes are optional:
Attribute PS VBS 32756 32760
Explanation Organization Record format Record length Block size
You can use any sequential data set; ESP assigns the correct attributes.
322
Generating Data
Introduction
To generate data that you can use for scheduled activity reporting, ESP must simulate all the Events and ESP Procedures it would execute in a specified period. ESP does this by executing the ESP subsystem started task procedure in batch with a special parameter (PARM=SAR or PARM=SAD). The output that ESP generates by this simulation forms a scheduled activity data set. You can also create multiple schedule activity data sets. You may want to generate separate data sets on scheduled activity for the next day or for the next week, or you may want different activity data sets for different production groups. Note: ESP does not reflect an Event in the scheduled activity data set unless it contains either a SCHEDULE or EXPECT command.
SADGEN command
When creating a job to generate a scheduled activity data set, you can limit the simulation to specific Event data sets, prefixes, and classes by the appropriate use of the different parameters of the SADGEN command. You can also use the ESPSADG symbolic variable in an ESP Procedure to affect the simulation. This variable is set equal to 1 during SADGEN processing, otherwise it is set to 0. For example, the following statement at the beginning of an ESP Procedure causes ESP not to simulate the Procedure during SADGEN processing:
IF ESPSADG=1 THEN QUIT
When ESP creates a scheduled activity data set, it contains a record for each job you want to submit, within the time range you have specified on a schedule statement. If you specify neither the FROM nor TO time range, ESP provides the following default:
'NOW' TO '6AM TOMORROW'
323
Generating Data, Continued
Example
The example below is a batch job, SADGEN, that generates a scheduled activity data set called CYBER.SAD. The name of the started task procedure for ESP is ESP.
//SADGEN JOB... //S1 EXEC ESP,PARM='SAR' //SYSPRINT DD * //SYSIN DD * SADGEN DATASET('CYBER.SAD') FROM('8AM TODAY')TO('8AM TOMORROW')
324
Extracting Data
Introduction
After ESP generates the data, you can extract the data to produce a standard format scheduled activity report. You can create the report either in batch or online using the LSAR command, or using option S on the Main Menu.
LSAR command
The LSAR command lists a scheduled activity report including the following data: 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 scheduled activity report defaults to now. If you do not use either ENDING or UNTIL with the FROM keyword, and you do not specify TO, the scheduled activity report contains all data generated by the SADGEN command, which ESP stores in the scheduled activity data set.
Example: Displaying scheduled activity data
The following example requests a report on activity scheduled in an eight hour period starting at 5 a.m. using the data set CYBER.SAR. ESP presents the data in scheduled time sequence.
LSAR DSN('CYBER.SAR') FROM('5AM TODAY UNTIL 1PM TODAY') TIMESQ
325
Generating Scheduled Versus Actual Report
Introduction
You can update a scheduled activity data set with current job status, creating a scheduled versus actual report. This allows ESP to calculate the completion status of a schedule, so that you can see how much work has been completed and how much remains. If you use CSF to monitor the workload, you receive more up-to-date information because ESP automatically updates the CSF. However, to generate a hardcopy report on the current status from CSF, you may need to code your own extensions. For more information on CSF see Chapter 7, Consolidated Status Facility.
SADUPD command
You perform the schedule update in a similar way to the schedule activity generation. Instead of the SADGEN command, use the SADUPD command. ESP can run a job at frequent intervals during a day to update the scheduled activity database. The job executes in a fraction of the time of the original schedule generation. After ESP has run the scheduled update, use the STATUS keyword on the LSAR command, or specified on the Option S panel, to request a status display instead of the regular schedule display. This provides the status of all jobs in the schedule, as well as the time and percent of the schedule still remaining. ESP displays actual start and end times, completion codes, and rerun indicators.
Example 1: Creating a scheduled activity data set
This example uses JCL to create the scheduled activity data set:
//SADGEN JOB CYB1000,CLASS=A //S1 EXEC ESP,PARM='SAR' //SYSIN DD * SADGEN DATASET('CYBER.ESP.SAD') FROM('5AM TODAY')TO('5AM TOMORROW')
326
Generating Scheduled Versus Actual Report, Continued
Example 2: Updating a scheduled activity data set
This example shows the JCL which may be used to provide an update on this scheduled activity:
//SADUPD JOB CYB1000,CLASS=A //S1 EXEC ESP,PARM='SAR' //SYSIN DD * SADUPD DATASET('CYBER.ESP.SAD')
327
Generating Projected Versus Actual Data
Introduction
The scheduled activity update feature provides you with actual start and end times for jobs. ESPs modeling feature can project these times in advance. As a result, ESP can generate a Projected vs. Actual report that shows each jobs projected and actual start and end times. For detailed information on modeling, refer to the Advanced Users Guide.
Projected report
To generate a projected versus actual report:
Step 1
3 4
Action Before ESP starts the workload you are interested in, generate a scheduled activity data set using the SADGEN command in a batch job. When the SADGEN completes, run a model in batch. The model processor updates each jobs projected start and end times in the SAD file. Ensure that the model processing covers the appropriate period. After all jobs in the SAD file are complete, update the scheduled activity data set using the SADUPD command in a batch job. Use the LSAR command with the PROJECTED keyword to generate a Projected vs. Actual report.
LSAR DSN('CYBER.SADFILE') PROJECTED
328
Extracting Tape Information
Introduction
You can request the ESP extract tape volume serial information during a scheduled activity data set generation run. ESP references the tape management catalog when it generates the scheduled activity data set. ESP can then generate a data set using this extracted information and feed the data set into the TMS or CA1 tape pull program.
Extract information
To extract information, take these steps:
Step 1
Action Use the INPUTDS statement in the job documentation data set or ESP Procedure identifying the tape data sets associated with each job. For example:
JCLLIB PROD.JCL APPL PAYROLL JOB JOB1 RELEASE JOB2 JOB JOB2 INPUTDS PROD.GDG(-1) ENDJOB SELECT (JOB1,JOB2)
2 3
Generate a scheduled activity using the SADGEN command in a batch job. Use the LSAR command specifying TAPEPULL(dsname), where dsname is the pre-allocated PDS to store tape data set information. An example is shown below:
LSAR DSN('CYBER.ESP.SAD') TAPEPULL('PROD.TAPE.PULL')
ESP creates a member for each job. You should re-initialize the TAPEPULL data set before you generate the scheduled activity data set. Use this PDS as input to the TMS or CA1 tape pull program.
329
Using Job Mapping
Introduction
Job mapping is a reporting facility that allows you to produce detailed job information. You can generate the following reports: Type of Report Content of Report Job activity This report contains detailed information on jobs including job name, Application name, job type, Event name, ESP Procedure name, JCL library, execution time, CPU time, and predecessor and successor jobs. Job descendent This report shows a job and its successors. Unlike the scheduled activity report, which is based on time, the job mapping feature generates data based on Event names. These Events may be scheduled or may require data set or manual triggers. There is no need for these Events to have executed as history data is not required for the jobs. If history data is available, this historical information is incorporated into the reports.
Setting up job mapping
To set up job mapping: Step 1 2 3 Action Allocate a sequential data set to store the job mapping data. Generate data for the report using the MAPGEN command. Use the JOBMAP command to display a job activity report or use the JOBTREE command to display a job descendent report.
330
Job Mapping Data Set
Job mapping data set
Allocate a sequential data set to store the data. This is referred to as the job mapping data set.
Explanation Organization Record format Record length Block size
Attributes for 3390 DASD PS VBS 32756 27998
Otherwise use PS VBS 32756 16384
331
Generating Data for the Report
Introduction
Use the MAPGEN command to generate data for the job mapping data set that can be used by the JOBMAP and JOBTREE commands to produce reports. To use the MAPGEN command, use a batch job that executes the ESP started task procedure with the special parameter, PARM=SAR or PARM=SAD. The MAPGEN command takes the information for an Event, or set of Events, and stores it in your job mapping data set. To use this command, specify the name of your job mapping data set and an Event descriptive name (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 the output in the ESP.MAPGEN data set. The name of the started task procedure for 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 generate data for all Events with descriptive names that start with PAY and store the output in the ESP.MAPGEN data set.
//MAPGEN JOB ... //S1 EXEC ESP,PARM='SAR' //SYSPRINT DD SYSOUT=* //SYSIN DD * MAPGEN DSN('ESP.MAPGEN') EVENT(PAY-)
332
Producing a Job Activity Report
JOBMAP command
Use the JOBMAP command to produce a job activity report. This report contains detailed job information. For each job, regardless of its frequency, the job activity report lists the following information: 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 job mapping 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 the JOBMAP command in batch, by executing PGM=ESP with the correct SUBSYS parameter, or in Page mode.
333
Producing a Job Activity Report, Continued
Example Using JOBMAP in batch
The following example creates a Job Activity Report for all jobs. The subsystem 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 Using JOBMAP in Page mode
The following example creates a Job Activity Report, for all jobs, in Page mode.
JOBMAP DSN('ESP.MAPGEN')
Reviewing the output
For each job, ESP produces output similar to the following:

JOB NAME -------PAYJOB01 APPL NAME --------PAYROLL TYPE ---JOB SCHEDULING ---------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: -NONEBEFORE: PAYJOB02 PAYJOB03 RESOURCES: -NONEPROC: MY.ESPPROC(PAYJOB01) TAG:
Customizing your job activity report
Because of the amount of data generated for each job, you may want to limit the report to a specific Application, produce an index, or suppress certain fields in your report.
334
335
Generating a report for a specific Application
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 PAYROLL Application.
JOBMAP DSN('ESP.MAPGEN') APPL(PAYROLL)
Generating an index
You can use the JOBINDEX, APPLINDEX and RESINDEX keywords to produce an index by job name, Application name, or resource name, respectively.
Example
The following example creates a Job Activity Report with an index by job name and an index by Application name.
JOBMAP DSN('ESP.MAPGEN') JOBINDEX APPLINDEX
Sample index of The following is a sample index of jobs that will appear at the end of your Job jobs Activity Report:
JOB INDEX JOB NAME APPL NAME -------- --------PAYJOB01 PAYROLL PAYJOB02 PAYROLL PAYJOB03 PAYROLL END OF LIST PAGE ---1 2 2
Sample index of The following is a sample index of Applications that will appear at the end of Applications your Job Activity Report:
APPL NAME JOB NAME --------- -------PAYROLL PAYJOB01 PAYJOB02 PAYJOB03 END OF LIST APPLICATION INDEX PAGE PAGE ---1 2 2
336
Suppressing fields
To suppress certain fields, use the NODISPLAY parameter. You can suppress the following fields: Field CALENDAR CLASS CPU ELAPSED EVENT HOLDCOUNT JCLDS PGMER PRED PROC RESOURCE SCOPE SUCC TAG TAPES Description Calendar name(s) Job class CPU time Elapsed execution time Event name Hold count JCL data set and member name Programmer name List of predecessor jobs ESP Procedure data set and member name List of resources Scope (externals and manuals only) List of successor jobs Tag Tape drives and mounts (both cartridge and reel)
Example
The following example suppresses the display of CPU time, elapsed execution time, and tape drives and mounts.
JOBMAP DSN('ESP.MAPGEN') NODISPLAY(CPU,ELAPSED,TAPES)
337
Producing a Job Descendent Report
Introduction
Use the JOBTREE command to produce a job descendent report. This report lists a job and all successor, or descendent, jobs. Since the JOBTREE command uses the job mapping data set as input, you can report only on jobs contained in that data set. You can use the JOBTREE command in batch, by executing PGM=ESP with the correct SUBSYS parameter, or in page mode. To use the JOBTREE command, you must specify the name of the job mapping data set, the specific name of a job, and optionally the name of an Application to which the job belongs. If you do not specify the name of an Application, ESP examines all Applications in the job mapping data set for a match and uses the first one that it finds.
Example Using JOBTREE in batch
In the following example, a Job Descendent Report is produced for job PAYJOBA. The subsystem name for ESP, 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 Using JOBTREE in page mode
The following example creates a Job Descendent Report, for job PAYJOBA, in page mode.
JOBTREE DSN('ESP.MAPGEN') JOB(PAYJOBA)
Example
In the following example, a job descendent report is produced for job START.APPL in the PAYROLL Application.
JOBTREE DSN('ESP.MAPGEN') JOB(START.APPL) APPL(PAYROLL)
338
Producing a Job Descendent Report, Continued
Reviewing the output
The report uses indentation to indicate successor relationships. A job that is indented farther than the job on the previous line indicates a successor relationship. Consider the following flow of jobs:
PAYJOBA
PAYJOBB
PAYJOBC
PAYJOBD
PAYJOBE
A Job Descendent Tree for PAYJOBA looks like the following. This indicates that PAYJOBA releases PAYJOBB and PAYJOBC, PAYJOBB and PAYJOBC release PAYJOBD, and PAYJOBD releases PAYJOBE.
JOB DESCENDENT TREE PAYJOBA JOB PAYROLL PAYJOBB JOB PAYROLL PAYJOBD JOB PAYROLL PAYJOBE JOB PAYROLL PAYJOBC JOB PAYROLL PAYJOBD JOB PAYROLL PAYJOBE JOB PAYROLL
339
Putting it All Together
Sample batch job
The following is a sample batch job to: Allocate a job mapping data set (STEP1) Generate data for the job mapping data set for all Events with descriptive names that start with P (STEP2) Generate a Job Activity report, with an index by job name, for all jobs in the PAYROLL Application (STEP3) Generate a Job Descendent report for START.APPL in the PAYROLL Application 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) JOBINDEX JOBTREE DSN('MY.MAPGEN') JOB(START.APPL) APPL(PAYROLL) /*
340
ESP FLOWDOC
Overview
ESP FLOWDOC provides the ability to generate reports detailing information about workload scheduled by ESP Workload Manager. The following outlines what 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)
Graphical representation
The entire process is represented as follows:
User Input
ESP
SAD File
CYBES090
VSAM
CYBES091
FlowDoc
341
ESP FLOWDOC, Continued
ESP FLOWDOC components
ESP FLOWDOC consists of three components: 1. ESP data generation 2. Database generation 3. Report generation
ESP data generation
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) /*
342
Database generation
The database generation step is used to create the VSAM database. The following JCL would be used to execute this utility:
//STEP1 EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DELETE DAILY.FLOWDOC CLUSTER DEFINE CLUSTER(NAME(DAILY.FLOWDOC) RECORDSIZE(64 32760) KEYS(53 0) INDEXED SHR(3 3) CYLINDERS(40 20) VOLUMES(vol_ser)) /* //STEP2 EXEC PGM=CYBES090 //STEPLIB DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK //SYSPRINT DD SYSOUT=X //SYSUT1 DD DISP=SHR,DSN=DAILY.SADGEN //SYSUT2 DD DISP=SHR,DSN=DAILY.FLOWDOC
Note: The space allocated for the VSAM database should be approximately 25% greater than the space consumed by the SADGEN data set.
343
Report generation
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 be used to generate a report:
//stepname //STEPLIB //SYSPRINT //SYSUT1 //SYSIN FLOWDOC { { /* EXEC PGM=CYBES091 DD DISP=SHR,DSN=CYBER.ESP.SSCPLINK DD SYSOUT=* DD DISP=SHR,DSN=DAILY.FLOWDOC DD * 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 can contain wild cards. If a range of dates is desired, the FROM and TO must be specified. If only a single date is desired, then DATE should be specified. Single dates and date ranges are mutually exclusive. Multiple FLOWDOC statements may be present in the input stream.
344
Report organization
The data is presented organized by subApplication with Application or Event. The jobs are shown in the order in which they will be executed. If a job is referenced as a predecessor of a job in another Application as an EXTERNAL job, the referencing job name and Application name for that job is shown provided that the referencing job is part of an Application which is already on the database. Repeated executions of an Application or Event are grouped together to eliminate redundant reporting. These repeating Applications are shown by date. If there is any variation in the sequence of jobs executed, each variation will be shown separately. For example, if an Application has a series of jobs which run daily but some which only run on Monday, a thirty day report would display twenty five executions of the Application showing all of the non-Monday jobs and four executions of the Application showing all jobs.
345
Report headings
The following shows the headings as they appear in the report, and what they mean: Heading HOLD TAG TYPE Description This field is set to Y if the ESP JOB definition statement specified the HELD keyword. This field is the first eight bytes of the job tag. This field can be one of: TASK a task MAN a manual LINK a link EXT an external job JOB a normal job This field is the expected submission time of the job. If it is blank, then the ESP SADGEN process has determined no specific time. This time reflects ESP statements, which affect submission time such as DELAYSUB. This is the job name as defined in the ESP Procedure. This is the hold count as determined by ESP. If a job does not have a hold count, i.e. no predecessor(s), then a value of 0 will be placed in the hold count field. This lists all of the jobs (two per line) which are released by this job. If a job does not have any successor(s), then (NONE) will be placed in the release field. This lists all of the resources (one per line) which are used by this job. These fields are only present for external jobs. They represent the first and second scope times in the format hh:mm where hh is the hours and mm is the minutes. This lists all of the downstream jobs, one per line, showing the Application name and the referencing job name. A downstream job is a job that references this job as an external. It may release this job or it may require this job as a predecessor.
SUB TIME
JOB NAME HC
RELEASES
RESOURCE SCOPE
SUCCESSOR
346
Sample report generation jobs
The following are examples of report generation jobs that could be used to produce ESP FLOWDOC reports:
Example 1
The following report generation JCL could be used to produce a report detailing information about the PAYROLL Application starting today ending tomorrow:
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A //STEP01 EXEC PGM=CYBES091 //STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR //SYSIN DD * FLOWDOC APPL(PAYROLL) FROM(TODAY) TO(TOMORROW)
Example 2
The following report generation JCL could be used to produce a report detailing information about an Application which is invoked be an Event called 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 report detailing information about the BILLING Application from 4pm today until 4pm 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)
347
Example 4
The following report generation JCL could be used to produce a report detailing information about the CLAIMS Application from Monday to Friday. Jobs in the CLAIMS Application that have varying run frequencies will be displayed on their respective day, i.e. jobs coded as RUN MONDAY will be displayed on Mondays run date.
//FLOWDOC JOB (ACCOUNT),'ALLOC ESP DATASETS',CLASS=A,MSGCLASS=A //STEP01 EXEC PGM=CYBES091 //STEPLIB DD DSN=CYB2.ESP451.SSCPLINK,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=CYB2.ESP451.FLOWDOC,DISP=SHR //SYSIN DD * FLOWDOC APPL(CLAIMS) DATE(MONDAY) FLOWDOC APPL(CLAIMS) DATE(TUESDAY) FLOWDOC APPL(CLAIMS) DATE(WEDNESDAY) FLOWDOC APPL(CLAIMS) DATE(THURSDAY) FLOWDOC APPL(CLAIMS) DATE(FRIDAY)
Sample JCL and report
The following example shows the report generation JCL and the report produced by that JCL.
Report generation JCL
The following report generation JCL could be used to produce a report detailing information about the PAYROLL and ACCTPAY Applications from September 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)
348
Sample ESP FLOWDOC report
The following FLOWDOC report results from the previous JCL:
APPLICATION: PAYROLL RUN DATES: FRI 12 SEP 1997 HOLD ---N N N N N N N N N N N TAG --PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL TYPE ---LINK JOB JOB JOB JOB JOB JOB JOB JOB JOB JOB SUB TIME ---22.00 20.00 20.00 20.00 20.00 20.00 20.00 20.00 20.00 20.00 20.00 JOBNAME ------START PAY1 PAY2 PAY3 PAY4 PAY5 PAY6 PAY7 PAY8 PAY9 PAY10 HC -1 1 1 1 1 4 1 1 1 3 RELEASES RESOURCE --------------PAY1 CPUABS PAY2, PAY3 PAY4, PAY5 PAY6 IMS PAY6 IMS PAY6 PAY6 PAY7, PAY8 PAY9 PAY10 PAY10 PAY10 END CPUABS SCOPE ----*** SUCCESSOR *** APPL JOBNAME ----------
ACCTPAY
ACCT1
ACCTPAY
ACCT5
349
Flowcharting
Introduction
Schedulers and operators sometimes find it helpful to have a graphical representation of the workload. Graphic flow charts make it easier to see job dependencies and to monitor the progression of work.
Creating flowcharts
You can create flow charts of workloads using the following PC based graphics software: MS Project TIMELINE.
ESP produces an input file for the PC software. This input file is then used in creating the graphic flow chart of the workload. You have the option of viewing the ESP workloads on the PC, or sending the output to the PC printer or plotter when you want a paper copy. Generation of flow charts consists of some operations on the mainframe, a PC file transfer, and some additional operations on a PC. For a real-time, graphical view of the workload, refer to the ESP Workstation Users Guide.
350
Generating Flowcharts Using MS Project
Introduction
ESPs GENPROJ feature exports data that describe an existing ESP Application in a format that can be used by PC based project management software, Microsoft Project.
Exported fields
The exported fields include: Jobname SubApplication name Start date and end date Duration Late start time and late end time Percent complete Tag.
GENPROJ feature
This section describes how to test and use the GENPROJ feature. Follow these instructions:
Step 1
Action 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 with VB or FB format and an LRECL of at least 72. Create an active ESP Application or use an Application you can display using the LISTAPPL command. If you need to create a dummy test Application, you may want to insert a built-in delay prior to the first job by using an EARLYSUB command. This ensures that the Application does not complete prior to the GENPROJ data extract. For example:
APPL TESTAPPL JOB JOB1 EARLYSUB NOW PLUS 24 HOURS RUN DAILY RELEASE JOB2 ENDJOB
351
Generating Flowcharts Using MS Project, Continued
GENPROJ feature (continued)
Step 3
Action Use the GENPROJ command to extract data from the Application. For example:
GENPROJ TESTAPPL.0 DATASET('SYS1.TESTAPPL.GENPROJ')
Download the data set (SYS1.TESTAPPL.GENPROJ) to a DOS file, like TESTAPPL.TXT, using your installations file transfer procedure. You should specify the ASCII and CRLF file transfer options. Execute the Cybermation-supplied utility CONVERT.EXE on your PC. You may need to copy this program from a diskette supplied by Cybermation. If your installation did not receive this diskette, please contact Cybermation Technical Support. At the DOS prompt, or in Windows: File Run, switch to the appropriate directory and enter: CONVERT <input file> <output file>. For example:
CONVERT TESTAPPL.TXT TESTAPPL.MPX
The extension .MPX identifies the file as an Microsoft Project file. If you enter CONVERT without operands the command syntax is displayed. Start Microsoft Project on your PC. Within Microsoft Project, open the .MPX file, for example TESTAPPL.MPX. Once the project has been opened within Microsoft Project, it can be manipulated and viewed in the same way any other project. A PERT chart displays the Application horizontally with each job shown as a box within the chart. Bold boxes identify critical path jobs. Boxes with a diagonal slash indicate that this job is complete. You should save the Application as a project file, e.g. TESTAPPL.MPP. Subsequent GENPROJ data extracts can be used to update the project status of an Application.
352
Generating Flowcharts Using MS Project, Continued
Illustration of steps 1-5
These steps are illustrated below:
APPL on APPLFILE
GENPROJ
mydsn download
mydsn.mpx MS Project mydsn.mpp
Convert
mydsn.txt
353
Generating Flowcharts with ESP and Timeline
Introduction
ESPs GENFLOW feature exports data that describes a scheduled ESP Application in a format used by the PC based project management software, Timeline. ESP uses information from a Scheduled Activity data set and exports the following fields: Jobname Start time and end time.
GENFLOW feature
This section describes how to test and use the GENFLOW feature. Follow these instructions: Step 1 Action Access ESP in Page mode. Issue the GENFLOW command, specifying two positional parameters: The name of a scheduled activity data set (SADGEN file). ESP uses this data set as input. The name of a file to which GENFLOW will write the data. If you do not specify the DCB attributes, GENFLOW sets them to: LRECL=80, BLKSIZE=3120. Issue a FLOW command for each separate flowchart you require. The FLOW command identifies a flow chart by a name of up to 7 characters. The FLOW command also identifies jobs and/or Applications to be included. After the flow commands have been entered (you can specify as many as required), type GO. ESP reads the SADGEN file and writes the output to the target file.
GENFLOW 'ESP.DAILY.SADGEN' 'CYB.PC.TRANSFER' FLOW PAYROLL APPL(PAYROLL) FLOW BACKUPS JOBS(BACK-) GO
354
Generating Flowcharts with ESP and Timeline, Continued
GENFLOW feature (continued)
Step 4 5
Action Use a PC file transfer program to send the data to a PC. On the PC, use a file editor to edit the file, as described below. Each flow command generates two sections in the file. Each section is preceded by a file identifier in the form: --ffffx.CSV where ffff is the flow ID, and x is T for TASK or D for dependencies. For the above example, you will see the following:
--PAYROLLT.CSV 100 nnn 900 .... PAYROLLD.CSV 100 -.... BACKUPST.CSV -100... -... BACKUPDS.CSV -100.. -...
6 7
Each FLOW generates a TASK section, named ffffT.CSV, and a dependency section, ffffD.CSV, where ffff is the ID on the FLOW statement. Split the file into two files for each flow. The file names should : Be called ffffT.CSV and ffffD.CSV Contain the corresponding contents of the main file, excluding the file identifier (--ffffx.CSV) line. You can now access Timeline. 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. Once the data has been analyzed, you can view the data in GANTT (spreadsheet format) or PERT (Flowchart format). To print the flowchart, use the GRAPHIC, PERT function.
355
Generating Flowcharts with ESP and Timeline, Continued
Illustration of steps 1-8
These steps are illustrated below:
SADGEN file
GENFLOW FLOW GO
mydsn
download Split file mydsn.txt
chart1t.csv chart1d.csv
Timeline mydsn.mlp
356
Job Documentation Overview
Introduction
ESPs job documentation facility lets you create a complete and centralized definition of each one of your jobs. This powerful feature allows you to document a jobs entire requirements, including its predecessors and successors, its schedule frequency, all the resources it requires, and so on. Users and operators can retrieve the job documentation information easily using the JOBINFO command or through the Consolidated Status Facility. Job documentation may also be used for informational purposes.
In this chapter
This chapter contains the following topics: Topic Contents of Job Documentation Control Information User Description Creating Job Documentation Using The Jobs Option Updating Job Documentation Using Job Documentation Using the Control Information Referencing Job Documentation Members Overriding Job Documentation Using Job Documentation for Qualified Jobs Using Job Documentation for Links and Tasks Retrieving Information Converting Existing Job Documentation Other Uses of Job Documentation See Page 358 359 360 362 363 366 367 368 370 371 372 374 376 378 381
357
Contents of Job Documentation
Introduction
A job documentation entry is a member of a partitioned data set (PDS). Each entry consists of the following information in two parts, either of which is optional: Job documentation entry Control information Explanation Information that ESP will use directly when processing a job, such as the JCL library, job dependencies, and schedule frequency. Other information you wish to store about a job. This may include ABEND codes, messages, restart instructions, job severity, and so on.
User description
Comment
Either section may include comments within /* */ pairs.
358
Control Information
Introduction
The control information comes first in your job documentation entry and follows a very specific format, as shown below:
jobname: JOBDOC
Example
For example, to specify the start of job documentation for the Job PAYJOB1 enter the jobname followed by a colon, a space and the JOBDOC keyword like this:
PAYJOB1: JOBDOC
Using CLANG and REXX
Control information uses the same job statement information you use in an ESP Procedure. You can also use CLANG and REXX within job documentation to handle conditional or complex requirements.
Example control information
Control information is specified as shown below:

PAYJOB: JOBDOC DATASET PROD.JCL.CNTL RELEASE (PAYJOB2,PAYJOB3) CCFAIL (STEP,GT,4) RUN WORKDAYS IF MONDAY(MONDAY) THEN DELAYSUB 7PM ELSE DELAYSUB 6PM
Storing requirements
You may choose to store all requirements for a job in a job documentation library. Alternatively, you can also store some requirements in ESP Procedures and others in job documentation members. For example, you may choose to use job documentation to store only the resource requirements for a job and use ESP Procedures to store scheduled frequency, job relationships, and time dependencies.
359
User Description
Introduction
The user description section of your job documentation must begin with the keyword USERDESC as a heading. After that, the rest of the data can be formatted as you choose. You can divide the user description section into paragraphs and identify each paragraph with a label. This will allow you to retrieve selected information by label name. ESP supplies the following standard labels: ESP Label FUNCTION PROGRAMMER ABENDS Use this Label to Describe what the job does. Identify the programmer of the job Identify ABEND codes and recovery activity. A number sign (#) may precede each ABEND code. This lets you request display information about a specific ABEND code when retrieving information with the JOBINFO command. Identify message codes and recovery activity. A number sign (#) may precede each message ID code. This lets you request display information about a specific message ID when retrieving information with the JOBINFO command.
MESSAGES
Customized labels
You can use any of your own labels as long you observe the following guidelines: A label consists of a word, 1-16 characters long, followed by a colon and at least one blank. A label must be the first entry on a line. A label can precede any type of information, such as report distribution information, severity codes, and escalation procedures. Each paragraph ends with the next label or the end of the PDS member. You can specify as many labels as you wish.
360
User Description, Continued
Example
In the example below, the USERDESC keyword identifies this as the user description area of job documentation. Each of the five user description paragraphs begins with a label (i.e. FUNCTION, PROGRAMMER, ABENDS, MESSAGES, SEVERITY) followed by a colon (:).
USERDESC FUNCTION: sort and merge payroll files PROGRAMMER: joan smith ABENDS: #SB37 space problem - double space requirements and restart job from failing step MESSAGES: #AC101 number of available accounts <50 warning #Z001 user not authorized SEVERITY: 3
361
Creating Job Documentation
Introduction
Create one entry for each job you want to document. Use a member name equal to the jobname; otherwise you will need to override this in an ESP Procedure. To create job documentation, use either ISPF edit or the Jobs option of the ESP Main Menu
362
Using The Jobs Option
Introduction
The Jobs Option (Option J on the Main Menu) provides panels for creating job documentation members. These panels do not provide fields for all possible data, but they can assist you in specifying some of your requirements. You can then add to these requirements using ISPF edit.
Creating a job documentation member
Follow these steps to create a job documentation member for a job:
Step 1
Action Select Option J Note: The first time you select this panel, you must specify the name of the pre-allocated PDS file to store job documentation. This PDS then becomes your default. Complete the jobname and other control information on the Job Specifications screen, as shown below.
363
Using The Jobs Option, Continued
Step 3 4
Action Enter 1 on the command line to access the Job User Description panel. Complete any user description information, as shown below.
If you have DJC or JES3 installed you can enter 2 on the command line to define DJC/JES3 specifications. Refer to the Advanced Users Guide for more information. Press PF3 twice to return to the Main Menu.
364
Using The Jobs Option, Continued
Result
You have now created and stored job documentation. ESP stores the information in a member of the job documentation PDS with the same name as the jobname. The information is stored as shown below.
PAYJOB1: JOBDOC DATASET PROD.JCL.CNTL RELEASE (PAYJOB2,PAYJOB3) CCFAIL (STEP1 GT 4) USERDESC FUNCTION: sort and merge payroll files PROGRAMMER: joan smith ABENDS: #SB37 space problem - double space requirements and restart job from failing step MESSAGES: #AC101 number of available accounts <50 - warning #Z001 user not authorized
Points to note about the example shown
In this example, notice the following: The first line identifies the 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.
365
Updating Job Documentation
Introduction
You can return to the PDS member where your job documentation entry resides and update the information using either ISPF edit or the ED command from the Consolidated Status Facility. Note: Do not use the Job Specifications panel (Option J) to update existing job documentation. This option is only for initially setting up your documentation. When you try to use this panel to update an existing entry, you will receive an error message indicating the member already exists.
Updating the previous example
For example, you could update the previous example to: Insert IF-THEN-ELSE statements to allow for different delayed submission times Insert a RUN statement to identify the jobs frequency Add a user field to identify the jobs severity.
Resulting job documentation
The job documentation now looks like this:

PAYJOB1: JOBDOC DATASET PROD.JCL.CNTL RELEASE (PAYJOB2,PAYJOB3) CCFAIL (STEP1 GT 4) RUN WORKDAYS IF TODAY(MONDAY) THEN DELAYSUB 7PM ELSE DELAYSUB 6PM USERDESC FUNCTION: sort and merge payroll files PROGRAMMER: joan smith ABENDS: #SB37 space problem - double space requirements and restart job from failing step MESSAGES: #AC101 number of available accounts <50 - warning #Z001 user not authorized SEVERITY: 3
366
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.
367
Using the Control Information
Introduction
To use the control information directly, you must use the DOCLIB statement in an ESP Procedure. This statement identifies the name of your job documentation library.
ESP Procedure
The ESP Procedure below shows a DOCLIB statement pointing to the library, CYBER.JOBS.DOC, that contains documentation on jobs specified in this Procedure.
APPL PAYJOBS JCLLIB CYB.JCL.CNTL DOCLIB CYBER.JOBS.DOC JOB PAYJOB1 JOB PAYJOB2 JOB PAYJOB3 ENDJOB
ESP then uses the job documentation information to establish dependencies and any other requirements. To invoke this Procedure, use an INVOKE command in an Event.
368
Using the Control Information, Continued
Relationship with Event and Procedure
The diagram below shows the relationship between an Event, an ESP Procedure and a job documentation library. When ESP executes the Event, the INVOKE command invokes the ESP Procedure. The DOCLIB statement in the ESP Procedure identifies the name of the job documentation library. ESP retrieves the job documentation (if it exists) for each job identified by a JOB statement. This includes jobs submitted as part of the ESP Procedure, links, tasks, qualified jobs, external jobs, and manual jobs.
Job Documentation Library
A: JOBDOC RUN DAILY RELEASE B
ESP Procedure Event

INVOKE . . . DOCLIB . . . JOB A
369
Referencing Job Documentation Members
DOCMEM keyword
ESP retrieves job documentation by jobname. If you wish to reference a job documentation member with a name other than the jobname, use the DOCMEM 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)
370
Overriding Job Documentation
Introduction
Job information can be specified in different places. This includes ESP Procedures, job documentation, and tracking models. As a result, it is possible to have conflicting information specified for a job. Therefore, you must ensure ESP knows which information to use.
Rules
ESP uses the following rules: Type of information ESP Procedure information Job documentation information overrides corresponding job documentation information. tracking model information.
Example
For example, if you specify a HISTFILE as below, it overrides the HISTFILE specified in a tracking model for the job.
APPL PAYJOBS DOCLIB CYBER.JOBS.DOC JCLLIB CYBER.JOBS.JCL JOB PAYJOB1 HISTFILE HIST2 RUN DAILY ENDJOB
Temporary override
You can temporarily override the control information specified in job documentation from within an ESP Procedure by specifying the new control information you want to use. In this example, the RELEASE statement for PAYJOB1 overrides any RELEASE statement specified in the job documentation for the job.
DOCLIB CYBER.JOBS.DOC APPL PAYJOBS JOB PAYJOB1 RELEASE NEXTJOB ENDJOB
371
Using Job Documentation for Qualified Jobs
Job qualifier
ESP uses the 8-character jobname to access job documentation. If you wish to use job documentation for jobs defined with a job qualifier, you can do one of the following: Use the DOCMEM keyword when you define the job in the ESP Procedure and specify the name of the member used for the jobs documentation. Use IF-THEN-ELSE logic in the job documentation member to check the qualifier of a job and process different statements. Use the ESPAPQUAL symbolic variable for jobs in an Application. Use the ESPJQUAL variable for jobs in a DJC/JES3 network.
Each approach is illustrated below.
DOCMEM method
This method shows you how you use different job documentation members for different qualified versions of a job. Job A.RUN1 references member A1; job A.RUN2 references member A2.
JOB A.RUN1 DOCMEM(A1) JOB A.RUN2 DOCMEM(A2)
IF-THENELSE method
This method uses a common job documentation member for Job A. ESP processes different statements based on the job qualifier. If the qualifier is RUN1, the job runs daily and releases Job Y. If the qualifier is RUN2, the job runs on workdays and releases Job Z. Visually, the dependencies look like this:
A.RUN1
A.RUN2
372
Using Job Documentation for Qualified Jobs, Continued
Job documentation member
The job documentation member looks like this:

A: JOBDOC IF ESPAPQUAL=RUN1 THEN DO RUN DAILY RELEASE Y ENDDO IF ESPAPQUAL=RUN2 THEN DO RUN WORKDAYS RELEASE Z ENDDO
373
Using Job Documentation for Links and Tasks
Introduction
You can use job documentation for links and tasks that you have identified in an ESP Application.
Example: Documenting links and tasks
In this example, the Application consists of a job, a task, and a link. The Application identifies their names and the job documentation library contains the processing requirements, as shown below:
Example: Documenting a job and a link
This example uses job documentation to store resource requirements. In this Application there are two jobs: MEMOBACK and MEMOBACK.MSG. The specifications are that: The first job requires 1 unit of a resource called DB2TAB The second job is a link that sends a message when job MEMOBACK completes successfully.
374
Using Job Documentation for Links and Tasks, Continued
IF statement
ESP uses the same job documentation member for each job since it does not check the qualifier when accessing job documentation. In order to prevent the link from using the resource, the job documentation member for MEMOBACK uses an IF statement to assign a resource requirement to the unqualified job only. The ESP Procedure and job documentation member look like this:
ESP Procedure
DOCLIB `CYBER.JOBS.DOC' JCLLIB `CYBER.JOBS.JCL' APPL MEMO JOB MEMOBACK RUN WORKDAYS RELEASE MEMOBACK.MSG JOB MEMOBACK.MSG LINK PROCESS RUN WORKDAYS SE `MEMOBACK IS DONE' U(*) ENDJOB
Job Documentation Member

MEMOBACK: JOBDOC IF ESPAPQUAL=`' THEN + RESOURCE (1,DB2TAB)
375
Retrieving Information
Introduction
You can retrieve job documentation information using the Consolidated Status Facility (CSF), or the JOBINFO (JI) command from the operator console, the ESP command processor, or ISPF interface (Line mode or Page mode). You can display all information for a job or display selected information as identified by fields and labels.
Using CSF
You can access job documentation information directly from CSF with the following commands. Command BD ED Explanation Browse job documentation Edit job documentation
ESP retrieves the information from the data set identified by the DOCLIB statement in an ESP Procedure. Using this method ESP retrieves all information on the job. You cannot select individual fields.
Using TSO
If a job is submitted by an ESP Procedure, ESP searches the job documentation library identified by the DOCLIB statement. If a job documentation library was not identified in the ESP Procedure, or the job was not scheduled from an ESP Procedure, the JOBINFO command looks for the file name JOBDOC. If the file is allocated, it is opened and searched for a member corresponding to the jobname. The JOBDOC file may consist of a concatenation of several partitioned data sets. To use the JOBINFO command in TSO you must pre-allocate a file to your TSO session, either in LOGON procedure or LOGON CLIST. You can dynamically allocate this file during a session by issuing the following TSO command:
ALLOC FI(JOBDOC) DA(data set name) SHR
Using an operator console
The console version of the JOBINFO command requires the JOBDOC file in the ESP started task procedure. You can issue the following commands from an operator console, or from Page mode, respectively:
F ESP,JOBINFO jobname or OPER JOBINFO jobname
376
Retrieving Information, Continued
Examples: Retrieving job documentation information
Some examples of retrieving job documentation are shown below. To display all information about PAYJOB1, type: To display ABEND information for PAYJOB1 as well as the contents of the user defined field SEVERITY, type: To display PAYJOB1s successor (RELEASE) and JCL data set (DATASET) information, type:
JOBINFO PAYJOB1
JI PAYJOB ABENDS FIELD(SEVERITY)
JI PAYJOB1 RELEASE DATASET
Retrieving job documentation information
The following table summarizes where and how you can retrieve job documentation information:
Origin Command BD or ED Consolidated Status Facility Page mode or line mode JOBINFO
Retrieved from Library specified in the ESP Procedure DOCLIB in ESP Procedure or JOBDOC DD allocated to your TSO session Page mode or line mode OPER JOBINFO JOBDOC DD allocated to the ESP started task F ESP,JOBINFO JOBDOC DD allocated to the Operator console ESP started task
377
Converting Existing Job Documentation
Methods for converting documentation
You may already use some form of job documentation other than ESPs that you would like to convert. There are two methods for converting documentation. The method you use depends on how you want to use your existing job documentation. If you want to use ESP to retrieve your existing job documentation in its present format, you can insert a USERDESC label in each job documentation member. If you want ESP to modify the data to allow retrieval of information by label name, you can use the GENDOC command.
Retrieving existing job documentation
In order to retrieve your existing job documentation through ESP, follow these steps: Step 1 Action Update each member to include the USERDESC heading at the beginning of the information. An example is shown below: Before:
THIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH. FREQUENCY: LAST WORKDAY OF THE MONTH
After:
USERDESC THIS JOB PRINTS THE SALARY INCREASES FOR THIS MONTH. FREQUENCY: LAST WORKDAY OF THE MONTH
Allocate the job documentation file(s), with the DD name of JOBDOC, to your TSO session or to the ESP started task. This enables you to use the JOBINFO command to extract information.
378
Converting Existing Job Documentation, Continued
Introduction
You can convert an existing PDS job documentation library into an ESP documentation library using the GENDOC command in Line mode, Page mode 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 make when the old documentation converts.
Commands
You can use the following commands: Command Explanation REMOVE Identifies lines that are not to be copied to the output data set. LABEL Alters or replaces lines in the output data set, or inserts lines at different locations. GO Indicates that all specifications are complete and that the copy process should proceed
New data set
For each selected member of the input data set, ESP generates a corresponding member in the output data set. ESP automatically adds the following two lines to each member of the new data set:
jobname: JOBDOC USERDESC
GENDOC can insert appropriate paragraph labels in the converted user description section to allow retrieval of information by label.
379
Converting Existing Job Documentation, Continued
Example: Using GENDOC to convert job doc.
Below is a set of sample conversion instructions for ESP:

GENDOC JOBDOC.DATA ESP.JOBDOC.DATA LEV(A-,B-) SNUM REMOVE ** LABEL SYSOUT REVIEW SYSOUT_REVIEW INLINE LABEL RESTART PROCEDURES RESTART: BEFORE GO
The above example tells ESP to: Copy all members beginning with A and B from the data set JOBDOC.DATA to the data set ESP.JOBDOC.DATA, suppressing any line numbers in the right-hand 8 columns of each source member record. Not copy any lines containing **. Replace any lines starting with SYSOUT REVIEW with the character string SYSOUT_REVIEW. Overlay the semicolon on any line beginning with STEP. The semicolon is positioned after the 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 the end of the conversion
ESP issues the following message at the end of the conversion to indicate the number of members in the input and output data sets.
ESP000 nnn MEMBERS IN SOURCE DATASET, mmm MEMBERS PROCESSED
380
Other Uses of Job Documentation
Introduction
You can use ESPs job documentation facility for more than just jobs. You can also create documentation libraries for documenting such items as: Startup and shutdown procedures Telephone numbers Trouble shooting procedures.
Remember to allocate the JOBDOC file and use proper labels.
Example: Storing phone numbers
This example shows you how to use a job documentation member to list phone numbers for software support. A label identifies the name of each product so that you can retrieve the information easily.
USERDESC /* LISTS PHONE NUMBERS FOR SOFTWARE SUPPORT */ ESP: REGULAR (905) 479-4611 AFTER HOURS (416) 287-5021 CICS: (905) 123-4567 . . .
If you call the above member SUPPORT, you can retrieve support phone numbers for ESP by typing the following:
Input JI SUPPORT FIELD(ESP) Output ESP: REGULAR (905) 479-4611 AFTER_HOURS (416) 287-5021
381
382
Using Resources Overview
Introduction
You can ensure that jobs in an ESP Application are submitted only when all of their resource requirements are met. Because you do this without the need for manual intervention, there are no unnecessary delays before a job starts. ESPs Resource feature allows you to automate resource management. Note: Before you start to use ESPs Resource features, your Systems Programmer needs to define a resource data set called the RESFILE, and specify the CPUs and nodes in your environment. If you want ESP to make default resource assignments, the RESDFLT initialization statement must also be specified.
In this chapter
This chapter contains the following topics: Topic What is a Resource? Types of Resources Scope of Resources Using Real Devices Routing Jobs to Other Systems Managing Jobs Requesting Resources Default Resources Working with Resources Defining Resources Setting Resources Deleting Resources Displaying Resource Information Step-level Resource Release Resource Absorption Example: Controlling Mutually Exclusive Jobs Example: Controlling Access to an Online System Example: Time Periods for Low Priority Jobs Example: Using a Resource for a Self-completing Task Example: Controlling Access to a Database See Page 385 386 387 388 389 390 391 396 398 399 401 402 403 405 407 410 412 414 416 417
383
Overview, Continued
In this chapter (continued)
Topic Example: Running Jobs on a Particular System Example: Controlling Mutually Exclusive Groups of Jobs Example: Planning for a System Shutdown - Part 1 Example: Planning for a System Shutdown - Part 2 Example: Schedule Dependency
See Page 418 420 424 426 428
384
What is a Resource?
Definition of a resource
A resource is any type of real or abstract object that impacts a jobs ability to run successfully and can be quantified. Resources are classified by resource type and by scope.
Examples of resources
Some examples of resources are: Tape drives Scratch tapes Online systems Databases Time periods The completion of a job.
385
Types of Resources
Three types of resources
ESP resources are classified into three types. They are: Renewable Depletable Threshold.
Renewable resource
A renewable resource is a borrowed resource. When a job is submitted by ESP, the job removes the resource from the resource pool. However, the resource is not permanently used up. Instead, it is returned to the resource pool at the end of execution, whether successful or not. In other words, the job temporarily borrows the resource to allow it to execute successfully. For example: A renewable resource can be used to control concurrent access to a database.
Depletable resource
A depletable resource is a consumed resource. When a job is submitted by ESP, the job removes the resource from the resource pool, and does not return it at the end of execution. The resource is used up and can only be replenished through an explicit action, such as issuing an appropriate ESP command. The job 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 pool when a job writes a permanent data set onto it.
Threshold resource
A threshold resource is a sizing resource. A job does not actually remove the resource from the pool of resources while it executes. You can think of a threshold resource as a variable height doorway into the system. If the resource quantity is set to 2, any number of jobs requiring 2 or less units are submitted. However, any job requiring 3 or more units are too high to pass through the door and so are not submitted. ESP sizes the job against the current level of the threshold resource. For example: A threshold resource can be used to represent elapsed time and limit the size of jobs entering the system. This allows you to prevent long-running jobs from being submitted just before scheduled downtime.
386
Scope of Resources
Resource levels
You can classify the scope of the resources you define according to the following resource levels: Type of resource Local Resource Global Resource Enterprise Resource Explanation Each processor maintains an individual counter for the resource. The resource availability counter is shared among all processors within a node. The resource availability counter is shared among all nodes. This type has a true meaning only when one ESP system submits the work for all nodes.
387
Using Real Devices
Overview
A real resource represents an actual hardware device. It is normally used for tape transports. The limitation is that they can work properly only in a single CPU environment. There is no capability to be aware of the status of devices on 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 control blocks for the resources. Then ESP counts how many of the UCBs (unit control 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 seconds or minutes before the job actually allocates the UCB. ESP ensures that it does not over-allocate a resource when scheduling jobs that require it. ESP uses an effective available count that is the lower of the following values: real value and the available count maintained by ESP.
Example
For example, if a job requires three units of a real resource, and ESPs available count is three, ESP waits for the resource if there are only two devices actually online and unallocated.
388
Routing Jobs to Other Systems
Overview
In a multiple CPU environment, a job may require a mix of resources that are not available on the ESP system submitting the job. However, these resources may be available on another processor, either on the current node or on a remote 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 job is routed to the required node or processor. The JCL ESP uses to route jobs is specified as part of the NODE and CPU definitions in your ESP Initialization Parameters. 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 job needs is on SYSB, ESP routes the job to SYSB. If these systems are within the same JES node, ESP submits the job and inserts a /*JOBPARM SYSAFF=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 resources required by the job has the GRAVITY attribute in its definition. ESP can cause a job to be routed to another CPU within the same node regardless of the GRAVITY setting.
389
Managing Jobs
Overview
When the Application Manager readies a job for submission, it checks to see if the job has requested any resources. If so, the Application Manager passes the job to the Resource Manager component. The Resource Manager submits the job when the required resources become available. If all of a jobs resource requirements cannot be met, ESP does not submit the job.
Multiple resources
If a job requires multiple resources, or multiple units of a single resource, and all of these resources are not available when the job is readied for submission, ESP does not hold on to any resources. As soon as another job ends that is using a resource this job needs, or the resource status changes in any way - for example, by the RESDEF command being issued - the job is rechecked for submission.
Renewable resources
If a job is using a renewable resource, the resource is taken when the job is submitted and is freed up as soon as the job ends, whether it is successful or not. A failed job, by default, has the same resource requirements upon restart as at submission time.
390
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 can be done at an Application level or at a job level. An individual job can request any number of different resources. You can use resources for jobs and tasks, but not for links.
Statements
When you specify resource requirements, there are two statements you can use: The RESOURCE statement The PRIORITY statement.
Using the RESOURCE statement
Use the RESOURCE statement to identify resource requirements. In parenthesis, specify the number of units required, followed by the resource name. 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 resource specifications together. For example, if your requirements are one unit of the resource called CICS and two units of a resource called SCRATCH, specify:
RESOURCE (1,CICS,2,SCRATCH)
Placing the RESOURCE statement
When you use a RESOURCE statement within an Application to provide specific resource information for an individual job, you place the statement between the JOB ... ENDJOB pair. The RESOURCE statement then affects only that individual job. It also overrides any resources that occur before the JOB ... ENDJOB pair. If the RESOURCE statement is specified outside the scope of a JOB ... ENDJOB pair, the RESOURCE statement applies to the jobs that follow until a new RESOURCE statement, outside the scope of a JOB statement, occurs. Jobs inserted into an Application after it has been generated do not inherit any resource requirements.
391
Requesting Resources, Continued
Example: Requesting resources
In the following example, all jobs in the Application require 1 unit of the NITESHFT resource except job A that requires 1 unit of the CICS resource.
APPL ABC JCLLIB 'CYB.ESP.JCL' RESOURCE (1,NITESHFT) JOB A RESOURCE (1,CICS) RUN DAILY ENDJOB JOB B RUN DAILY ENDJOB JOB C RUN DAILY ENDJOB
Adding resource requirements
The ADD keyword on the RESOURCE statement allows you to specify resources in addition to the resource requirements already specified for a job or the Application. You use it by specifying RESOURCE ADD, the number of units, and then the resource name.
Example
In the following example, job A needs 1 unit of the CICS resource in addition to 1 unit of the NITESHFT resource:
RESOURCE (1,NITESHFT) JOB A RESOURCE ADD(1,CICS)
392
Dropping resource requirements
The DROP keyword on the RESOURCE statement specifies that one or more resource requirements are dropped for the jobs that follow, until a new RESOURCE statement occurs either within a JOB ... ENDJOB pair, or outside the scope of a JOB... ENDJOB pair. You use it by specifying RESOURCE DROP and then the resource name, like this:
RESOURCE DROP(T3420) RESOURCE DROP(CICS,T3420)
To free a job from any resource dependency (except default resources) you specify:
RESOURCE DROP
Example
In the following example, job ABC requires 1 unit of the LOWPRIO resource and 2 units of the IMS resource. If the scheduled day is Friday, the LOWPRIO requirement is removed.
JOB ABC RUN DAILY RESOURCE (1,LOWPRIO,2,IMS) IF TODAY('FRIDAY') THEN RESOURCE DROP(LOWPRIO) ENDJOB
Dropping default resources
You cannot drop default resources using the DROP keyword. Instead, you must request 0 units of the default resource to indicate you do not want to use the default resource for a job or group of jobs.
Example
In the following example, job ABC does not have the ELAPSED default resource assigned to it and has a requirement for 1 unit of CICS.
JOB ABC RESOURCE (0,ELAPSED,1,CICS) ENDJOB
393
Using the PRIORITY statement
You can use the PRIORITY statement in a job definition to specify the relative priority of the job within an ESP group. The maximum value is 99; the lowest priority value, and the default, is 0. This allows you to prioritize jobs within one group without the possibility of delaying 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. The queuing sequence of jobs in other groups is not affected. PRIORITY only applies 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 CYBER PROD.nnn identifies jobs in the PROD group. For instance, a job that is assigned a priority in a group called CYBER is compared only to other jobs in the CYBER group, and not to jobs in another group called PROD.
Example: Setting priority
The following example sets a priority of 99 for job BIGJOB. ESP queues this job ahead of other jobs from the same group when these jobs are waiting for the MSTRFILE resource.
JOB BIGJOB PRIORITY 99 RESOURCE (1,MSTRFILE)
394
Example: Setting priority
The following example sets a different priority for jobs B, C and D. Each job requires 1 unit of a renewable resource called MSTRFILE. When job A completes, 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 10 JOB C RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 20 JOB D RUN DAILY RESOURCE (1,MSTRFILE) PRIORITY 30 ENDJOB
395
Default Resources
Introduction
ESP can determine some of the significant resource requirements that a job might have by looking at the jobs run history. If required, ESP can then make default resource assignments automatically.
Default assignments
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 a default assignment
The information used to assign default resources is based on information contained in ESPs Job Index file. ESP bases the default resource levels that it assigns on an average of the samples found in the Job Index. The number of samples depends on the index count specified when the jobs tracking model was defined. Only information from normal job completions, and not from abends, is used. The information is updated each time a new generation of an Application is created.
Default resources
To set up default resources, you need to take these steps:
Step 1 2
Action Use the RESDFLT initialization statement in the ESP Initialization Parameters to identify the default resource you want to use. Issue the RESDEF ADD command to define the default resource.
396
Default Resources, Continued
Example: Default scratch tape resource
The following ESP initialization statement causes ESP to use a default resource 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 requirements to each job in an Application when it creates a generation of that Application.
Effecting Applications
Each Application ESP creates uses default resources you have set up. In an Application you can code RESOURCE (0,resname) if you do not want ESP to assign default resources for a job, or for an Application.
397
Working with Resources
RESDEF command
You define, display, set, and delete resources using the RESDEF command. In a multiple CPU environment, you must issue the RESDEF command from a master ESP system. This is normally the same system on which your Applications are built. Note: Your ESP administrator needs to grant you the necessary access for these functions. The following sections describe how to define and work with resources. Refer to the Examples section later in this chapter for more examples of using resources.
398
Defining Resources
Introduction
Once you define a resource, the definition is stored in an ESP file, called the RESFILE. This information is saved across restarts of ESP unless ESP is restarted with the RESFORM option. Resource definitions are normally stored in the ESP Initialization Parameter data set, or another data set that ESP reads at startup time.
Defining a resource
Use the RESDEF command to define a resource. When you define a resource, you need to: Step 1 2 3 4 5 6 7 Action Name the resource, using up to 8 alphanumeric characters, the first of which must be a letter. Use the ADD keyword to indicate you are adding a resource. Indicate the scope as local, global, or enterprise. Indicate the type as renewable, depletable, or threshold. Indicate if the resource corresponds to a real device and specify the IBM generic or esoteric Unit Name for the device. Indicate the CPU to which the resource applies, if it is a local resource and you have more than one CPU. Specify the maximum and available quantities associated with the resource. For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. Maximum is the total quantity of the resource that exists; available is the current quantity.
Indicate whether or not the resource has gravity. This allows a job to be routed to another node if the resource is not available on the node on which the job was submitted.
Example: Defining a renewable resource
This example defines a resource called DATABASE. It is a global, renewable resource with maximum and available quantities of 1.
RESDEF DATABASE ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)
399
Defining Resources, Continued
Example: Defining a threshold resource
This example defines a resource called CICSUP. It is a local, threshold resource on SYSA with an availability count of 1.
RESDEF CICSUP ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(1)
Defining a real resource
A real resource is one that is associated with an actual hardware device. This is normally a tape transport. ESP looks at the number of online, unallocated devices to satisfy a jobs real resource requirement.
DEVICE parameter
To define a real resource, use the DEVICE parameter, on the RESDEF command, to specify a valid MVS device name (i.e., legal value for the UNIT= keyword in JCL). The unit name can be a generic, such as 3480, or an installation-defined esoteric such as TAPE. Real resources should be defined as local and renewable. Use the MAX parameter to identify the number of devices available to ESP submitted jobs.
RESREFR command
ESP supplies the RESREFR command to refresh resource status. This may be required when you change the environment. For example, if a job is waiting for tape drive resources and you vary more online, ESP is not immediately aware of this. The RESREFR command causes ESP to look at the environment and refresh the status of real resources.
Example: Defining a real resource
This example defines a resource called T3480. It is a local, renewable, real resource that represents a device type of 3480. There is a maximum of 20 of these devices.
RESDEF T3480 ADD LOCAL RENEWABLE DEVICE(3480) MAX(20)
400
Setting Resources
Changing a resource
Use the SET keyword on the RESDEF command to change the scope or the quantity of a resource. You cannot change the type of a resource without deleting and redefining it. For depletable and threshold resources, there is only one quantity. You can specify either maximum (MAX) or available (AVAIL). For renewable resources, there are maximum and available quantities. If you set the maximum, the available count changes. Setting the available count has no effect on the maximum count.
Example
This example sets the available quantity of the resource LOWPRIO to 1.

RESDEF LOWPRIO SET AVAIL(1)
Setting quantities automatically
For some resources you might want ESP to set the quantity for you automatically. For example, you might have a resource called CICSUP to represent that a started task called CICS is active. You can use ESP to automatically set the quantity of the resource to indicate the availability. Refer to Job Monitoring and Alert Processing in the Advanced Users Guide for more information.
401
Deleting Resources
Deleting a resource
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.
402
Displaying Resource Information
CSF and ESP commands
You can display information about a resource using the Consolidated Status Facility and ESP commands.
Using the Consolidated Status Facility
Using CSF, you can use the LR command for a job to display the resources associated with that job, and determine what jobs have resources allocated. If a job is awaiting resources, the status field in CSF states waiting for resources, and the PNODE field in CSF states RESWAIT. In the following example, the LOCKOUT resource is displayed to determine what jobs are using the resource and what jobs are waiting for the resource.
Resource LOCKOUT List Own Wait Resource LOCKOUT Global Renewable 1 needed by PAYJOBD, Appl PAYROLL.396 TORONTO * Max=1 Avail=0 1 used by BILLJOBA, Appl BILLING.293
You can drop resource dependencies using the DR command.
Using the RESDEF command
Use the LIST keyword on the RESDEF command to display one or more resources. The display shows the name of the resource, the type of resource, and the quantities associated with the resource. You can also display the jobs using the resource and the jobs needing the resource. This example displays the CICSUP resource. It is a local, threshold resource with an available count of 1 on CPU1 and an available count of 0 on CPU2.
RESDEF CICSUP LIST Resource CICSUP NODE1 CPU1 NODE1 CPU2 Local Threshold Avail=1 Avail=0
The following command is used to display all resources.

RESDEF LIST
403
Displaying Resource Information, Continued
Using the LISTAPPL command
The LISTAPPL (LAP) command displays resource requirements for jobs not yet submitted in an active Application. Sample output might look like this:
LAP TURNOVER.14 ALL APPL 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
404
Step-level Resource Release
Introduction
Step-level resource release allows you to return resources back to the resource pool at job step-end. Previously, resources would remain allocated to a job for the duration of the job.
Description
Step-level resource release is achieved by the use of a new STEPEND statement. STEPEND is coded within the scope of the job statement. You may release part or all of the resources back to the resource pool. You can have more than one STEPEND statement in one job.
Types of resources
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 stepname procstep n1,resname
Description Indicates the name of the job step. Indicates the name of the proc step. Indicates the quantity and name of the resource to be released.
405
Step-level Resource Release, Continued
Example Stepend statement
The following example shows releasing one unit of a resource after STEP1, PROCA finishes:
APPL ONE JCLLIB CYBER.JCLLIB.CNTL JOB JOBA RUN DAILY RESOURCE (6,T3480) STEPEND STEPNAME(STEP1) PROCSTEP(PROCA) RELRES(1,T3480) ENDJOB
The following example shows releasing two more units of the same resource later in the same job:
APPL ONE JCLLIB CYBER.JCLLIB.CNTL JOB JOBA RUN DAILY RESOURCE (5,T3480) STEPEND STEPNAME(STEP3) PROCSTEP(PROCB) RELRES(2,T3480) ENDJOB
Ensure the stepnames and procsteps you specify match your JCL exactly. You can release resources by specifying just a procstep and not a stepname, if that is how your JCL is tailored.
Note
Step-level Resource Release only works if USERMOD 11 is off. When USERMOD 11 is on, the Application Manager does not get step-end notification.
406
Resource Absorption
Introduction
In ESP Workload Manager Version 5 Release 1, jobs that required a large resource count would encounter processing delays as jobs with low resource requirements would continually grab the resource, thus keeping the overall available resource count low. In ESP Workload Manager Version 5 Release 2, Resource Absorption reserves the resources that are available at the time the job is next in the queue and holds them while waiting to accumulate the remainder of resources required for that job. Jobs with smaller resource requirements can not use the reserved resource.
Description
The ABSORB statement will only ABSORB resources if the request is for less than or equal to the maximum resource defined. An ABSORB statement is coded within the scope of the job, above the RESOURCE statement, where Absorption is to occur. ABSORB can also be used at the Application level.
Priority jobs
A job with a higher priority and the same resource requirements will take the resources and run before the lower priority job with the ABSORB statement. Once the higher priority job completes, or has the resources it needs, the process of gathering resources starts again.
407
Resource Absorption, Continued
Example Absorb statement
The following example shows coding an ABSORB statement within the scope of the job:
APPL ABSRES JCLLIB CYBER.JCLLIB.CNTL JOB JOBX RUN DAILY ABSORB RESOURCE (4,T3480) ENDJOB
When JOBX is first in the queue, the Resource Manager begins the process of reserving the required resources, 4 units of T3480. Jobs that follow JOBX in the queue that require less than or equal to the same resource, and are the same job priority, will not be submitted before JOBX.
Types of resources
Absorption is available for the following types of resources: Renewable Depletable.
Example Application with Absorption
The following example shows an Application with an Absorb statement:

APPL ABSRES JCLLIB 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) ENDJOB SELECT (A,B,C,D,E,F) Continued on next page
408
Resource Absorption, Continued
Example continued Application with Absorption
The following example shows the CSF display of Application ABSRES:

Jobname A B C D E F APPL ABSRES ABSRES ABSRES ABSRES ABSRES ABSRES GEN 10 10 10 10 10 10 Pnode EXEC EXEC EXEC RESWAIT RESWAIT RESWAIT Status EXECUTING STEP2 EXECUTING STEP1 EXECUTING STEP1 Waiting for Resources Waiting for Resources Waiting for Resources
Example continued Application with Absorption
The following example shows the current resource allocations:

Resource Resource ABSRES ABSRES List Own Wait Global Renewable 3 needed by D, Appl ABSRES.11 1 needed by E, Appl ABSRES.11 1 needed by F, Appl ABSRES.11 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
TOR1
409
Example: Controlling Mutually Exclusive Jobs
Introduction
In this example, a renewable resource controls the execution of two jobs so that 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 B
Waiting for Resource
Setting -up mutually exclusive jobs
Take the following steps to set this up:
Step 1
Action Define a global, renewable resource with maximum and available quantities of 1.
RESDEF DB2TAB1 ADD GLOBAL RENEWABLE MAX(1) AVAIL(1)
Specify, in the Application in which each job is defined, a requirement of 1 unit of the resource. For example:
JOB A RESOURCE (1,DB2TAB1) JOB B RESOURCE (1,DB2TAB1)
410
Example: Controlling Mutually Exclusive Jobs, Continued
Result
At any time there is either 1 unit of the resource available, or no units of the resource available. If, for example, job A is executing, the available count of the resource is 0 and ESP prevents job B from executing. ESP returns the resource to the system upon completion (successful or not) of job A.
Extending this example
You can extend this example to any number of jobs. If you need to control mutually exclusive groups of jobs, see the example later in this chapter.
411
Example: Controlling Access to an Online System
Introduction
This example uses a renewable resource to control the maximum number of concurrent job executions. The criteria for this example are: Access to an IMS region is limited to a small number of jobs at any one time Job A and either job B or job C can execute at the same time Jobs B and C cannot execute at the same time.
Visually, the requirements look like this:
1,IMS
A B C
IMS 3
2,IMS 2,IMS
Take the following steps: Step 1 Action 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)
412
Example: Controlling Access to an Online System, Continued
(continued)
Step 2
Action In an Application, specify the number of units each job requires. For example, Job A B C RESOURCE Statement RESOURCE (1,IMS) RESOURCE (2,IMS) 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.
413
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 1 Action Define a threshold resource with an available quantity of 1. The name of the resource is LOWPRIO.
RESDEF LOWPRIO ADD GLOBAL THRESHOLD AVAIL(1)
For each low priority job, identify a resource requirement of 1 unit of the resource, like this:
JOB ABC RESOURCE (1,LOWPRIO)
Set up two Events: one to set the quantity of the resource to 0, and the other to set the quantity of the resource to 1. The Events look like this:
EVENT ID(OPER.SET_LOWPRIO_ON) SCHEDULE 9AM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(1)' ENDDEF EVENT ID(OPER.SET_LOWPRIO_OFF) SCHEDULE 4PM WORKDAYS VS 'F ESP,RESDEF LOWPRIO SET AVAIL(0)' ENDDEF
Result
ESP turns the LOWPRIO resource on and off automatically. Any job requiring one unit of the LOWPRIO resource can only execute between 9 a.m. and 4 p.m. on workdays.
414
Example: Time Periods for Low Priority Jobs, Continued
9 a.m. to 4 p.m.
Allow low priority jobs
4 p.m. to 9 a.m.
Disallow low priority jobs
In a multiple CPU environment, you might have different time periods to run low priority jobs on different systems. You can define different local resources and set them independently.
415
Example: Using a Resource for a Self-completing Task
Introduction
A link cannot have a resource requirement because a link is marked complete as soon as it becomes ready. Instead, you can use a self-completing task that requires a resource.
Self completing task
This example uses a task called WAIT4.LOWPRIO that requires one unit of a resource called LOWPRIO.
JOB WAIT4.LOWPRIO TASK PROCESS RUN ANY RELEASE NEXTJOB RESOURCE (1,LOWPRIO) ESP AJ WAIT4.LOWPRIO COMPLETE APPL(WAIT4.%ESPAPGEN) ENDJOB
Result
When the LOWPRIO resource becomes available, ESP readies the task and issues an ESP AJ command to complete itself. This command uses an ESP symbolic variable (%ESPAPGEN) for the Application generation number to ensure the task is marked complete in the correct generation.
416
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.
Take the following steps: Step 1 Action 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)
In the Applications for each job, specify the number of units required. A job that updates the database requires 999 units; a job that reads the database requires 1 unit. For example, Job A B C Z RESOURCE Statement RESOURCE (999,DBASE1) RESOURCE (1,DBASE1) RESOURCE (1,DBASE1) 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 units of the DBASE1 resource.
417
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 run on a particular system. Instead of hard coding this requirement in JCL, ESP can 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 ESP
Initialization Parameters that assign names to your master and slave ESP systems and identify routing JCL for routing jobs to each system. These definitions must be in place for proper routing. For example, the following are two CPU definitions that specify routing JCL:
CPU SYSA ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSA')CURRENT CPU SYSB ADD NODE(TORONTO) ROUTEJCL(/*JOBPARM SYSAFF=SYSB')
Defining the resources
You can represent each system by a local, threshold resource. The name of the CPU must be the same as that identified in your ESP Initialization Parameters. For example, the following defines two local, threshold resources called 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 the resource
To specify a job must run on SYSB, request 1 unit of the SYSB resource. For example,
JOB XYZ RESOURCE (1,SYSB)
A job may request other resources, which may be either local or global. ESP tries to find all the resources a job needs on one system.
418
Example: Running Jobs on a Particular System, Continued
Result
When the SYSB resource is available, ESP submits the job and adds a system affinity card for SYSB. For example, ESP adds the following card:
/*JOBPARM SYSAFF=SYSB
419
Example: Controlling Mutually Exclusive Groups of Jobs
Introduction
In this example, ESP controls resources such that one group of jobs does not execute while another group is running. The technique illustrated here can be used whether or not both groups of jobs are in the same Application.
Criteria for this example
The criteria for this example are: One group of jobs consists of jobs B and D. The other group of jobs consists of jobs C and E. All jobs in one group must complete successfully before processing any jobs in the other group.
Take the following steps to set this up: Step 1 Action Define a global, depletable resource with a maximum quantity of 1.
RESDEF MUTUAL ADD GLOBAL DEPLETABLE MAX(1)
Use a different task as a predecessor to each group of jobs. Each task requires one unit of the depletable resource and completes itself when the resource requirement is met. Use a link at the end of each group of jobs to reset the available count of the depletable resource to 1.
420
Example: Controlling Mutually Exclusive Groups of Jobs,

Continued
Visual perspective
Visually, the dependencies look like this:

A
(job)
START.1
(task)
START.2
(task)
B
(job)
C
(job)
D
(job)
E
(job)
RESET.1
(link)
RESET.2
(link)
A sample Application is shown on the next page.

421

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

Continued
Result
ESP produces the following results: When job A ends successfully, ESP completes one of the tasks and starts processing one group of jobs. The predecessor task for the other group of jobs requires the MUTUAL resource, which is not available. When the first group of jobs is done, a link sets the available quantity of the MUTUAL resource to 1. This allows the other group of jobs to process.
423
Example: Planning for a System Shutdown - Part 1
Introduction
You can use the ELAPSED default resource to prevent long running jobs from starting prior to a system shutdown. ESP uses historical information to assign elapsed time resource requirements to each job in an Application when it creates a generation of that Application.
Setting-up this example
To set up this example: Define the ESP resource representing elapsed time. The name of the resource 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 the resource representing elapsed 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 a master-slave environment, you should define a local resource for each CPU and use the same name for the resource.
RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(9999)
Turning on the ELAPSED resource
The following ESP initialization statement causes ESP to use a default resource for elapsed time.
RESDFLT ELAPSED(RUN_TIME)
When ESP creates an Application, each job is assigned a RUN_TIME requirement, unless you have specified RESOURCE (0,RUN_TIME) in your Application.
424
Example: Planning for a System Shutdown - Part 1, Continued
Setting up a countdown procedure
The following example uses an Event called OPER.SHUTDOWN that invokes an ESP Procedure. When you trigger this Event, specify the number of minutes until shutdown in the USER1 field.
Actions carried out by the ESP procedure
The ESP Procedure: Assigns the USER1 variable to a variable called TIME Sends a message to CN(01) informing them of the number of minutes until shutdown Sets the available quantity of an ESP 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 is passed as the USER1 variable) The process repeats until the amount of time left is less than zero.
/* /* PASS NUMBER OF MINUTES TO SHUTDOWN USING USER1 /* PARAMETER WHEN TRIGGERING EVENT /* /*SEND MESSAGE, DECREMENT TIME AND RE-TRIGGER EVENT IN /*1 MINUTE IF TIME >=0 /* INTEGER TIME TIME=USER1 SEND 'SYSTEM COMING DOWN IN %TIME MINUTES' CN(01) RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA) TIME=TIME-1 IF TIME>=0 THEN ESP TRIGGER OPER.SHUTDOWN + USER1('%TIME') AT('REALNOW PLUS 1 MINUTE')
425
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 is not enough elapsed time available. If the RUN_TIME resource is defined as a local resource for each CPU then each CPU can have its own counter. ESP only submits a job to JES if there is enough of the RUN_TIME resource available on any CPU. Even though JES controls where the job executes, ESP can automatically insert a system affinity card to control routing.
Resource check
When a jobs predecessor and time requirements have been met, ESP checks to see if the required resources are available. For example, ESP checks to see if enough of the RUN_TIME resource is available for job XYZ on each of the CPUs. If no ORDER has been specified on the CPU definitions in the ESP Initialization Parameters for the master, ESP checks each CPU in the order in which they are defined. Suppose ESP doesnt find enough of the resource on SYSA but does find enough of the resource available on SYSB, ESP submits the job and adds a system affinity card to route the job to SYSB. If no JCL has been specified for the ROUTEJCL parameter in the CPU Initialization Parameter, ESP submits the job and JES determines where the job runs.
Multiple resource requirements
If a job needs the RUN_TIME resource and must execute on a particular system, on SYSA for example, you have two resource requirements. You should specify a resource requirement of 1 unit of SYSA in your Applications. This is a local, threshold resource with quantity of 1. ESP will not submit a job until enough of the RUN_TIME resource is available and the SYSA resource is available; each of these local resources needs to be available on the same system.
426
Example: Planning for a System Shutdown - Part 2, Continued
Defining the system resources
Define a local resource that represents the CPU. For example, the following defines two local, threshold resources called SYSA and SYSB, each with an available count of 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. For example,
JOB XYZ RESOURCE (1,SYSA)
Defining the default resources
The following example defines two local RUN_TIME resources, one for SYSA and one for SYSB.
RESDEF RUN_TIME ADD LOCAL CPU(SYSA) THRESHOLD AVAIL(99999999) RESDEF RUN_TIME ADD LOCAL CPU(SYSB) THRESHOLD AVAIL(99999999)
Setting the resources
You can set the available count of your RUN_TIME resources using the procedure explained in Part 1 of this example. Use the CPU parameter on the RESDEF command to specify the system on which you are setting the resource. For example,
RESDEF RUN_TIME SET AVAIL(%TIME) CPU(SYSA)
The system resources, SYSA and SYSB, may be always available. You may choose to turn them off when the system is coming down and turn them on when the system comes up using ESP or some other form of automation.
Result
When enough of the RUN_TIME resource is available and the system resource (i.e. SYSA or SYSB) is available, ESP submits the job and adds a system affinity card for the appropriate system.
427
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 job with an unpredictable frequency. In this example, PAYJOB2 requires that the previous run of PAYJOB1 has completed successfully. Take the following steps: Step 1 Action 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 the predecessor job, PAYJOB1.
RESDEF PAYJOB1 ADD GLOBAL THRESHOLD AVAIL(0)
For the successor job, define the first job as a resource requirement.
JOB PAYJOB2 RESOURCE (1,PAYJOB1)
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 the available quantity of the PAYJOB1 resource to 0. This prevents PAYJOB2 from running without its dependency the next time it is scheduled.
JOB END.PAYJOB2 LINK PROCESS RUN ANY ESP RESDEF PAYJOB1 SET AVAIL(0)
428
Example: Schedule Dependency, Continued
Visually, the dependencies look like this:
PAYJOB1
(job)
PAYJOB2
(job)
END.PAYJOB1
(link)
END.PAYJOB2
(link)
Result
ESP produces the following results: When PAYJOB1 ends successfully, ESP processes a link called END.PAYJOB1. The link sets the available count of the PAYJOB1 resource 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 PAYJOB1 resource to 0.
429
430
Using XCF with ESP Overview
Introduction
ESP Workload Manager Version 5 Release 2 has been enhanced to use the Cross-System Coupling Facility (XCF) component of MVS/ESA or OS/390. There is new functionality and commands added to ESP Workload Manager.
In this chapter
This chapter contains the following topics: Topic Commands XCF Services State Awareness Trace See Page 432 433 437 438
431
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 DELETE MEMBER member DISPLAY ACTIVE|ACTIVITY DISPLAY GROUP|GROUPS DISPLAY SERVICE|SERVICES DISPLAY SYSTEM|SYSTEMS DISPLAY TRACE FORCE MEMBER member HELP PURGE CONNECTION connection PURGE SERVICE service SET TERMOPT LEAVE|QUIESCE SET TRACE SYSOUT(class) SPIN TRACE START SERVICE service START TRACE STOP GROUP STOP MEMBER member STOP SERVICE service STOP TRACE VERIFY MEMBER member Short Form DEL M|MEM member D A|ACT D G|GR D S|SERV D SYS D TR FORCE M|MEM member H|? PG CON connection PG S|SERV service T TO L|Q T TR S(class) SP TR S S|SERV service S TR P G|GR P M|MEM member P S|SERV service P TR VER M|MEM member
Command reference
For detailed information on all the ESP XCF commands, see the ESP Workload Manager Command Reference.
432
XCF Services
Introduction
XCF Services are functions of ESP that use Sysplex architecture. ESP currently registers these two XCF Services: Data set triggering (dstrig) Job tracking (tracking).
Enabling XCF Services
XCF Services are registered and started via the XCF START SERVICE xxxx command. This command must be coded in the Initialization Parameter data set. XCF Services must be coded in all the ESP subsystems in the XCF group. When an XCF Service is coded and started on the ESP Master, a listener is activated. When an XCF Service is started on the ESP Slave(s), it will connect to the ESP Masters listener for that Service.
Job tracking and data set triggering
In ESP Workload Manager Version 5 Release 1, an ESP Slave subsystem writes Job tracking and data set triggering records to a QUEUE file and the ESP Master subsystem reads those records from the QUEUE file. In ESP Workload Manager Version 5 Release 2, you have the option to use XCF for Job tracking and data set triggering. When XCF is used, the ESP Slave transmits Job tracking and data set triggering records to the ESP Master via XCF. This provides a quicker vehicle for communicating, thus reducing contention on the QUEUE file. If XCF Services are not enabled, ESP Workload Manager Version 5 Release 2 will continue to write Job tracking and data set triggering records to the QUEUE file.
QUEUE file
The QUEUE file is still required in ESP Workload Manager Version 5 Release 2. The QUEUE file has a record of Abended Job information (available via the DAB command) and also information on jobs in the Input, Execute and Output pnodes.
433
XCF Services, Continued
QUEUE file to XCF Migration considerations
The ESP Master will always check the QUEUE file for Job tracking and data set triggering records written by ESP Slaves. To migrate from the QUEUE file to an XCF connection, add the XCF START SERVICE xxxx commands in the ESP Master and ESP Slave Initialization Parameter data set at the same time. If you are going to add the XCF START SERVICE xxxx commands separately, put them in the ESP Master first. If the ESP Slave has the XCF START SERVICE xxxx commands in the Initialization Parameters and the ESP Master does not, Job tracking and data set triggering records cannot be sent from the ESP Slave to the ESP Master.
Starting XCF Services
The following is the syntax for the XCF START SERVICE commands in the Initialization Parameter data set:
XCF START SERVICE DSTRIG XCF START SERVICE TRACKING
Displaying XCF Services
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 DSTRIG Active TRACKING Active Group P520 P520 Member P521 P521 Continued on next page
434
Displaying active XCF Service connections
To display active XCF Service connections, enter the following command from an ESP Master:
XCF DISPLAY ACTIVE
The following is an example of a response to the above command:

Group=P520, Member=P521 Partner Service Listener DSTRIG Listener TRACKING P522 DSTRIG P522 TRACKING Status Active Active Active Active Connection 1,5 3,7
Stopping an XCF Service
To stop an XCF Service, enter the following command:

XCF STOP SERVICE DSTRIG
Restarting an XCF Service
To restart an XCF Service on the fly after it has been stopped, enter the following command:
XCF START SERVICE DSTRIG
Purging XCF Services
When you purge a Service on an ESP Master, the Service gets purged and restarted. ESP stops and starts the listener. This should only be used in situations when XCF STOP SERVICE does not appear to be working.
Example of Purging a Service
The following is an example of purging an XCF Service:

XCF PURGE SERVICE DSTRIG
Result:
ESP4221I Listener and 1 connection purged, Service=DSTRIG, Group=P520, Member=P521 Continued on next page
435
Example of a restarted Service
Display the active XCF connections from an ESP Master:

XCF DISPLAY ACTIVE
The following example shows the Service DSTRIG connected on a new listener compared to the previous DISPLAY ACTIVE illustration:
Group=P520, Member=P521 Partner Service Listener TRACKING Listener DSTRIG P522 TRACKING P522 DSTRIG Status Active Active Active Active Connection 3,7 4,8
436
State Awareness
Introduction
In an XCF group, State Awareness exists between all the ESP subsystems in the group. Each ESP is a unique member of a common group, but they all know the operating status of each other.
Description
Each ESP subsystem knows which other ESPs are active, quiesced or failed in the XCF group. Each ESP member also knows the XCF Services that are available on the ESP Master.
Displaying the members
To display the members in the XCF group and their respective states, use the XCF DISPLAY GROUP command.
XCF DISPLAY GROUP Group=P520, Member=P521, TermOpt=Quiesce Group Member System ASID Jobname SSID ESP P520 P521 SYSA 0081 P521 P521 Master P520 P522 SYSA 007D P522 P522 Slave Status Active Active
Stopping a member
To stop an ESP XCF member, use the XCF STOP MEMBER command.
XCF STOP MEMBER member
Stopping the group
To stop all the ESP XCF members in the XCF group simultaneously, use the XCF STOP GROUP command.
XCF STOP GROUP
437
Trace
Introduction
The XCF Trace facility is a debug tool. XCF Trace captures data and spools the output to a preset sysout class. This should not be used unless instructed by Cybermation technical support.
Commands
The following shows how to activate and capture data using XCF Trace: Step 1. Action Define a sysout class by entering: XCF SET TRACE SYSOUT(x) Activate the trace by entering: XCF START TRACE When you have captured the data, turn the trace off and spool the current XCF trace file to output by entering: XCF STOP TRACE
2.
3.
Spin Trace
The XCF SPIN TRACE command is used to spool the current XCF trace file to output and start a new XCF trace file. It can be used when the trace file is started upon initialization of the ESP subsystem and kept running for the duration of the subsystem session.
Usage notes
The XCF SET TRACE SYSOUT(x) and XCF START TRACE commands can be specified in the Initialization Parameter data set, but XCF STOP TRACE and XCF SPIN TRACE cannot. It is recommended to put XCF SET TRACE SYSOUT(x) in the Initialization Parameter data set because then only XCF START TRACE is required to start it on the fly.
438
Optimizing ESP Applications to Use Distributed Manager Overview
Introduction
When your ESP network contains one or more Distributed Managers, you may be required to create ESP Applications that run workload on one or more ESP Agents controlled by a Distributed Manager. You should consider certain guidelines when defining Applications that run workload managed by a Distributed Manager. The structure of the ESP Applications that require management by a Distributed Manager can be tailored to make the most efficient use of the Distributed Manager's ability to manage previously scheduled workload when the mainframe is unavailable. This chapter describes the guidelines you may want to follow when defining distributed Applications, and those ESP features that are not currently supported by the Distributed Manager. If this is a new installation of ESP Workload Manager that does or will include one or more Distributed Managers, you should read this chapter before you begin coding ESP Applications.
In this chapter
This chapter contains the following topics: Subtask Planning Applications to Optimize DM Establishing Ownership of a Workload Object Creating Distributed Applications for use with Distributed Manager Defining Manager Ownership of an Application Changing Manager Ownership of an Application Changing Manager Ownership of an Application Dynamically See Page 440 446 447 448 450 451
439
Planning Applications to Optimize DM
Introduction
Before you define a new distributed ESP Application, or update an existing distributed Application, you should consider the features and limitations of the Distributed Manager. Creating Applications that optimize the abilities of the Distributed Manager ensure the completion of the Application when the mainframe is unavailable, either due to scheduled maintenance or a planned or unplanned outage.
Steps
Follow these steps to plan optimal Applications: Step 1 2 Action Plan the proposed workflow for this Application. 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. Review the workflow to identify the following: 1. The owning Manager of each workload object. See Establishing Ownership of a Workload Object on page 446. 2. The number of times the owning Manager changes from a Distributed Manager to the central ESP Workload Manager or vice versa. See Example 2 - not recommended structure on page 443. 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 Manager together, reducing the communication required between Distributed Managers. See Example 1 - recommended structure on page 442.
440
Planning Applications to Optimize DM, Continued
Steps (continued)
Step 5
Action Review the list of ESP functions not supported by the current release of DM. Eliminate the use of the following functions in any ESP Application that runs workload managed by a Distributed Manager. Resolution of runtime symbolic variables Resolution of runtime CLANG or REXX statements Workload objects containing EXTERNAL or MANUAL keywords ESP Alerts. For more detailed information, refer to Unsupported functions on page 445. Create a set of rules for defining distributed Applications at your site.
Features and limitations
The primary purpose of a Distributed Manager is to track scheduled workload that is running on ESP Agents. As status is returned from an Agent, the Distributed Manager passes the status to the central ESP Workload Manager or any other interested Distributed Managers. If the mainframe is down or communications to the mainframe is unavailable, the Distributed Manager continues to track workload, releasing workload objects under its control as their dependencies are met. When the mainframe becomes available again, the Distributed Manager sends all status updates to the ESP Workload Manager at that time. The Distributed Manager can release workload under its control, or send status to another Distributed Manager that is interested in the completion of a workload object. It cannot, however, determine that a workload object has completed if information from the owning Manager (such as the central ESP Workload Manager) is unavailable. Refer to the following examples that graphically describe the optimal way to design the interrelationships within an ESP Application.
441
Example 1 recommended structure
The following example shows an ESP Application that runs MVS, UNIX and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Note that the workload is grouped to limit the number of changes of owning Manager and the number of interdependencies between Managers.
Central ESP Workload Manager
JOB A
JOB B
Distributed Manager 1
Change
NT_JOB S
UNIX_JOB F
NT_JOB T
UNIX_JOB G NT_JOB V
Change
UNIX_JOB H
In this example, the dependency on the availability of the mainframe is limited to the beginning of the Application: ESP Workload Manager schedules the Application and manages the first two workload objects. After they complete, the connection to the mainframe may be lost, or the mainframe taken down for maintenance and the workload continues to run because it does not rely on intervention from the mainframe. Ideally, remove all dependencies on the mainframe entirely, or limit them to the beginning or end of the Application.
442
Example 2 - not recommended structure
The following example shows an ESP Application that runs MVS, UNIX and Windows NT workload, controlled by a central ESP Workload Manager and two Distributed Managers. Distributed Manager 1 controls the UNIX workload and Distributed Manager 2 controls the Windows NT workload. Note that the workload objects have many inter-platform dependencies, and the owning Manager changes five times within the Application. In this example, if the mainframe becomes unavailable after JOB A completes, workload cannot continue to run after UNIX_JOB F and NT_JOB S complete.
Central ESP Manager
JOB A
Change
Change
UNIX_JOB F
NT_JOB S
Change
JOB B
Change
NT_JOB S
Change
UNIX_JOB G NT_JOB S
Change
Central ESP Manager
JOB C
443
Example 2 - not recommended structure, continued
In the above example, each Distributed Manager has a dependency on the availability of the mainframe throughout the entire Application. If the mainframe or communication to it becomes unavailable at any point during the execution of the Application, the work cannot continue to run. A workload object may complete, but the next workload object may not be released until the mainframe becomes available again. This Application structure defeats the purpose of the Distributed Manager in this case.
444
Unsupported functions
Some ESP functions are not yet supported by ESP Distributed Managers. While your workload objects will not cause errors in the Distributed Manager if they contain statements the Distributed Manager does not recognize, your workload may not perform as expected. The following ESP functions are not supported by Distributed Managers: Resolution of runtime symbolic variables Resolution of runtime CLANG or REXX statements Workload objects containing EXTERNAL or MANUAL keywords ESP Alerts.
Support of these functions varies depending on the owning Manager of the Application or workload object. Refer to the following to determine when a function is unavailable: State of central ESP Workload Manager ESP Workload Manager available Owned by ESP Workload Manager Owned by a Distributed Manager Runtime symbolic variables Runtime scripting of CLANG and REXX EXTERNAL MANUAL Alerts Runtime symbolic variables Runtime scripting of CLANG and REXX EXTERNAL MANUAL Alerts
ESP Workload Manager unavailable
Runtime symbolic variables Runtime scripting of CLANG and REXX EXTERNAL MANUAL Alerts
445
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 an Application
The owning Manager of an Application is defined on the APPL statement or in the Application definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager. The owner specified at the Application level also applies to all Links and Tasks within the Application, unless the owner is specified in the Link or Task definition. The owning Manager determines the status of the Application, and is the only Manager that can complete the Application. Therefore, if you are running a distributed Application that must be able to complete when the mainframe is unavailable, a Distributed Manager must be the owner.
Owner of a Link or Task
The owner of a Link or Task is defined either at the Application level, with the OWNER keyword on the APPL statement, or in the Link or Task definition with the OWNER keyword. Specifying the OWNER keyword in the Link or Task definition overrides any specified at the Application level. Specifying a Distributed Manager as the owning Manager of a Link or Task allows you to define the Link or Task as non-MVS workload. The Distributed Manager determines if the conditions of the Link or Task are met.
Owner of an MVS job
The owner of an MVS job is always the central ESP Workload Manager.
Owner of a distributed workload object
The owner of a distributed workload object is not determined by an OWNER keyword - it is determined by the network topology defined in the AGENTDEF file. A Manager - either a Distributed Manager or the central ESP Workload Manager, owns each Agent. The Manager that owns the Agent running the workload object owns the distributed workload object.
446
Creating Distributed Applications for use with Distributed Manager
Introduction
You can optimize your ESP Applications for use with a Distributed Manager by keeping some simple rules in mind when designing the Application. Also, consider if the Application will run most efficiently under the ownership of a Distributed Manager or the central ESP Workload Manager.
Steps
Follow these steps to create an ESP Application that optimizes Distributed Manager's capabilities: Step 1 Action If this Application must be able to complete when ESP Workload Manager is unavailable, specify a Distributed Manager as the owner. Specify an OWNER keyword on the APPL statement or specify an owner in the Owner field in ESP Workstation. Structure the Application to minimize embedded dependencies on MVS workload. If dependencies on MVS workload are required within the Application, try to place them at the beginning or end of the Application. Ensure you do not include External or Manual jobs within the Application. Ensure any symbolic variables can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime symbolic variables. Ensure any CLANG or REXX used within the Application can be resolved at the time the Event is triggered. A Distributed Manager cannot resolve runtime-scripting requirements. Ensure you do not use ESP Alerts in the Application. Group workload by Distributed Manager, where possible.
3 4
6 7
447
Defining Manager Ownership of an Application
Introduction
The owning Manager of an Application is the only Manager that can start or complete an Application, change the status of an Application, or send notifications to the other Managers regarding the status of an Application. The owner of an Application is also the owner of all Links and Tasks within the Application, unless the owner is specified within the Link or Task definition. The owning Manager of an Application is defined on the APPL statement or in the Application definition on ESP Workstation. If no owner is specified, the owner defaults to the central ESP Workload Manager. If you are running a distributed Application that must be able to complete when the mainframe is unavailable, specify a Distributed Manager as the owner.
Steps
Follow these steps to define the owner of an Application: 1 2 Create a new Application or edit an existing Application. 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. Enter a valid Distributed Manager name, up to 16 alphanumeric characters in length. The first character must be alphabetic or a national character, as follows:
APPL PAYROLL OWNER(DMTOR)
2. Proceed to step 5.
448
Defining Manager Ownership of an Application, Continued
Steps (continued)
Step 3
Action 1. On the APPL statement, specify an OWNER parameter. Enter a valid Distributed Manager name, up to 16 alphanumeric characters in length. The first character must be alphabetic or a national character. Define the circumstances under which you want ownership of the Application determined. Specify the exceptions first. Specify the normal business as usual circumstances next. For example, the following example defines a Distributed Manager as the owner of the Application on weekends:
IF TODAY ('WEEKEND') THEN APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL ENDDO
2. 1. 2. 3.
5 6 7
Proceed to step 5. In the Workload Editor, bring up Workload Definition Defaults On the Application tab, find the Owner field Enter a valid Distributed Manager name, up to 16 alphanumeric characters in length. The first character must be alphabetic or a national character. Simulate the Event that runs this Application for each circumstance. Ensure the results are as expected. Save the Application. If you are using ESP Workstation, upload the Procedure to the mainframe.
449
Changing Manager Ownership of an Application
Introduction
Depending on how ownership is specified in your Application, there may be times when you want to change the ownership, such as you expect the mainframe to be shut down for maintenance. You need to change the ownership in the Application and trigger the Event prior to shutting down ESP Workload Manager.
Steps
Follow these steps to change the ownership of an Application: Step 1 2 Action Edit the Application. If an owner is currently defined for the Application, change the owner to the new name. Otherwise, add an owner name in the Owner field on ESP Workstation, or add an OWNER statement as follows:
APPL PAYROLL OWNER(DMTOR)
3 4 5 6
Simulate the Event that runs this Application to ensure no unforeseen problems. Save the Application. If you are using ESP Workstation, upload the Procedure to the mainframe. When the Event is triggered, the new owner controls the status of the Application.
450
Changing Manager Ownership of an Application Dynamically
Introduction
Depending on how ownership is specified in your Application, there may be times when you want to change the ownership dynamically. For example, if the mainframe is shut down for maintenance on a certain schedule, you can use ESP to change the ownership of the Application to a Distributed Manager during those scheduled times. This is especially important if your Application must be able to complete (and perhaps run additional generations of the Application) even if the mainframe is unavailable. Ensure the Event is triggered prior to shutting down ESP Workload Manager.
Steps
Follow these steps to change the ownership of the Application dynamically: Step 1 2 Action Create a new Application or edit an existing Application. Define the circumstances under which you want ownership of the Application determined. Specify the exceptions first. Specify the normal business as usual circumstances next. For example:
IF TODAY FRIDAY THEN APPL PAYROLL OWNER(DMTOR) ELSE APPL PAYROLL ENDDO
3 4 5
Simulate the Event that runs this Application for each circumstance. Ensure the results are as expected. Save the Application. If you are using ESP Workstation, upload the Procedure to the mainframe.
451
452
Glossary of Terms Glossary
Term Alert
Application Application Wait
Audit log
Authorization string Authorization table AUTOVAR
Calendar
CCFAIL
CLANG Condition code Consolidated Status Facility
Explanation A mechanism you define to ESP to trigger ESP activity when specific actions take place in your Application. For example, you can use ESP to trigger an Event when a job fails. See ESP Application. A status in which the execution of an Application has to wait until a previous generation of the Application completes. An audit trail of ESP activity. It stores information on administration activities, operator commands, and Application and Event processing. One of four job related fields that is used to identify the ownership of a job. A table ESP may use to control access to job tracking data. Automatic variable; a variable used to represent an initial or trailer job step, or DJC net card. A collection of definitions of holidays, special days and special periods that are unique to your installation. Abbreviation for condition code fail. CCFAIL statements define conditions, which, if met, should cause the job to fail. Control language. This is a high level programming language developed for ESP. A code indicating the results of processing a job step. An ESP facility for displaying and manipulating the workload.
453
Glossary, Continued
Term COPYJCL Descriptor code
DJC
DJC job network ESP Application ESP Procedure External job Event
Event data set Event group EVENTSET
Explanation Location of a copy of the submitted JCL. A one or more digit code used to describe the characteristics of a message to an MVS console. Dependent Job Control; a Cybermation product used to control resources and job networks at the initiator level. A group of related jobs where dependencies are controlled at the initiator level. A group of related jobs and tasks. A collection of stored instructions to be executed by ESP when invoked by an Event. A job defined in an ESP Procedure that ESP submits from another Procedure. A basic unit of work to ESP. An Event starts an active function such as sending a message or invoking an ESP Procedure. A VSAM data set where ESP stores Event definitions. Group of ESP Events with the same Event prefix (first name). Event data set.
454
Glossary, Continued
Term Group
HISTFILE History file Job index data set Job monitor
Job tracking Job tracking definition table Link Manual job
Model Page mode P-Node
Post Predecessor job
Explanation A high-level index, to which specific users are allowed access. Normally a group is a collection of users with common access requirements. History file. A VSAM data set used to store historical information. A VSAM data set used to store an index to the most recent executions of a job. An ESP facility for monitoring a jobs progress at any stage of processing and for taking action at significant points. An ESP facility to track job data in real time as jobs are processed. A table used to specify the characteristics of jobs, STCs and TSUs you want to track. A task in an Application that does not require manual completion. A job which ESP does not submit as part of either an ESP Application or a DJC/JES3 job network. A definition of your environment (e.g. CPUs, initiators, resources). A method to communicate with ESP using ISPF, producing scrollable output from ESP. Processing node. A processing stage through which a job must pass during its time on the system. To mark complete. For example, you can post a job complete. Any job that must complete before another job can be released.
455
Glossary, Continued
Term Qualifier Resource REXX
Route code SAD file
SAF
Schedule Signal Special day Special period
SubApplication Subsystem Successor job
Explanation An addition to the jobs name, used to uniquely identify similar jobs. An item of hardware, a software resource or an abstract condition. Restructured eXtended eXecutor. This is a high level, procedural language developed by IBM. You can invoke the REXX language interpreter from ESP to extend ESPs capabilities. A one or more digit code used to route a message to an MVS console. Scheduled activity data set file; a sequential data set ESP uses to store scheduled activity information on jobs. System Authorization Facility; a generic set of operating system interfaces that allows a security product to implement access control against the components of the operating system. Also used to refer to the use of the interface. A list of Events to execute, sorted in time sequence. A manual or automated task used for scheduling. A day with special significance for scheduling at your installation. A period of processing with special significance for scheduling at your installation. An example is a fiscal month. A group of jobs within an Application. An MVS facility that ESP uses to manage and control requests among its components. Any job that depends on the completion of another job before it can be released.
456
Glossary, Continued
Term Symbolic variable
Explanation 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 an evolving, large system computing environment. System message interception A facility used to intercept system messages as they are written to the system message data set. System security product A product installed to implement system security. Also known as the host security system or product. Task An element of an Application that requires completion. For example, a task may represent the checking of a report. Tracking model A centralized definition of the attributes and processing phases of a group of jobs. TRAKFILE Tracking file; a non-VSAM data set used to store job tracking data. userid A short (8 bytes or less) field used to identify a system user. It can represent an actual person or an active program, job or routine. XCF XCF (Cross System Coupling Facility component of MVS/ESA or OS/390) services allow authorized programs to communicate with programs on the same or different MVS images.
457
458
/ //* FROM statement .............................................. 187 //* UNTIL statement ............................................. 187 4 4-4-5 period example ............................................................ 134 A ABANDON DEPENDENCIES statement ............ 203 ABANDON RESOURCES statement................... 205 ABANDON SUBMISSION statement.................. 203 Absolute day ......................................................... 110 Access to calendars....................................................... 124 to Events............................................................. 63 Accessing ESP as a program ....................................................... 55 as a TSO command processor ............................ 56 in batch ............................................................... 54 ISPF option ........................................................ 45 ACTIVE function.................................................. 159 Adding job dependency using CSF ............................... 278 job relationship using CSF ............................... 280 relationship between 2 jobs .............................. 251 resource requirements....................................... 388 scheduled Event execution ................................. 96 Advancing Event processing ................................... 69 Advancing job based on holiday ........................... 128 AFTER statement.................................................. 206 AJ command ......................................................... 251 Altering Event ....................................................... 101 ALTEVENT command ......................................... 101 Anticipated end times............................................ 199 APPL statement..................................................... 184 Application changing owner of ............................................ 446 changing the definition ..................................... 253 command processing ........................................ 196 creating for use with DM.................................. 443 CSF commands................................................. 270 defining owner of ............................................. 444 description ........................................................ 177 displaying ......................................................... 249 distributed......................................................... 436 dynamically changing owner of........................ 447 generating ......................................................... 179 manipulating..................................................... 251 naming.............................................................. 184 optimizing for Distributed Manager ................. 435 owning Manager of........................................... 442
planning, for use with DM................................ 436 reommended structure for DM ......................... 438 working with..................................................... 248 Application generations concurrent processing....................................... 184 number ESP assigns ......................................... 181 Application phases ................................................ 179 APPLJOB command ............................................. 251 Arithmetic expression ........................................... 147 Arithmetic operations............................................ 148 Attributes, of a job ................................................ 227 Authorization string External jobs..................................................... 214 Manual jobs...................................................... 218 B Batch, invocation of ESP ........................................ 54 Blank lines,history report ...................................... 308 BREAK command ................................................ 308 Built-in functions ACTIVE ........................................................... 159 combining......................................................... 164 DAYS_BETWEEN.......................................... 152 DAYS_FROM.................................................. 152 DAYS_TO........................................................ 152 DEFINED......................................................... 157 ESP Procedure.................................................. 150 JOBONQ.......................................................... 159 LENGTH.......................................................... 157 SELECTED...................................................... 156 SUBSTR........................................................... 158 TAPES ............................................................. 162 TODAY............................................................ 153 TOMORROW .................................................. 154 YESTERDAY .................................................. 154 Built-in symbolic variables ................................... 145 Bypassing a job.................................................................. 251 a job based on time........................................... 203 a scheduled Event execution .............................. 97 Event,specific day .............................................. 69 Bypassing a job ..................................................... 277 C Calendar access ............................................................... 125 contents ............................................................ 124 deletion of entries ............................................. 125 specifying in Event ............................................. 86 SYSTEM.......................................................... 125 CALENDAR command .......................................... 86 CALENDAR statement......................................... 125 Canceling an Event
459
for specific day ................................................... 69 next execution .................................................... 97 Changing Application definition ........................... 253 changing ownership of Application....................... 446 dynamically ...................................................... 447 CLANG,language elements................................... 141 CLIST,to access ESP .............................................. 56 Commands CSF................................................................... 270 processing in an Application ............................ 196 Comments ESP Procedure.................................................. 140 Event .................................................................. 86 Comparing expressions ......................................... 148 Comparison operators ........................................... 148 Completing a job................................... 252, 255, 277 Concurrent access to online system....................... 408 Concurrent processing,Applications ..................... 184 Conditional jobs,defining...................................... 195 CONDITIONAL keyword .................................... 196 Conditions,freeform filtering................................. 289 Consolidated Status Facility.......................... See CSF Continuation character,ESP Procedure ................. 140 Control information,using ..................................... 365 Controlling access to database,using resource ...... 413 CONVERT.EXE utility......................................... 348 Converting job documentation .............................. 374 COPY command ................................................... 306 Copying JCL ........................................................... 82 COPYJCL command............................................... 82 COPYJCL statement ............................................. 188 COREQ statement................................................. 206 Countdown procedure ........................................... 421 Creating reports..................................................... 293 CRITERIA command............................................ 303 Critical jobs default............................................................... 240 defining ............................................................ 195 CRITICAL keyword ..................................... 195, 240 Critical path........................................................... 238 displaying ......................................................... 242 External jobs..................................................... 240 historical elapsed times .................................... 241 identifying critical jobs..................................... 240 multiple ............................................................ 241 Critical path analysis turning off......................................................... 240 turning on ......................................................... 239 Cross-System Coupling Facility............................ 427 CSF add dependency................................................ 278 add job relationship .......................................... 280 add LINK PROCESS ....................................... 281 freeform filtering .............................................. 285 inserting job...................................................... 273
installation written commands .......................... 284 presentation fields ............................................ 264 presentation titles.............................................. 264 reset time .......................................................... 276 set User Status .................................................. 282 Status fields ...................................................... 292 views ................................................................ 256 CSF commands ..................................................... 270 Application....................................................... 270 ESP definitions................................................. 272 jobs................................................................... 271 subApplication ................................................. 270 CSF Extensions ..................................................... 284 D Data set names in ESP Procedure ......................... 140 Data set trigger objects.......................................... 228 controlling ........................................................ 232 displaying ......................................................... 233 ready status....................................................... 232 setting up .......................................................... 229 Data set triggering ................................................... 74 any closure.................................................. 74, 230 data set creation.................................................. 74 job-level....................................................... 230 displaying Events ............................................... 77 job level............................................................ 228 multiple closures................................................. 76 job-level....................................................... 231 multiple data sets ................................................ 75 job-level....................................................... 231 Data set,job mapping............................................. 328 DATASET statement ............................................ 189 Date fields,history reporting.................................. 299 Date format,history report ..................................... 306 DATEFORM command ........................................ 306 DAYS_BETWEEN function ................................ 152 DAYS_FROM function ........................................ 152 DAYS_TO function .............................................. 152 Default resources................................................... 392 dropping ........................................................... 393 DEFHOL command .............................................. 126 DEFINED function ............................................... 157 Defining a job.................................................................. 191 Event using a link ............................................. 243 function of Event ................................................ 78 holiday.............................................................. 126 resource ............................................................ 395 special day........................................................ 129 special period ................................................... 131 when Event executes .......................................... 66 DEFSPEC command ............................................. 129 Delayed submission time....................................... 198 Delaying
460
Event processing ................................................ 69 job based on holiday......................................... 128 Delaying submission ............................................. 198 DELAYSUB statement ......................................... 198 DELETE command............................................... 102 Deleting calendar entries................................................. 125 CSF view.......................................................... 267 Event ................................................................ 102 resource ............................................................ 398 Depletable resource............................................... 382 DESELECT statement .......................................... 209 Deselecting jobs .................................................... 209 DEVICE resource ................................................. 396 DISPLAY command ............................................. 307 Displaying Application....................................................... 249 critical path....................................................... 242 data set trigger objects...................................... 233 data set triggered Events..................................... 77 data sets for triggering Events ............................ 77 Events................................................................. 93 External jobs..................................................... 212 history report fields .......................................... 307 scheduled activity data ..................................... 322 scheduled Events ................................................ 88 Distant Application ............................................... 212 Distributed Manager functions of....................................................... 437 limitations of .................................................... 437 unsupported functions ...................................... 441 DO statement......................................................... 142 DOCMEM keyword.............................................. 366 Documentation,for jobs......................................... 353 Dropping default resources............................................... 393 resource requirements....................................... 389 DSNAME statement.............................................. 229 DSTRIG command,Event ....................................... 74 DSTRIG statement ................................................ 229 DUEOUT EXEC statement................................... 200 DUEOUT INPUT statement ................................. 200 Dueout times job end.............................................................. 200 job start............................................................. 200 propagating....................................................... 201 DURATION statement.......................................... 241 E Early submission time ........................................... 198 EARLYSUB statement ......................................... 198 Elapsed time resource ........................................... 420 multi-CPU ........................................................ 422 ELSE statement..................................................... 141 ENDDEF command ................................................ 62
ENDDO statement ................................................ 142 Ending job definition .................................................... 191 report definition................................................ 309 ENDJOB statement ............................................... 191 ENDR command ................................................... 309 Enterprise resource................................................ 383 ESP commands from CSF .......................................................... 283 issuing from an Application ............................. 243 loading................................................................ 58 ESP FLOWDOC ................................................... 337 components....................................................... 338 data generation ................................................. 338 database generation .......................................... 339 examples........................................................... 343 overview........................................................... 337 report generation .............................................. 340 report headings ................................................. 342 ESP Procedure built-in functions .............................................. 150 comments ......................................................... 140 continuing a line ............................................... 140 data set names................................................... 140 expressions ....................................................... 147 indentation........................................................ 140 invoking............................................................ 139 label.................................................................. 140 name ................................................................. 140 overriding ......................................................... 174 re-executing...................................................... 165 syntax ............................................................... 140 terminating with EXIT ..................................... 142 terminating with QUIT ..................................... 143 using CLANG................................................... 141 using Event commands..................................... 171 ESP statement ....................................................... 243 ESPNOMSG statement ......................................... 243 Event access ................................................................. 63 altering.............................................................. 101 bypassing............................................................ 99 bypassing one execution..................................... 97 comments ........................................................... 86 concept ............................................................... 16 data set triggered ................................................ 74 deleting............................................................. 102 description .......................................................... 61 displaying ........................................................... 93 expected time...................................................... 89 function .............................................................. 78 issuing operator command ............................. 84 sending message ............................................ 78 submitting job ................................................ 78 invoking ESP Procedure..................................... 81
461
missed................................................................. 69 name ................................................................... 63 next execution times ........................................... 90 overdue............................................................... 69 pending execution............................................... 71 postponing .......................................................... 98 resuming ............................................................. 99 scheduling........................................................... 67 setting calendars ................................................. 86 setting symbol libraries....................................... 85 simulating ........................................................... 94 to invoke an Application .................................. 254 trigger ................................................................. 66 triggered in error ................................................ 97 triggering ............................................................ 96 EVENT command................................................... 62 Event commands using in ESP Procedure .................................... 171 Event processing advancing ........................................................... 69 delaying .............................................................. 69 ignoring .............................................................. 69 Exceptions,Event scheduling................................... 68 EXIT statement ..................................................... 142 EXPECT statement ................................................. 89 Expected time of Event ........................................... 89 Expression............................................................. 147 External job Application....................................................... 212 critical path....................................................... 240 tagging.............................................................. 234 EXTERNAL keyword........................................... 212 F Field formats,history reporting.............................. 297 Field lengths,history report ................................... 307 Fields for history reporting.......................................... 311 history reporting ............................................... 296 Filter Specifications panel..................................... 263 First day of week................................................... 110 FLOW command................................................... 350 Flowcharting ......................................................... 346 MS Project........................................................ 347 TIMELINE....................................................... 350 FLOWDOC........................................................... 337 components....................................................... 338 data generation ................................................. 338 database generation .......................................... 339 examples........................................................... 343 overview........................................................... 337 report generation .............................................. 340 report headings ................................................. 342 Freeform filtering conditions ......................................................... 289
CSF................................................................... 285 examples........................................................... 291 keywords .......................................................... 286 FROM command................................................... 302 functions not supported by DM............................. 441 Functions of ESP..................................................... 14 not supported by DM........................................ 441 G Generation phase,Application ............................... 179 Generations of an Application............................... 181 GENFLOW command........................................... 350 GENPROJ command ............................................ 348 Global resource ..................................................... 383 Gravity attribute .................................................... 385 H Held jobs,defining................................................. 195 HELP facility .......................................................... 46 Help panels.............................................................. 50 HISTFILE command............................................. 302 History file for reporting ..................................................... 302 History report blank lines ........................................................ 308 date format ....................................................... 306 display fields .................................................... 307 ending............................................................... 309 field lengths ...................................................... 307 history file ........................................................ 302 list of fields....................................................... 311 output data set .................................................. 306 page break ........................................................ 308 reporting fields ................................................. 296 sample .............................................................. 309 selection criteria ............................................... 303 sort criteria ....................................................... 307 structure............................................................ 295 subtotals............................................................ 308 time range......................................................... 302 titles.................................................................. 307 width................................................................. 309 History reporting ................................................... 294 HOLD command ..................................................... 98 in Event .............................................................. 71 Hold count............................................................. 179 job in an Application ........................................ 179 Holding an Event .................................................... 98 Holiday defining ............................................................ 126 defining with a template ................................... 168 using to schedule .............................................. 128 Home Application ................................................. 212 Hyphen,using in batch........................................... 310
462
I IF statement........................................................... 141 Ignoring Event processing ................................................ 69 Indentation ESP Procedure.................................................. 140 Index for job activity report .................................. 332 INFOMSG command .............................................. 53 Informational messages displaying ........................................................... 53 Inheriting relationships.......................................... 209 INPUT command .................................................. 302 Input criteria,history report ................................... 302 INPUTDS statement ............................................. 326 Inserting a job CSF................................................................... 273 resource requirements....................................... 387 Inserting LINK PROCESS.................................... 281 INVOKE command,in Event .................................. 81 Invoking Application....................................................... 254 ESP Procedure,using Event................................ 81 ISPF panels ............................................................. 45 Issuing commands using a link ....................................................... 221 Issuing operator command using Event......................................................... 84 J JCL creating a copy ................................................... 82 for routing jobs................................................. 385 JCL library ............................................................ 185 temporary ......................................................... 186 JCLLIB statement ................................................. 185 JES queue using JOBONQ function .................................. 159 Job Activity Report ............................................... 330 customizing ...................................................... 331 Job ancestor wait................................................... 184 Job dependency adding, using CSF ............................................ 278 Job Descendent Report.......................................... 334 Job documentation ................................................ 353 converting......................................................... 374 example-storing phone numbers....................... 377 links and tasks .................................................. 370 member............................................................. 366 other uses.......................................................... 377 qualified jobs.................................................... 368 user description ................................................ 356 using control information ................................. 365 Job mapping .......................................................... 327 setting up .......................................................... 327
Job priority............................................................ 390 Job qualifier .......................................................... 191 External job ...................................................... 212 Job relationships adding, using CSF ............................................ 280 Application....................................................... 206 inheriting .......................................................... 209 using resources ................................................. 424 JOB statement ....................................................... 191 Job types ............................................................... 211 JOBATTR statement............................................. 227 JOBDOC file......................................................... 372 JOBMAP command .............................................. 330 JOBONQ function................................................. 159 generated variables........................................... 160 Jobs attributes........................................................... 227 bypassing.......................................................... 277 completing........................................................ 277 CSF commands................................................. 271 on-request......................................................... 193 ownership of..................................................... 442 qualifying ......................................................... 191 requirements ..................................................... 197 specifying owner .............................................. 442 submitting without dependencies...................... 203 JOBTREE command............................................. 334 JUMPTO statement............................................... 143 K Keywords freeform filtering .............................................. 286 L Label ESP Procedure.................................................. 140 job documentation ............................................ 356 LAP command ...................................................... 249 Late Submission time ............................................ 200 LATESUB statement ............................................ 200 LAX command...................................................... 212 LDTE command...................................................... 77 LDXE command ............................................. 77, 233 LENGTH function ................................................ 157 Length of a variable .............................................. 157 Librarian data sets as input ............................................................... 60 ESP Procedure.................................................. 140 submitting a job .................................................. 80 LIBSUB command.................................................. 80 limitations of Distributed Manager ...................... 437 Line mode ............................................................... 55 Link owning Manager of........................................... 442 specifying owner .............................................. 442
463
LINK keyword ...................................................... 219 LINK PROCESS,inserting, using CSF.................. 281 Links common uses .................................................... 221 definition .......................................................... 219 job documentation ............................................ 370 resource limitation............................................ 412 triggering an Event ........................................... 243 using for notification ........................................ 222 using to add job relationship ............................ 280 using to define an Event ................................... 243 using to issue commands .................................. 221 using to keep Application active ...................... 222 LIST command ....................................................... 93 LISTAPPL command............................................ 249 LISTSCH command................................................ 88 LOAD command ..................................................... 58 Local resource....................................................... 383 Logical day............................................................ 110 Logical expression ................................................ 147 Logical operators .......................................... 148, 149 LSAR command.................................................... 322 M Main Menu........................................................ 45, 47 Manager changing owner of Application ........................ 446 dynamically changing owner of Application .... 447 Manager of an Application.................................... 444 Manual job,Application ........................................ 216 MANUAL keyword .............................................. 216 MAPGEN.............................................................. 329 MEMBER statement JCLLIB............................................................. 185 TEMPLIB......................................................... 186 MS Project,flowcharts........................................... 347 Multiple runs of a job............................................ 192 Mutliple critical paths ........................................... 241 Mutually exclusive groups of jobs................................................... 416 jobs................................................................... 406 N Naming an Application ......................................... 184 NEXT command ..................................................... 90 Next execution times Event .................................................................. 90 Non-MVS workload................................................ 25 Non-MVS workload,reporting .............................. 311 NORUN statement ................................................ 209 NOSCHED command ............................................. 68 Notification job status .......................................................... 236 using a link ....................................................... 222 NOTIFY statement................................................ 236
NOW,scheduling term........................................... 114 Numeric fields,history reporting ........................... 297 O One time Event........................................................ 68 Operator commands from Events ........................................................ 84 Operator console retrieving job documentation............................ 372 Operator precedence ............................................. 148 Operators arithmetic.......................................................... 148 comparison ....................................................... 148 logical....................................................... 148, 149 Optional jobs,defining........................................... 195 Overdue Event................................................. 69, 100 OVERDUE status, jobs......................................... 199 Overriding elapsed times for critical path........................... 241 ESP Procedure.................................................. 174 JCL library ....................................................... 186 Owner of Application, changing .................................. 446 of Application, changing dynamically.............. 447 of Application, defining.................................... 444 of distributed workload .................................... 442 Owning Manager................................................... 442 of Application................................................... 442 of distributed workload object.......................... 442 of Link.............................................................. 442 of MVS job....................................................... 442 of Task.............................................................. 442 P Page breaks history report .................................................... 308 Page mode............................................................... 50 displaying informational messages ..................... 53 PANSUB command ................................................ 80 Panvalet datasets as input ............................................................... 60 ESP Procedures ................................................ 140 submitting a job .................................................. 80 Pending execution Event .................................................................. 71 Postponing an Event................................................ 98 POSTREQ statement............................................. 206 Postrequisite job.................................................... 206 PREREQ statement ............................................... 206 Prerequisite job ..................................................... 206 Presentation fields,changing order ........................ 264 Presentation titles,CSF .......................................... 264 Primed data set triggers........................................... 76 Prioritizing work using resources ................................................. 410
464
Priority of a job based on resources............................................ 390 PRIORITY statement ............................................ 390 Process phase,Application..................................... 180 Projected versus actual report ............................... 325 Propagating dueout times ...................................... 201 Q Qualified jobs,job documentation ......................... 368 Qualifying a job.................................................................. 191 job names ......................................................... 191 QUIT statement..................................................... 143 R Real device types,resource .................................... 384 Real resources ....................................................... 384 limitations......................................................... 384 REALNOW, scheduling term ............................... 115 REEXEC statement............................................... 165 Re-executing an ESP Procedure............................ 165 Refreshing resource status..................................... 396 RELDELAY statement.......................................... 198 RELEASE command,in Event ................................ 71 RELEASE statement ............................................. 206 Removing job dependencies,CSF.......................... 275 Renewable resource .............................................. 382 Repetitive information........................................... 167 Replacing scheduled Event execution ................................. 97 Report balancing using a task ....................................................... 226 Reporting............................................................... 293 history............................................................... 294 invoking............................................................ 301 non-MVS workload .......................................... 311 projected versus actual ..................................... 325 scheduled versus actual .................................... 323 Reporting fields..................................................... 296 character ........................................................... 297 CPU time.......................................................... 299 dates ......................................................... 299, 300 elapsed time...................................................... 298 format ............................................................... 297 numeric............................................................. 298 Request jobs .......................................................... 193 REQUEST keyword.............................................. 193 Requesting a job.................................................................. 194 subApplication ................................................. 247 Requesting a job.................................................................. 251 RESDEF command ............................................... 395 RESDFLT statement ............................................. 392 Resetting time dependency
using CSF ......................................................... 276 Resetting User Status field .................................... 282 Resource ABSORB statement.......................................... 404 Absorption........................................................ 403 counts ............................................................... 395 STEPEND statement ........................................ 401 Step-level release.............................................. 401 RESOURCE statement.......................................... 387 Resource types ...................................................... 382 Resources changing quantitiy ............................................ 397 default requirements ......................................... 392 defining ............................................................ 395 deleting............................................................. 398 feature............................................................... 379 for resubmitted job ............................................ 386 for inserted jobs................................................ 387 real device ........................................................ 384 removing dependency....................................... 205 setting ............................................................... 397 specifying dependency ..................................... 387 types ................................................................. 382 RESREFR command............................................. 396 Resubmitted job,resource requirement.................. 386 RESUME command................................................ 99 in Event .............................................................. 72 Retrieving job documentation ............................... 372 REXX extensions CSF................................................................... 284 ROSCOE datasets as input ............................................................... 60 ESP Procedure.................................................. 140 submitting a job .................................................. 79 ROSSUB command ................................................ 79 Routing jobs resource availability ......................................... 385 using a resource................................................ 414 RUN statement ...................................................... 208 S SADGEN command.............................................. 320 SADGEN,ESPSADG variable .............................. 320 SADUPD command .............................................. 323 SCHEDULE command ........................................... 67 Schedule criteria.................................................... 103 examples........................................................... 119 testing ............................................................... 123 using CLANG................................................... 122 using GENTIME .............................................. 122 where you can use .................................... 103, 104 Scheduled activity dataset ..................................... 320 updating............................................................ 323 Scheduled activity reporting.................................. 318
465
limiting scope ................................................... 320 setting up .......................................................... 318 Scheduled vs actual report .................................... 323 Scheduling Event .................................................................. 67 one-time Event ................................................... 68 Scheduling terms................................................... 111 first day of week ............................................... 110 NOW ................................................................ 114 REALNOW...................................................... 115 workday............................................................ 110 Scope of job statement .......................................... 196 Screens ISPF interface..................................................... 48 Security,based on Event prefix................................ 63 SELECT statement................................................ 208 SELECTED function ............................................ 156 Selecting CSF view.......................................................... 268 Selection criteria history report .................................................... 303 Self-completing task.............................................. 412 SEND command,in Event ....................................... 78 Sending a message in an Application .............................................. 196 using Event......................................................... 78 Setting resource ............................................................ 397 User Status field ............................................... 282 SETWIDTH command ......................................... 309 Simplifying code,using templates.......................... 167 SIMULATE command............................................ 94 Simulating an Event ................................................ 94 SORT command.................................................... 307 Sort criteria,history report ..................................... 307 Sorting,date fields in a history report .................... 300 Special day defining ............................................................ 129 using to schedule .............................................. 130 Special period defining ............................................................ 131 intervals ............................................................ 131 using to schedule .............................................. 133 Started task dependency....................................................... 223 State Awareness .................................................... 433 SUBAPPL statement.............................................. 244 subApplication ...................................................... 244 controlling ........................................................ 247 CSF commands................................................. 270 displaying ......................................................... 246 naming.............................................................. 244 requesting ......................................................... 247 SELECT statement ........................................... 246 WAIT option .................................................... 244
SUBDELAY PNODE ........................................... 258 SUBERROR PNODE ........................................... 259 Submission delay .................................................. 258 Submission error ................................................... 258 SUBMIT command,in Event................................... 78 Submitting a job from Librarian .................................................... 80 from ROSCOE ................................................... 79 Panvalet .............................................................. 80 using Event......................................................... 78 without dependencies ....................................... 203 without resources.............................................. 205 SUBSTR function ................................................. 158 Subtotals history report .................................................... 308 Suppressing messages ........................................... 243 SUSPEND command .............................................. 99 in Event .............................................................. 72 Suspending an Event ............................................... 99 Symbol introducer character ................................. 145 Symbol Library specifying in Event ............................................. 85 Symbolic variables determining length............................................ 157 in ESP Procedures ............................................ 145 substring ........................................................... 157 SYMLIB command ................................................. 85 Synchronizing Applications .................................. 214 Syntax,ESP Procedure .......................................... 140 System affinity ...................................................... 415 SYSTEM calendar ................................................ 125 System identifier Event .................................................................. 65 System shutdown multi-CPU ........................................................ 422 planning............................................................ 420 System Status field CSF................................................................... 260 System,for Event execution..................................... 65 T TAG statement ...................................................... 234 Tagging jobs.......................................................... 234 day of week ...................................................... 234 high priority...................................................... 234 Tape information,extracting .................................. 326 Tape pull program................................................. 326 TAPES function .................................................... 162 Task common uses .................................................... 226 dueout time....................................................... 201 job documentation ............................................ 370 owning Manager of........................................... 442 specifying owner .............................................. 442 TASK keyword ..................................................... 225
466
Templates.............................................................. 167 purpose ............................................................. 167 TEMPLIB statement ............................................. 186 Temporary JCL ..................................................... 186 limited use ........................................................ 187 options.............................................................. 186 TEST command .................................................... 123 Testing schedule criteria................................................ 123 THEN statement.................................................... 141 Threshold resource................................................ 382 Time and date scheduling........................................ 15 due-out time...................................................... 200 early submit time .............................................. 198 job end.............................................................. 200 job start............................................................. 200 job submission.................................................. 203 late submission time ......................................... 200 predecessor....................................................... 203 resetting using CSF........................................... 276 resource ............................................................ 205 Time periods prioritizing work............................................... 410 Time range history report .................................................... 302 TIMELINE flowcharts ......................................................... 350 Titles history report .................................................... 307 TODAY function .................................................. 153 TOMORROW function......................................... 154 TRIGGER command............................................... 96 Triggering an Event................................................. 96 using a link ....................................................... 243 Types of jobs......................................................... 211 Types of resource .................................................. 382 U Updating CSF view.......................................................... 266 scheduled activity dataset ................................. 323 Usage meter............................................................. 49 USE command ........................................................ 49 User description .................................................... 356 labels ................................................................ 356
User Status field CSF................................................................... 260 setting and resetting.......................................... 282 USERDESC keyword ........................................... 356 V V command CSF................................................................... 261 View CSF................................................................... 256 customizing ...................................................... 262 deleting............................................................. 267 selecting............................................................ 268 updating............................................................ 266 View Definitions panel.......................................... 261 VS command........................................................... 84 W Wait option Application....................................................... 184 jobs................................................................... 184 WAIT option subApplication ................................................. 244 Width,history report .............................................. 309 Workday................................................................ 110 Workload object owning Manager of........................................... 442 Workstation............................................................. 28 X XCF commands......................................................... 428 State Awareness ............................................... 433 Trace ................................................................ 434 XCF Service displaying ......................................................... 431 stopping ............................................................ 431 XCF Services data set triggering ............................................. 429 job tracking....................................................... 429 starting.............................................................. 430 Y YESTERDAY function......................................... 154
467
468
Readers Comment Form

ESP v.5.2 UG-02
We want to hear from you!
Please use this form to communicate your comments about this publication, its organization or subject matter with the understanding that Cybermation may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you.
If your comment does not need a reply (for example, pointing out a typing error), check this box and do not include your name and address below. If your comment is applicable, we will include it in the next revision of the manual.
If you would like a reply, check this box. Be sure to print your name and address below. Page Number(s) Comment(s)
Name _______________________________________________ Company _____________________________________________ Address ______________________________________________ Fax: _________________________
469
Mail this form to: Cybermation Inc. 80 Tiverton Court Markham, Ontario L3R 0G4 Attn: Documentation Dept. or Fax it to: Documentation Dept. (905) 479-4614
470
Readers Comment Form

ESP v.5.2 UG-02
We want to hear from you!
Please use this form to communicate your comments about this publication, its organization or subject matter with the understanding that Cybermation may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you.
If your comment does not need a reply (for example, pointing out a typing error), check this box and do not include your name and address below. If your comment is applicable, we will include it in the next revision of the manual.
If you would like a reply, check this box. Be sure to print your name and address below. Page Number(s) Comment(s)
Name _______________________________________________ Company _____________________________________________ Address ______________________________________________ Fax: _________________________
471
Mail this form to: Cybermation Inc. 80 Tiverton Court Markham, Ontario L3R 0G4 Attn: Documentation Dept. or Fax it to: Documentation Dept. (905) 479-4614
472

ESP User Guide

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ESP User Guide

Uploaded by

Copyright:

Available Formats

ESP Workload Manager

About this Guide

Who should read this guide

How to use this Guide

Conventions Used in this Guide

The Syntax diagrams in this guide use the following conventions:

Optional, mutually exclusive parameters. Enter one or none.

Introduction to ESP Concepts Overview

Time and Date Scheduling

Triggers for an Event

Data Set Triggering

Triggers for a data set

Controlling processing requirements

Uses of an ESP procedure

Visually, an Application might look like this:

Last workday of month

The corresponding Application definition might look like this:

For more information on Applications refer to Using Applications on page 178.

Inheriting Job Relationships

Consider the following three jobs and their schedule frequencies.

Distributed Workload Objects

ESP Distributed Manager

Scope of job documentation

Consolidated Status Facility (CSF)

Graphical User Interface

The following are some examples of variables:

Attributes of symbolic variables

Tailoring Job Control Language

Tailoring Job Control Language, Continued

Type of resource ... Threshold

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

Job Monitoring and Alert Processing

System Message Interception

Fields to use as selection criteria

Scheduled activity reporting

Use of modeling reports

For more information on modeling, see the Advanced Users Guide.

Host security programs

For more information on security, see the ESP Administrators Guide.

Getting Started Overview

Accessing ESP as an ISPF Option

Screens for ISPF interface

Accessing ESP as an ISPF Option, Continued

Main Menu Screen

The screen below shows the ESP Main Menu.

ESP's menu panels

Accessing ESP as an ISPF Option, Continued

ESP Main Menu Options

Option Set your ESP defaults

Accessing ESP as an ISPF Option, Continued

ESP Main Menu Options (continued)

Consolidated Status Facility (CSF)

Accessing ESP as an ISPF Option, Continued

ESP Main Menu Options (continued)

Option ESP Utilities

Accessing ESP as an ISPF Option, Continued

USE command sample

Using ESPs Help Option

Using ESPs Page mode

Accessing ESP as an ISPF Option, Continued

Example: Page mode screen

The following is an example of using Page mode:

Input line entry