Esp Advance Dug

ESP Workload Manager
Version 5.2
Advanced Users Guide

ESP-AU-02
Second Edition (October 1999) This edition applies to Version 5 Release 2 of ESP Workload Manager. 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 the 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. All other brand and product names are trademarks or registered trademarks of their respective companies.
ii
ESP Workload Manager Version 5.2
Table of Contents
Summary of Changes........................................................................... 10
Using Symbolic Variables

About Symbolic Variables................................................................... 12 Getting Started With Symbolic Variables ........................................... 13 Using Built-In Symbolic Variables ..................................................... 14 Types of User-Defined Symbolic Variables........................................ 17 Assigning a Value to a Symbolic Variable.......................................... 19 Customizing Date and Time Variables Using GENTIME .................. 21 Combining Symbolic Variables with Other Variables ........................ 26 Using Substrings.................................................................................. 28 Working With Compound Symbolic Variables................................... 31 Working With USER1,2,3,4 Symbolic Variables ............................... 33 Formatting Symbolic Variable Output ................................................ 37 Storing Symbolic Variables................................................................. 41 Using Symbolic Variable Libraries ..................................................... 45 Controlling Which Statements ESP Processes .................................... 47 Resolving Symbolic Variable Errors................................................... 49 Working With Undefined Symbolic Variables ................................... 50 Specifying Job Names ......................................................................... 51 Specifying Time Dependencies in an Application .............................. 52 Using Symbolic Variables to Schedule ............................................... 53 Command Input ................................................................................... 54 Built-in Symbolic Variables ................................................................ 55 Generated Date/Time Symbolic Variables (GENTIME) .................... 61
Tailoring JCL
Using Symbolic Variables ................................................................... 64 Examples of Using Panvalet Data Sets................................................ 65 Adding a Restart Step .......................................................................... 69 Routing Jobs to Other JES Nodes........................................................ 70 Checking Condition Codes.................................................................. 71 Using the CCCHK Statement .............................................................. 72 Using the CCFAIL Statement.............................................................. 77 Including and Excluding JCL .............................................................. 79 Modifying the Symbol Introducer ....................................................... 82 Assigning Security to a Symbol .......................................................... 83 Using an Exclusion Sign...................................................................... 84 Using Automatic Variables (AUTOVARS) ........................................ 87 Simulating the JCL ESP Submits ........................................................ 93 Submitting Jobs Outside ESP .............................................................. 94
Contents
iii
Job Monitoring and Alert Processing

Comparing Job Monitoring and Alert Processing ............................... 96 Functions of Job Monitoring and Alert Processing ............................. 98 Planning for Job Monitoring and Alert Processing ........................... 100 How Job Monitoring Works .............................................................. 101 Using Alert Processing ...................................................................... 112 ESPS Built-in Monitor Variables..................................................... 124
Advanced Use of ESP Procedures

Handling Schedule Criteria ............................................................... 130 Working with Special Periods ........................................................... 136 Testing Invocation of an ESP Procedure........................................... 140 Combining CLANG Elements........................................................... 142 Using Recursive Procedures.............................................................. 147 Overriding Inherited Relationships ................................................... 148 Resolving External Dependencies ..................................................... 154 Defining the Scope of External Dependencies .................................. 156
Advanced Use of Applications

Changing Job Attributes .................................................................... 162 Posting of External and Manual Jobs ................................................ 163 Controlling the Release of Jobs ......................................................... 174 Scheduling Multiple Runs of a Job.................................................... 182 Using SubApplications ...................................................................... 184 Submitting Different Jobs Based on Data Set Activity ..................... 188 Running All or Part of an Application............................................... 190 Taking Action Based on Time........................................................... 193 Setting Up Step-Level Dependencies ................................................ 202
Using Templates
Setting Up A Template ...................................................................... 206 Starting and Ending the Template Definition.................................... 207 Passing Information to a Template.................................................... 210 Working With Templates .................................................................. 213 Using Templates to Define Holidays................................................. 216 Using Templates in Applications ...................................................... 219
Advanced Tracking
Tracking System Messages ............................................................... 228 Manipulating the Tracking of Messages ........................................... 231 Defining Processing Nodes (P-Nodes) .............................................. 233 Displaying Tracking Information ...................................................... 237
iv
Contents
Advanced Forecasting
How Modeling Works ....................................................................... 240 Limitations of Modeling.................................................................... 241 Setting Up Your Model ..................................................................... 242 Generating the Scheduled Activity Data Set ..................................... 243 Activating the Model Processor ........................................................ 244 Defining the Model............................................................................ 246 Defining Your Environment.............................................................. 247 Defining Your Report........................................................................ 251 Closing Definition Mode and Generating Model .............................. 255 Examining the Model Reports........................................................... 256 A Modeling Example With Sample Reports ..................................... 259
Using REXX with ESP

About Using REXX........................................................................... 272 Adding REXX to ESP ....................................................................... 274 Using ESP Commands Within REXX............................................... 276 Assigning REXX Variables to ESP Variables .................................. 277 Using CLANG Variables With ESP-REXX ..................................... 278 Entering ESP-REXX in Multiple Fragments..................................... 279 Built-In Functions With CLANG Equivalent.................................... 280 Commands and Functions With TSO Equivalent.............................. 282 Built-In Functions With No CLANG Equivalent.............................. 283 Trapping Output From Commands.................................................... 289 Inserting Adhoc Request Jobs ........................................................... 294 Using REXX to Build Applications .................................................. 296 Using REXX to Define Special Days................................................ 300 Updating a Symbolic Variable .......................................................... 301 Using REXX Execs ........................................................................... 303
Using ESP With DJC/JES3 Job Networks

What Is a Job Network ...................................................................... 308 Defining the Job Network.................................................................. 310 Selecting Jobs for Submission........................................................... 316 Specifying Other DJC Parameters..................................................... 321 Defining Other Types of Jobs............................................................ 322 Examples of DJC Networks .............................................................. 324 Submitting Job Networks .................................................................. 333 Statements to Define Job Networks................................................... 334
Contents
Using Signals
Typical Uses for Signals.................................................................... 338 Defining the Signal............................................................................ 339 Waiting for the Signal to Post............................................................ 340 Posting a Signal ................................................................................. 341 Cycling a Signal................................................................................. 342 Combining Signals and Scheduling Criteria ..................................... 343 Displaying Signal Information .......................................................... 348 How Pending Signals Work .............................................................. 350 Manual and Automatic Posting of Signals ........................................ 352
GLOSSARY
vi
Contents
About This Guide

Introduction
Enterprise Systems Platform Workload Manager (ESP Workload Manager) is a very powerful and versatile system for scheduling jobs and managing workload. This guide builds on your existing knowledge of ESP. It includes the advanced and less commonly used features of ESP.
Who should read This guide is for the scheduler who has experience with ESP and a general this guide knowledge of the functions of the product. If you fit the following description,
this guide is specifically for you: You are a scheduler or you schedule jobs for your organization. You are an intermediate to expert user of MVS and ISPF. You have ESP installed on your system and have an intermediate to expert knowledge of it. If you do not fit this description but you want to find out about the advanced functions of ESP, you will still find this guide useful.
How to use this guide
Take the following approach to locating and using information in this guide: Read the first section of the relevant chapter to review the general characteristics of the function. Review the examples to understand how you might use a procedure in a specific business situation. Follow the approach used in the examples as a guide when trying the ESP functions on your own.
Continued on next page
About This Guide
About This Guide, continued

How this guide is organized
Using Symbolic Variables introduces you to the flexibility and power of symbolic variables and describes how to create, store, and use these powerful tools in different areas. Tailoring JCL shows you how to use symbolic variables, inclusion statements, and automatic variables in JCL. Job Monitoring and Alert Processing describes how to check on the progress of jobs and how you can use job monitoring and the Alert feature to trigger an Event at a specific stage in a job. Advanced Use of ESP Procedures explains the less common features of ESP Procedures, how to combine multiple features, and how to apply ESP Procedures to different scheduling activities. Advanced Use of Applications describes the advanced features of Applications and shows you how to combine various features of ESP to make your Applications more powerful. Using Templates describes the use of templates for simplifying the specification of repetitious commands or statements, such as those you use to define holidays or jobs. Advanced Tracking discusses how you can define and use system message interception and manual processing nodes. Advanced Forecasting introduces you to ESPs modeling features and describes how models can forecast the way jobs will process in your environment. Using REXX with ESP outlines how REXX interacts with ESP and includes procedures for inserting ESP-REXX statements. Using ESP with DJC/JES3 Job Networks discusses how you can use ESP to set up DJC or JES3 job networks. Using Signals describes how you can use signals in Events to ensure that Events only execute under certain conditions. A glossary defines the terms used in this guide.
About This Guide
About This Guide, continued

Conventions used This guide uses uppercase letters for naming the following: in this guide
Data sets Members Jobs.
Examples: a data set, USER1.SAMP.ESPPROC, a member, PAYROLL, a job, PROD100A. Command names and keywords appear in uppercase. These names appear exactly as you would enter them: Example: Use the HOLD command... When you type information, you can use lowercase letters. For example, when you type a command on the command line, you do not need to type the command in uppercase letters. Menu, screen, and field names will appear in italics: Example: Choose option G from the Main Selection Menu.
About This Guide
Summary of Changes
Introduction
This manual contains information previously presented in ESP-AU-01, which supports ESP Workload Manager Version 5.1. This manual contains terminology, maintenance and editorial changes. A vertical line to the left of the text indicates technical changes or additions to the text.
Changed information
New information The following symbolic variables have been added:
ESPSID ESPSMFID ESPSUBSYS CPUSERIAL CPUMODEL SYSJNAME HWNAME LPARNAME VMUSERID SYSPLEX SYSNAME SYSCLONE ESPDSN.
10
About This Guide
Using Symbolic Variables Overview

Introduction
ESP provides powerful substitution capabilities through the use of symbolic variables. A symbolic variable is an object whose value may be changed during ESP processing. The value of a variable is a single character string, of any length, that may contain any characters. When ESP encounters a symbolic variable, it substitutes the current value of that variable. With symbolic variables you have the flexibility to define date parameters, specify job names, define job dependencies and to use in command input. This chapter contains the following topics: Topic About Symbolic Variables Getting Started With Symbolic Variables Using Built-In Symbolic Variables Working With User-Defined Symbolic Variables Working With Undefined Symbolic Variables Specifying Job Names Specifying Time Dependencies in an Application Using Symbolic Variables to Schedule Command Input Built-in Symbolic Variables Generated Date/Time Symbolic Variables (GENTIME) See Page 12 13 14 16 50 51 52 53 54 55 61
In this chapter
11
About Symbolic Variables

Benefits of using symbolic variables
You can use symbolic variables throughout ESP to enhance its flexibility and power. Some reasons for using symbolic variables are: Time savings - you do not have to enter specific characters, such as dates, each time you want to perform the same kind of processing. Reduction of coding errors - you enter a symbolic variable only once. Reduction in length of input - symbolic variables shorten the line of input data. You can insert symbolic variables in: ESP Procedures Job Documentation members Events JCL Symbolic variable libraries ESP Initialization Parameters USER1,2,3,4 parameters (with TRIGGER and APPLJOB RESUB commands) Text of the TITLE and FOOTING commands of ESP.
Where to insert symbolic variables
12
Getting Started With Symbolic Variables

Introduction
ESP has a number of built-in symbolic variables that are listed at the end of this chapter. Once you master these symbolic variables, you can create your own symbolic variables. To create you own symbolic variables, refer to Working With User-Defined Symbolic Variables on page 16.
Each type of symbolic variable has its own format. Format of symbolic variable The following conventions apply to all ESP symbolic variables: conventions Explanation The symbolic variable introducer distinguishes symbolic variables from other data. ESP assigns the % symbolic variable as a default at installation. Use % in front of the symbolic variable name. Use when you want to use the value of a symbolic variable. For example, in an assignment statement like NAME=JEAN, %NAME resolves to the value of JEAN. Other Introducers To use a different introducer: Make a global change to an ESP initialization parameter or Change the introducer in the JCL for a single job or Use a double percentage sign %%. Single Quotation Enter at the beginning and end of the symbolic Marks () variable value whenever you assign a value to symbolic variable name. For example, P=IEFBR14 End of symbolic Use any of the following to signify the end of a variable symbolic variable name: A period. Another separator (such as a space, comma or a semicolon). Another introducer character and symbolic variable. Caution: ESP treats anything of the form %X(%Y) as a substring specification. If you need to use this format, you must signify the end of the symbolic variable %X as described above. For example, use %X.(%Y). Symbolic Variable % - Symbolic Variable Introducer
13
Using Built-In Symbolic Variables

About built-in symbolic variables
There are a number of symbolic variables that are built-in to ESP. Each of these symbolic variables has a specific name and function. For a detailed list of built-in symbolic variables, refer to Built-in Symbolic Variables on page 55. The name of a built-in date/time symbolic variable consists of a prefix and descriptive characters. For example, the built-in symbolic variable %ESPADAY consists of the prefix ESPA and the descriptive characters DAY. Refer to the following for a description of the prefixes: Prefix ESPA ESPS Explanation Tells ESP to substitute the actual submission value. Tells ESP to substitute the scheduled value at the time of processing.
Format of a built-in symbolic variable name
Understanding the prefixes
Example 1: An EVENT using built-in symbolic variables to send a message
In this example, the EVENT is triggered by a data set. The EVENT uses builtin symbolic variables to send a message to console 1. Built-in symbolic variables represent the changeable components of the message as follows: %ESPEVENTrepresents the name of the EVENT %ESPATIME represents the actual time the EVENT triggers Following is an example of this EVENT:
EVENT ID(CYBER.TRIGPAY) SEND %ESPEVENT HAS BEEN TRIGGERED AT %ESPATIME CN(01)
Following is an example of the message on console 1 if this EVENT is triggered at 09.45.07:

CYBER.TRIGPAY HAS BEEN TRIGGERED AT 09.45.07
14
Using Built-In Symbolic Variables, continued

Example 2: Built- This example uses built-in symbolic variables to represent a date parameter in symbolic that shows the numbers of the scheduled month, scheduled day, and scheduled variables create a year. Assume you want the format of the date parameter to look like this: date parameter
MMDDYYYY Built-in symbolic variables to represent the changeable components of the date parameter, as follows: %ESPSMM represents the scheduled number of the month. %ESPSDD represents the scheduled day of the month. %ESPSYEAR represents the scheduled day of the year. For a scheduled date of April 20th, 1998, the symbolic variables resolve to form a date parameter like this:
Symbolic Variables
%ESPSMM%ESPSDD%ESPSYEAR
Substituted values of April 20, 1998 04011998
15
Working With User-Defined Symbolic Variables Overview

Introduction
This section explains the two types of user defined symbolic variables and how they are used. This section contains the following topics: Topic Types of User-Defined Symbolic Variables Assigning a Value to a Symbolic Variable Customizing Date and Time Variables Using GENTIME Combining Symbolic Variables with Other Variables Using Substrings Working With Compound Symbolic Variables Working With USER1,2,3,4 Symbolic Variables Formatting Symbolic Variable Output Storing Symbolic Variables Using Symbolic Variable Libraries Controlling Which Statements ESP Processes Resolving Symbolic Variable Errors See Page 17 19 21 26 28 31 33 37 41 45 47 49
In this section
16
Types of User-Defined Symbolic Variables

About userdefined symbolic variables
A user-defined symbolic variable can be either a character string or an integer. symbolic variable variables are character variables by default unless you declare them as integers in a declaration statement. You can work with symbolic variables in ESP Procedures and symbolic variable libraries. These areas are discussed under the topic Storing Symbolic Variables on page 41. The following rules apply to naming a user-defined symbolic variable: The symbolic variable cannot exceed 64 characters. The symbolic variable name cannot be the name of a CLANG built-in function and should not be the name of a built-in symbolic. The first character of the symbolic variable name must be alphabetic. Characters in position 2 to 64 can be any combination of alphabetic, numeric, national characters or underscore. Following are the characteristics or character strings and integers:
Format of userdefined symbolic variables
Understanding user-defined symbolic variables
Symbolic Variable Character
Explanation Is by default a variable length field. To have a fixed length field, define the field length in an assignment statement Use if you want to assign values that are either alphabetic or numeric. Manipulate these values as character strings. For example: P=IEFBR14. Use if you want to assign arithmetic values or expressions. Manipulate these values as numbers. For example: I=3*26 and NUMBER=39. Note: You must use an INTEGER statement to define an integer symbolic variable before you can assign a value to it.
Integer
17
Types of User-Defined Symbolic Variables, continued

Example 1: Defining an integer symbolic variable
The following input line defines symbolic variable X as an integer symbolic variable:
INTEGER X
You can also declare more than one symbolic variable in the same statement. Example 2: Defining multiple The following line declares integer I, WEEK#, and DD: integer symbolic variables
INTEGER I,WEEK#,DD
18
Assigning a Value to a Symbolic Variable

Overview
You can assign either a value or an expression to a symbolic variable as in the following examples: P=IEFBR14 assigns a value to the symbolic variable. NUM=3*26 assigns an expression to the symbolic variable. The integer NUM has the value 78. A value must be assigned to a symbolic variable prior to its use. Note: If you assign a character string to an integer variable, ESP evaluates the character string as if it were an arithmetic expression and then stores the result as an integer.
Format of assigned statements
The following formatting rules apply when you are assigning a value to a symbolic variable: For character symbolic variables, place single quotation marks ( ) around the assigned value. For example, JOBNAME=PAYROLL. If you want a quotation to be inserted in the value, use two single quotation marks (). For example, MESSAGE=ITS ALMOST DONE Do not add the introducer character (%) to the symbolic variable when you are assigning a value to the symbolic variable. For example, use NAME=FRED not %NAME=FRED.
19
Assigning a Value to a Symbolic Variable, continued

Assigning a value An integer variable requires a definition before you can assign a value to it. to a defined The following example shows how you can assign a value to an integer integer
immediately after you define it.

INTEGER X
X=2 When processing an ESP Procedure, ESP performs symbolic variable substitution prior to any IF checking. When you define an integer variable, you should define it outside the scope of any IF statement. You can then assign it a value. For example:
INTEGER X,Y IF TODAY(MONDAY) THEN DO X=1 Y=%X+6 ENDDO
20
Customizing Date and Time Variables Using GENTIME

Overview
To customize the date and time symbolic variables for scheduling criteria, use a GENTIME command. Refer to Generated Date/Time Symbolic Variables (GENTIME) on page 61 for a list of the symbolic variables that the GENTIME command generates. Following is the format of the GENTIME command:
GENTIME prefix criteria
Format of the GENTIME command
Description of the GENTIME command
Following is a description of the parts of the GENTIME command:
Field GENTIME Prefix
Description Is the command name. Must be entered in uppercase. Is the part of the GENTIME command that you assign. Can be from 1 to 8 characters (national characters, such as #, are acceptable).
Criteria
Note: The prefixes ESPA and ESPS are reserved for ESPs built-in symbolic variables and cannot be used in the GENTIME command. Consists of standardized descriptive characters. For example, the symbolic variable characters MM represents two digits of the scheduled month. Note: Refer to the Table at the end of this chapter for a list of built-in GENTIME names.
21
Customizing Date and Time Variables Using GENTIME,

continued To generate symbolic variables that refer to the next workday, you choose the symbolic variable prefix NW. Following is the GENTIME command:
GENTIME NW TODAY PLUS 1 WORKDAY
Example of generating a date/time symbolic variables
The above input generates three date and time symbolic variables: %NWMM %NWDD %NWYY You can now use these symbolic variables as follows:
%NWMM%NWDD%NWYY
For example, if today is August 10, 1999 and tomorrow is a workday, these symbolic variables are resolved as follows: Symbolic Variables Substituted values on August 10, 1999 081099
%NWMM%NWDD%NWYY
22

continued You can use the output from one GENTIME command as input to another GENTIME statement. The following example uses a GENTIME command to generate a date variable for one week ago. This date is then used in the second GENTIME to generate date variables for the workday prior to one week ago:
/* one week ago GENTIME PWK TODAY LESS 1 WEEK /* 1 workday prior to 1 week ago GENTIME PWD %PWKDATE LESS 1 WORKDAY
Using multiple GENTIME commands
If today is August 12, 1999, the symbolic variable PWKDATE resolves to August 5, 1999 and PWDDATE resolves to August 4, 1999.
23

continued
Other examples The following table lists some typical schedule criteria for a GENTIME using GENTIME command. You can adapt the format from these examples for use in your own
GENTIME commands: Scheduling User Criteria Prefix Seven days after OVER today Two workdays before PPD today Previous workday PD Previous day Next day Next workday Two workdays after today One week prior to today First day of current month Previous month TMSPD TMSND ND NND LW BGMNTH PMNTH GENTIME Statement GENTIME OVER TODAY PLUS 7 DAYS GENTIME PPD TODAY LESS 2 WORKDAYS GENTIME PD TODAY LESS 1 WORKDAY GENTIME TMSPD TODAY LESS 1 DAY GENTIME TMSND TODAY PLUS 1 DAY GENTIME ND TODAY PLUS 1 WORKDAY GENTIME NND TODAY PLUS 2 WORKDAY GENTIME LW TODAY LESS 1 WEEK GENTIME BGMNTH 1ST DAY OF MONTH STARTING TODAY GENTIME PMNTH 1ST DAY OF MONTH LESS 1 MONTH STARTING TODAY GENTIME PMNTH1 1ST DAY OF MONTH STARTING %PMNTHDATE
First day of previous month
PMNTH1
24

continued You can test the symbolic variables produced by a GENTIME command prior to storing the generated symbolic variables permanently in a symbolic variables library or ESP Procedure. Enter the following commands in Page mode or Line mode: Step 1 1 Action Enter the GENTIME command with your prefix and criteria. Enter the ECHO command to send the symbolic variables back to your terminal for display
Testing date/ Time symbolic variables
Note: When you use a GENTIME command for testing or demonstration purposes, the generated symbolic variables are only temporary. They are lost when you exit from the screen.
Example: Testing The following example shows how to test the generated symbolic variables: GENTIME
Enter the following input, using Page mode or Line mode:

GENTIME PD YESTERDAY ECHO %PDMM%PDDD%PDYY
Assuming that you test the symbolic variables as of September 20th, 1998, the values sent to your terminal should look like this:
Symbolics %PDMM%PDDD%PDYY
Substituted Values on September 20, 1998 091998
25
Combining Symbolic Variables with Other Variables

Overview
You can combine symbolic variables with the following: Other variables Literal character strings Constants. To combine symbolic variables, you concatenate or attach the symbolic variable to another character or group of characters.
Understanding concatenation of symbolic variables
To assign values to variables V1 and V2, your statements might look like this: Example 1: Concatenation of multiple V1=ABC symbolic V2=DEF variables Assign a value to symbolic variable V3 by concatenating symbolic variable V2 to the end of V1. Enter the following statement:
V3=%V1%V2
When ESP substitutes a value for V3, it uses ABCDEF. If you want to include a period (.) in your concatenated string, use 2 periods (..) as ESP will treat the first period as a delimiter. For example, if you want V3 to have the value of V1 concatenated with V2 and separated with a period, use the following:
V3=%V1..%V2
When ESP substitutes a value for V3, it uses ABC.DEF.

26
Combining Symbolic Variables with Other Variables, continued

Example 2: Concatenation of symbolic variables and literal strings You can concatenate a symbolic variable onto a literal string. In this case, the symbolic variable V1 has the value ABC and the literal string is XYZ. Assign a value to symbolic variable V4 by concatenating V1 to XYZ:
V1=ABC V4=%V1+XYZ
Note: The plus sign (+) joins the values on the right side of the above statement. When ESP processes the above input, the result is ABCXYZ.
Example 3: Concatenation of symbolic variables and contents
You can combine a symbolic variable with a constant, either by typing a separator or by creating a new variable. Assume you want to create a new symbolic variable V5 by concatenating the constant named PAYROLL to the end of the symbolic variable%ESPSMM. Method 1: Use a period (.) as a separator between the symbolic variable name and the constant. For example, you might define symbolic variable V5 like this:
V5=%ESPSMM.PAYROLL
Method 2: You can create a new symbolic variable, such as P, to represent the name of the constant. You then concatenate the new symbolic variable %P to the original symbolic variable %ESPSMM. Define symbolic variable V5 this way:
P=PAYROLL V5=%ESPSMM%P
If ESP is scheduled to process V5 in the month of January, the result is V5=01PAYROLL.
27
Using Substrings
Overview
You can use substring notation when you want to use a portion or substring of a symbolic variable. If you are working with symbolic variables in an ESP Procedure, you can also use the SUBSTR built-in function for substrings. The syntax for substring notation is:
%symbolic(start_position:end_position)
Format of substring notation
Understanding the format of the substring notation
Refer to the following for a description of the parts of the substring format:
Field symbol start_position
Description The name of the symbolic variable. The starting position in the symbolic variable. Note: If end_position is omitted, this represents the length of the substring, beginning at position 1. The ending position in the symbolic variable. Note: This field is optional.
end_position
Examples of the substring notation
To explain how you can use substring notation to modify the length of a symbolic variable, consider a symbolic variable LONGWORD assigned the value HIPPOPOTAMUS. Use any of the following methods to modify the field length.
In this situation, you want the result to be HIP. To remove the characters at Example 1: Create a shorter the end of the symbolic variable name, enter the following: version of the symbolic variable
%LONGWORD(3)
28
Using Substrings, continued
To force a longer field length, ESP can add trailing blanks to the end of the Example 3: Creating a longer symbolic variables value. symbolic variable
In this situation you want the resulting value to have fixed field length of 20. Since there are only 12 characters in HIPPOPOTAMUS, use substring notation to increase the length to 20. Enter the following:
%LONGWORD(20)
The resulting value is HIPPOPOTAMUS . Note that your installation may have changed the way this works in that a string will not be padded with blanks when the specified length is longer than the symbolic variables value. Substring notation is very useful for formatting date values, as the following example demonstrates.
Assume that today is Sunday, September 20,1998. The following table Example 4: Substring demonstrates several methods of entering symbolic variable names and the notation sets field corresponding values for each symbolic variable: length of date Symbolic Variable Name %ESPADAY %ESPADATE %ESPAMONTH(2) %ESPAYEAR(3:4) Corresponding Values SUNDAY SUNDAY 20TH SEPTEMBER 1998 SE 98
29
Using Substrings, continued

Example 5: Extracting the generation number of a GDG
This example uses the LENGTH function and substring notation to extract the 4-character generation number of a GDG that has caused a data set trigger. The length of the data set name in this example varies. The LENGTH function calculates the length of the data set name, represented by ESPTRDSN. Substring notation extracts the appropriate substring.
INTEGER X X=LENGTH(ESPTRDSN) GEN=%ESPTRDSN(%X-6:%X-3)
For example, if the data set name that caused the data set trigger is A.B.C.G0293V00: X=14, because there are 14 characters in the data set name GEN extracts a substring of the data set name, beginning with position 8 and ending with position 11. This resolves to 0293.
30
Working With Compound Symbolic Variables

Overview
A compound symbolic variable combines the values of any number of other symbolic variables by means of iterative substitution. The following is the format for inserting compound symbolic variables: Parentheses ( ) enclose the symbolic variables immediately following the symbolic variable introducer (% by default). The characters within the parentheses are known as a test. There is no maximum limit to the number of nests. Any compound variable can nest more compound variables. If there are multiple sets of nests, insert each nest in a separate set of parentheses. For example, A=%(B%(C%D)).
Format of compound symbolic variables
Example of using The following example uses compound symbolic variables to define daily compound variations. In this example, you require different tape volume serial numbers symbolic for a job, depending, on the day of the week you schedule a job. Follow these variables
steps:
Enter the following input in a symbolic variable library or an ESP Procedure:

VOL1=TAPESUN VOL2=TAPEMON VOL3=TAPETUE VOL4=TAPEWED VOL5=TAPETHU VOL6=TAPEFRI VOL7=TAPESAT VOLX=%(VOL%ESPSDOW#)
%ESPSDOW# is a built-in ESP symbolic variable that represents the weekday number of the scheduled day. Sunday is 1, Monday is 2, Tuesday is 3, and so on. The values are not influenced by any definitions you may have for your calendars. Next, instruct ESP to retrieve the volume serial number that corresponds to the matching week day. Your JCL input looks like this:
VOL=SER=%VOLX
31
Working With Compound Symbolic Variables, continued

Example of using compound symbolic variables, continued
If ESP submits the above JCL on a Tuesday, it produces the following results:
VOLX=`%(VOL%ESPSDOW#)'
VOLX=`%VOL3'
VOLX=`TAPETUE'
VOL=SER=TAPETUE
32
Working With USER1,2,3,4 Symbolic Variables

Overview
ESPs TRIGGER and SIMULATE commands support four user symbolic variables: %USER1, %USER2, %USER3, %USER4. You can use these symbolic variables to pass information to an ESP Procedure and JCL. Each variable can be up to 80 characters in length. The following example uses the USER symbolic variables to send a message to a user. When you want to send a message, you will need to supply the message text and the user ID information. 1. Define an ESP Procedure, like the one below, to send a message. %USER1 represents the user ID(s) to receive the message; %USER2, %USER3, %USER4 represent the message text.
USER1- userid(s) - separate with commas USER2- message text USER3- message text USER4- message text SEND %USER2 USER(%USER1) SEND %USER3 USER(%USER1) SEND %USER4 USER(%USER1) /* /* /* /*
Example 1: Sending a message
2. Define an Event to invoke the above Procedure, like this:

EVENT ID(USER01.SEND_MESSAGE) INVOKE CYB.ESP.PROCS(SENDMSG)
33
Working With USER1,2,3,4 Symbolic Variables, continued

Example 1: Sending a message, continued
3. When you trigger the Event, pass the USER symbolic variables, like this:
ESP ----------------------TRIGGER AN EVENT----------------------COMMAND ===> FIll in any of the following optional fields and then press enter) REPLACE/ADD ===> (Defaults to REPLACE ) TRIGGER TIME ===> (May include date. Default is NOW). NOXEQ (Y/N) ===> ( Y bypasses next scheduled execution) SYSTEM ===> (System ID) APPL on HOLD ===> ( Y places any APPLgenerated by Event in APPLHOLD) User Parameters passed to Event: USER1 ===> FRED USER2 ===> ***************************** USER3 ===> SCHEDULING IS EASY WITH ESP USER4 ===> ***************************** ROOTJOBS ===> ===>
Alternatively, you can use the TRIGGER command to trigger the Event through page mode, batch, a system console, or an ESP Procedure. The following example demonstrates how to pass the USER variables on the TRIGGER command.
TRIGGER USER01.SEND_MESSAGE USER1(FRED) + USER2(******************************) + USER3( SCHEDULING IS EASY WITH ESP ) + USER4(*****************************)
34

Example 2: Running adhoc jobs
This example uses the USER parameters to simplify the process of submitting adhoc jobs. This allows you to use a single Event and a single ESP Procedure for multiple adhoc jobs which a user may request at anytime. With the proper security controls, you may allow users to submit their own work using this technique. 1. Set up an ESP Procedure which submits the job. One method is shown below.
SUBMIT SYS1.JCLLIB(%USER1)
2. Define an event to invoke the above procedures. 3. Trigger the Event and pass the job name as the USER1 variable. Note: Instead of using a SUBMIT command, you might want to submit the job as part of an Application. This allows you to view the job using the Consolidated Status Facility. You can choose to create a single job Application or insert the job into an active Application. Following are sample ESP Procedures for each of these methods: Create a Single Job Application In this example, ESP generates an Application containing one job. The name of the Application is the same as the jobname.
APPL %USER1 JCLLIB SYS1.JCLLIB JOB %USER1 RUN ANY ENDJOB
35

Example 2: Running adhoc jobs, continued
Insert Job Into an Active Application In this example, ESP inserts the job into the current generation of an Application called LEFTOVER.
ESP AJ %USER1 INSERT APPL(LEFTOVER.0)
Example 3: Resubmitting a Job from an operator console
This example uses the USER parameters to resubmit a job from an operator console. 1. Set up an ESP Procedure that issues an AJ command to resubmit a job, like this:
ESP AJ %USER1 RESUB APPL(%USER2..0)
2. Create an Event (e.g. CYBER.RESUB) to invoke the above Procedure. 3. Trigger the Event. Pass the jobname as the USER1 variable and the Application name as the USER2 variable. An example is shown below. The jobname is PAYJOB1 and the Application name is PAYROLL.
F ESP,TR CYBER.RESUB USER1(PAYJOB1) USER2(PAYROLL)
This results in ESP issuing the following command:

ESP AJ PAYJOB1 RESUB APPL(PAYROLL.0)
Alternatively, you can use separate Events for different Applications so that the Application name is not required. You might have Events like CYBER.RESUB_PAYROLL and CYBER.RESUB_BILLING, for example, to resubmit jobs in the PAYROLL and BILLING Applications, respectively.
36
Formatting Symbolic Variable Output

Overview
ESP lets you use various methods to control the way a symbolic variable appears in printable form. ESP offers you the flexibility of using either the built-in formatting functions or an output format descriptor to organize your output data. These methods include: using built-in formatting functions using output format descriptors. The following topics describe the above methods in detail. You can use any of the built-in formatting functions appearing in the following table: Function %CE %RJ Format of Output Centers the assigned value within the output. Justifies the assigned value on the right side of the input line. Example: This example defines a title for reporting output including: report name followed by five digits of the time and the full date (all centered over output). right-justified page number. Enter the formatting function as follows:
TITLE ESP REPORT%CE(%TIME(5) %DATE)%RJ(PAGE%PAGE)
Using built-in formatting functions
%LENGTH Results in a numeral denoting the length of the assigned value. Example: Assume that THURSDAY is the value for %ESPSDAY. Since there are 8 characters in THURSDAY, the expression %LENGTH(%ESPSDAY) results in the numeral 8.
37
Formatting Symbolic Variable Output, continued

Using built-in formatting functions, continued
Function %EVAL
Format of Output Results in a numeral denoting the value of an expression. By combining %EVAL with an output format descriptor at the end of the expression, you can insert leading blanks or zeros in the resulting output.(See the topic on output format descriptors later in this chapter.) Example: Assume that the input is: %LENGTH(%ESPSDAY) The resulting output is the numeral 8. By adding %EVAL and the format descriptor (F5) at the start and end, respectively, the revised input looks like this: %EVAL(%LENGTH(ESPSDAY)) (F5) This expression results in the output 00008
38

Using output format descriptors
Using output format descriptors gives you greater control over the positioning of characters in your ESP output. Output format descriptors are formatting characters that ESP defines for you. You can use the descriptors with symbolic variables to add or drop blank spaces and zeros in front of the characters. symbolic variable. The following table shows the output descriptors you can use with ESP: Descriptor Explanation Sets a field to a fixed length, with leading zeros preceding the Fn value you assign to the field. F is the formatting character. n is the number of characters in the fixed length. The maximum number is 15. Assume that %I is the symbolic variable and that the value for I is 100. You want the output to have a fixed length of 6 characters with leading zeros, like this: 000100 . To obtain the above output results, type the symbolic variable followed by the format descriptor enclosed in parentheses (), like this: %I(F6). Sets a field to a fixed length, with leading blanks preceding the value you assign to the field. Z is the formatting character. n is the number of characters in the fixed length. The maximum number is 15. Assume that %I is the symbolic variable and that the value for I is 100. In this situation, you want the output to have a fixed length of 6 characters, with leading blanks, like this: 100. To obtain the above output results, type the symbolic variable followed by the format descriptor enclosed in parentheses(), like this: %I(Z6).
Zn
39

Using output format descriptors, continued
Descriptor Explanation Sets a field to a variable length with no leading zeros and blank V spaces preceding the assigned value. This is the default output format for numeric variables. V is the formatting character and is the only character in this descriptor. Assume that I is assigned the value of 00100. In this situation the variable has 2 leading zeros. To remove the leading zeroes, type the symbolic variable followed by the format descriptor enclosed in parentheses(), like this:%I(V). This resolves to 100.
40
Storing Symbolic Variables

Overview
You can define and assign values to a symbolic variable in an ESP Procedure, a job documentation member, or in a symbolic variable library. The same rules apply to working with symbolic variables in job documentation members and ESP Procedures.
Using symbolic variables in symbol libraries
The following statements can only be used with symbolic variables stored in a symbolic variable library (Caution: You cannot use these statements in an ESP Procedure): %INCLUDE %EXCLUDE %ENDINCL %ENDEXCL CHECKEXC NOCHECKEXC SECURE FLAGUNDEF ALLOWUNDEF Note: The first four statements in the above list are statements that use the symbolic variable introducer character; they are not symbolic variables.
Using symbolic variables in ESP Procedures using the INVOKE command
You can store symbolic variables in an ESP Procedure without using symbolic variable libraries. You simply direct ESP to the data set member where the symbolic variables are stored by using an INVOKE command from an Event or from another ESP Procedure. This technique offers you the flexibility of CLANG. For example, you can use IF-THEN-ELSE type logic and other English language elements to define and work with symbolic variables.
41
Storing Symbolic Variables, continued

Example: Invoking symbolic variables
The following example uses an INVOKE command in an Application to invoke a data set containing symbolic variables. These symbolic variables can be used in this Application definition and in the JCL for jobs submitted as part of this Application
APPL BILLING JCLLIB SYS1.JCL INVOKE CYB.SYMBOLS(DATES) JOB . . . ENDJOB
CYB.SYMBOLS(DATES)
GENTIME ND TOMORROW DATE1=%NDMM%NDDD%NDYY MYDSN=CYB.ESP.DATA
Using symbolic variables in Applications
You can also define and work with symbolic variables as part of your Application. The following are some rules to follow: A variable has the value given to it by the last assignment statement executed. At Application process time, an assignment made to a variable within the scope of a JOB statement, is available only for that job. A value must be assigned to a symbolic variable prior to its use. You cannot use a symbolic variable assigned a value within the scope of a JOB statement as part of a jobname or qualifier. Ensure that any symbolic variables used to create a jobname or qualifier will have the same value at process time that they did at Application generation time. Actual date and time symbolic variables (e.g. %ESPATIME) for job names and qualifiers should not be used, as their values change.
42

Example: Using symbolic variables in an Application
The following example shows how to assign values to symbolic variables in an Application: The following is an Application with multiple runs of the same job called EXTRACT. Each run requires a different division number which is specified for each job using a variable called DIVISION. During simulation and Application generation modes, DIVISION has the value 789 because this is the last value assigned to it. However, during Application process mode, ESP submits each job with a different DIVISION number.
APPL EXTRACTS JCLLIB SYS1.JCL JOB A.RUN1 DIVISION=123 RUN DAILY RELEASE A.RUN2 ENDJOB JOB A.RUN2 DIVISION=456 RUN DAILY RELEASE A.RUN3 ENDJOB JOB A.RUN3 DIVISION=789 RUN DAILY ENDJOB
43

Using built-in functions
A number of functions are already built in to ESP. You can use the following functions in an ESP Procedure to work with symbolic variables. For more information on these functions, refer to Working with ESP Procedures in the ESP Users Guide. DEFINED LENGTH Checks to see if a symbolic variable has been defined. It returns either a 1 for true or a 0 for false. Resolves to the length of the variable that comes after the function name (in parentheses). This function does not return a true or false value. Instead, it resolves to a whole number equal to the length of the named symbolic variable. Use this function in an expression or in the concatenation of two or more variables. Resolves to a partial string, based on the symbolic variable that comes after the function name (in parentheses). Specify the symbolic variable name, starting position and length of substring.
SUBSTR
Example: SUBSTR function resolves to the day of the week
In this example the symbolic variable is ESPSDAY, and the function looks like this:
SUBSTR(1,3,%ESPSDAY)
When ESP encounters the above function, it resolves to the first 3 characters of the scheduled day of the week. For example, on a scheduled day of Monday, it resolves the variable to MON.
44
Using Symbolic Variable Libraries

Overview
It is useful to keep common symbolic variables together in a symbolic variable library; the symbolic variables will be available to all Events that refer to that symbolic variable library. Symbolic variable libraries define and store symbolic variables. A symbolic variable library consists of one or more sequential data sets or PDS members. The DEFSYML command gives a logical name to these data set structures. When ESP encounters the name of a symbolic variable library in an Event during processing, it obtains the value from the appropriate data set or member. Different Events can reference the same symbolic variable library. Note: CLANG is not available in a symbolic variable library.
/************************************************* Example: A symbolic variable /* THIS IS THE GLOBAL SYMBOLIC VARIABLE DATA SET*/ library /* IT CONTAINS GENERALLY USEFUL VARIABLES. */ /************************************************* TAPE=3480 PRFX=PROD /* PROVIDE DATE SYMBOLS IN THE FORM /* MM/DD/YY DD/MM/YY AND YY/MM/DD DATEF1=%ESPSMM/%ESPSDD/%ESPSYY DATEF2=%ESPSDD/%ESPSMM/%ESPSYY DATEF3=%ESPSYY/%ESPSMM/%ESPSDD /* /* /* /* GENERATE SOME DATE VARIABLES REFERRING TO THE FIRST WORKDAY OF THIS MONTH, THE LAST WORKDAY OF THIS MONTH, THE PREVIOUS WORKDAY AND THE NEXT WORKDAY FW FIRST WORKDAY OF MONTH STARTING TODAY LW LAST WORKDAY OF MONTH PWD TODAY LESS 1 WORKDAY NWD TODAY PLUS 1 WORKDAY
GENTIME GENTIME GENTIME GENTIME
45
Using Symbolic Variable Libraries, continued

Access to symbolic variable libraries depends on your security system and on Accessing symbolic variable how your system administrator has assigned access to ESP. A system libraries
administrator assigns access to symbolic variables according to the specific library sets that each user group requires. You may already have access to use existing symbolic libraries. However, if you wish to create or change symbolic variables, you require an appropriate level of access to the library. See the ESP Administrators Guide for more information on the setup of symbolic variable libraries. You specify symbolic variable libraries in Events using a SYMLIB command. The following example shows a typical command of this type.
SYMLIB SYMSET1
Referencing libraries in Events
There may be one or more symbolic variable libraries specified in an Event. When ESP encounters a SYMLIB command, it reads the appropriate symbolic variable library data sets. Once ESP has read all data sets identified by the SYMLIB, the Event executes. Note: If ESP encounters more than one value for a symbolic variable, it uses the last value it locates. You can view lists of symbolic variable libraries that are already defined. Viewing lists of symbolic variable These lists display the following: libraries
The names of all library sets. The data sets within each library set. Event prefixes that are eligible to use the symbolic variable libraries. user or group prefixes with authorization to use the libraries (this feature is optional with ESP and may not be available at your installation).
Enter the LISTSYML command to view the libraries at your console, as follows:
LISTSYML
46
Controlling Which Statements ESP Processes

About controlling statements ESP processes
Use the %INCLUDE and %EXCLUDE statements to control the statements that ESP reads from a symbolic variable library. You can control processing according to the following criteria: day of week date time Event ID value of a logical expression. Note: Before using the %INCLUDE and %EXCLUDE statements, check with your system administrator to see if there have been any modifications to the way ESP recognizes these statements.
Using inclusion statements
Inclusion statements specify the statements ESP should include when reading from a symbolic variable library. Use the following statement to start and end inclusion statements: %INCLUDE to define the start of an inclusion statement. %ENDINCL to define the end of an inclusion statement. Note: Instead of a %ENDINCL statement, you can define the end of an inclusion statement by using a second %INCLUDE.
Example: Inclusion statements change the value of a symbolic variable
Suppose you want ESP to obtain different values for the symbolic variable PARMDATA according to the following schedule:
MONTH January 1st to May 31st June 1st to June 30th July 1st to July 31st August 1st to December 1st
VALUE ANY OLD DATA VALUE FOR JUNE VALUE FOR JULY ANY OLD DATA
47
Controlling Which Statements ESP Processes, continued

Example: Inclusion statements change the value of a symbolic variable, continued
To achieve the above results, type the following inclusion statements in the symbolic variable library:
%INCLUDE IF(TODAY(JAN FEB MAR APR MAY AUG SEP OCT NOV DEC)) PARMDATA = ANY OLD VALUE %INCLUDE IF(TODAY(JUNE)) PARMDATA=VALUE FOR JUNE %INCLUDE IF(TODAY(JULY)) PARMDATA=VALUE FOR JULY %ENDINCL
Using exclusion statements
Exclusion statements tell ESP to exclude specific statements when reading from a symbolic variable library. Use the following statements to start and end exclusion statements: %EXCLUDE to define the start of the exclusion statement. %ENDEXCL to define the end of the exclusion statement. Note: Instead of a %ENDEXCL statement, you can define the end of an exclusion statement by using a second %EXCLUDE.
Example: Combining inclusion and exclusion statements
In this example, you want a symbolic variable PROG to take on the value LTAC1000 every weekday, except Monday. On Monday, you want ESP to retrieve the value LTAC1010. To achieve the desired result, insert the following inclusion and exclusion statements in the symbolic variable library:
%EXCLUDE DAY(MON) PROG=LTAC1000 %INCLUDE DAY(MON) PROG=LTAC1010 %ENDEXCL
48
Resolving Symbolic Variable Errors

Overview
Errors can occur when you use symbolic variables that are undefined or if you incorrectly specify the symbolic variable libraries for an Event.
49
Working With Undefined Symbolic Variables

Overview
Undefined symbolic variables usually occur when you make a spelling error in typing a symbolic variable name. By default, ESP does not flag undefined symbolic variables as errors. If a symbolic variable is undefined, ESP assigns the value of the variable name. If you want to instruct ESP to flag undefined symbolic variables, use the following statements in the symbolic variable library: Type FLAGUNDEF to define the start of flagging Type ALLOWUNDEF to define the end of flagging. ESP uses the FLAGUNDEF statement to flag references to undefined symbolic variables in the symbolic variable library data set. It then checks all subsequent symbolic variable references and issues an error message if it finds any more undefined symbolic variables. If the error (an undefined symbolic variable) occurs while it is submitting a job, ESP deletes the job and requests the user to correct and resubmit the job. Below are two examples that demonstrate how to turn the flag indicator on and turn if off when you no longer need it.
In this situation, suppose that you erred when naming the symbolic variable Example 1: Inserting the flag %ESPSDD. Assume you typed %EXPSDD by mistake. Due to the spelling indicator error, %EXPSDD is an undefined symbolic variable. You can flag all your deliberate undefined symbolic variables by typing a FLAGUNDEF command like the one in the following symbolic variable library:
INTEGER I,J,K,WEEK# FLAGUNDEF WEEK#=%EXPSDD/7 + 1
Example 2: Undefined symbolic variables
In this example, assume that the symbolic variables BC and XY are undefined as follows:
FLAGUNDEF A=%BC ALLOWUNDEF B=%XY
If ESP encounters the above statements while it is submitting a job: A=%BC results in an error message (because flagging is on). B takes on the value %XY (because flagging is off).
50
Specifying Job Names

Overview
You can use symbolic variables in ESP Procedures to specify job names or parts (i.e. substrings) of job names. In this example, ESP sets a symbolic variable called DC to the first two characters of the name of the Event invoking this definition. The Event name is available through the built-in ESP variable %ESPEVENT. When building the jobname ESP uses this variable as the 3rd and 4th character. Note that a period is used after %DC to designate the end of the symbolic name.
DC=%ESPEVENT(1:2) JOB OR%DC.1234 RUN DAILY ENDJOB
Example: 3rd and 4th character represent data center code
This allows you to use common Procedures that ESP can invoke through different Events, as shown below.
Event LAX.DAYJOBS JOB OR%DC.1234 SFO.DAYJOBS JOB ORSF1234 ESP Procedure Jobname JOB ORLA1234
51
Specifying Time Dependencies in an Application

Overview
You can use symbolic variables in Application definitions to define time dependencies for jobs. These dependencies include early submit times and various cutoff times such as an abandon submission time.
Example: DELAYSUB and ABANDON SUBMISSION times
In this example, job X has a delayed submission time of %PRODTIME and a cutoff time for submission of %LATE_CUTOFF. ESP assigns the following values: 5PM to LATE_CUTOFF 4PM to PRODTIME on workdays 10 minutes after the scheduled time of the Event to PRODTIME on nonworkdays.
LATE_CUTOFF=5PM IF TODAY(WORKDAY) THEN PRODTIME=4PM ELSE PRODTIME=NOW PLUS 10 MINUTES JOB X DELAYSUB %PRODTIME ABANDON SUBMISSION %LATE_CUTOFF RUN DAILY ENDJOB
52
Using Symbolic Variables to Schedule

About using symbolic variables to schedule
You can use symbolic variables when you are defining schedule criteria for jobs in an ESP Procedure. Symbolic variables allow you to: Represent a frequency. Create your own scheduling terms. Use the GENTIME command to assist you with complex criteria.
Example: Using a This example uses a symbolic variable called X_SCHEDULE to represent the symbolic variable schedule criteria for job X in two different Applications. Job X is submitted as to represent schedule criteria part of APPL1 and is external to APPL2.
APPL APPL1 JCLLIB SYS1.JCL INVOKE CYB.ESP(SCHED) JOB X RUN %X_SCHEDULE ENDJOB
53
Command Input
Overview
You can use symbolic variables in commands that ESP issues. This includes both ESP commands and non-ESP commands (e.g. MVS, CICS, JES, and so on.). Here is an example with the following criteria: $PQ command purges output older than a specified number of days You may wish to purge output older than a specified number of workdays An ESP integer variable can be used to calculate the number of days from 3 workdays ago This variable can be used as part of the $PQ command.
Example: Purging Output
INTEGER NUMBER NUMBER=DAYS_FROM(TODAY LESS 3 WORKDAYS) VS $PQ,Q=U,A=%NUMBER
54
Built-in Symbolic Variables

Overview
ESPs built-in symbolic variables are grouped in the following categories: Time Environment Application. Note: You cannot assign values to built-in symbolic variables. These are symbolic variables that resolve to time and date values. Both actual and scheduled times and dates are available for all symbolic variables. Actual times and dates (ESPA variables) are drawn from the actual system time. Scheduled times and dates (ESPS variables) are based on the time the Event was scheduled to trigger. Type Date Year Symbolic Variable ESPADATE ESPSDATE ESPAYY ESPSYY ESPAYEAR ESPSYEAR Description
Time-based symbolic variables
Month
Day
Event date in full. Example: Sunday 4th January 1998 Last two digits of the year. Example:98 Year. Example: 1998 ESPAMM Number of month. ESPSMM Example:01 for January ESPAMMM First three characters of month. ESPSMMM Example: Jan ESPAMONTH Name of Month. ESPSMONTH Example: January ESPADAY Name of the day ESPSDAY Example: Monday ESPADD Number of actual day of month. ESPSDD Example: 09 ESPADDD Julian day, or the number day in the year. ESPSDDD Example: 365 ESPADOW# Number of day in week, regardless of first day of week setting in a calendar. ESPSDOW# Example: 1 for Sunday, 2 for Monday, etc.
55
Built-in Symbolic Variables, continued

Time-based symbolic variables, continued
Type Time Hour Minutes Seconds
Symbolic Variable ESPATIME ESPSTIME ESPAHH ESPSHH ESPAMN ESPSMN ESPASS ESPSSS
Description Time in 24 hour format. Example: 14.55.32 Hour in 24 hour format. Example: 14 Minute of hour. Example: 55 Number of seconds past the minute. Example: 32
56

Environment symbolic variables
These are variables that hold values describing the local or Event environment. Type Local Variable ESPSID ESPSMFID ESPSUBSYS CPUSERIAL CPUMODEL SYSJNAME HWNAME LPARNAME VMUSERID SYSPLEX SYSNAME SYSCLONE Event ESPDSN Description ESP system identifier. Example: ESPM. SMF identifier. Example: A090. ESP sub-system identifier. Example: ESPM. CPU serial number. Example: 0D0905 CPU model number. Example: 9221 Name of the address space where the symbol is used 1 to 8 character key used for name of the hardware box 1 to 8 character key used for machines with multiple LPARs 1 to 8 character key used when you run MVS under VM 1 to 8 character key used to name your Sysplex 1 to 8 character key used for the name of the current MVS image 1 to 2 character key used for the name of the current MVS image Name of the data set that is calling up the current data line. This symbolic variable can only be used in JCL. Name of the Event. Current ESP group. Current job name. This symbolic variable can only be used in JCL. Name of the library member if any (null if data set is sequential). This symbolic variable can only be used in JCL. ID of the user who triggered the Event. ID of the user who defined, or last modified, the Event.
ESPEVENT ESPGROUP ESPJOBN ESPMEMBER
ESPTRUSR ESPUSR
57

Environment symbolic variables continued
Type Variable Data set ESPTRDSN Trigger Event ESPTRJOB
ESPTRVOL
ESP Procedure
ESPINFOREC
ESPJQUAL ESPREEXEC# ESPSADG
Description The name of the data set if ESP triggers the Event by data set activity. The name of the job or user that created, closed or renamed the data set, if ESP triggers the Event by data set activity. The volume serial of the device on which the data set activity occurred, if ESP triggers the Event by data set activity. Information/Management record number associated with a job. This symbolic variable is only available after job submission and has a default value of null. Qualifier of a job in a DJC/JES3 network. Number of re-executions of an ESP Procedure. If SADGEN run=1, otherwise=0.
58

Application symbolic variables
These are symbolic variables that relate to ESP Applications. Unless noted below, an Application variable is only available during Application process mode. Type Variable Application ESPAGEN ESPAJOB ESPAPPL Description Absolute generation number of an Application. Name of a job in an Application. Name of an Application. This symbolic variable is available during Application generation and process modes. Qualifier of a job in an Application. This symbolic variable is only available during Application process mode. Submission number for a job in an Application. The first time ESP submits a job in an Application, this symbolic variable =1. If ESP resubmits the same job from the same generation of the Application, the submission number increases for that job. This number resets for each generation of an Application. Tag associated with a job in an Application. Name of the current job in an Application. This variable is available during Application generation and process modes. Qualifier of the current job in an Application. This variable is available during Application generation and process modes. Job number of job being rerun. Job name of job being rerun. Name of the fromstep specified on a restart. This only resolves if it is specified on the resubmission panel. User ID initiating a resubmission of a job. Names of root jobs specified on a trigger. Name of the tostep specified on a restart. This only resolves if it specified on the resubmission panel.
ESPAPQUAL
ESPASUB#
ESPATAG ESPCUJOB
ESPCUQUAL
ESPRRJID ESPRRJOB FROMSTEP
RESUB_USER ROOTJOBS TOSTEP
59

Application symbolic variables, continued
Type Flags
Variable ESP_APPL_GEN
ESP_APPL_PROC
Description If generation run=1, otherwise=0. This flag is available during Application generation and process modes. If generation run=1, otherwise=0. This flag is available during Application generation and process modes.
60
Generated Date/Time Symbolic Variables (GENTIME)

GENTIME generated symbolic variables
The following table lists the symbolic variables ESP generates with the GENTIME command. prefix represents the prefix you specify when using GENTIME. Note: You cannot assign values to built-in symbolic variables. Type Date Year Variable prefixDATE prefixYY prefixYEAR Month prefixMM prefixMMM prefixMONTH Day prefixDAY prefixDD prefixDDD prefixDDQL prefixDOW# Description Event date in full. Example: Sunday 4th January 1998 Last two digits of the year. Example: 98 Year. Example: 1998 Number of month. Example: 01 for January First three characters of month. Example: Jan Name of month. Example: January Name of the day of the week. Example: Monday Number of actual day of month. Example: 09 Julian day, or the number day in the year. Example: 365 Ordinal qualifier for day of month. Example: st, nd, rd or th Number of day in the week, regardless of first day of week setting in a calendar. Example: 1 for Sunday, 2 for Monday, etc. Time in 24 hour format. Example: 14.55.32 Hour in 24 hour format. Example: 14 Minute of hour. Example: 55 Number of seconds past the minute. Example: 32
Time Hour Minutes Seconds
prefixTIME prefixHH prefixMN prefixSS
61
62
Tailoring JCL Overview

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, and add a condition code check step to the JCL it submits by entering statements in an ESP Procedure. This chapter contains the following topics: Topic Using Symbolic Variables Examples of Using Panvalet Data Sets Adding a Restart Step Routing Jobs to Other JES Nodes Checking Condition Codes Using the CCCHK Statement Using the CCFAIL Statement Including and Excluding JCL Modifying the Symbol Introducer Assigning Security to a Symbol Using an Exclusion Sign Using Automatic Variables (AUTOVARS) Simulating the JCL ESP Submits Submitting Jobs Outside ESP See Page 64 65 69 70 71 72 77 79 82 83 84 87 93 94
In this chapter
Tailoring JCL
63

About symbolic variables
You can use symbolic variables in ESP to modify JCL, reducing or eliminating the number of manual JCL changes. This saves time and reduces errors. You may use symbolic variables anywhere in JCL except in catalogued procedures. ESP resolves the symbolics at job submission time. You may choose to use symbolics for such things as: Data set names Data parameters Control cards.
64
Tailoring JCL
Examples of Using Panvalet Data Sets

About Panvalet data sets
The use of Panvalet data sets with sequence numbers to hold runtime JCL can cause problems in cases where symbolic variable substitution occurs. Since Panvalet uses non-standard sequence numbers (5 digits rather than 8), they are not recognized as such by ESP. When symbolic variable substitution results in a final value that is shorter than the data length before substitution, the sequence number may be shifted left into the data portion of the card image, thus loading JCL errors. In order to avoid this problem, on lines where such symbolic variable substitution may occur, insert the character pair /* (slash, asterisk), preceded by at least one blank, after the actual data. For example:
%LONGSYMBOL_NAME /*
Example 1: Using In this example, the JCL contains some ESP built-in symbolic variables to a date as input represent the scheduled month number, scheduled month day, and scheduled
year. The symbolic variables are used as part of the date but could appear elsewhere in the JCL.
//SYSIN DD * %ESPSMM%ESPSDD%ESPSYY
When ESP submits this JCL for an Event scheduled on June 9,1998, ESP substitutes the built-in symbolic variables as shown below.
Substituted JCL on June 9, 1998 //SYSIN DD * 060998
Original JCL //SYSIN DD * %ESPSMM%ESPSDD%ESPSYY
Tailoring JCL
65
Examples of Using Panvalet Data Sets, continued

Example 2: Using Date-qualified data sets are often used in production JCL. You can use ESP dates to qualify symbolic variables when there is a need to refer to the current and previous data set names
date-qualified data sets. This technique is especially useful when only working days are valid. In this example, we will create and use the following ESP symbolic variables: %CURRDATE, to represent the current Julian date. %PREVDATE, to represent the previous workdays Julian date. The following statements use ESP built-in symbolic variables and the GENTIME command to create ESP symbolic variables CURRDATE and PREVDATE. These statements could be located within the ESP Procedure that defines the job, invoked from another ESP Procedure, or stored in a symbolic variables library.
GENTIME PREV TODAY LESS 1 WORKDAY CURRDATE=%ESPSYY%ESPSDDD PREVDATE=%PREVYY%PREVDDD
The production JCL looks like this:

//SYSUT1 DD * //SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D%PREVDATE, // UNIT=SYSDA,SPACE=(TRK,1) //SYSUT1 DD * //SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D%CURRDATE, // UNIT=SYSDA,SPACE=(TRK,1)
During ESP processing, the JCL symbolic variables resolve to current values. If ESP processes the JCL for a scheduled date of Monday, February 21, 1998 (Julian day 052) and the previous workday is Friday, February 18,1998, the JCL ESP submits looks like this:
//SYSUT1DD * //SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D98049, // UNIT=SYSDA,SPACE=(TRK,1) //SYSUT1DD * //SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D98052, // UNIT=SYSDA,SPACE=(TRK,1)
You can use ESPs COPYJCL function to save a copy of this JCL as submitted. Refer to the ESP Users Guide for more information on this feature.
66
Tailoring JCL

Example 3: Using This example shows how to assign values to different symbolic variables and different how to use them in JCL. symbolic variables in JCL
Symbolic variable name is DATEPARM and is assigned the string consisting of scheduled month number, scheduled day of month number, and scheduled year separated by /.
DATEPARM=%ESPSMM/%ESPSDD/%ESPSYY
Symbol name is BIGDSN and is assigned a string representing a data set name.
BIGDSN=CYBER.JCL.TEMP.LIBRARY
Symbolic variable name is JOBCARD and is assigned a string representing a typical job card.
JOBCARD=//JOB1 JOB ACC1,NAME,CLASS=A
Once you have assigned values to symbolic variables, you can then use them in JCL. Here is a sample job with JCL that looks like this:
%JOBCARD //S1EXEC PGM=MYPGM,PARM=%DATEPARM //DD DSN=%BIGDSN,DISP=SHR
On December 9, 1998, ESP submits the following JCL:

//JOB1 JOB ACC1,NAME,CLASS=A //S1EXEC PGM=MYPGM,PARM=12/09/98 //DD DSN=CYBER.JCL.TEMP.LIBRARY,DISP=SHR
Tailoring JCL
67

Example 4: Using symbolic variables with values longer than their names
When using symbolic variables in JCL, you may need to ensure that ESP substitutes the value for the symbolic variable in the correct column. This can be a problem if the length of the symbolic variable value is less than the length of the symbol name. In this case, you should use an intermediate symbolic variable that will have the correct length when ESP substitutes the value of the symbolic variable. For example, suppose you want the 3-character month name (%ESPSMMM) and 4-digit year (%ESPSYEAR) to end in column 72 of a control card. Define the following symbol in a symbol library or ESP Procedure.
DATE07=%ESPSMMM%ESPSYEAR
Use %DATE07 starting in column 65 of the JCL, like this: 65 % 66 D 67 A 68 T 69 E 70 0 71 7 72
Here is an example of how ESP may resolve the symbolic variable: 65 J 66 A 67 N 68 1 69 9 70 9 71 4 72
Example 5: Building a control card
This example builds a control card consisting of two dates: LBILDATE previous days date, in MM/DD/YY format FMTHDATE first day of the current month, in MM/DD/YY format. Put the following statements in an ESP Procedure or symbol library.
GENTIME PRE YESTERDAY GENTIME FMT 1ST DAY OF MONTH STARTING TODAY CCARD=LBILDATE=%PREMM/%PREDD/%PREYY,FMTHDTE=%FMTMM/%FMTDD/%FMTYY
Use %CCARD in the JCL for the job. On May 10,1998, ESP resolves the JCL as follows: %CCARD resolves to:
LBILDATE=05/09/98,FMTDATE=05/01/98
68
Tailoring JCL
Adding a Restart Step

About adding a restart step
A restart product may require the insertion of JCL to invoke it. ESP can automatically add a restart step to a job defined in an ESP Application. ESP adds this step when it submits the job. Your installation must identify the statement ESP is to add as the restart step using the ERMSTEP Initialization Parameter in ESPs Initialization Parameter data set. It may look like this:
ERMSTEP(//RESTART EXEC ENCORE)
Format of the restart step
Use the following statement in an Application definition to have ESP add a restart step:
OPTIONS RESTARTSTEP
You can use this statement as a global option for all jobs in an Application or for all jobs within a subApplication, or within the scope of a JOB statement for selected jobs. The statement OPTIONS NORESTARTSTEP turns off the option.
Example of adding a restart step
In the following example, ESP adds a restart step to jobs A and C, but not to job B.
APPL ABC JCLLIB SYS1.JCL OPTIONS RESTARTSTEP JOB A RUN DAILY RELEASE B ENDJOB JOB B OPTIONS NORESTARTSTEP RUN DAILY RELEASE C ENDJOB JOB C RUN DAILY ENDJOB
Tailoring JCL
69
Routing Jobs to Other JES Nodes

About routing jobs
ESP can automatically insert a /*ROUTE statement into the JCL it submits. This statement routes a job to a different node for execution. Include the ROUTE XEQ statement in the job definition, specifying the name of the JES node to which you want to route the job. In this example, ESP adds a /*ROUTE card to the JCL it submits for job B.
JOB A RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY ROUTE XEQ(NODE2) RELEASE C ENDJOB JOB C RUN DAILY ENDJOB
Format for routing jobs
Example: Routing a Job
Note: In order to track jobs, or run Applications that have jobs that run across different JES nodes, your environment must be set up to track jobs across JES nodes. Check with your ESP system administrator before using this feature.
70
Tailoring JCL
Checking Condition Codes

Introduction
You can use ESP to check condition codes, while your jobs are executing, and take different actions. If a job receives a bad condition code, ESP can consider the job as failed and prevent successor jobs from being submitted. ESP provides two methods for handling condition codes: The CCCHK statement The CCFAIL statement. Cybermation recommends that you use the CCCHK statement. It is easier to use and offers more options. For example, you can use multiple CCCHK statements for any job, you can stop a job immediately when a bad condition code is received, or associate a condition code with a particular program. CCCHK was developed to replace CCFAIL and is not intended to be used in combination with CCFAIL. If the two statements are used together, CCCHK overrides CCFAIL.
Tailoring JCL
71
Using the CCCHK Statement

About the CCCHK statement
Use the CCCHK statement to identify specific completion codes and indicate how ESP should handle the job when those completion codes are matched. Some of the features available with CCCHK: Jobs may be stopped immediately after a job step, without executing the remainder of the job. CCCHK statements may be associated with specific step names or specific programs. For example, a CCCHK statement can indicate an action to be taken only when an IEBGENER program ABENDs a certain way. Several CCCHK statements may be active for a single job. For example, one CCCHK statement might indicate a particular action, and other statements might indicate some exceptional cases. A typical CCCHK statement looks like the following. This indicates to fail a job if any return code is greater than zero (i.e. between 1 and 4095).
CCCHK RC(1:4095) FAIL
Format of the CCCHK statement
To use the CCCHK statement, identify: To what it applies. This could be a jobname, a step name, a procedure step name, a program name, or a combination of these. The return codes in which you are interested. Whether it represents a success or a failure. Whether the job should continue or stop.
Limiting the condition code check
You can limit the CCCHK statement to jobs, steps, procedure steps and programs.
In the following example, a condition code greater than zero in STEP10 causes Example 1: Identifying a the job to fail: return code from a step
JOB PAYJOB2 CCCHK STEP(STEP10) RC(1:4095) FAIL
72
Tailoring JCL
Using the CCCHK Statement, continued
In the following example, a condition code of 12 produced by program Example 2: Identifying a IEBGENER for job PAYJOB3 is acceptable. return code from a program
JOB PAYJOB3 CCCHK PROGRAM(IEBGENER) RC(12) OK
Specifying return The RC parameter on the CCCHK statement identifies good or bad return codes codes and must be specified. You can specify return codes as a number (num),
a range of numbers (num1:num2), a system ABEND code (Sccc), or a user ABEND code (Unnn). Note: When specifying a system ABEND code, CCCHK does not affect the normal handling of the ABEND. If you specify CONTINUE on a system ABEND that halts processing, processing does not continue. Use one of the following parameters to indicate success or failure: Specifying success or failure OK FAIL Indicates that the job has not failed. This is the default. Indicates that the job should be considered failed. When the job has failed, it may or may not continue, depending upon the action specified (i.e. CONTINUE or STOP).
Specifying the action
Use one of the following parameters to indicate what action to take: CONTINUE Indicates the job should continue processing with the next step, whether or not the job is considered failed. This is the default. Indicates the job should be stopped immediately. No other steps should be executed.
STOP
Tailoring JCL
73

Specifying the action, continued
If a step fails, and a matching CCCHK statement specifies CONTINUE, the job proceeds as usual. Subsequent steps are given an opportunity to execute, but they are bypassed (as usual) unless their COND parameter specifies EVEN or ONLY. However, when STOP is specified on the CCCHK statement, the job is flushed immediately and not even the COND=EVEN or COND=ONLY steps execute.
MVS RESTART
CCCHK does not work for jobs that have an MVS RESTART job card. The Restart card specifies the step at which to initiate a restart and MVS ignores any step(s) prior to the specified step. The CCCHK statement may appear in the ESP Initialization Parameters or in an Application. You can use the statement as a global option for all jobs in an ESP Application or within the scope of a job statement for an individual job. When a job is executing, all pertinent CCCHK statements are searched sequentially whenever any job step ends. The statements that are pertinent to a job include those in the ESP Initialization Parameters and those in the Application. The statements are searched in the following order: 1. Job specific CCCHK statements within an Application 2. Global CCCHK statements within an Application 3. CCCHK statements placed within the ESP Initialization Parameters. At the end of each step, these CCCHK statements are searched until a statement is found that matches the JOB, STEP, PROGRAM, and RC parameters of the step that just ended. Searching then stops and the first matching CCCHK statement determines the disposition of the job. If FAIL was specified on the first matching CCCHK statement, the job is considered failed. If OK was specified for a particular step, the job is not considered failed, unless the matching CCCHK statement for some other step has indicated FAIL. If the matching CCCHK statement from any step indicates FAIL, the job is considered failed.
Processing the CCCHK command
74
Tailoring JCL

Processing the CCCHK command, continued
If CONTINUE was specified on the first matching CCCHK statement, the job proceeds with the next step. That step may be bypassed if it contains certain COND parameters on its EXEC statement. If STOP was specified, the job stops immediately, and no other steps are executed.
CCHK combinations
The following combinations are possible with the CCCHK statement: OK with CONTINUE FAIL with CONTINUE No action is taken. Processing continues as if CCCHK is not used. The job is treated as a CCCHK failure, but normal processing continues and other failures may be detected. The job is treated as a CCCHK failure and is stopped immediately. The job is treated as a CCCHK failure and is stopped immediately. (It is the same as FAIL with STOP.)
FAIL with STOP OK with STOP
When ESP submits a job, it adds an ESPCCCHK step that runs as the first step Adding the ESPCCCHK step of the job. The CCCHK information is passed as part of SYSIN. If you are using ESP Encore, the Encore step handles the condition code checking.
Example 1: Global CCCHK
The following globally placed CCCHK statement indicates any job in the PAYROLL Application is considered to have failed if any step produces a condition code greater than 0 (i.e. between 1 and 4095).
APPL PAYROLL JCLLIB CYBER.JCL.CNTL CCCHK RC(1:4095) FAIL JOB PAYJOB1 ...
Tailoring JCL
75

The following local and global CCCHK statements indicate any job in the Example 2: Global and Local PAYROLL Application is considered failed and stops processing immediately CCCHK if a condition code of greater that 0 is produced. A condition code of 8 in any statements
step for PAYJOB2 is considered to be acceptable and processing continues for PAYJOB2.
APPL PAYROLL JCLLIB CYBER.JCL.CNTL CCCHK RC(1:4095) FAIL STOP JOB PAYJOB2 CCCHK RC(8) OK CONTINUE
Example 3: Failing jobs based on return code and program
The following local and global placed CCCHK statements indicate: Any job in the PAYROLL Application is considered failed and stops processing immediately if a condition code of greater that 0 is produced. A condition code of 12 produced by program IEBGENER for job PAYJOB3 is acceptable and the job is not flagged as failed and processing continues for this job.
APPL PAYROLL JCLLIB CYBER.JCL.CNTL CCCHK RC(1:4095) FAIL STOP JOB PAYJOB3 CCCHK PROGRAM(IEBGENER) RC(12) OK CONTINUE
Comparing CCCHK to CCFAIL
The CCCHK statement can specify complex criteria more easily than the CCFAIL statement. For example, the following statements perform the same function:
CCFAIL(STEP1,GT,8)(STEP2,GT,4)(STEP3,GT,8)(STEP4,GT,8)(STEP5,GT,8)
CCCHK STEP(STEP02) RC(5:4095) FAIL STOP CCCHK RC(9:4095) FAIL STOP
76
Tailoring JCL
Using the CCFAIL Statement

About using the CCFAIL statement
You can use the CCFAIL statement to identify what condition codes should cause ESP to consider a job as failed. You can use the statement as a global option for all jobs in an ESP Procedure or within the scope of a job statement for an individual job. A job-specific CCFAIL statement overrides the global CCFAIL statement. Note: Cybermation recommends the use of the CCCHK statement instead of the CCFAIL statement for handling condition codes. For information on using CCCHK, refer to Using the CCCHK Statement on page 72. When ESP submits a job, it adds a trailer step (ESPCCFCK) to the job, which executes only if the condition codes specified for failure are not met. Otherwise, the trailer step does not execute and the job fails with a JOB FAILED - JCL ERROR condition. Steps after a bad condition code execute unless you have COND parameters in the JCL to bypass them. Note: The CCFAIL statement is limited by what you can do with the COND parameter in JCL.
Format of the CCFAIL statements
The CCFAIL statement has the following syntax:

CCFAIL (STEPNAME,OPERAND,VALUE)
Field stepname
Description Specifies a step name. You must use the exact job or PROC step name. For procedures, use stepname.procstepname. An asterisk (*) represents any step. A valid operator EQ (equal to), GT (greater than), GE (greater than or equal to), LT (less than), LE (less than or equal to), NE (not equal to), or their corresponding mathematical symbols. The value of the condition code for which you want to check.
operator
value
Tailoring JCL
77
Using the CCFAIL Statement, continued

Examples of CCFAIL statements
The following examples illustrate how you can use the CCFAIL statement to handle condition code checking. Refer to Using Automatic Variables (AUTOVARS) on page 87 for other techniques you can use to handle condition code checking. This example causes a job to fail if any step gets a condition greater than 4.
CCFAIL (*,GT,4)
Example 1: Any step
The trailer step that ESP adds to a job looks like this:
//ESPCCFCK EXEC PGM=IEFBR14,COND=((4,LT))
Example 2: Using This statement will cause a job to fail if it gets a condition code greater than a PROCSTEP zero in procedure step STEPP within the JCL step STEPJ.
CCFAIL (STEPJ.STEPP,GT,0)
Example 3: Global and local conditions
In this example, the job-specific CCFAIL statement overrides the global CCFAIL statement. Job ABC will fail if STEP2 gets a condition code greater than 4. Any condition code for the other steps in the job will be accepted as good.
CCFAIL (*,GT,8) JOB ABC CCFAIL (STEP2,GT,4)
Example 4: Exceptions for a particular step
In this example, the job has 4 steps: STEP1, STEP2, STEP3, STEP4. The following statement will cause a job to fail if STEP2 gets a condition code greater than 4, or if any other step gets a condition code which is greater than 8.
CCFAIL (STEP1,GT,8) (STEP2,GT,4) (STEP3,GT,8) (STEP4,GT,8)
78
Tailoring JCL
Including and Excluding JCL

About including and excluding JCL
ESP can include or exclude portions of JCL it submits by using %INCLUDE and %EXCLUDE statements imbedded in JCL. Note: Before using the %INCLUDE and %EXCLUDE statements, check with your system administrator to ensure there were no changes during your ESP installation that would affect the way ESP recognizes these statements. For example, another product may make conflicting use of these terms, in which case your system administrator can change them.
Format of including and excluding JCL
You can insert any of the following control statements, starting in column 1, in JCL: %INCLUDE %ENDINCL %EXCLUDE %ENDEXCL to begin inclusion to end inclusion to begin exclusion to end exclusion
To continue a %INCLUDE or %EXCLUDE statement onto a second line: Insert a plus sign (+) at the end of the first line, if you dont want any leading blank spaces in the second line. Insert a hyphen (-) at the end of the first line, if you want to include leading blank spaces in the second line. You can include only one continuation per statement.
Criteria used with include and exclude statements
In JCL, you can use the following criteria with inclusion and exclusion statements: Day of week Date Time Event ID JCL being submitted or JCL being copied to COPYJCL Value of a logical expression.
Tailoring JCL
79
Including and Excluding JCL, continued

Example: Using the %INCLUDE statement
This example shows how to use the %INCLUDE statement to include a DD statement on Mondays.
%INCLUDE DAY(MON) //INPUT02 DD DSN=CYBER.XFILE(0),DISP=SHR %ENDINCL
Using logical expressions
The IF keyword lets you selectively include or exclude JCL based on the value of any logical expression.
%INCLUDE IF(TODAY(LAST WORKDAY OF YEAR)) //STEP3 EXEC PGM=CHKWRITE,PARM=YES %ENDINCL
When ESP executes the above statements, it includes STEP3 if the scheduled day is the last workday of the year.
Copying JCL to a You can use statements so that ESP creates a modified copy of JCL it writes to library a COPYJCL library.
Assume you want ESP to use a new version of a job card when it writes the JCL to the COPYJCL library. The control statements from the JCL look something like this:
%EXCLUDE COPYJCL //A JOB CYBAC01,CLASS=A,MSGCLASS=0 %INCLUDE COPYJCL //A JOB CYBAC01,CLASS=A,MSGCLASS=0,RESTART=STEP02 %ENDINCL %ENDEXCL
80
Tailoring JCL
Including and Excluding JCL, continued

Copying JCL to a library, continued
The second line states the job card for the submitted JCL. The fourth line states the job card for the COPYJCL. When ESP submits this JCL, it: Creates a modified version of the job card containing only the expression covered by the %INCLUDE statement. Writes the resulting data to a member in the COPYJCL library. When ESP writes the JCL to a COPYJCL library it removes all control statements from the data, so that no control statements appear in the data in the COPYJCL library.
Using multiple
%INCLUDE and %EXCLUDE statements
You can use multiple %INCLUDE and %EXCLUDE statements in the JCL for a job. When ESP submits the following job, it includes: STEP0010. STEP0020, if the scheduled date and actual date are equal. STEP0030, if the actual time of submission is greater than 07.59 a.m. STEP0040, from April 20,1998 up to, but not including, August 23,1998.
//MYJOB JOB CYB999,FRED,CLASS=A,MSGCLASS=S //STEP0010 EXEC PGM=IEFBR14 %INCLUDE IF(ESPSDATE=ESPADATE) //STEP0020 EXEC PGM=PGM1 %INCLUDE IF(ESPATIME GT 07.59.00) //STEP0030 EXEC PGM=PGM2 %INCLUDE FROM(APRIL 20,1998) TO(AUG 23,1998) //STEP0040 EXEC PGM=PGM3 %ENDINCL
Tailoring JCL
81
Modifying the Symbol Introducer

About modifying The symbol introducer is the character that identifies symbolic variables to the symbol ESP. Normally this character is the percentage sign (%). What if you want to introducer
include percentage signs in your JCL, without ESP interpreting the sign as a symbol introducer? There are three ways that you can control how ESP interprets the percentage sign (%) in JCL. Make a change to the ESP Initialization Parameter called SYMBOL to change the symbol introducer for your installation. Use a double percentage sign (%%) before the symbol. For example, if you want %DATE to appear in the JCL, specify %%DATE. When ESP submits the job, it removes the first percentage sign and leaves the second one. Change the symbol introducer for a single job. To make this change you will need to use a special control statement in the JCL, that is, the // *ESPSYMBOL statement.
Formatting the symbol introducer
The format for inserting the control statement in the JCL is shown below, where x represents the symbol introducer you choose:
//*ESPSYMBOL X
Place the character you want to use as the symbol introducer in column 14 of the card image, separated from //*ESPSYMBOL by a single blank. If the job belongs to an ESP Application, the change remains in effect for the rest of the job, or until ESP encounters another //*ESPSYMBOL statement; other jobs in the Application are not affected. If the job does not belong to an ESP Application, the change applies to all subsequent jobs submitted by the same Event, or until ESP encounters another //*ESPSYMBOL statement.
Example: Changing the symbol introducer
The following example shows how you can change the symbol introducer. To change the symbol introducer to a question mark (?) for a job, type the following statements in the jobs JCL:
//*ESPSYMBOL ? //ABC JOB . . . ?INCLUDE DAY(MONDAY) //STEP1 EXEC PGM=PGM1,PARM=DATE=?ESPSYY?ESPSDDD ... ?ENDINCL
82
Tailoring JCL
Assigning Security to a Symbol

About assigning security on a symbol
A secured symbol is one that contains sensitive data, such as a password, and consequently requires additional security. ESP exerts control over secured symbols based on how ESP processes the symbol. These are some of the controls that ESP exerts on secured symbols: ESP only produces the assigned values for JCL submitted to an internal reader. ESP does not produce the assigned values when writing JCL to a COPYJCL library (that is, symbols remain secured when copied to COPYJCL). END or VS commands do not produce the assigned values. You cannot assign a secured symbol to another symbol: a secured symbol cannot appear to the right of the equal sign (=) in an assignment statement.
Identifying a secured symbol
To identify a secured symbol to ESP, follow these steps: Define the symbol in a symbol library. For example, the statement below defines a symbol with the name PASSWORD.
PASSWORD=OPEN
Type the SECURE command directly after the statement defining the symbol. For instance, to secure a symbol with the name PASSWORD:
SECURE PASSWORD
In this example, ESP only resolves the symbolic %PASSWORD when it encounters the symbol in JCL it submits to the internal reader.
Tailoring JCL
83
Using an Exclusion Sign

About using an exclusion sign
ESP allows you to assign the exclusion sign () to the end of JCL card images to exclude specific lines of JCL from ESP submission. You can request that ESP checks the last non-blank character of every card image submitted to the internal reader. If the symbolic variable is set to a , the card image is deleted. If the symbol is set to blanks, null, or to any other string, the card image is not deleted. Note: Any data in columns 73 through 80 inclusive is ignored in the input data. A not sign () will be honored as the last character in columns 1 through 72 inclusive. This is an alternative to using %INCLUDE IF and %EXCLUDE IF.To activate this feature, enter the statement CHECKEXC anywhere in a symbolic library data set. Multiple exclusion symbols can be used. To turn the feature off, specify NOCHECKEXC. To use this feature, follow these steps. 1. Type the CHECKEXC command anywhere in a symbol library data set. 2. Define the symbol, either in a symbol library data set, or in an ESP Procedure. The value can be a blank character, null character or any other character string. 3. Use the symbol in your JCL wherever you want to exclude a JCL statement. 4. Reference the symbol library in your Event which submits the JCL.
84
Tailoring JCL
Using an Exclusion Sign, continued

Example 1: Using Assume a job consists of three steps. You want ESP to include all steps each an exclusion sign day, except on Mondays and Thursdays. On these days, you do not want ESP
to include STEP1 and STEP3 in the JCL it submits. X is the name of the symbol. In this example, the exclusion commands and definition of symbol X are both in the same symbol library data set as follows:
CHECKEXC X= %INCLUDE DAY(MON THU) X= %ENDINCL HERE IS AN EXAMPLE OF USING THE EXCLUSION SYMBOL IN JCL. //JOB1 JOB ACCOUNT //STEP1 EXEC PGM=MTEXC%X //STEP2 EXEC PGM=ANYDAY //STEP3 EXEC PGM=IEFBR14%X
When ESP submits the job, it includes: STEP2 each time. STEP1 and STEP3 only when the value of X is a blank character. STEP1 and STEP3 are not submitted to the internal reader if the value of X is the exclusion sign ().
Example 2: Exclude JCL by using an ESP Procedure
The next example shows how to exclude JCL by using an ESP Procedure to set the value of an exclusion symbol on the first workday of the month. On the first workday of the month, the symbol FW is set to and consequently STEP3 is not written to the internal reader or COPYJCL library, if specified. In a symbol library, type this command:
CHECKEXC
In an ESP Procedure, type,

IF TODAY(FIRST WORKDAY OF MONTH) THEN FW= ELSE FW=
Tailoring JCL
85
Using an Exclusion Sign, continued

Example 2: Exclude JCL by using an ESP Procedure, continued
In the JCL, type:

//MYJOB JOB ... //STEP1 EXEC PGM=LTOP5396 //STEP2 EXEC PGM=LTSS4330 //STEP3 EXEC PGM=SORT,%FW //PARM=(FIELD,A) %FW
Notice that STEP3 contains the symbol %FW. When the job is run on the first workday of a month, ESP will exclude STEP3 from the JCL it submits because the ESP Procedure defines the value as .
86
Tailoring JCL
Using Automatic Variables (AUTOVARS)

About AUTOVARS
ESP lets you define symbols representing lines of JCL, data, or comments that ESP automatically includes at the beginning or end of the jobs JCL. ESP can automatically add initial steps, trailer steps, and NET control statements to a specific job or to many jobs. These symbols are known as automatic variables or AUTOVARS. You can use AUTOVARS instead of embedded JCL statements for activities such as: Inserting JOBPARM cards. Handling condition codes. Using a restart manager or other product that requires the insertion of JCL to call the program. Processing ESP commands in batch. Defining DJC or JES3 net control statements in a symbolic variable library. ESP inserts automatic variables at submission time. If a COPYJCL library has been specified, this copy of the JCL only includes the automatic variables if the job is not part of an ESP Application. If the job belongs to an Application, ESP adds the automatic variables each time the job is submitted, or resubmitted, as part of the Application.
Defining AUTOVARS
You define an AUTOVAR in a symbol library data set or ESP Procedure similar to the way you define any other symbolic variable. However, you must include the following information when you are defining any AUTOVAR: Conditions for processing. Type of AUTOVAR. The number of the AUTOVAR. Unlike other symbolic variables which you refer to by variable name, ESP includes automatic variables if the correct conditions are met.
Tailoring JCL
87
Using Automatic Variables (AUTOVARS), continued

Processing conditions
ESP recognizes three different conditions for automatic variables. These conditions determine whether ESP includes the AUTOVARS for a job it is submitting. The three conditions are: Global Job Default. You can include all three conditions in a symbol library or ESP Procedure. ESP recognizes three types of automatic variables. The type tells ESP where to include the AUTOVAR in the JCL. The three types are: ISTEPnn NETCnn TSTEPnn initial step net control statement trailer step
Types of AUTOVARS
Order of processing
When ESP encounters more than one processing condition for a single job, it inserts the conditions in this order: Global, first Job-specific, second Default, last. You must give each AUTOVAR a number when you define it. Follow the rules below: Use numbers 1 to 99, without leading zeros. Insert the number directly after the type name, as in ISTEP1. Make sure that you number each AUTOVAR sequentially, as in ISTEP1, ISTEP2. The following example defines two ISTEP AUTOVARS with sequential numbering.
ULTTTR47_ISTEP1=//S1 EXEC PGM=MYTRACE ULTTTR47_ISTEP2=//TRADS DD DSN=PROD.MSTR.DATA
Numbering of AUTOVARS
88
Tailoring JCL

Numbering of AUTOVARS, continued
The following statement defines an AUTOVAR that is: Global An initial step The first AUTOVAR of this type (ISTEP).
GLOBAL_ISTEP1=/*JOBPARM SYSAFF=DALG
Using GLOBAL AUTOVARS
A global AUTOVAR applies to all jobs that an Event submits. The following example defines four global AUTOVARS. The first statement identifies an initial step; the next three statements identify trailer steps.
GLOBAL_ISTEP1=//S1 EXEC PGM=RSTRTPGM GLOBAL_TSTEP1=//LAST EXEC PGM=IEFBR14,COND=(16,GE) GLOBAL_TSTEP2=//*PUTS DUMMY LAST STEP IN EACH JOB GLOBAL_TSTEP3=//*FOR CONDITIONAL STEP EXECUTIONS
Using JOB AUTOVARS
A job AUTOVAR applies to a specific job. A job-specific AUTOVAR overrides any corresponding default AUTOVAR (if one has been specified). The following example defines three job-specific AUTOVARS. The first statement is an initial step for JOB24ABC, the second statement is a trailer step for JOB24ABC, the last statement is a NET control statement for job CYBER439.
JOB24ABC_ISTEP1=/*JOBPARM SYSAFF=*,LINES=20 JOB24ABC_TSTEP1=//LSTEP EXEC PGM=CN,COND=(4,EQ,STEP1) CYBER439_NETC1=//*NET TAPES=3
If you are using job-specific AUTOVARS for a qualified job as specified in an ESP Procedure, you must start with the job name followed by a double underscore (__) between the job name and qualifier and a single underscore (_) after the qualifier. The following example defines an initial step for the qualified job JTOP5196.RUN1.
JTOP5196_ _RUN1_ISTEP=//FSTEP EXEC PGM=LTOP5196
Tailoring JCL
89

Using DEFAULT A default AUTOVAR applies to any job that an Event or Procedure submits, AUTOVARS provided no job-specific AUTOVAR has been defined.
The following example defines two default AUTOVARS. The first AUTOVAR is an initial step, the second AUTOVAR is a trailer step.
DEFAULT_ISTEP1=/*JOBPARM SYSAFF=ANY,TIME=30,LINES=10 DEFAULT_TSTEP1=//LSTEP EXEC PGM=CNUP,PARM=ALL
The following example illustrates the order of processing each condition. Assume that ESP encounters the following AUTOVARS when it is submitting jobs.
GLOBAL_ISTEP=//*ESP GLOBAL STEP ABC_ISTEP1=//*ESP JOB SPECIFIC STEP FOR JOB ABC DEFAULT_ISTEP1=//*ESP DEFAULT STEP
ESP includes the first two AUTOVARS for job ABC. For the other jobs, ESP includes the first and third AUTOVARS.
Using initial steps Use ISTEPnn to insert an initial step before the first EXEC statement of a job. (ISTEPnn) The following example defines three ISTEP AUTOVARS for JOB1.
JOB1_ISTEP1=//S1 EXEC PGM=RSTRTPGM JOB1_ISTEP2=//STEPLIB DD DSN=PROD.ALT,DISP=SHR JOB1_ISTEP3=//SYSPRINT DD SYSOUT=*
Using NET control statements (NETCnn)
Use NETCnn for a DJC or JES3 net control statement. ESP inserts NETC variables before any ISTEP type of variable and before the first EXEC statement. The following example defines two NETC AUTOVARS for job JOB1 and one NETC AUTOVAR for job ESPNOSUB.
JOB1_NETC1=//*NET ID=DAILYAC,AB=F,RL=JOB2, JOB1_NETC2=//*TC=2 ESPNOSUB_NETC1=//*NET RS=IDMSDOWN
90
Tailoring JCL

Use TSTEPnn to insert a trailer step at end of file or before the next job card. Using trailer steps (TSTEPnn) The following example defines a TSTEP AUTOVAR for job CYBER407.
CYBER407_TSTEP1=//LSTEP EXEC PGM=RPTAUDIT,PARM=NO
Insert the following three statements, each containing an ISTEP type of Example 1: Defining the first AUTOVAR: step in a job
GLOBAL_ISTEP1=//*ALL OUTPUT TO BE ROUTED TO REMOTE3 ULTTTR47_ISTEP1=//S1 EXEC PGM=MYTRACE ULTTTR47_ISTEP2=//TRADS DD DSN=PROD.MSTR.DATA
Statement 1 defines the first step, which ESP adds globally to all jobs. Statements 2 and 3 define the first two steps of a specific job called ULTTTR47. Insert the following three statements, each containing a NETC type of Example 2: Defining a net AUTOVAR: control statement
ULTTTR47_NETC1=//*NET ID=NET27A,RELEASE=ULTTTR22, ULTTTR47_NETC2=//*OPHOLD=YES ULTTTR22_NETC1=//*NET ID=NET27A,HC=1
Statements 1 and 2 identify NET control statements for a job named ULTTTR47. Statement 3 identifies a net control statement for a job named ULTTTR22.
Example 3: Defining an endof-file step
Insert the following two statements, each containing a TSTEP type of AUTOVAR:
DEFAULT_TSTEP1=//LSTEP EXEC PGM=RPTAUDIT,PARM=YES CYBER407_TSTEP1=//LSTEP EXEC PGM=RPTAUDIT,PARM=NO
Statement 1 identifies a default trailer step added to all jobs except where a job specific AUTOVAR exists. Statement 2 identifies an end-of-file step for a specific job named CYBER407.
Tailoring JCL
91
Using Automatic variables (AUTOVARS), continued

Example 4: Adding a trailer step for automatic recovery
This example of an ESP Procedure: Submits a job called RECOVER if a monitored job ends with a U1492. Adds a series of trailer steps to invoke ESP in batch and complete a job called BADJOB in the PAY Application.
DEFAULT_TSTEP1=//LAST EXEC PGM=ESP,REGION=4M DEFAULT_TSTEP2=//SYSPRINT DD SYSOUT=* DEFAULT_TSTEP3=//SYSIN DD* DEFAULT_TSTEP4=APPLJOB BADJOB COMPLETE APPL(PAY.0) IF MNCMPC=U1492 THEN SUBMIT SYS1.JCL(RECOVER)
The JCL for the RECOVER job might look like this:
//RECOVER JOB . . . //S1 EXEC PGM=CLEANUP
When ESP adds the trailer steps, the JCL it submits looks like this:
//RECOVER JOB . . . //S1 EXEC PGM=CLEANUP //LAST EXEC PGM=ESP,REGION=4M //SYSPRINT DD SYSOUT=* //SYSIN DD * APPLJOB BADJOB COMPLETE APPL(PAY.0
The first example defines default trailer steps. If the highest job step return Example 5: Adding a trailer code is 0 or 4, the ESPCCFCK step executes and ESP considers the job step for handling successful. Otherwise, the ESPCCFCK step is bypassed and ESP considers the condition codes job as failed.
DEFAULT_TSTEP1=// IF RC=0 OR RC=4 THEN DEFAULT_TSTEP2=//ESPCCFCK EXEC PGM=IEFBR14 DEFAULT_TSTEP3=// ENDIF
The second example defines trailer steps for job ABC. If the highest job step return code is 0, 4, or between 12 and 24, the ESPCCFCK step executes and ESP considers the job successful. Otherwise, the ESPCCFCK step is bypassed and ESP considers the job as failed.
ABC_TSTEP1=// IF RC=0 OR RC=4 OR (RC>12 AND RC<24) THEN ABC_TSTEP2=//ESPCCFCK EXEC PGM=IEFBR14 ABC_TSTEP3=// ENDIF
92
Tailoring JCL
Simulating the JCL ESP Submits

About simulating You can use the PRINT option of the SIMULATE command to see the JCL the JCL ESP will which ESP will submit for a job on any date. ESP displays the JCL at your submit
terminal or writes it to a data set. You can also invoke a module to scan JCL during simulation. Use the SIMULATE command in Page mode, Line mode, or a batch job, or use option E.3 from the Main Selection Menu. The following examples request simulation of the PROD.PAYROLL Event: This command requests ESP simulate the next occurrence of the Event and display JCL for all jobs. Output is displayed at your terminal.
SIMULATE EVENT(PROD.PAYROLL) PRINT(*)
Using the SIMULATE command
This command requests ESP simulate the next occurrence of the Event and display JCL for MYJOB. Output is displayed at your terminal.
SIMULATE EVENT(PROD.PAYROLL) PRINT(*) ROOT(MYJOB)
This command requests ESP simulate the Event for the last day of the current month. Output is displayed at your terminal.
SIMULATE EVENT(PROD.PAYROLL) SCHED(LAST DAY OF MONTH) PRINT(*)
You can use the JCLSCAN option of the SIMULATE command to invoke a JCL scan exit module. The following command invokes a module called ABCSCAN to scan JCL during a simulation.
SIMULATE EVENT(PROD.PAYROLL) JCLSCAN(ABCSCAN)
Note: For more information on using the SIMULATE command, refer to the ESP Command Reference.
Tailoring JCL
93
Submitting Jobs Outside ESP

About submitting Once you have inserted ESP control statements in JCL, you must use ESP to outside ESP submit the job. If you submit the job using another method, such as TSO
SUBMIT, the ESP control statements will cause JCL errors. If ESP is unavailable for some reason, you can submit the job from outside ESP using the SCAN command in batch.
The SCAN command
The SCAN command allows you to: Search for ESP control statements within data sets and members of a partitioned data set Retrieve a working copy of a job that you want to submit Write the output from the working copies of the jobs to a data set. The following example demonstrates how you might enter a typical SCAN command. If ESP is down you must run the SCAN command in batch. If ESP is up you can use any mode. In this case, the output is a list of the JCL that ESP would submit on March 31, 1998 for MYJOB:
SCAN PROD.JCL.CNTL(MYJOB) EVENT(PROD.SUBMYJOB) SCHED(31ST MARCH 1998) SYMLIB(ESP.SYMBOLS(MYSYM))
Example: Using the SCAN command
PROD.JCL.CNTL(MYJOB) tells ESP where it can find the JCL for MYJOB. EVENT(PROD.SUBMYJOB) is the Event that submits the job. SCHED(31ST MARCH 1998) is the schedule criteria. SYMLIB (ESP.SYMBOLS(MYSYM)) contains symbol definitions for the job.
Note: For more information on using the SCAN command, refer to the ESP Command Reference.
94
Tailoring JCL
Job Monitoring and Alert Processing Overview

Introduction
ESP Workload Managers job monitoring is an extension of ESP job tracking. Through job monitoring, ESP triggers Events automatically when a job reaches a particular stage in processing, such as at the end of a step, at the end of a job, or when a job is purged. Alert processing is a similar mechanism you can use to instruct ESP to trigger Events automatically. You can use Alerts for the different stages of job processing in an ESP Application, such as at submission time, at the end of a job, or when a job is resubmitted. This chapter contains the following topics: Topic Comparing Job Monitoring and Alert Processing Functions of Job Monitoring and Alert Processing Planning for Job Monitoring and Alert Processing How Job Monitoring Works Setting Up Job Monitoring Using Alert Processing ESPS Built-in Monitor Variables See Page 96 98 100 101 102 112 124
In this chapter
95
Comparing Job Monitoring and Alert Processing

About job monitoring and alert processing
When deciding whether to use Job monitoring or Alert processing, keep the following in mind. You can only use Alert processing with jobs that are part of an Application. This restriction means that manually submitted jobs and STCs cannot take advantage of Alert processing. Alerts do not support step-level checking but monitor jobs at the following monitor points: Submit Job start Resubmit Overdue Abend Failure Job end. While job monitoring has no restrictions, you must create a specific monitor Event or generic tracking model to run it. Job monitoring checks at these monitor points: Job start Step end Job end Overdue Purge Post.
Using monitor variables
You can use a set of built-in variables called monitor variables to get the most flexibility from job monitoring and Alert processing. Monitor variables work much the same as other symbolic variables that ESP processes. However, unlike other symbolic variables, monitor variables are only available with job monitoring and Alert processing. For more information on symbolic variables, refer to Using Symbolic Variables on page 11. For a list of ESPs built-in monitor variables and their definitions refer to ESPS Built-in Monitor Variables on page 124. You can use them in monitor Events and in the ESP Procedures that monitor Events invoke.
96
Comparing Job Monitoring and Alert Processing, continued

How monitor variables work
You can place a monitor variable in any type of Event or ESP Procedure. However, the monitor variable can take on its assigned value only when you use it in a job monitor Event, an Event triggered by an Alert, or in an ESP Procedure invoked by a job monitor Event or Alert. ESP assigns values to the monitor variable in one of the following ways: A monitor Event contains a monitor variable. ESP triggers the Event at the monitor point and substitutes the value for the monitor variable. For example, an ESP Procedure might contain the monitor variable MNJOBNO with an assigned value of 1234. At the associated monitor point, ESP assigns the variable a value of 1234. If a non-monitor Event encounters a monitor variable, ESP sets the variable to null or zero. Assume that ESP invokes the monitor variable called MNJOBNO as part of a normal schedule (not at a monitor point). ESP then sets the value of the monitor variable to zero (0) for an integer or null for a character.
Using a symbolic As with other symbolic variables, use the symbol introducer character at the introducer beginning of a monitor variable. The symbol introducer tells ESP to interpret character (%)
the characters as a symbolic variable name and to retrieve the assigned value. The percentage sign (%) is the default introducer character for ESP. Check with your ESP system administrator to verify the symbol introducer at your ESP installation.
97
Functions of Job Monitoring and Alert Processing

About the functions
Some of the functions you can perform using a job monitor Event or an Alert Event are: Send a message to a user or console. Automatically start a sub-system. Restart a standard job by automatically re-submitting it. Automatically restart a started task following an ABEND. Activate or deactivate resources by issuing the appropriate commands. Hold or release jobs or Applications when a sub-system or started task starts or stops. As part of the job monitor or Alert Event, you must state what kind of activity the Event performs when the job reaches the monitor point. Job monitor and Alert Events can perform the same tasks as other Events, such as sending messages, issuing ESP commands, submitting JCL, and invoking an ESP Procedure. You can use an Event to invoke an ESP Procedure which processes conditional or complex actions. Using additional tools, you can add a wide variety of job conditions and values to ESP Procedures. These additional tools include: CLANG, which is a high-level programming language you can use to control the job monitors actions in an ESP Procedure. CLANG allows you to add logical conditions through the use of IF-THEN-ELSE statements. For more information on using CLANG, refer to the ESP Users Guide. REXX, which is an IBM high-level programming language. You can use REXX with ESP to extend its capabilities. For more information on using REXX, refer to Using REXX with ESP on page 271. Monitor variables, which are symbols passed from a job monitor Event. These symbols help you automate ESP processing as much as possible. For more information on using monitor variables, refer to How Job Monitoring Works on page 101.
Defining Event activities
Invoking ESP Procedures
98
Functions of Job Monitoring and Alert Processing, continued

Using other symbols with monitor Events
An ESP Procedure may contain both monitor and non-monitor variables. A monitor Event or any other kind of Event can invoke this Procedure. However, if a non-monitor Event or non-Alert Event invokes a Procedure containing monitor variables, ESP sets the variables to zero (numeric) or null (character). The only variables that apply to the job being monitored are the monitor variables (i.e. those with names beginning with the characters MN). All other symbolic variables relate to the monitor Event itself. Here is how ESP interprets symbolic variables (other than monitor variables) representing scheduled and actual times or dates: For scheduled time variables such as ESPSTIME and ESPSDATE, ESP substitutes the time at which it reaches the monitor point. For example, ESPSTIME can represent the time ESP reaches the step end monitor point. For actual time variables such as ESPATIME and ESPADATE, ESP substitutes the time at which the Event actually executes. For example, ESPATIME can represent the time when ESP actually processes the end of a step. The actual processing time might be earlier or later than expected.
Storing monitored information
ESP stores certain types of information at all the monitor points you request. ESP stores other types of information at specific monitor points only, depending on where you place the monitor point. For example, stepname and procstepname are available only for step-end monitoring.
99
Planning for Job Monitoring and Alert Processing

Overview
Plan your monitoring requirements in steps, based on jobs that ESP is currently tracking. 1. Analyze the jobs and decide which ones you want to monitor. 2. Decide if you will use a job monitor Event or an Alert Event. 3. Identify the significant processing steps in the jobs. Relate these steps to the available monitor points. 4. Analyze the information you expect to receive at each step and then determine the action you want ESP to take. 5. Define Events to trigger the action. The Events can invoke ESP Procedures if conditional or complex groups of actions are necessary. Note: Many jobs and monitor points require the same or similar actions, so you can use common ESP Procedures to perform the actions for a wide variety of jobs.
Steps for planning
100
How Job Monitoring Works

About the ESP job monitoring feature
The ESP job monitoring feature works in the following way: 1. When the job is submitted, ESP detects that a specific monitor Event or a monitor group exists for the job. A monitor group acts as a high level index to point ESP to high level Event prefixes. 2. ESP uses the monitor group specified in an ESP Procedure, tracking model, or job documentation. ESP then searches for an Event. 3. ESP locates the monitor Event. The identifier of the monitor Event must match the appropriate job and group combination. A monitor Event states the monitoring requirements, including monitor point and ESP action. 4. ESP executes the monitor Event (and ESP Procedure, if applicable). 5. The monitor Event (or ESP Procedure, if Applicable) triggers ESP actions when the job reaches the specified monitor point during processing. Monitor points are the detailed job steps that ESP gathers information about.
Summary of monitoring points
The following table summarizes all the monitor points: Monitor Point JOBSTRT STEPEND JOBEND OVERDUE Activation Point Start of the job. At the end of each step in the job. This includes steps which are bypassed. End of the job. When the job becomes overdue from any processing stage, including user-defined P-Nodes. In order for this to activate for a job, the job must have been submitted. Job purge, unless NOTRACK_PURGE has been selected as a tracking option. When the job is posted from a processing stage, including user-defined P-Nodes.
PURGE POST
101
Setting Up Job Monitoring

About setting up job monitoring
There are different methods for setting up job monitoring. Each of these is described below. The method you choose may depend on the number of jobs you need to monitor, the monitor points for each job, whether ESP submits the job, your access to job tracking models, and your access to the Job Tracking Definition Table.
Using this method, you use a tracking model to identify the name of an Event Method 1: Generic tracking that you want ESP to trigger when a job reaches a particular step in processing. model You can use this method to monitor job starts, job ends, and step ends. The DEFTM command defines a tracking model. A tracking model supports each of the job monitor points and you can define more than one monitor point for each tracking model. Use any of the following keywords on the DEFTM command to trigger an Event at the indicated stage in processing: JOBABENDEVENT JOBENDEVENT JOBFAILEVENT JOBSTARTEVENT STEPABENDEVENT STEPENDEVENT STEPFAILEVENT Job ABEND. End of job. This includes both normal and abnormal completions. Job failure including ABENDs and condition code failures. Job start. Step ABEND. End of step. Step failure including ABENDS and condition code failures.
The following example defines a tracking model called BADEND. ESP triggers the Event PROD.ABENDED_JOBS each time a job associated with this model ABENDs.
DEFTM BADEND JOBABENDEVENT(PROD.ABENDED_JOBS)
102
Setting Up Job Monitoring, continued

Method 1: Generic tracking model, continued
Jobs are associated with a tracking model using a Job Tracking Definition Table. For more information on tracking models and Job Tracking Definition Tables refer to the ESP Administrators Guide. To set up job monitoring using generic tracking, complete these steps: 1. Check the model your job uses. The LTJ command displays this information. 2. Alter this tracking model (using DEFTM command with REPLACE option) to identify the monitor point and the name of your monitor Event. 3. Define your job monitor Event. Alternatively you can define a new tracking model and update the Job Tracking Definition Table to associate your job with this new model.
Method 2: Identify a monitor group in an ESP procedure
Using this method, you identify the prefix of your job monitor Event when you define your job in an ESP Procedure. This prefix must be your user ID or a group to which you have access. The job monitor Event must use a specific naming convention. Note: This method requires that you use an ESP Procedure to submit the job. Refer to Step 3: Defining and naming a monitor Event on page 106.
Using this method, you identify the prefix of your monitor Event in a job Method 3: Identify a tracking model. This prefix must be your user ID or a group to which you have monitor group in a tracking model access. The job monitor Event must use a specific naming convention. Refer to Step 3: Defining and naming a monitor Event on page 106. To set up job monitoring using Methods 2 and 3, complete these steps: 1. Select or set up a monitor group. 2. Specify the group in the job. 3. Define a monitor Event, including the monitor points. The following topics discuss each of the above steps in greater detail.
103

Method 3: Identify a monitor group in a tracking model, continued Step 1: Select a monitor group
You can select either of the following types of groups: A special group that you set up for defining monitor Events only. Any ESP group to which you have access. Note: Setting up a special group is an administration function. You can set one up through the DEFGROUP command, through option M on the Main Selection Menu, or through your security system if you are using SAF.
Step 2: Name the To tell ESP to monitor a job, you must specify a monitor group name in every monitor group in job or group of jobs to be monitored. the job
You can insert the monitor group name in any of the following: Tracking models ESP Procedures Job documentation The method and format of inserting the monitor group name differ according to where you insert the name.
Tracking model method
You can use the DEFTM command to define a tracking model for an individual job or group of jobs. Include the monitor group name in the tracking model. The format for defining the tracking model looks like this:
DEFTM modelname MONITOR(groupname)
104

For this example, the name of the tracking model is JOBMON and the Example: Defining a monitor group name is PROD. Type the following command to define the monitor group in a tracking model tracking model:
DEFTM JOBMON MONITOR(PROD)
For more information about the DEFTM command, refer the ESP Command Reference.
ESP procedure method
You can insert a monitor group name in a job statement within an ESP Procedure or job documentation member. This method cannot be used for jobs identified as External or Manual. For External jobs, you can identify the monitor group name in the home Application (i.e. the Application that submits the job) or use the tracking model method; for Manual jobs you must use the tracking model method to identify a monitor group name. The format for specifying the monitor group looks like this:
MONITOR groupname
For example, you have a job called PAYJOB1 and a monitor group called Example: Defining a PROD. The statements for the ESP Procedure are: monitor group in an ESP JOB PAYJOB1 Procedure
MONITOR PROD
Note: When you specify a monitor group in an ESP Procedure it can apply to a group of jobs. In the example below ESP will look for monitor Events for jobs A and B.
MONITOR PROD JOB A RUN DAILY RELEASE B JOB B RUN DAILY ENDJOB
105

Step 3: Defining and naming a monitor Event
When you use generic job monitoring, you can use any name for your monitor Event. When you are not using generic monitoring, name your monitor Events according to the following format:
prefix.jobname_monitorpoint
An explanation of the above syntax follows: prefix The prefix must be the same as the monitor group name specified in the tracking model, job documentation or ESP Procedure. Make sure you check that the prefix and monitor group name correspond. Insert the complete jobname, for example PAYROLL1. Use an underscore as a separator between the jobname and the monitor point (you cannot insert blank spaces). Insert the name of the specific monitor point you want ESP to detect. The monitor point tells ESP precisely when to execute the monitor Event. You can include multiple monitor points for a job if necessary, but additional monitor points require separate Events.
jobname _(underscore) monitor point
Example: A monitor Event
Assume that the monitor group name is PROD, the jobname is PAYJOB1, and the monitor point is JOBEND. The monitor Event name looks like this:
PROD.PAYJOB1_JOBEND
106

Example: Monitoring step end, sending message
In this example, a job monitor Event executes when a particular step of a job PAYJOB1 completes. The Event then sends a series of messages to the defining user. This example defines the prefix of the job monitor Event in an ESP Procedure because ESP submits the job as part of a Procedure. Set up job monitoring in the following way: 1. Specify the prefix of your job monitor Event in the ESP Procedure that submits the job, like this:
JOB PAYJOB1 MONITOR ESPMON
2. Define a monitor Event using these criteria: The name of the Event is ESPMON.PAYJOB1_STEPEND. The monitor Event must have a prefix of ESPMON because ESPMON is the monitor group name specified in the jobs definition in the Application. The monitor point is STEPEND. The SEND command informs the defining user of the jobname, step name, the actual time the step ends, step return codes and step completion codes. Note that a period after %MNJOB indicates the end of the symbol name. Otherwise, ESP would treat %MNJOB(%MNSTEP) as a substring specification. The Event is to execute on system SYSA, regardless of the system on which the job executes (unless SYSA is inactive).
The Event definition statements look like this:

EVENT ID(ESPMON.PAYJOB1_STEPEND) SYSTEM(SYSA) SEND %MNJOB.(%MNSTEP) HAS ENDED AT %ESPATIME USER(*) SEND RC=%MNRC CMPC=%MNCMPC USER(*)
107

Example: Monitoring step end, sending message, continued
When PAYJOB1 is submitted, the jobs tracking model informs ESP to look for Events with these attributes: the prefix ESPMON the jobname PAYJOB1 an underscore (_) a monitor point. In this example, assume ESP finds ESPMON.PAYJOB1_STEPEND. ESP then executes this Event each time PAYJOB1 completes a step.
JOB PAYJOB1 MONITOR ESPMON
EVENT ID(ESPMON.ABC_JOBEND) EVENT ID(ESPMON.DOCJOB_JOBEND) EVENT ID(ESPMON.PAYJOB1_STEPEND)
Example: Monitoring for an ABEND
In this example, ESP restarts a CICS started task called CICSDEMO. The task is restarted when CICSDEMO ABENDs on completion code U0601 prior to its normal shutdown time of 10 p.m. Job monitoring invokes an ESP Procedure to check the time and completion code. This example defines the prefix of the job monitor Event in a tracking model because CICSDEMO is not a job submitted by an ESP Procedure. Set up job monitoring in the following way: 1. Set up or use an existing monitor group with the name PROD in a tracking model definition statement as follows:
DEFTM MONSTC MONITOR(PROD)
108

Example: Monitoring for an ABEND, continued
2. Define an ESP Procedure using the following criteria: If the actual time of the ESP Procedure is before 10 p.m. and the completion code for the monitored job is U0601, use an operator command. The operator command restarts the monitored job and sends a message to console 01. If either of the above conditions (time or completion code) are not met, the ESP Procedure sends a message to console 01 indicating the name of the job and the completion code. The ESP Procedure is in CYBER.ESP.MON(CICS0601). The ESP Procedure looks like this:
CICS0601:ESPPROC /* CHECK IF BEFORE 10PM AND COMPLETION CODE IS U0601*/ IF ESPAHH<22 AND MNCMPC=U0601 THEN DO VS S %MNJOB SEND RESTARTING %MNJOB AFTER %MNCMPC CN(01) ENDDO ELSE SEND %MNJOB HAS FAILED WITH CMPC=%MNCMPC CN(01)
3. Define the monitor Event as follows:

EVENT ID(PROD.CICSDEMO_JOBEND) SYSTEM(CPU0) INVOKE CYBER.ESP.MON(CICS0601) ENDDEF
109

Example: Monitoring online system completion
In this example, ESP submits a job after a started task TSOVTAM has ended successfully. Job monitoring invokes an ESP Procedure to check the return code. The example assumes that ESP is tracking the started task. Set up job monitoring in the following way: 1. Specify a monitor group with the name CYBER in the started tasks tracking model definition statement. In this example, the tracking model is called MONITOR1.
DEFTM MONITOR1 MONITOR(CYBER)
2. Define the ESP Procedure to handle the requirements. The ESP Procedure looks like this:
/* CHECK RETURN CODE*/ IF MNRC=0 THEN DO SEND %MNJOB HAS ENDED SUCCESSFULLY CN(01) SEND BACKUP JOB BEING SUBMITTED CN(01) SUBMIT PROD.JCL.CNTL(TSOBACK) ENDDO ELSE SEND %MNJOB HAS FAILED; CMPC=%CMPC CN(01) NONDEL

EVENT ID(CYBER.TSOVTAM_JOBEND) SYSTEM(CPU1) INVOKE CYBER.ESPPROC.MON(TSOEND) ENDDEF
Example 4: Setting a resource based on online start
In this example, ESP sets a resource when a started task called CICS starts. Job monitoring invokes an ESP Procedure to set a resource called CICSUP. The example assumes that ESP is tracking the started task. Set up job monitoring in the following way: 1. Specify a JOBSTARTEVENT in the started tasks tracking model definition statement. In this example, the tracking model is called MONCICS.
DEFTM MONCICS JOBSTARTEVENT(PROD.SET_STC_ON)
110

Example: Setting a resource based on online start
2. Define the ESP Procedure to set the resource. Since you may want to use the same Procedure for different started tasks, you can use the MNJOB symbolic variable to check the name of the monitored job. The following Procedure checks the name of the job. If the jobname is CICS, ESP sets the available count of the CICSUP resource to 1:
IF MNJOB=CICS THEN ESP RESDEF CICSUP SET AVAIL(1)

EVENT ID(PROD.SET_STC_ON) SYSTEM(ESPM) INVOKE CYBER.ESPPROC.MON(STCS) ENDDEF
111
Using Alert Processing

About using alert The Alert feature enables ESP to trigger an Event for all jobs, or only specific processing jobs, in an ESP Application. You can trigger the Event at any monitor point,
such as time of job submission, job start time, or when a job becomes overdue at any processing stage.
Three steps to use Alerts
To use the Alert feature, you need to take these three steps: 1. Use the NOTIFY statement in an ESP Application to identify when to trigger the Alert. 2. Define the Alert with the ALERTDEF command. 3. Define the Event triggered by the Alert. The definitions relate to each other in the following way:
NOTIFY processing_point ALERT(alert_id)
ALERTDEF ADD ID(alert_id) EVENT(event_name)
EVENT ID(event_name)
Following is a detailed discussion of these steps: Note: The steps do not need to be defined in any particular order.
Step 1: Using the To set up an Alert process in an Application, use the NOTIFY statement with NOTIFY the ALERT keyword. The NOTIFY statement can refer to all jobs in an statement
Application or it can be job specific within the scope of a JOB statement. The format for the NOTIFY statement to use the Alert feature looks like this:
NOTIFY condition ALERT(identifier)
112
Using Alert Processing, continued

Step 1: Using the NOTIFY statement, continued
NOTIFY
Triggers an Event at a specific stage in a job (when the ALERT keyword is part of the statement). The NOTIFY command can also notify users or consoles. Condition that triggers the Alert. This can be one or more of the following: SUBMIT, JOBSTART, RESUB, OVERDUE, ABEND, FAILURE, JOBEND. Triggers an Event. Specifies either an asterisk (*) or a logical identifier to a maximum of four characters as follows: If the identifier is an asterisk, ESP re-triggers the same Event. If the identifier is a logical identifier, then ESP makes the association with an Event through an ALERTDEF command.
condition
ALERT identifier
Note: The only condition you can use with external jobs, manual jobs, links, and tasks is OVERDUE. This example processes an Alert identified FAIL when a job ABENDS.
NOTIFY ABEND ALERT(FAIL)
Step 2: Defining Alerts
When you use a 4-character identifier with the NOTIFY statement, you must define an Alert and specify the name of the Event to be triggered. Use the ALERTDEF command to add an Alert definition.
ALERTDEF ADD ID(FAIL) EVENT(PROD.FAILPROC)
An Alert definition points to an Event which is triggered when the Alert is processed as part of the NOTIFY statement.
113

Step 3: Defining Alert Events
Define the Event specified as part of the Alert definition. If the Event invokes an ESP Procedure, you will need to define this as well.
EVENT ID(PROD.FAILPROC) INVOKE PROD.ESP(FAILPROC)
Displaying Alerts The ALERTDEF command displays Alert definitions. It displays each Alert
identifier and the corresponding Events. Sample output from the command is shown below.
oper alertdef ALERT ID EVENT NAME FAIL CYBBP01.INFOSYS PROB CYBBP01.RECOVER WHCK PROD.J1_CHECKEND
Your ESP installation may already have Alert definitions in the initialization parameters. To view existing definitions and their corresponding Events, type the ALERTDEF command. In certain cases such as job end monitoring, you can use job monitor variables Using symbolic variables in Alert in the Procedure for an Alert. For more information on job monitor variables, processing refer to How Job Monitoring Works on page 101. In addition to monitor variables, you can also use other symbolic variables such as ESPATIME and ESPADATE. However, these non-monitor symbolic variables apply only to the Alert Event itself - not to the job that triggered the Alert.
114

Example 1: Job monitor variables send message to console
This example sends a message to a user when a job in an Application fails. Setting this up requires a three-step procedure that: Defines the ALERT. Adds the ALERT keyword to an ESP Procedure. Incorporates job monitor variables in the Event.
Step 1 - Use NOTIFY Statement Insert the ALERT keyword in an ESP Procedure as follows:
JOB JOBX NOTIFY ABEND ALERT(ABX) RUN DAILY ENDJOB
When JOBX ABENDs, ESP processes the NOTIFY statement and ALERT keyword in the above ESP Procedure. This triggers the Event called USER1.CHECK_X Step 2 - Define Alert Include the following definition of ALERT in the initialization statements:
ALERTDEF ADD ID(ABX) EVENT(USER1.CHECK_X)
The above definition associates the Event called USER1.CHECK_X with the identifier ABX.
115

Example 1: Job monitor variables send message to console, continued
Step 3 - Define Event Insert job monitor variables in the Event called USER1.CHECK_X as follows:
EVENT ID(USER1.CHECK_X) SE %MNJOB HAS ABENDED WITH CMPC=%MNCMPC USER(USER1) ENDDEF
The above Event uses job monitor variables to send a message to the user ID USER1.
Example 2: Alert This example uses the format ALERT(id). When ESP processes a NOTIFY processing command with ALERT (ID), it must first locate a corresponding definition for triggers specific ALERT and then trigger the appropriate Event. Event
In this example, assume ESP triggers an Event whenever a job in the ESP Application ABENDs. This involves a three-step process. Step 1 - Use NOTIFY Statement Use the ALERT keyword with the NOTIFY command in the following ESP Procedure:
APPL ABC JCLLIB NOTIFY ABEND ALERT(INFO) JOB A POSTREQ B JOB B POSTREQ C ENDJOB SELECT A
116

Example 2: Alert processing triggers specific Event, continued
Step 2 - Define Alert Enter the following ALERTDEF command in the initialization statements to trigger the Event called PROD.CREATE_RECORD:
ALERTDEF ADD ID(INFO) EVENT(PROD.CREATE_RECORD)
Step 3 - Define Event Define the PROD.CREATE_RECORD Event. The Event may look like this:
EVENT ID(PROD.CREATE_RECORD) INVOKE PROD.ESPPROC(INFOSYS) ENDDEF
ESP then triggers the Event called PROD.CREATE_RECORD each time a job in the above ESP Application ABENDs. Visually, this is how the definitions relate to each other:
NOTIFY ABEND ALERT(INFO)
ALERTDEF ADD ID(INFO) EVENT(PROD.CREATE_RECORD)
EVENT ID(PROD.CREATE_RECORD)
117

Example 3: Resubmitting a job once following a failure
In this example, assume ESP triggers an Event whenever job A in an Application fails. If the job is resubmitted and fails again, ESP considers the job complete. Follow the steps below . Step 1 - Use NOTIFY Statement Set up an ESP Application that looks like this. When job A fails, ESP triggers an Alert called BADA.
APPL BACKUPS JCLLIB CYB.JOBS.CNTL JOB A RUN DAILY RELEASE B NOTIFY FAIL ALERT(BADA) ENDJOB
Step 2 - Define Alert Add the Alert definition like this:

OPER ALERTDEF ID(BADA) EVENT(CYB.AFAIL)
In this example, Alert ID(BADA) points to the Event CYB.AFAIL. This Event is triggered when job A fails.
Step 3 - Set Up ESP Procedure
Define an ESP Procedure to take action if the job has been resubmitted. The Procedure tests the value of the MNRRJOB variable. If MNRRJOB is not null, the job is a rerun. ESP issues an AJ command to complete the job. Your ESP Procedure may look like this:
IF MNRRJOB NE THEN ESP AJ A COMPLETE APPL(%MNAPPL..%MNAPPLGEN)
118

Example 3: Resubmitting a job once following a failure, continued
Note: You could not use the %ESPAPSUB# variable here to check for the submission number as it does not get passed as a monitor variable. This variable applies to the monitor Event and not to the job being monitored, and in this example, always resolves to zero. The only symbolic variables that apply to a job being monitored are the monitor variables. Step 4 - Define Event Define the Event like this:
EVENT ID(CYB.AFAIL) INVOKE CYB.ESP(AFAIL)
119

Example 4: Alert This example uses the format ALERT(*) to re-trigger the same Event and ESP processing reProcedure. The criteria for this example is that the Application should be triggers same marked complete if a task called WAIT4.TAPE has not been marked complete Event
by 7 p.m.
The ESP Procedure containing the ALERT keyword looks like this:
/* /*Check to see if this ESP Procedure is being invoked /*due to an ALERT statement by testing MNJOB variable /* IF MNJOB = THEN DO /* If so, perform monitor processing and exit IF MNPOINT=OVERDUE AND MNJOB=WAIT4 AND MNQUAL=TAPE THEN + ESP AJ ALL COMPLETE APPL(%MNAPPL..%MNAPPLGEN) EXIT ENDDO /* /* Otherwise, perform regular processing /* APPL TAPEJOBS... JCLLIB CYB.ESP.JCL NOTIFY OVERDUE ALERT(*) JOB WAIT4.TAPE TASK DUEOUT EXEC 7PM RUN DAILY RELEASE NEXTJOB ENDJOB JOB NEXTJOB RUN DAILY ENDJOB
120

Example 4: Alert processing re-triggers same Event
The ESP Procedure tests the MNJOB (monitor jobname) variable to see if ESP is invoking the Procedure due to the triggering of an Event or due to the ALERT keyword. If MNJOB is not a null string, the ESP Procedure is being invoked by the Alert. ESP verifies the monitor point and the name of the overdue job, and completes the Application. Otherwise, ESP generates the Application.
Example 5: Taking different paths in an Application
This example shows you how ESP can take different paths in an Application based on a jobs return code. The Application is set up so that: If J1 ends with a return code of 50, ESP bypasses subApplication PATH2. If J1 ends with a return code of 0, ESP bypasses subApplication PATH1. If J1 ends with a return code other than 0 or 50, ESP sends a message.
Visually, the Application and subApplications look like this:

J1
J1.RCCHECK
=50 =0 Other
J2A
J2Z
send message
J3A
J3Z
121

Example 5: Taking different paths in an Application, continued
Step 1 - Use Notify Statement Set up and ESP Application that looks like this:
JCLLIB SYS1.JCL APPL WH JOB J1 NOTIFY JOBEND ALERT(WHCK) RUN DAILY RELEASE J1.RCCHECK ENDJOB JOB J1.RCCHECK TASK RUN DAILY RELEASE (J2A,J2Z) ENDJOB SUBAPPL PATH1 JOB J2A RUN DAILY RELEASE J3A JOB J3A RUN DAILY ENDJOB SUBAPPL PATH2 JOB J2Z RUN DAILY RELEASE J3Z JOB J3Z RUN DAILY ENDJOB
Step 2 - Define Alert Add the Alert definition like this:

ALERTDEF ADD ID(WHCK) EVENT(PROD.J1_CHECKEND)
In this example, Alert ID(WHCK) points to the Event PROD.J1_CHECKEND. This Event is triggered when job J1 ends.
122

Example 5: Taking different paths in an Application, continued
Step 3 - Define Event Define the Event like this:

EVENT ID(PROD.J1_CHECKEND) INVOKE CYB.ESP(CHECKEND)
Step 4 - Set Up ESP Procedure Define an ESP Procedure to take different actions based on return codes. If return code is 0: bypass PATH1 and complete the J1.CHECK task. If return code is 50: bypass PATH2 and complete the J1.RCCHECK task. Otherwise, send a message to indicate how J1 ended.
Your ESP Procedure may look like this:

IF MNRC=0 THEN DO ESP AJ PATH1 BYPASS APPL(WH.0) ESP AJ J1.RCCHECK COMPLETE APPL(WH.0) EXIT ENDDO IF MNRC=50 THEN DO ESP AJ PATH2 BYPASS APPL(WH.0) ESP AJ J1.RCCHECK COMPLETE APPL(WH.0) EXIT ENDDO SEND J1 HAS ENDED RC = %MNRC U(*)
123
ESPS Built-in Monitor Variables
MNACCT1 MNACCT2 MNACCT3 MNAPPL MNAPPLGEN MNAUTHS
MNCMPC
Up to eight characters of the first account number field. Up to eight characters of the second account number field. Up to eight characters of the third account number field. Application name. This variable is null if the job is not part of an Application. Generation number of an Application. This variable is null if the job is not part of an Application. Authorization string. This is either the user ID for the job or one of the first three account numbers. The string depends on the definition at the time of installation. Character representation of completion code. ESP produces one of the following completion codes: For a non-ABEND step termination, the code is a numeric code without leading zeros. Example: 8. If you are comparing MNCMPC with a number, enclose the number in quotes. Example 8. For a system ABEND, the code is S, followed by a three character system ABEND code. Example: SB37. For a user ABEND, the code is U, followed by a four digit user ABEND code. Example: U1012. For a non-executed step, the code is NOTEXEC. For a system crash, the code is SYSERROR.
124
ESPS Built-in Monitor Variables, continued
MNHICMPC
MNHIRC
MNJOB MNJOBTYPE
MNJOBNO
MNJSTART MNMXCMPC
In abnormal user or system ABEND situations, it may be impossible to invoke a step end monitor point. If this happens, ESP invokes the job end monitor point instead. Completion codes are as follows: If the system crashes, the result is SYSERROR. If a job fails because of an error in the JCL, the result is JCLERROR. If a job fails because of a completion code error, the result is CCFAIL. Character representation of the highest completion code from the execution of a step. This is not affected by ESP generated status codes such as JCLERROR and CCFAIL. Highest return code from the execution of a step. This is not affected by ESP generated status codes such as JCLERROR and CCFAIL. Jobname. Type of job. The result can be any of the following: A job. Started task (STC). TSO user (TSU). JES job number, expressed as an integer variable. MNJOBNO has a value of 0 for a job that has not been submitted. Job start time in the format yyyymmdd, for example, 19931222. Highest completion code, expressed as an alphanumeric variable. These are the same as the completion codes for MNCMPC (above).
125
MNMXRC
MNNETID MNNXN
Highest return code, expressed as an integer variable. The integer can be within the following ranges: Non-ABEND codes are from 0 to 4095. System ABEND codes are from 10,000 to 14,095. A user ABEND code is from 20,000 to 24,095. The decimal value for a system ABEND is actually added to 10,000. So the system ABEND SB37 (2871 when converted from hex to decimal) would give a return code of 12,871. Similarly, the decimal value for a user ABEND is added to 20,000. DJC network identifier (used only if an ESP Procedure defines a DJC network) or JES3 jobnet. Name of the remote execution node (i.e. ESP nodename) for a job whose tracking data was transmitted from another node. This is set to a null string if the job runs within the same JES node. Name of a P-Node in which the job is currently executing. The result can be any of the following: If the job is either starting or ending, the result is EXEC. If the job is at a step end, the result is EXEC. (You can distinguish step end from start or end of a job by using the MNPOINT variable). If the job or step is overdue, the result is the P-Node for the overdue job or step. If the monitor point is POST, the result can be INPUT, EXEC, OUTPUT, or any manual PNode. If ESP has purged the job and the job has no manual P-Nodes, the result is null.
MNPNODE
126
MNPOINT
MNPOSTBY
MNPSTEP MNPROG MNQUAL MNRC
Name of the monitor point, for example, STEPEND. For Alert processing: the name of the monitor point for a job which is late starting is OVERDUES; the name of the monitor point for a job which is late ending is OVERDUE. Manual or automatic entry of the POST command, indicating a job has completed a processing stage. The result can be any of the following: SYSTEM for all automatic stages up to and including PURGE User ID for monitor points where a user manually posts a job from a P-Node SYSCONnn for monitor points where a system console operator performed a POST (nn is the console number) SYSTEM for an automatic POST following a system crash. JCL procedure step name (used for a step end monitor point only). Program name (used for a step end monitor point only). Job qualifier. If the job does not have a qualifier, this is set to null. Return code, expressed as an integer variable. The integer can be within the following ranges: Non-ABEND codes are from 0 to 4095 System ABEND codes are from 10,000 to 14,095 A user ABEND code is from 20,000 to 24,095. The decimal value for a system ABEND is actually added to 10,000. So the system ABEND SB37 (2871 when converted from hex to decimal) would give a return code of 12,871. Similarly, the decimal value for a user ABEND is added to 20,000. The return code for a non-executed step is -1.
127
ESPs Built-In Monitor Variables, continued
MNRDRON MNRDRX MNRRJOB MNRRJOBNO MNSTEP MNSTEPNO
Time that JES reads the job into the system, in the format hh,mm. Time stamp for reader-on date and time. Jobname of a job ESP is re-running. It has a value of null of the job is not a rerun. Job number of a job ESP is rerunning (expressed as an integer variable). Step name (used for a step end monitor point only). integer step number for a job. The meaning of the number varies as follows: For a step end monitor point, the integer is the actual step number. For a job end monitor point, the integer is the number of steps in the job.
MNSYS
ID of the system where the monitor point occurred. The result depends on the type of monitor point as follows: For JOBSTRT, STEPEND or JOBEND monitor points, the result is the ID of the system where ESP is executing the job. For a POST monitor point, the result is the system where posting occurs. ESP may execute the monitor Event on a system other than the one where the monitor point occurred.
128
Advanced Use of ESP Procedures Overview

Introduction
The ESP Users Guide discusses the basic functions of ESP Procedures. This chapter shows you how to use less common features and combine multiple ESP features. This chapter contains the following topics: Topic Handling Schedule Criteria Working with Special Periods Testing Invocation of an ESP Procedure Combining CLANG Elements Using Recursive Procedures Overriding Inherited Relationships Resolving External Dependencies Defining the Scope of External Dependencies See Page 130 136 140 142 147 148 154 156
In this chapter
129
Handling Schedule Criteria

About handling schedule criteria
When you define the schedule criteria for a job, you may have complex criteria that cannot be described with RUN/NORUN or SELECT/DESELECT statements. This topic shows examples of handling different schedule criteria.
Example: Run a The ESP Procedure in this example tests whether the day of the month is job based on even even and then selects MYJOB on even days only. ESP selects the job on the days
2nd, 4th, 6th, etc. days of the month.
INTEGER DAY DAY=%ESPSDD IF DAY//2*2=DAY THEN SELECT MYJOB
For example, if today is the 14th day of a month, ESP takes the following steps: 1. Assigns the value of 14 to the integer variable DAY. 2. Evaluates the expression 14//2*2 = 14 as true, and selects MYJOB. If however, today is the 15th day of a month, ESP takes the following steps: 1. Assigns the value of 15 to the integer variable DAY. 2. Evaluates the expression 15//2*2 = 15 as false (15//2*2 becomes 7*2 which is 14). ESP does not select MYJOB.
Example: Run a job every two weeks
The following ESP Procedure selects a job called BIWEEK every second Monday except on holidays. ESP selects the job on July 11,1998, July 25,1998, and so on. The Procedure determines whether the number of days since July 11,1998 is a multiple of 14 and selects the job accordingly.
JOB BIWEEK INTEGER NUMBER NUMBER=DAYS_FROM(JULY 11,1998) IF NUMBER//14*14=NUMBER THEN DO RUN TODAY NORUN HOLIDAY ENDDO ENDJOB
130
Handling Schedule Criteria, continued

Example: Run job every two weeks, continued
For example, if today is August 8, 1998, ESP takes the following steps: 1. Assigns the value of 28 to the integer variable NUMBER. 2. Evaluates the expression 28//14*14 = 28 as true, and selects BIWEEK (unless it is a holiday). If however, today is August 9, 1998, ESP takes the following steps: 1. Assigns the value of 29 to the integer variable NUMBER. 2. Evaluates the expression 29//14*14 = 29 as false (29//14*14 becomes 2*14 which is 28). ESP does not select BIWEEK.
Example: Run a job on certain weeks of the month
This example runs a job according to the following criteria: Monday through Saturday during the 3rd and 4th week of October.
IF ESPSMM=10 THEN DO RUN ANYDAY OF 3RD 4TH WEEK OF MONTH NORUN SUNDAY ENDDO
Example: Run a job according to day of week
This example runs a job according to the following criteria: The job runs on the 15th day of the month, if it is not a Tuesday The job runs on the 16th day of the month, if the 15th day of the month is on a Tuesday. The statements look like this:
IF TODAY(15TH DAY OF MONTH) AND TODAY(NOT TUESDAY) THEN RUN TODAY IF TODAY(16TH DAY OF MONTH) AND TODAY(WEDNESDAY) THEN RUN TODAY
131

Example1: Run a This example uses the GENTIME command in an ESP Procedure to handle a job according to complex schedule. The criteria to run the job are: workday
The 10th day of the month is a Saturday or a Sunday, then run the job on the 2nd workday after the 10th day of the month Otherwise, run the job on the first workday of the month after the 10th day of the month. This solution uses the GENTIME command to generate date and time variables for the 10th day of the month. Based on the day of the week this falls on, the job runs accordingly. The statements look like this:
GENTIME TEN 10TH DAY OF MONTH STARTING TODAY IF TENDAY=SATURDAY OR TENDAY=SUNDAY THEN RUN %TENDATE PLUS 2 WORKDAYS ELSE RUN %TENDATE PLUS 1 WORKDAY
Example 2: Run a job according to workday
This example uses the GENTIME command in an ESP Procedure to handle a complex schedule. The criteria to run the job are: Run a job on the 3rd last day of the month, if this is a workday. Otherwise, run the job on the previous workday. This solution uses the GENTIME command to generate date and time variables for the 3rd last day of the month. The job runs on this date less 0 workdays. If the date is a workday the job runs on that date, otherwise it runs on the previous workday. The statements look like this:
JOB MYJOB GENTIME XX LAST DAY OF MONTH LESS 2 DAYS RUN %XXDATE LESS 0 WORKDAYS ENDJOB
132

Example: Run a This example uses the GENTIME command in an ESP Procedure to handle a job relative to the complex schedule. The criteria to run the job are: next month
Two workdays prior to the 40th day before the last day of the next month. The statements look like this:
GENTIME SR LAST DAY OF MONTH LESS 40 DAYS + STARTING TODAY PLUS 1 MONTH IF TODAY(%SRDATE LESS 2 WORKDAYS) THEN SELECT THISJOB
This solution uses the GENTIME command to generate a date variable, with the prefix SR, that refers to 40 days before the last day of the next month. If today is 2 workdays prior to this SRDATE, ESP selects the job.
Selecting different jobs based on the scheduled hour
The following two examples instruct ESP to select jobs based on the hour of processing an Event. The Event is scheduled multiple times in a day. The schedule frequency for each job is: JOBA runs at 09:00, 11:00, 13:00, 15:00, 17:00, 19:00, 21:00, 23:00 JOBB runs at 02:00, 04:00, 06:00, 08:00, 10:00, 12:00 Either situation can be approached in one of two ways. In what follows: Example 1 uses IF/THEN statements Example 2 uses symbolic variables to represent job frequency. This second approach may be preferable for programmers. Example 1: IF/THEN statements define hourly scheduling The ESP Procedure in this example uses IF/THEN statements to define hourly scheduling. ESPSHH is the built-in symbolic variable for the scheduled hour. The Procedure looks like this:
IF ESPSHH=09 OR ESPSHH=11 OR ESPSHH=13 OR ESPSHH=15 OR ESPSHH=17 OR ESPSHH=19 OR ESPSHH=21 OR ESPSHH=23 THEN SELECT JOBA IF ESPSHH=02 OR ESPSHH=04 OR ESPSHH=06 OR ESPSHH=08 OR ESPSHH=10 OR ESPSHH=12 THEN SELECT JOBB
133

Selecting different jobs based on the scheduled hour
Example 2: Symbolic variables define hourly scheduling The approach in this example uses a 48-character symbolic variable for each job. The symbol uses 2 consecutive characters to represent each hour (starting from 00 and ending at 23). To define this symbol, use the following rules: If the job is not to run at a particular hour, use XX in that hours position. If the job is to run at a particular hour, use the 2-digit hour number in that position. If a job runs every hour, define a symbol and assign it the following value:
000102030405060708091011121314151617181920212223 If a job runs at 10:00 and 15:00, define a symbol and assign it the following value: XXXXXXXXXXXXXXXXXXXX10XXXXXXXX15XXXXXXXXXXXXXXXX
The following ESP Procedure selects a job based on the value in the current hours position within the frequency symbolic.
/* REPRESENT JOB FREQUENCY WITH SYMBOLIC STRING AFREQ=XXXXXXXXXXXXXXXXXX09XX11XX13XX15XX17XX19XX21XX23 BFREQ=XXXX02XX04XX06XX08XX10XX12XXXXXXXXXXXXXXXXXXXXXX /* DETERMINE WHERE TO LOOK IN THE STRING /* SPOS IS STARTING POSITION /* EPOS IS ENDING POSITION INTEGER HOUR,SPOS,EPOS HOUR=ESPSHH SPOS=2*HOUR + 1 EPOS=SPOS + 1 /* USE SUBSTRING TO SELECT JOBS IF %AFREQ(%SPOS:%EPOS)=%ESPSHH THEN SELECT JOBA IF %BFREQ(%SPOS:%EPOS)=%ESPSHH THEN SELECT JOBB
134

Selecting different jobs based on the scheduled hour, continued
For example, at 02:00 ESP compares the 5th and 6th character of each job frequency symbolic with 02. For JOBA, AFREQ(5:6)=XX which is not equal to 02. ESP does not select JOBA. For JOBB, BFREQ(5:6)=02 which is equal to 02. ESP selects JOBB. If you need to add more jobs to this ESP Procedure: Define a symbolic variable to represent the frequency of the job. Add an IF statement to select the job.
135
Working with Special Periods

About special periods
After you define special periods in a calendar, you can use ESP to: Determine where you are in a given period. Generate date and time variables based on a period. Determine how many periods have passed. The following examples demonstrate how to use ESP Procedures in these ways. This example uses built-in functions to determine: The number of days from the start of a period. The number of days to the end of a period. The name of the special period is PERIOD. The ESP Procedure looks like this:
INTEGER PER_START,PER_END PER_START=DAYS_FROM(FIRST DAY OF PERIOD STARTING + 00.01 TODAY) PER_END=DAYS_TO(LAST DAY OF PERIOD)
Example: Determine number of days relative to a period
Example: Determine number of workdays relative to a period
This example uses built-in functions to determine: The number of workdays from the start of a period. The number of workdays to the end of a period. The name of the special period is PERIOD. The ESP Procedure looks like this:
INTEGER WORK_START,WORK_END WORK_START=DAYS_BETWEEN(FIRST DAY OF PERIOD STARTING + 00.01 TODAY,TODAY,WORKDAYS) WORK_END=DAYS_BETWEEN(TOMORROW,LAST DAY OF PERIOD + STARTING 00.01 TODAY,WORKDAYS)
136
Working with Special Periods, continued

Example: Select a job on the nth workday of a period
There may be a different number of workdays in special periods with the same name. A job may run on the nth workday of a period. For example, you may have the following: A period that contains either 20 or 21 workdays. A job that must run on the 21st workday of a period only when there are 21 workdays in the period. If you tell ESP to run the job on the 21st workday of the period and there are only 20 workdays in the period, ESP will run the job on the 1st workday of the next period. In the following ESP Procedure: The name of the special period is SPEC. ESP checks to see if there are 21 workdays in the period. Selects the job only if there are 21 workdays in the period.
JOB ABC IF DAYS_BETWEEN(1ST WORKDAY OF SPEC STARTING TODAY, + LAST WORKDAY OF SPEC,+ WORKDAYS) >= 21 THEN + RUN 21ST WORKDAY OF SPEC
Example: Generate symbolic based on a special period
This example creates a symbolic variable called FINANCIAL_YEAR that consists of two, 2-digit year numbers. The criteria for the year numbers are based on the financial year, which runs from May 1 to April 30. If the current month is January, February, March or April, use last year followed by this year. For any other month, use current year followed by next year.
137

Example: Generate symbolic based on special period, continued
The ESP Procedure looks like this:

IF ESPSMM<5 THEN DO GENTIME LAST TODAY LESS 1 YEAR FINANCIAL_YEAR=%LASTYY%ESPSYY ENDDO ELSE DO GENTIME NEXT TODAY PLUS 1 YEAR FINANCIAL_YEAR=%ESPSYY%NEXTYY ENDDO
If the current year is 1998, ESP generates the following results: FINANCIAL_YEAR=9798 , from January through April. FINANCIAL_YEAR=9899 , from May through December. This example calculates the number of weeks in a period based on a 4-4-5 Example: Determine cycle. The name of each period is PERIOD445 and there are twelve of these in number of weeks a period called FISCAL_YEAR. in 4-4-5 period The ESP Procedure looks like this:
IF TODAY(ANYDAY OF 3RD 6TH 9TH 12TH PERIOD445 + OF FISCAL_YEAR) THEN WKS_PERIOD=5 ELSE WKS_PERIOD=4
138

Example: Determine number of periods
This example uses the DAYS_BETWEEN function to find the absolute number of occurrences of a special period called FISCAL_MONTH between today and an arbitrary point in the past (January 1, 1998 in this example). ESP then generates date and time variables based on the number of occurrences of the period.
INTEGER I,J,K,L /* USE THE DAYS_BETWEEN FUNCTION TO FIND THE ABSOLUTE NUMBER OF /* OCCURRENCES OF FISCAL_MONTH BETWEEN TODAY AND AN ARBITRARY /* POINT IN THE PAST, 1ST JAN 98 IN THIS EXAMPLE I=DAYS_BETWEEN(1ST JAN 98,00.01 TODAY,FISCAL_MONTH) /* PREVIOUS FISCAL_MONTH WILL BE I-1 L=I-1 /* PRIOR TO THAT FISCAL_MONTH WILL BE I-2 K=I-2 /* AND PRIOR TO THAT FISCAL_MONTH WILL BE I-3 J=I-3 /* GENTIME CAN THEN DEVELOP DATE/TIME VARIABLES BASED ON /* NTH OFFSETS FROM THE ARBITRARY POINT OF TIME GENTIME XXX %J.TH FISCAL_MONTH OF YEAR STARTING 1ST JAN 98 GENTIME YYY %K.TH FISCAL_MONTH OF YEAR STARTING 1ST JAN 98
GENTIME ZZZ %L.TH FISCAL_MONTH OF YEAR STARTING 1ST JAN 98
139
Testing Invocation of an ESP Procedure

About invoking an ESP Procedure
ESP can invoke an ESP Procedure based on various activities. For example, ESP may trigger an Event to invoke an ESP Procedure based on: Data set activity. Job monitoring activity or an Alert process. A scheduled time. A manual trigger. You can also use different Events to invoke the same ESP Procedure. This topic shows how you can test to find out what method and what Event is being used. Different types of Events can invoke the same ESP Procedure. You can use statements in the ESP Procedure to test the method of invocation based on the value of built-in symbolic variables. If ESPTRDSN NE , the ESP Procedure is invoked by a data set triggered Event. If MNJOBNO > 0, the ESP Procedure is invoked by a job monitor or Alert process. Otherwise, if both of the above conditions are false then the ESP Procedure is invoked by a scheduled or manually triggered Event. The following instructions demonstrate how you can test within an ESP Procedure to find out how it is being invoked.
/* DATASET TRIGGER? /* IF ESPTRDSN = THEN DO SEND THIS EVENT TRIGGERED BY %ESPTRDSN U(BP01) EXIT ENDDO /* /* JOB MONITOR OR ALERT PROCESS? /*
Testing the method of invocation
140
Testing Invocation of an ESP Procedure, continued

Testing the method of invocation, continued
IF MNJOBNO > 0 THEN DO SEND THIS EVENT TRIGGERED BY %MNJOB U(BP01) EXIT ENDDO /* /* OTHERWISE, SCHEDULED OR TRIGGERED MANUALLY /* SEND EVENT SCHEDULED OR TRIGGERED MANUALLY U(BP01)
Testing the Event Different Events can invoke the same ESP Procedure. You can use statements
in the ESP Procedure to check the name of the Event invoking it, like this:
Event Select A USER.DAYJOBS USER.NIGHTJOBS
ESP Procedure
Selected Jobs
IF ESPEVENT=USER.DAYJOBS A, B THEN SELECT B IF ESPEVENT=USER.NIGHTJOBS - A, C THEN SELECT C
141
Combining CLANG Elements

About combining This topic contains some examples of combining different CLANG elements. CLANG elements
Example: Setting symbolic variables based on different criteria
The ESP Procedure in this example sets different values for symbolic variables based on the name of the data set that triggered the Event. The symbolic variables are DCNUM, which represents a data center number, and DC, which represents a data center code. These variables are used as a task name that ESP completes. The criteria for setting the symbolics are: If the first 4 characters of the data set name are FRED, ESP sets DCNUM equal to the 9th and 10th character of the data set name. If the first 6 characters of the data set name are BARNEY, ESP sets DCNUM equal to the 11th and 12th character of the data set name. If DCNUM=01 or 11, ESP sets DC=ATL. If DCNUM=02 or 12, ESP sets DC=COL.
142
Combining CLANG Elements, continued

Example: Setting symbolic variables based on different criteria, continued
The ESP Procedure first checks to see if it is being invoked by a data set triggered Event. The Procedure looks like this:
/* /* SET DATA CENTER NUMBER AND DATA CENTER CODE BASED ON /* NAME OF DATASET THAT TRIGGERED THE EVENT /* IF ESPTRDSN NE THEN DO IF %ESPTRDSN(1:4)=FRED THEN DO DCNUM=%ESPTRDSN(9:10) IF DCNUM=01 THEN DC=ATL IF DCNUM=02 THEN DC=COL ESP AJ %DC%DCNUM COMPLETE APPL(%ESPAPPL..%ESPAPGEN) EXIT ENDDO IF %ESPTRDSN(1:6)=BARNEY THEN DO DCNUM=%ESPTRDSN(11:12) IF DCNUM=11 THEN DC=ATL IF DCNUM=12 THEN DC=COL ESP AJ %DC%DCNUM COMPLETE APPL(%ESPAPPL..%ESPAPGEN) EXIT ENDDO ENDDO
143

Example: Setting symbolic variables based on different criteria, continued
/*APPLICATION DEFINITION APPL APPL1 JCLLIB ... JOB ATL01 TASK RELEASE ATLJOB JOB ATL11 TASK RELEASE ATLJOB JOB COL02 TASK RELEASE COLJOB JOB COL12 TASK RELEASE COLJOB . .
. The Event looks like this:

EVENT ID(PROD.PREHISTORIC) SCHEDULE 4PM DAILY DSTRIG FRED.CAR01.BEDROCK ANYCLOSE DSTRIG FRED.CAR02.BEDROCK ANYCLOSE DSTRIG BARNEY.CAR11.BEDROCK ANYCLOSE DSTRIG BARNEY.CAR12.BEDROCK ANYCLOSE INVOKE PROD.ESP.PROCS(APPL1)
Here are examples of what ESP produces, when different data sets are updated:
FRED.CAR01.BEDROCK (Data set) BARNEY.CAR12.BEDROCK (Data set) DCNUM=01 DC=ATL DCNUM=12 DC=COL ATL01 completed COL12 completed
144

Example: Build a This example builds a control card on the last workday of the month. The control card format of the card consists of the letter M followed by a series of 2-digit day of
the month numbers. These numbers range from the current day up to 31. For example, if the last workday of the month is the 29th day of the month, the control card looks like this:
M293031

IF TODAY(LAST WORKDAY OF MONTH) THEN DO CCARD=M JUMPTO L%ESPSDD L26: CCARD=%CCARD.26 L27: CCARD=%CCARD.27 L28: CCARD=%CCARD.28 L29: CCARD=%CCARD.29 L30: CCARD=%CCARD.30 L31: CCARD=%CCARD.31 ENDDO
If the last workday of the month is the 29th day of the month, ESP assigns the value M to the variable CCARD then jumps to the L29 label. ESP processes the assignment statements identified with the labels L29, L30 and L31. Each statement builds on the previous value of the CCARD variable. ESP builds the control card like this:
CCARD=`M'
CCARD=`M29'
CCARD=`M2930'
CCARD=`M293031'
145

Checking for a job in the input queue
JOBONQ is a built-in function that you can use to check whether a job or group of jobs is currently on any JES queue. You can use the JOBONQ function in conjunction with the REEXEC statement to re-execute an ESP Procedure at a specific time or after a certain interval of time. The following example demonstrates how to use JOBONQ with a REEXEC statement. This ESP Procedure performs the following functions: It checks to see if any job with the name RMTJOB is on hold in the input queue. (In this example, it is assumed there will be either no jobs or one job). ESP assigns the count of jobs to the integer variable JOBCOUNT. ESP then puts the resulting values for the job into the symbolic variables ZJOBID1, ZJOBNO1, ZJOBH1, ZJOBQ1. If no job is on hold in the input queue, the Procedure checks the current time. ESP performs the following actions: If the time is past 10 p.m. (22:00), ESP sends a message to the console indicating that it is not going to wait any longer for the job. If the time is before 10 p.m., ESP sends a message indicating the job is still outstanding. In this circumstance, the Procedure re-executes in 30 minutes. If RMTJOB is on hold in the input queue, the Procedure issues a JES command to release the job. The ESP Procedure looks like this:
INTEGER JOBCOUNT JOBCOUNT=JOBONQ(RMTJOB,Z,IH) IF JOBCOUNT>0 THEN VS $AJ%ZJOBNO1 ELSE DO IF ESPAHH>22 THEN DO SE I HAVE BEEN LOOKING FOR RMTJOB FOR QUITE AWHILE U(JOE) SE IT IS PAST 10PM, I AM GIVING UP U(JOE) ENDDO ELSE DO SE WAITING FOR RMTJOB TO BE SUBMITTED U(JOE) REEXEC IN(30) ENDDO ENDDO
Example: Checking for a job in the input queue
146
Using Recursive Procedures

About using recursive procedures
When you plan to bring your system down it may be useful to notify others of the shutdown and prevent long-running jobs from starting. This example uses an Event called OPER.SHUTDOWN which invokes an ESP Procedure. When you trigger this Event, specify the number of minutes until shutdown in the USER1 field. 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 ELAPSE 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 USER(CYBBP01) oper resdef elapse set avail(%time) TIME=TIME-1 IF TIME>=0 THEN ESP TRIGGER OPER.SHUTDOWN + USER1(%TIME) AT(REALNOW PLUS 1 MINUTE)
147
Overriding Inherited Relationships

About inherited relationships
Jobs in an Application may not have the same run frequency. ESP can select any jobs in a job stream and instruct them to run in the correct order. It bases the order of job execution on implied job relationships. When ESP selects the jobs, it checks to see if there are any inherited relationships between the jobs. To see what relationships are inherited, you can use ESPs simulation feature. Inherited relationships can apply to any type of job, including jobs within DJC networks and ESP Applications. Any job that possesses the INHERIT attribute allows a dependency chain to flow through it, even when the job itself is not selected.
Example: The inherited relationships take place by default
The following is a sample Application, where the inheritance of relationships takes place by default. When Friday is not the last workday of the month, ESP selects jobs A, B, C, D and F. Job F runs after job D, as the dependency chain passes through the unselected job, E.
Daily
Friday
Last workday of month
148
Overriding Inherited Relationships, continued

Overriding inherited relationships using INHERIT and NOINHERIT
The default ESP processing of inheritance within an Application may be overridden using the INHERIT and NOINHERIT parameters on the JOB and OPTIONS statements. Whether a job possesses the INHERIT attribute is determined by the following rules: By default, all jobs in an Application initially possess the INHERIT attribute. The jobs are scanned sequentially in the order in which they are defined in the Application. If an OPTIONS statement with either the INHERIT or NOINHERIT keyword is encountered, that becomes the default attribute for all subsequent jobs, until overridden by another OPTIONS statement. If the INHERIT or NOINHERIT keyword is coded on a JOB statement, the specified attribute overrides the default for that job only. Subsequent jobs revert to the current default attribute unless otherwise specified on their JOB statements. You can override the inheritance of job relationships using any of the following override methods: An OPTIONS NOINHERIT statement in an ESP Procedure. The NODE keyword in a JOB statement. The NOINHERIT keyword in a JOB statement. In many cases, you either need to inherit all relationships within an Application or you do not need to inherit any relationships in the Application. If you want to override the inheriting of all job relationships in an Application, you do not need to specify NOINHERIT for each job. Instead, you can use the OPTIONS NOINHERIT statement to set a default option. The following example demonstrates how you can use an OPTIONS NOINHERIT statement in an Application. No relationships are inherited in the BILLING Application.
APPL BILLING OPTIONS NOINHERIT JCLLIB . . . JOB . . .
Example: Using an OPTIONS NOINHERIT Statement
149

Using an OPTIONS NOINHERIT Statement, continued
Using OPTIONS NOINHERIT causes all subsequent jobs to possess the NOINHERIT attribute, unless overridden by another OPTIONS statement.
Example: Using the NODE keyword
The NODE keyword on a JOB statement defines a job as a node. No relationships pass through the node. A relationship between a predecessor to the node and a successor to the node only exists when ESP selects the node. Inheritance of relationships among the node and its successors still exist. The following example demonstrates the NODE keyword in a JOB statement. This example shows a job stream consisting of six jobs, with a node at Job B. Visually, the job stream looks like this:
NODE
150

Example: Using the NODE keyword, continued
The Application defining the job stream appears like this:

JOB A RELEASE B JOB B NODE RELEASE (C,D) JOB C RELEASE E JOB D RELEASE E JOB E RELEASE F ENDJOB JOB F ENDJOB
Based on the above Procedure, the job relationships depend on which jobs ESP selects. The following table shows how the relationships vary, depending on whether the node is part of the processing: Job Selection Jobs A and D Jobs A, B and E Jobs A, B and D Jobs A, D and F Job Relationships Jobs A and D run independently, since no relationships pass through the node. Job A runs before job B, and job B runs before E (the node is selected). Jobs run in the order of A, B and D since ESP selects the node. Job A runs independently of D and F because ESP does not select the node. ESP uses an implied relationship between jobs D and F and runs job D before F.
151

Using the NOINHERIT keyword
You can use a NOINHERIT keyword in a JOB statement to override the default for that job only. Subsequent jobs revert to the current default unless otherwise specified on their JOB statements. A job defined with the NOINHERIT attribute has a different effect on the job relationships, within its Application, depending on whether it is selected: An unselected NOINHERIT job prevents any dependencies passing through it. Any job it releases, either directly or indirectly, runs independently of the NOINHERIT jobs predecessors. An unselected NOINHERIT job breaks a dependency chain. A selected NOINHERIT job releases any selected immediate successors but does not pursue dependencies through any unselected successors. The following example shows a sample job stream. The job stream consists of 6 jobs, A, B, C, D, E and F. Visually, the job flow looks like this:
NOINHERIT
152

Using the NOINHERIT keyword, continue
The Application defining the above job stream looks like this:
JOB A RELEASE B JOB B NOINHERIT RELEASE (C,D) JOB C RELEASE E JOB D RELEASE E JOB E RELEASE F ENDJOB JOB F ENDJOB
Based on the above Application, the job relationships depend on which jobs ESP selects. The following table shows how the relationships vary, depending on whether the NOINHERIT job is selected. Job Selection Jobs A, B and E Job Relationships Job A runs before job B, but job E runs independently. Job E is not an immediate successor to the selected job B. Jobs A, C and D run independently. No dependencies pass through the unselected job B. Job A runs independently because no dependencies pass through the unselected job B. Job D runs before F because job E has the INHERIT attribute. Job B runs before job C since job C is an immediate successor. Job C runs before job F because job E has the INHERIT attribute.
Jobs A, C and D Jobs A, D and F
Jobs B, C and F
153
Resolving External Dependencies

About resolving external dependencies
ESP can look back to see if a job has completed, and it can look ahead to see if a job is scheduled. ESP performs these functions using the Job Index data set and a scheduled activity data set, respectively.
You can request that ESP generate a scheduled activity data file (SAD file). Resolving dependencies The SAD file contains information on all jobs or a subset of the jobs. ESP does using a scheduled not use this file in its normal scheduling; it uses a real time schedule, instead. activity set The primary reasons for using a SAD file are: To provide reports on upcoming schedules. To permit modeling. To resolve external dependencies. The following paragraphs contain more details about using SAD files to resolve external dependencies.
Identifying the file to ESP
Identify the file to ESP, using the SADLINK parameter. Select either of the following approaches: Use the SADLINK parameter that is set up in the ESP initialization file. Enter the SADLINK statement as an operator command. This approach allows you to add a new file without requiring you to restart the subsystem. Both of the above methods produce the following results: The SADLINK parameter (or statement) identifies an external SAD file with an internal identifier. Each time ESP initializes (or receives a SADLOAD command), ESP reads the contents of the SAD file and retains necessary information in a mainstorage resident look-up table.
SADLINK SAD1 DATASET(PROD.SADDAILY) GROUP(PROD)
154
Resolving External Dependencies, continued

Identifying the look-up table
To specify the look-up table for resolving external links, enter the SADLINK identifier on a RESOLVE statement in an Application. The RESOLVE statement instructs ESP to look at the scheduled activity data set to resolve an external dependency. ESP automatically selects the job if it is found. In the following example ESP only selects job ABC if it finds the job on the SAD file.
RESOLVE SAD1 JOB ABC EXTERNAL RELEASE XYZ JOB XYZ RUN DAILY ENDJOB
Loading the SAD Enter a SADLOAD command to refresh the in-core table whenever there has file been an update to the SAD file. As an alternative, you can automate the
SADLOAD command by instructing ESP to execute the ESP command processor. This step must follow the SAD file generation run. An example of a SADLOAD command appears below:
SADLOAD SAD1
The following example includes a step to issue the SADLOAD command.

Example: Defining Automatic Execution of SADLOAD command
The following series of commands defines an automatic SADLOAD command that occurs whenever the ESP command processor executes.
//SADGEN JOB ACCT1,GENERATE SAD FILE,CLASS=A //S1 EXEC ESP,PARM=SAD //SYSPRINT DD SYSOUT=* SADGEN DSN(PROD.SADDAILY) //S2 EXEC PGM=ESP,COND=(0,NE) //SYSPRINT DD SYSOUT=* //SYSIN DD * OPER SADLOAD SAD1
155
Defining the Scope of External Dependencies

About external dependencies
When a job is dependent on an external job, ESP can look back to see if the predecessor completed successfully. Use the SCOPE parameter to: Control how far back ESP searches the Job Index data set. Limit the forward search for a job in the SAD file (as a result of a RESOLVE statement in an ESP Procedure). On the days you select an external job, the SCOPE parameter instructs ESP to look back in the Job Index data set to see if the job has completed successfully. ESP does not use a look forward time unless you use a RESOLVE statement. If the job is not found, ESP waits for the dependency to be satisfied. The next example illustrates the use of the SCOPE parameter to define the scope of an external dependency.
Example: ESP checks back to see if job completed
In this example, ESP selects job ABC on Sundays. ESP looks back 24 hours to Saturday to see if the job has completed successfully.
JOB ABC EXTERNAL SCOPE(-24:00) RUN SUNDAY
Example: Using RESOLVE and SCOPE together
In this example, you want ESP to run two jobs A and B, but ESP cannot release job A until it makes sure that Job X is complete. Job X is an external job which may have run in the past 24 hours or may be scheduled in the next 24 hours. At the end of this example is a diagram illustrating the steps ESP performs to resolve this dependency. More detailed information follows:
156
Defining the Scope of External Dependencies, continued

Example: Using RESOLVE and SCOPE together, continued
1. ESP triggers an Event called CYBER.SAD_CREATE on Monday at 06:00. The Event executes a batch job which, in turn, produces a SAD file. The SAD file contains all jobs to run during the week ranging from Monday at 6:00 to the following Monday at 05:59. The SADGEN command looks like this:
SADGEN DATASET(PROD.ESP.SAD) FROM(06:00 TODAY) TO(05:59 MONDAY)
2. The SADLINK command in the ESP initialization parameters associates a logical identifier called SADWKLY with the actual SAD data set name of PROD.ESP.SAD. The SADLINK command looks like this:
SADLINK SADWKLY DATASET(PROD.ESP.SAD)
3. Each time ESP initialization occurs (or in response to a SADLOAD command), ESP performs the following activities: It reads the contents of the SAD file. It retains necessary information in a main storage resident look-up table. 4. Assume that ESP triggers the Event CYBER.TEST_EVENT on Tuesday at 16:00. The Event invokes an ESP Procedure called TESTPROC. The Procedure TESTPROC runs 2 jobs based on the following dependencies: JOBA depends on an external predecessor called JOBX. ESP must ensure that JOBX is complete before releasing JOBA. JOBB depends on JOBA.
157

The ESP Procedure, releasing JOB A and JOB B, looks like this:
TESTPROC:ESPPROC APPL TESTAPPL JCLLIB CYBER.TEST.JCL RESOLVE SADWKLY JOB JOBX EXTERNAL SCOPE(-24:00,24:00) RELEASE JOBA JOB JOBA RELEASE JOBB JOB JOBB ENDJOB SELECT (JOBA,JOBB)
5. ESP checks the SADWKLY in-core table to resolve the dependency for JOBA. If JOBX is scheduled within the specified scope, ESP ensures that JOBX is complete before releasing JOBA. If JOBX is not scheduled within the specified scope, ESP does not select JOBX and releases JOBA. 6. ESP checks the Job Index data set to see if JOBX has been run in the previous 24 hours. If so, ESP releases JOBA.
158

Monday 06:00 CYBER.SAD_CREATE triggers
1
SADGEN . . . JOBA JOBB JOBX /* ESP Initialization Parms */ SADLINK SADWKLY DATASET(`PROD.ESP.SAD')
2
ESP Address Space
SADWKLY in-core look-up table
PROD.ESP.SAD
. . . JOBA JOBB JOBX
Tuesday 16:00 CYBER.TEST_EVENT triggers
INVOKE TESTPROC
JOBX
6
PROD.ESP.JOBINDEX
TESTPROC:ESPPROC RESOLVE SADWKLY JOB JOBX EXTERNAL SCOPE(-24:00,24:00) RELEASE JOBA JOB JOBA RELEASE JOBB JOB JOBB ENDJOB SELECT (JOBA,JOBB)
159

Summary of options
The following chart summarizes the different options you have for using SCOPE and RESOLVE.
Option SCOPE without RESOLVE
RESOLVE without SCOPE
RESOLVE with SCOPE
Description Instructs ESP to look back in the Job Index data set to see if the job has completed successfully. ESP does not use a look forward time. If the job is not found, ESP waits for the dependency to be satisfied. Instructs ESP to look at the scheduled activity data set to resolve the dependency. ESP automatically selects the job if it is found. Instructs ESP to look at the scheduled activity data set within the specified scope. ESP automatically selects the job if it is found.
160
Advanced Use of Applications Overview

Introduction
This chapter discusses the advanced features of ESP Applications and shows you how to combine the various features of ESP to make your Applications more powerful. The ESP Users Guide discusses the basic functions of ESP Applications. This chapter contains the following topics: Topic Changing Job Attributes Posting of External and Manual Jobs Controlling the Release of Jobs Scheduling Multiple Runs of a Job Using SubApplications Submitting Different Jobs Based on Data Set Activity Running All or Part of an Application Taking Action Based on Time Setting Up Step-Level Dependencies See Page 162 163 174 182 184 188 190 193 202
In this chapter
161
Changing Job Attributes

About job attributes
In ESP, you can define a job with a number of different attributes by 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 criteria such as schedule criteria, system activity, or the status of another job. For example, job ABC is a regularly scheduled job each day except on Mondays when it is an on-request job. This job has different attributes based on schedule criteria. To define a job with different attributes, use the JOBATTR statement. This statement lets you change any attributes of a job within the scope of the JOB statement or in job documentation. Attributes include the keywords you can use on the JOB statement. In the following example, Job ABC runs daily. On Mondays, it is a request job.
JOB ABC RUN DAILY IF TODAY(MONDAY) THEN JOBATTR REQUEST ENDJOB
The JOBATTR statement
Example: Changing a job attribute
Example: Negating a job attribute
In the following example, Job ABC runs daily. It is an on-request job everyday except on Mondays, when it is a regularly scheduled job.
JOB ABC REQUEST RUN DAILY IF TODAY(MONDAY) THEN JOBATTR NOREQUEST ENDJOB
In the following example, Job ABC runs each weekday. On Fridays, it needs to be defined on hold; on the last workday of the month, it is an on-request job. When Friday is also the last workday of the month, ESP combines the different attributes resulting in ABC defined on hold and as an on-request job.
JOB ABC RUN WEEKDAYS IF TODAY(FRIDAY) THEN JOBATTR HOLD IF TODAY(LAST WORKDAY OF MONTH) THEN JOBATTR REQUEST ENDJOB
162
Posting of External and Manual Jobs

About external and manual jobs
When you define an Application, you must define a job submitted outside of the Application as an external or manual job. If more than one generation of the Application is active when the job ends, you must specify the generation in which you want ESP to post the job. There are different ways you can control the posting of these jobs. The following table summarizes these posting options:
Controlling the posting of external and manual jobs
Option POST-OLDEST
NOPOST_OLDEST
NOPOST_UNTIL_READY POST_WHILE_WAITING
NOPOST_WHILEWAITING
SCHEDULED
Where It Can Description Be Used TRACKOPT; Posts the job in the oldest APPL statement active generation of the Application in which the job has not been marked. TRACKOPT; Posts the job in all active APPL statement generations of the Application in which the job has not been marked complete. This is the default. APPL statement Does not post the job until its dependencies are met. APPL statement Posts the job even if it is waiting - status is APPLWAIT, SUBAPPL WAIT, or JOB_ANCESTOR_WAIT. APPL statement Does not post the job if it is waiting - status is APPLWAIT, SUBAPPL WAIT, or JOB_ANCESTOR_WAIT. JOB statement Indicates a range for the scheduled time of the Event that submits the job; trigger time is used for nonscheduled Events.
163
Posting of External and Manual Jobs, continued

Controlling the posting of external and manual jobs, continued
Note: You cannot use POST_OLDEST with either NOPOST_UNTIL_READY or NOPOST_WHILE_WAITING. The SCHEDULED keyword provides the most control for synchronizing Applications. You can use it for any external job but you cannot use it for a manual job. ESP can also resolve external dependencies using a Scheduled Activity data set. This technique is more commonly used with DJC/JES3 job networks which do not offer the flexibility of Applications. For more information on this feature, refer to Advanced Use of ESP Procedures on page 129.
Example: Using different posting options
This example illustrates the effects of using different posting options in an Application. Assume there are two generations of an Application active on the system with the following characteristics: The Application and generations are THISAPPL.1 and THISAPPL.2. Each Application contains an external job A which has not been posted complete. THISAPPL.2 is in an APPLWAIT state, waiting for THISAPPL.1 to complete.
THISAPPL.1 A
(External)
THISAPPL.2
(APPLWAIT)
A
(External)
When job A completes, ESP marks the job complete based on the posting option.
164

Example: Using different posting options, continued
Posting Options POST_OLDEST NOPOST_OLDEST POST_WHILE_WAITING NOPOST_WHILE_WAITING NOPOST_UNTIL_READY
Application in which Job Marked Completed THISAPPL.1 THISAPPL.1, THISAPPL.2 THISAPPL.1, THISAPPL.2 THISAPPL.1 THISAPPL.1, THISAPPL.2
In this example, job B runs Monday, Wednesday and Friday, and job A runs Example: Waiting on an everyday. Job B depends on the job A which is scheduled for the same day. external job with Visually, the dependencies look like this: the same scheduled date
Monday Tuesday A B
Wednesday
The ESP Procedure looks like this: JOB A EXTERNAL SCHEDULED(TODAY) RELEASE B RUN MON WED FRI ENDJOB JOB B RUN MON WED FRI ENDJOB
165

Example: Waiting on an external job with the same scheduled date, continued
The RUN statement for job A reflects the days you want it as an external dependency for job B. When ESP builds the Application on a Monday, Wednesday, or Friday, it checks to see if todays scheduled run of job A is complete. If todays job A is complete, ESP posts the external job complete. If todays job A is not complete, ESP waits until the job ends to post the external job complete.
Example: Waiting on an external job with a previous scheduled date different Application
In this example, ESP schedules job SUNJOB on Sundays and it depends on the successful completion of job SATJOB which ESP schedules on Saturdays. SATJOB and SUNJOB belong to different Applications. Visually, the dependencies look like this:
Saturday SATJOB Sunday SUNJOB

JOB SATJOB EXTERNAL SCHEDULED(YESTERDAY) RUN SUNDAY RELEASE SUNJOB ENDJOB JOB SUNJOB RUN SUNDAY ENDJOB
166

Example: Waiting on an external job with a previous scheduled date - different Application, continued
On Sunday you want to select job SATJOB as an external predecessor to job SUNJOB. When ESP builds this Application it checks to see if SATJOB from the previous day (YESTERDAY) is complete. If yesterdays SATJOB is complete, ESP posts the external job complete. If yesterdays SATJOB is not complete, ESP waits until the job ends successfully to post the external job complete.
Example: Waiting on an external job with a previous scheduled date same Application
This example is the same as the previous example except that the jobs belong to different generations of the same Application. ESP schedules job SUNJOB on Sundays and it depends on the successful completion of job SATJOB which ESP schedules on Saturdays. SATJOB and SUNJOB belong to different generations of the same Application. Visually, the dependencies look like this:
Saturday SATJOB Sunday SUNJOB
Since the jobs belong to the same Application, you need to use the JOBATTR statement to change SATJOBs attributes on Sunday. On Sunday, you do not want to run the job - you only want to build a relationship with the job. The ESP Procedure is shown below. The RUN statement for SATJOB reflects when the job is scheduled (Saturday) and when the external relationship needs to be built (Sunday).
167
Example: Waiting on an external job with a previous scheduled date - same Application, continued
JOB SATJOB IF TODAY(SUNDAY) THEN JOBATTR EXTERNAL SCHEDULED(YESTERDAY) RUN SATURDAY SUNDAY RELEASE SUNJOB ENDJOB JOB SUNJOB RUN SUNDAY ENDJOB
When ESP builds this Application on Sunday it checks to see if SATJOB from the previous day (YESTERDAY) is complete. If yesterdays SATJOB is complete, ESP posts the external job complete. If yesterdays SATJOB is not complete, ESP waits until the job ends successfully to post the external job complete.
Example; Waiting on a manual job that runs multiple times
In this example, job X is a manual job which runs multiple times throughout the day. Job B can run after the first successful run of job X that completes after midnight. Visually, the flow of jobs looks like this:
(23:15)
(00:15)
(01:15)
168

Example: Waiting on a manual job that runs multiple times, continued
The NOPOST_UNTIL_READY option ensures that ESP does not post job X until at least midnight. The ESP Procedure looks like this:
APPL XYZ NOPOST_UNTIL_READY JCLLIB . . . JOB X MANUAL DELAYSUB MIDNIGHT RUN DAILY RELEASE B ENDJOB JOB B
ESP produces different results based on the completion time of job X. For example, if job X runs at 11:15 p.m., 12:15 a.m., and 1:15 a.m., ESP produces the following: Completion Time for Job 11:15 p.m. (23:15) Results This run of job X does not post complete in the Application since the job does not become ready until midnight. Job X posts complete in the Application. This run of job X does not post complete in the Application as it will already have been marked complete.
12:15 a.m. (00:15) 1:15 a.m. (01:15)
Example: Waiting for another job to complete
In this example, job B is a manual job that should not complete until job A runs successfully. ESP submits job A. Since job B is a manual job, ESP has no control over the submission time for job B. However, you can still control when ESP posts the job complete.
169

Example: Waiting for another job to complete, continued
Visually the flow looks like this:
MANUALLY SUBMITTED
The NOPOST_UNTIL_READY option can ensure that job A completes successfully before job B posts complete in the Application. The Procedure looks like this:
APPL ABC NOPOST_UNTIL_READY JCLLIB . . . JOB A RELEASE B RUN DAILY ENDJOB JOB B MANUAL RELEASE C RUN DAILY ENDJOB JOB C RUN DAILY ENDJOB
170

Example: Waiting for an online task to complete
In this example, CICS is the name of a started task for an online system which is normally shut down at 7 p.m. weekdays and 4 p.m. weekends. If CICS comes down prior to its normal shutdown time you do not want the dependent jobs to be submitted. By using NOPOST_UNTIL_READY on the APPL statement you ensure that ESP does not post the CICS manual job as completed before normal shutdown time: If CICS completes prior to 7 p.m. on weekdays, the manual job does not post complete. If CICS completes prior to 4 p.m. on weekends, the manual job is not posted complete. The Procedure looks like this:
APPL BILLING NOPOST_UNTIL_READY JCLLIB . . . JOB CICS MANUAL DELAYSUB 7pm IF TODAY(SAT SUN) THEN DELAYSUB 4PM RUN DAILY RELEASE FIRSTJOB ENDJOB
Example: Posting In this example, a job in one Application must wait on an on-request job in a bypassed job in another Application. The request job may or may not be requested. another Job A is an on-request job in Application APPL1. Job B is in Application Application
APPL2 and must wait until job A completes successfully or is bypassed.
171

Example: Posting a bypassed job in another Application, continued
Take the following steps: Set up a link in APPL1 that waits on job A. Set up a task in APPL2 as a predecessor to job B. Use the link to issue a command to complete the task in APPL2. Visually, the flow looks like this:
APPL1 A
(REQUEST job)
APPL2 WAIT4.A
(task)
CHECK.A
(link)
(job)
Here is the definition for APPL1:

/* /* FIRST APPLICATION /* /* USE LINK AFTER REQUEST JOB TO POST TASK COMPLETE IN /* OTHER APPLICATION /* JCLLIB CYBBP01.TESTJOBS.CNTL APPL EXT1 JOB A REQUEST DELAYSUB REALNOW PLUS 1 HOUR RUN DAILY RELEASE CHECK.A ENDJOB JOB CHECK.A LINK PROCESS ESP AJ WAIT4.A COMPLETE APPL(EXT2.0) RUN DAILY ENDJOB
172

Example: Posting a bypassed job in another Application, continued

/* /* SECOND APPLICATION /* /* USE TASK AS A PREDECESSOR TO THE JOB YOU WANT TO RUN /* APPL EXT2 JCLLIB CYBBP01.TESTJOBS.CNTL JOB WAIT4.A TASK RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY ENDJOB

/* /* SECOND APPLICATION /* /* USE TASK AS A PREDECESSOR TO THE JOB YOU WANT TO RUN /* APPL EXT2 JCLLIB CYBBP01.TESTJOBS.CNTL JOB WAIT4.A TASK RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY ENDJOB
173
Controlling the Release of Jobs

About controlling the release of jobs
When you use ESP to set up a relationship between two jobs, such as job A with a successor of job B, ESP normally: Decrements the hold count of job B only upon successful completion of job A. Waits until the hold count of job B reaches zero before it considers the job eligible. Does not delay submission of job B when job A completes. Sometimes you may want to change the way ESP handles the release of a job. Using ESP, you can automatically: Delay the release of a job based on the actual time its predecessors complete. Set up optional predecessors, for example, one of two jobs must complete before the successor runs. Release a job with outstanding predecessors. Release a job based on how a predecessor terminates. The following examples illustrate these different techniques. You can instruct ESP to delay releasing a job based on the time its predecessors complete. For example, you may want ESP to wait a specific number of minutes, or until a particular time, before submitting a job. In this example: If job A completes prior to 06:23, ESP delays submission of job B by 5 minutes. If job B completes between 06:45 and 07:30, ESP delays submission of job C until 07:30.
Example: Delaying release based on time
174
Controlling the Release of Jobs, continued

Example: Delaying release based on time, continued
Visually, the dependencies look like this:
If time < 06.23 then wait 5 minutes
If time is between 06:45 and 07:30 then wait until 07:30
Set up the ESP Procedure like this:

APPL ABC JCLLIB . . . JOB A RELEASE B RUN DAILY ENDJOB JOB B /* /* IF TIME < 06.23 THEN WAIT 5 MINUTES /* ELSE RELEASE WHEN ELIGIBLE /* IF ESPATIME<06.23.00 THEN RELDELAY 5 RELEASE C RUN DAILY ENDJOB JOB C /* /* IF TIME IS BETWEEN 06:45 AND 07:30 THEN DELAY /* SUBMISSION UNTIL 07:30, ELSE RELEASE WHEN ELIGIBLE /* IF ESPATIME>06.45.00 AND ESPATIME<07.30.00 + THEN REEXEC AT(07.30) RUN DAILY ENDJOB
175

Optional predecessors
You can use the RELCOUNT statement to specify the hold count when a job becomes eligible for submission. By default, ESP will not consider a job eligible until its hold count is 0. In this example, job D waits for any of job A, job B, or job C to complete successfully. Visually the dependencies look like this:
A OR B OR C
Example: Optional job dependency

APPL ABC JCLLIB . . . /* JOB D WAITS FOR EITHER JOB A OR JOB B OR JOB C JOB A RUN DAILY RELEASE D ENDJOB JOB B RUN DAILY RELEASE D ENDJOB JOB C RUN DAILY RELEASE D ENDJOB JOB D RUN DAILY RELCOUNT 2 ENDJOB
176

Example: Optional job dependency, continued
When ESP builds the Application, job D has a hold count of 3. By specifying RELCOUNT 2 for job D, ESP releases this job when its hold count becomes 2. This means ESP releases job D when any of job A, job B, or job C complete successfully. In this example, job ABC cannot run until one of two data sets, Example: Optional data set PAYROLL.MASTERA or PAYROLL.MASTERB, has been created. trigger Whichever one is created first, causes ESP to submit job ABC. The dependency Visually the dependencies look like this:
Application does not need to wait for the other data set before it completes.
FILEA
OR
FILEB
ABC
Each data set trigger dependency is represented by a data set trigger object, FILEA and FILEB. Each of these objects is a predecessor to job ABC.
177

Example: Optional data set trigger dependency, continued

APPL PAYMAST JCLLIB CYBER.JCL DSTRIG FILEA CONDITIONAL DSNAME CYB.PAYROLL.MASTERA RUN DAILY RELEASE ABC ENDJOB DSTRIG FILEB CONDITIONAL DSNAME CYB.PAYROLL.MASTERB RUN DAILY RELEASE ABC ENDJOB JOB ABC RELCOUNT 1 RUN DAILY ENDJOB
When ESP builds the Application, job ABC has a hold count of 2. By specifying RELCOUNT 1 for job ABC, ESP releases this job when its hold count becomes 1. This means ESP releases job ABC when either FILEA or FILEB completes. FILEA completes when PAYROLL.MASTERA is created; FILEB completes when PAYROLL.MASTERB completes. The CONDITIONAL keyword on the FILEA and FILEB definitions indicates that these objects do not have to complete for the Application to complete. For example, if FILEA completes and job ABC runs to successful completion, ESP bypasses FILEB and the Application completes.
178

Notification of status
You may want to know if a certain number of predecessors are outstanding at a particular time. In this example, ESP sends a message if 5 out of 10 predecessors have not completed by 1 a.m. If 5 out of 10 predecessors are complete before 1 a.m., ESP processes the link and does not send a message. If 5 out of 10 predecessors are not complete before 1 a.m., ESP drops the dependencies on the link and sends a warning message. In either case, ESP completes the link. The definition of the link looks like this:
JOB CHECK.STATUS LINK PROCESS RUN DAILY AFTER (J1,J2,J3,J4,J5,J6,J7,J8,J9,J10) ABANDON DEPENDENCIES 1AM RELCOUNT 5 IF ESPAHH=01 THEN + SEND %ESPAPPL IS RUNNING LATE CN(01) ENDJOB
Releasing a job based on predecessor termination
You can instruct ESP to decrement the hold count of a successor job based on how a predecessor terminates. By default, ESP only decrements the hold count of a successor job when a predecessor terminates normally. The following options are available when you define a job relationship using a POSTREQ, PREREQ, RELEASE, or AFTER statement. A abnormal termination N normal termination U any termination
179

Releasing a job based on predecessor termination, continued
An example is shown below.
A
Any Termination
JOB A RELEASE (B(U))
Example: Job based on how a particular job terminates
In the following example, ESP submits a different job based on how a particular job terminates. If PAYJOB1 terminates abnormally, ESP submits job RECOVER If PAYJOB1 terminates normally, ESP submits job PAYJOB2. Visually the dependencies look like this:
PAYJOB1 PAYJOB1
Abnormal Abnormal Termination Termination Normal Normal Termination Termination
RECOVER RECOVER
PAYJOB2 PAYJOB2
180

Example: Job based on how a particular job terminates, continued
Set up the ESP Procedure like this:

APPL PAYJOBS JCLLIB . . . JOB PAYJOB1 RUN DAILY RELEASE (RECOVER(A),PAYJOB2) ENDJOB JOB RECOVER CONDITIONAL RUN DAILY ENDJOB JOB PAYJOB2 RUN DAILY ENDJOB
Notice that the RECOVER job is defined as a CONDITIONAL job as it is an optional job that may not execute. The Application will complete regardless of the execution of RECOVER.
181
Scheduling Multiple Runs of a Job

About scheduling You can use ESP to dynamically insert a job into an Application multiple times multiple runs in a day. Job MYJOB runs every hour on the hour, from 8 a.m. to 4 p.m.
To set up the Application, follow these steps: 1. Define a task which builds a time qualifier for the job, inserts the job, and re-executes in 1 hour. The time qualifier consists of the letter T and the actual hour, minute and second, to ensure the job ESP inserts is unique. The task in this example is MYJOB.HOURLY. 2. Define a link which completes the task at 4:01 p.m. This stops the submission of the job. The link in this example is MYJOB.STOPSUB. 3. Schedule an Event prior to 8 a.m. to invoke the ESP Procedure. Here is a sample ESP Procedure. Example: Scheduling multiple runs of a APPL THISAPPL job JCLLIB CYBBP01.TESTJOBS.CNTL
/* /* USE A TASK TO DYNAMICALLY INSERT MYJOB. /* BUILD TIME QUALIFIER AND INSERT JOB MYJOB.T%TIME /* INTO APPLICATION EVERY HOUR BETWEEN 8AM AND 4PM /* JOB MYJOB.HOURLY TASK RUN WORKDAYS DELAYSUB 8AM TIME=%ESPAHH%ESPAMN%ESPASS ESP AJ MYJOB.T%TIME INSERT APPL(%ESPAPPL..%ESPAPGEN) REEXEC AT(REALNOW PLUS 1 HOUR) ENDJOB /* /* STOP SUBMISSION OF MYJOB BY COMPLETING THE TASK /* MYJOB.HOURLY AT 4:01PM /* JOB MYJOB.STOPSUB LINK PROCESS RUN WORKDAYS DELAYSUB 4:01PM ESP AJ MYJOB.HOURLY COMPLETE APPL(%ESPAPPL..%ESPAPGEN) ENDJOB
182
Scheduling Multiple Runs of a Job, continued

Example: Scheduling multiple runs of a job, continued
Beginning at 8 a.m., the task: Builds a time symbolic (%TIME) for the job consisting of the actual hour, minute and second. For example, at 8 a.m., ESP assigns the value 080000 to the TIME variable. Issues an AJ command to dynamically insert MYJOB with a qualifier of T%TIME into the Application. For example, at 8 a.m., ESP uses a qualifier of T080000. Re-executes in 1 hour. At 4:01 p.m.: The link issues an AJ command to complete the MYJOB.HOURLY task. Note: Another method for handling this scenario is to use templates. Refer to Using Templates on page 205 for more information.
183
Using SubApplications
About subApplications
You can divide an Application into smaller subApplications. This provides you with the opportunity to display and manipulate portions of an Application using a single command. For basic information about subApplications, refer to the ESP Users Guide. In this example, the MASTER Application consists of two subApplications. The definitions for the Application are stored in three separate PDS members: CYB.ESP.PROCS(DEFAULTS) CYB.ESP.PROCS(STREAM1) CYB.ESP.PROCS(STREAM2). Visually, the Application and subApplications look like this:
Using subApplications for different job streams
MASTER
DEFAULTS
STREAM1
STREAM2
184
Using SubApplications, continued

Using subApplications for different job streams, continued
The DEFAULTS member specifies global processing options for the Application, including the name of the Application and the JCL library. It looks like this:
APPL MASTER JCLLIB CYBBP01.TESTJOBS.CNTL
The STREAM1 member defines the STREAM1 subApplication and looks like this:
SUBAPPL STREAM1 JOB A RUN DAILY RELEASE (B,C) ENDJOB JOB B RUN DAILY RELEASE D ENDJOB JOB C RUN DAILY RELEASE D JOB D RUN DAILY RELEASE Y ENDJOB
The STREAM2 member defines the STREAM2 subApplication and looks like this:
SUBAPPL STREAM2 JOB X RUN DAILY RELEASE Y ENDJOB JOB Y RUN DAILY RELEASE Z ENDJOB JOB Z RUN DAILY ENDJOB
185

Using subApplications for different job streams, continued
The following Event invokes the MASTER Application:

EVENT ID(CYBER.MASTER) SCHEDULE 8AM DAILY INVOKE CYBER.ESP.PROCS(DEFAULTS) INVOKE CYBER.ESP.PROCS(STREAM1)
Using subApplications for special requests
In this example, an Application contains a group of regularly scheduled jobs and a group of special jobs. Each day either the regular jobs run or the special jobs run, and some common jobs run. A user must request the special jobs. Visually, the Application and subApplications look like this:
B
NORMAL SUBAPPL
X OR
SPECIAL SUBAPPL
Set your Application up like this: use a subApplication called NORMAL to represent the regularly scheduled jobs use a subApplication called SPECIAL to represent the special on-request jobs identify each job in the SPECIAL subApplication as a REQUEST job.
186

Using subApplications for special requests, continued
Here is a sample ESP Procedure:

APPL ATOZ JCLLIB . . . JOB A RUN DAILY RELEASE (B,X) ENDJOB JOB B SUBAPPL NORMAL RUN DAILY RELEASE C ENDJOB JOB C SUBAPPL NORMAL RUN DAILY RELEASE Z ENDJOB JOB X REQUEST SUBAPPL SPECIAL RUN DAILY RELEASE Y ENDJOB JOB Y REQUEST SUBAPPL SPECIAL RUN DAILY RELEASE Z ENDJOB JOB Z RUN DAILY ENDJOB
When a user requests that the special jobs be run, you will need to issue commands to: Bypass the NORMAL subApplication. Request the SPECIAL subApplication. You may want to set up a manually triggered Event that invokes an ESP Procedure to take these actions. The following is an example of such an ESP Procedure:
ESP AJ NORMAL BYPASS APPL(ATOZ.0) ESP AJ SPECIAL REQUEST APPL(ATOZ.0)
187
Submitting Different Jobs Based on Data Set Activity

Example: Building a single job Application based on the closure of a data set
This example builds a single job Application based on the closure of a specific data set. Follow these steps to set up this type of Application: 1. Define an ESP Procedure that: checks the name of the data set that triggers the Event defines an Application to run the appropriate job. 2. Define the applicable data sets in an Event which invokes an ESP Procedure. You must specify the data set name and type of activity (e.g. ANYCLOSE).
Example: Using RUNJOB when one of three data sets closes
This example builds a single job Application called RUNJOB when any of three data sets closes. Depending on which data set closes, ESP runs job A, B, or C. 1. Define the Application in an ESP Procedure. A sample Application looks like this:
IF ESPTRDSN=YOUR.FIRST.DATASET THEN JOBNAME=A IF ESPTRDSN=YOUR.SECOND.DATASET THEN JOBNAME=B IF ESPTRDSN=YOUR.THIRD.DATASET THEN JOBNAME=C APPL RUNJOB JCLLIB . . . JOB %JOBNAME RUN ANY ENDJOB
When ESP triggers the Event, it assigns a value to the JOBNAME symbolic variable in accordance with the data set that closed. Data Set Name YOUR.FIRST.DATASET YOUR.SECOND.DATASET YOUR.THIRD.DATASET JOBNAME A B C
188
Submitting Different Jobs Based on Data Set Activity, continued

Example: Using RUNJOB when one of three data sets closes, continued
2. Enter the applicable data set names and applicable activity. The following example shows an Event that will trigger on any closure of these data sets:
EVENT ID(PROD.RUNJOB) DSTRIG YOUR.FIRST DATASET ANYCLOSE DSTRIG YOUR.SECOND DATASET ANYCLOSE DSTRIG YOUR.THIRD DATASET ANYCLOSE INVOKE CYB.ESP.PROCS(RUNJOB)
189
Running All or Part of an Application

About running all or part of an Application
Sometimes you may need to run all or part of an Application in addition to its normal schedule. For example, this may be required when rerunning an Application from a previous day. You may need to: Run only part of an Application. Rerun an entire Application. Rerun part of an Application. You can specify different options on the TRIGGER command for any of these activities. ESP allows you to trigger an Event: In addition to its regularly scheduled time. For a time and date in the past. With ROOT jobs, to run part of an Application. These examples show different options you can use when triggering an Event called PROD.PAYROLL. Trigger time is 4pm yesterday. Since this time has past, ESP will trigger the Event immediately. Job selection and scheduled dates are based on yesterdays date.
TRIGGER PROD.PAYROLL AT(4PM YESTERDAY) ADD
Example: Options when triggering an Event called

PROD.PAYROLL
Trigger time is last Friday. Since this time has past, ESP will trigger the Event immediately. Job selection and scheduled dates are based on last Fridays date.
TRIGGER PROD.PAYROLL AT(FRIDAY LESS 1 WEEK) ADD
Trigger time is Feb. 17, 1998. Since this time has past, ESP will trigger the Event immediately. ESP will generate an Application beginning with job C and will include all the successors it had on Feb 17, 1998.
TRIGGER PROD.PAYROLL AT(FEB 17,1998) ADD ROOT(C+)
ESP will generate an Application consisting of jobs A, C and F. This execution replaces the next scheduled execution of the Event.
TRIGGER PROD.PAYROLL ROOT(A,C,F) REPLACE
190
Running All or Part of an Application, continued

Example: Options when triggering an Event called PROD.PAYROLL, continued
Note: Before rerunning all or part of an Application you may want to use the SIMULATE command to simulate the activities of the Event, thereby ensuring correctness.
Rerunning a subApplication
This example illustrates a technique for rerunning a subApplication. It requires that the subApplication be stored in a PDS member of its own. Visually, the relationship between the Event and ESP Procedures looks like this:
PROD.RUN_SUBAPPL
(Event)
RUNSUB
(ESP Procedure)
DEFAULTS
(ESP Procedure)
%USER1
(ESP Procedure)
1. Define an ESP Procedure with two INVOKE statements. One INVOKE statement points to a DEFAULTS member which specifies default options for the Application. This includes the Application name and JCL library name. The other INVOKE statement points to a member represented by the symbolic variable %USER1. 2. Define an Event to invoke the ESP Procedure. The Event looks like this:
EVENT ID(PROD.RUN_SUBAPPL) INVOKE PROD.ESP.PROCS(RUNSUB)
PROD.ESP.PROCS(RUNSUB) contains two INVOKE statements and looks like this:

INVOKE PROD.ESP.PROCS(DEFAULTS) INVOKE PROD.ESP.PROCS(%USER1)
191
Running All or Part of an Application, continued

Rerunning a subApplication, continued
To run a subApplication, trigger the Event and specify the name of the subApplication as the USER1 variable. The following is an example of triggering the PROD.RUN_SUBAPPL Event with a USER1 parameter of SUBAPPL1. This causes ESP to invoke the DEFAULTS and SUBAPPL1 members of the PROD.ESP.PROCS data set.
TRIGGER PROD.RUN_SUBAPPL ADD USER1(`SUBAPPL1')
DEFAULTS
(ESP Procedure)
SUBAPPL1
(ESP Procedure)
192
Taking Action Based on Time

About taking action based on time
You can instruct ESP to take action when a job or task does not complete by a particular time, or if a job or subApplication has not started by a particular time. Depending on your requirements, ESP can either complete or bypass the task, job, Application, or subApplication. The next few examples demonstrate several different situations requiring ESP action based on time. For other examples of taking action for overdue work, refer to Job Monitoring and Alert Processing on page 95.
Example: Requesting different jobs based on the time of predecessor completion
You can instruct ESP to check the actual time before running jobs in an Application. Based on the actual time, ESP selects different jobs to run. Follow these steps to set up your Application: 1. Define the job relationships in an ESP Procedure. 2. Define a task to check the actual time. The time check task is defined as part of the Application. The following example demonstrates a typical Application in which ESP checks the actual time and runs the appropriate jobs. In this example, job A and job B run in sequence. After job B completes successfully, ESP checks the actual time. If the time is prior to 15:00, ESP requests job C and D. If the time is 15:00 or later, ESP requests job E and F. In either case, ESP completes a task.
193
Taking Action Based on Time, continued

Example: Requesting different jobs based on the time of predecessor completion, continued
CHECK.TIME
<15:00 >=15:00
194

Example: Requesting different jobs based on the time of predecessor completion, continued
JCLLIB CYBBP01.TESTJOBS.CNTL APPL BILL INDEX(9) WAIT JOB A RUN DAILY RELEASE B ENDJOB JOB B RUN DAILY RELEASE CHECK.TIME ENDJOB JOB CHECK.TIME TASK IF ESPATIME < 15.00.00 THEN DO ESP AJ C REQUEST APPL(BILL.0) ESP AJ D REQUEST APPL(BILL.0) ESP AJ CHECK.TIME COMPLETE APPL(BILL.0) ENDDO IF ESPATIME >= 15.00.00 THEN DO ESP AJ E REQUEST APPL(BILL.0) ESP AJ F REQUEST APPL(BILL.0) ESP AJ CHECK.TIME COMPLETE APPL(BILL.0) ENDDO RUN DAILY RELEASE (C,E) ENDJOB JOB C REQUEST RUN DAILY RELEASE D ENDJOB JOB D REQUEST RUN DAILY ENDJOB JOB E REQUEST RUN DAILY RELEASE F ENDJOB JOB F REQUEST RUN DAILY ENDJOB
195

Example: Completing an Application based on an incomplete task
In this example, a task called KEYPUNCH.DATA must complete by 6 p.m. Otherwise, ESP completes the Application. Visually, the job dependencies look like this:
KEYPUNCH.DATA
(task)
CHECK.TIME
(task)
NEXTJOB
(job)
Set up your Application as follows:

APPL KEYDATA JCLLIB SYS1.JCL JOB KEYPUNCH.DATA TASK RUN WORKDAYS RELEASE CHECK.TIME ENDJOB JOB CHECK.TIME TASK ABANDON DEPENDENCIES 6PM RUN WORKDAYS IF ESPAHH GE 18 THEN ESP AJ ALL COMPLETE APPL(KEYDATA.%ESPAPGEN) ELSE ESP AJ CHECK.TIME COMPLETE APPL(KEYDATA.%ESPAPGEN) RELEASE NEXTJOB ENDJOB JOB NEXTJOB RUN WORKDAYS ENDJOB
196

Example: Completing an Application based on an incomplete task, continued
ESP produces different results based on time: If KEYPUNCH.DATA is not complete by 6 p.m., ESP drops the time dependency on the CHECK.TIME task, checks the time, and completes the Application. If KEYPUNCH.DATA is complete prior to 6 p.m., ESP processes the CHECK.TIME task, checks the time, and completes itself. NEXTJOB is now ready to run and ESP will submit it. Another approach to this example involves using Alert processing when a link or task becomes overdue. Refer to Job Monitoring and Alert Processing on page 95 for more information. In this example, each of two tasks must complete by a certain time. Otherwise, Example: Sending a ESP completes the task and sends a message. message based on an incomplete Visually, the job relationships look like this: task
DC1.RECEIVED DC1.RECEIVED
DC2.RECEIVED DC2.RECEIVED
DC1.MESSAGE DC1.MESSAGE
DC2.MESSAGE DC2.MESSAGE
FIRSTJOB FIRSTJOB
197

Example: Sending a message based on an incomplete task, continued

JOB DC1.RECEIVED TASK RUN WORKDAYS RELEASE DC1.MESSAGE ENDJOB JOB DC1.MESSAGE LINK PROCESS ABANDON DEPENDENCIES 6AM RUN WORKDAYS IF ESPAHH GE 06 THEN DO ESP AJ DC1.RECEIVED COMPLETE APPL(THISAPPL.%ESPAPGEN) SEND NO DATA FOR DISTRIBUTION CENTRE 1 USER(BOSS) ENDDO RELEASE FIRSTJOB ENDJOB JOB DC2.RECEIVED TASK RUN WORKDAYS RELEASE DC2.MESSAGE ENDJOB JOB DC2.MESSAGE LINK PROCESS ABANDON DEPENDENCIES 7AM RUN WORKDAYS IF ESPAHH GE 07 THEN DO ESP AJ DC2.RECEIVED COMPLETE APPL(THISAPPL.%ESPAPGEN) SEND NO DATA FOR DISTRIBUTION CENTRE 2 USER(BOSS) ENDDO RELEASE FIRSTJOB ENDJOB JOB FIRSTJOB RUN WORKDAYS ENDJOB
The cut-off time is 6 a.m. for the DC1.RECEIVED task and 7 a.m. for the DC2.RECEIVED task. If a task has not been marked complete by its cut-off time, ESP uses a corresponding link to complete the task and send a message.
198

Example: Dropping dependencies based on time
You can instruct ESP to drop one or more dependencies based on time. In this example, job C waits for job A and job B. At 8 p.m., ESP drops job Cs dependency on job A. Visually, the dependencies look like this:
AA
CUT-OFF CUT-OFF 8PM 8PM
BB
CC

APPL ABC JCLLIB CYBBP01.TESTJOBS.CNTL JOB A RUN DAILY RELEASE C ENDJOB JOB B RUN DAILY RELEASE C ENDJOB JOB C RUN DAILY ENDJOB JOB DROP.A LINK PROCESS DELAYSUB 8PM ESPNOMSG AJ C DROPDEP(A) APPL(ABC.0) RUN DAILY ENDJOB
199

Example: Bypassing a subApplication that does not start by a specific time
You can instruct ESP to take action if a subApplication has not started by a particular time. In this example a subApplication must start processing by 11 a.m. Otherwise, ESP bypasses the subApplication. Visually, the job relationships look like this:
B
SUBAPPL LOWPRIO
CHECK.STATUS
200

Example: Bypassing a subApplication that does not start by a specific time, continued

APPL TOOLATE JCLLIB CYBBP01.ESP.DEMO.JCL JOB A RUN DAILY RELEASE B ENDJOB JOB B SUBAPPL LOWPRIO ESP AJ CHECK.STATUS COMPLETE APPL(TOOLATE.%ESPAPGEN) RUN DAILY RELEASE C ENDJOB JOB C SUBAPPL LOWPRIO RUN DAILY ENDJOB JOB CHECK.STATUS LINK PROCESS DELAYSUB 11am RUN DAILY ESP AJ LOWPRIO BYPASS APPL(TOOLATE.%ESPAPGEN) ENDJOB
Job B is the first job in the subApplication. ESP produces different results based on whether or not job B has been submitted by 11 a.m.: If job B is submitted by 11 a.m., ESP marks the CHECK.STATUS link complete. If job B is not submitted by 11 a.m., ESP processes the CHECK.STATUS link and bypasses the subApplication.
201
Setting Up Step-Level Dependencies

About step-level dependencies
You can set up a dependency between one job and a specific step in another job. This allows you to streamline processing and run jobs concurrently. This is useful when you have a long running job that does not need to complete before releasing the next job. You can instruct ESP to monitor a job and trigger an Event when a job completes a certain processing step. For more information on job monitoring, refer to Job Monitoring and Alert Processing on page 95. To set up a step-level dependency, you will need to: Define a task in an Application as a predecessor to the job waiting for the step to complete. Use step-level monitoring to monitor the predecessor job. Check the step name and completion code. Post the task complete to release the successor, if the step completion code is acceptable. The following example illustrates this technique.
Example: Steplevel dependencies
This example shows you how to release job B after STEP0010 in job A completes successfully. 1. Set up a task as a predecessor to job B. 2. Define an ESP Procedure to complete the task if STEP0010 of job A completes successfully. 3. Define a step level monitor Event for job A to invoke this ESP Procedure. Visually, the dependencies look like this:
Step end monitor Event
(Event)
A.STEP0010
(task)
B
(job)
202
Setting Up Step-Level Dependencies, continued

Example: Step-level dependencies, continued
The Application looks like this:

APPL ABC JCLLIB SYS1.JCL JOB A MONITOR CYBER RUN DAILY JOB A.STEP0010 TASK RUN DAILY RELEASE B JOB B RUN DAILY ENDJOB The job monitor Event for Job A looks like this: EVENT ID(CYBER.A_STEPEND) INVOKE CYBER.ESP.PROC(ASTEP) The ESP Procedure invoked by the job monitor Event looks like this: IF MNSTEP=STEP0010 AND MNCMPC=0 THEN ESPNOMSG AJ A.STEP0010 COMPLETE APPL(ABC.0)
203
Setting Up Step-Level Dependencies, continued

Using general procedures
If you need to set up many step-level dependencies, consider using: Symbolic variables in generalized ESP Procedures Standardized task names (e.g. jobname.stepname). The following example shows a general ESP Procedure which checks the stepname and completion code for different jobs. When invoked by an Event, ESP: Goes to a label representing the jobname (JUMPTO %MNJOB). Checks the stepname and completion code. Goes to the label COMPLETE to complete the task or exits.
JUMPTO %MNJOB A: IF MNSTEP=STEP0010 AND MNCMPC=0 THEN JUMPTO COMPLETE IF MNSTEP=STEP0050 AND MNCMPC=0 THEN JUMPTO COMPLETE EXIT B: IF MNSTEP=STEP0020 AND MNCMPC=0 THEN JUMPTO COMPLETE EXIT COMPLETE: ESPNOMSG AJ %MNJOB..%MNSTEP COMPLETE APPL(ABC.0)
204
Using Templates Overview

Introduction
A template is an element of CLANG that allows you to specify repetitive commands or statements once, such as those you use to define holidays or jobs. The template allows you to: Simplify the specification of repetitious commands or statements, such as those you use to define holidays or jobs. Use and enforce standards. Reduce maintenance. You can use templates in any areas where CLANG is available. This includes ESP Procedures, Initialization Parameters, and Page mode or Line mode. This chapter describes how to use the template feature and provides examples of using templates to handle various scheduling requirements.
In this chapter
This chapter contains the following topics: Topic Setting Up A Template Starting and Ending the Template Definition Passing Information to a Template Working With Templates Using Templates to Define Holidays Using Templates in Applications See Page 206 207 210 213 216 219
Using Templates
205
Setting Up A Template
About setting up a template
A template consists of a TEMPLATE statement, one or more body statements, and an ENDTEMPL statement. The body statements normally include some symbolic variables to represent data that changes for different uses of the template. You pass information to your template so that ESP can resolve the symbolic variables used within the template. In the following example, the template called PRTJOBS uses one variable called NAME. This represents a job name. You specify a value for this variable when you want to use the template. The first PRTJOBS statement passes USERA to the PRTJOBS template and ESP substitutes this value for %NAME. The second PRTJOBS statement passes USERB to the PRTJOBS template and ESP substitutes this value for %NAME.
TEMPLATE PRTJOBS (1,NAME) JOB %NAME RUN DAILY ENDJOB ENDTEMPL PRTJOBS USERA PRTJOBS USERB
To set up a template, you: 1. Use the TEMPLATE statement to give your template a name and identify parameters you want to pass through the template. 2. Define the statements that you want repeated each time the template is used. These are the body statements. 3. End the template definition with the ENDTEMPL statement. 4. To use a template you have defined, specify the name of the template followed by the parameters you are passing to the template. Once you define a template, it is available for use at any time while the same command environment is active. For example, if you define a template in Page mode, it is available until you exit from Page mode. Or, if you define a template in an ESP Application, the template can be used while the Application is active.
206
Using Templates
Starting and Ending the Template Definition

About template definitions
A TEMPLATE statement starts the template definition. You must give the template a name and identify the parameters (positional, keyword, or keyword(data)) that you are going to pass to the template. Rules for passing information to the template are: Positional parameters must be passed in the order specified. Keywords allow you to pass data, in any ESP recognized format.
Example
In the following example, the name of the template is XMAS and it accepts one positional parameter represented by the variable YEAR:
TEMPLATE XMAS (1,YEAR)
Here is an example of passing data to the above template. ESP substitutes the value 1998 for the variable YEAR within the template:
XMAS 1998
Example
In the following example, the name of the template is PAYJOBS. It accepts one positional parameter, represented by the variable JOBNAME, and a keyword, represented by NEXT():
TEMPLATE PAYJOBS (1,JOBNAME,NEXT())
Here is an example of passing data to the above template. ESP substitutes the following values within the template: PAYROLL1 for the variable NAME; PAYROLL2,PAYROLL3 for the variable NEXT.
PAYJOBS PAYROLL1 NEXT(PAYROLL2,PAYROLL3)
Using variables with your template
Templates use symbolic variables to simplify the specification of repetitive code. You use the same symbol introducer character for these variables that you use for other symbolic variables, with the per cent sign (%) as the default.
Using Templates
207
Starting and Ending the Template Definition, continued

Using variables with your template, continued
Variables in your template may be used in other places in your ESP Procedure. You can identify either local or global variables on your TEMPLATE statement using the following keywords: LOCALVARIABLES The variables are used only within the body of the template. This is the default and should normally be used. The variables may be used within, and outside, the body of the template.
GLOBALVARIABLES
Example: Using a In the following example, the name of the template is XMAS, it accepts one template variable positional parameter represented by the variable NAME, and this variable can
be used only within the template:

TEMPLATE PRTJOBS (1,NAME) LOCALVARIABLES
Note: If you want to use a template variable during process mode for an ESP Application (in JCL, for example), you need to assign it to a non-template variable within the scope of a JOB statement, then use the non-template variable. A template variable always resolves to the last value it is assigned in the Procedure.
Defining the body of a template
The body of the template consists of the statements you want repeated each time the template is used. It may include ESP commands, CLANG, job definitions, and other ESP code. ESP performs symbolic variable substitution during template processing.
208
Using Templates
Starting and Ending the Template Definition, continued

Example: A job that runs daily
The following statements define a job that runs daily. The name of the job is represented by the symbolic variable NAME. ESP substitutes the value of this variable during template processing based on information you pass to the template:
JOB %NAME RUN DAILY ENDJOB
Example: Ending Use the ENDTEMPL statement to end the template definition. the template definition
The following statement ends a template definition:

ENDTEMPL
Using Templates
209
Passing Information to a Template

About passing information to a template
After you define a template, you can use it. To use a template, specify the name of the template followed by the parameters you are passing to the template. The information you pass must correspond to the format identified on the TEMPLATE statement. In the following example, the data USERA is passed to the template called PRTJOBS. ESP substitutes the value USERA for the symbolic variable %NAME within the template.
TEMPLATE PRTJOBS (1,NAME) . . . ENDTEMPL PRTJOBS USERA
Example: Passing data
Example: Three positional parameters
In the following example, the ANYHOL template accepts three positional parameters: NAME, DATE and YEAR. The parameters may not contain blanks, or other separators, and must be be passed to the template in the order specified. %NAME resolves to XMAS, %DATE resolves to DEC25, and %YEAR resolves to 1998:
TEMPLATE ANYHOL (3,NAME,DATE,YEAR) . . . ENDTEMPL ANYHOL XMAS DEC25 1998
Example: One positional parameter
In the following example, the ANYHOL template accepts one positional parameter called NAME, followed by a DATE() parameter. Whatever data you pass with DATE(), ESP resolves to %DATE. The DATE() data may contain any characters. %NAME resolves to XMAS and %DATE resolves to DEC 25,1998 , in this example:
210
Using Templates
Passing Information to a Template, continued

Example: One positional parameter, continued
TEMPLATE ANYHOL (1,NAME,DATE()) . . . ENDTEMPL ANYHOL XMAS DATE(DEC 25,1998)
Example: Checking system activity
This example checks if different job names are active on the current system and sends a message indicating the status. Without using a template, you need to repeat the code for each job name you want to check. The code is the same with the exception of the job name:
IF ACTIVE(CICS1066) THEN + SEND CICS1066 IS ACTIVE U(FRED) ELSE SEND CICS1066 IS NOT ACTIVE U(FRED) IF ACTIVE(CICS1215) THEN + SEND CICS1215 IS ACTIVE U(FRED) ELSE SEND CICS1215 IS NOT ACTIVE U(FRED) IF ACTIVE(CICS1492) THEN + SEND CICS1492 IS ACTIVE U(FRED) ELSE SEND CICS1492 IS NOT ACTIVE U(FRED) IF ACTIVE(IMSPROD) THEN + SEND IMSPROD IS ACTIVE U(FRED) ELSE SEND IMSPROD IS NOT ACTIVE U(FRED)
Using Templates
211
Passing Information to a Template, continued

Example: Checking system activity, continued
You can use a template to define the common code. In this example, a template (called STATUS) uses one positional parameter for the job name. You pass different job names through the template by specifying the template name and the job name. The job name is represented by a symbolic variable, %JOBNAME:
TEMPLATE STATUS (1,JOBNAME) IF ACTIVE(%JOBNAME) THEN + SEND %JOBNAME IS ACTIVE U(FRED) ELSE SEND %JOBNAME IS NOT ACTIVE U(FRED) ENDTEMPL STATUS STATUS STATUS STATUS CICS1066 CICS1215 CICS1492 IMSPROD
212
Using Templates
Working With Templates

About working with templates
This topic describes how to: Invoke templates. Use multiple templates. Change template definitions. You can store template definitions in a separate data set/member, if you want. Use an INVOKE statement, in your Event or ESP Procedure, to invoke your templates. In the following example, the INVOKE statement is used to invoke a template member:
APPL AC JCLLIB CYBER.JCLLIB.CNTL INVOKE CYBER.PROCLIB.CNTL(ACPAY) ACPAY ACTEST1 ACPAY ACTEST2
Invoking templates
Using Templates
213
Working With Templates, continued

Using multiple templates
You can define more than one template in an ESP Procedure. The following Procedure contains two templates, ACPAY and ACREC.
APPL AC JCLLIB CYBER.JCLLIB.CNTL TEMPLATE ACPAY (1,JOBNAME) JOB %JOBNAME RUN DAILY SUBAPPL ACCTPAY ENDJOB ENDTEMPL TEMPLATE ACREC (1,JOBNAME,NEXT()) JOB %JOBNAME IF NEXT NE THEN RELEASE (%NEXT) SUBAPPL ACCREC ENDJOB ENDTEMPL ACPAY ACTEST1 ACPAY ACTEST2 ACREC ARTEST1 NEXT(ARTEST2) ACREC ARTEST2
214
Using Templates
Working With Templates, continued

Changing templates
By using a template, you can make changes easily. Instead of making a change in different places, you need change only your template. The following examples show different changes for a template called RPT. Each change affects all jobs that use this template.
Example: Adding In this example, a SUBAPPL statement is added: a SUBAPPL statement TEMPLATE RPT (1,JOBNAME,FREQ(WORKDAYS))
JOB %JOBNAME RUN %FREQ SUBAPPL FINRPT ENDJOB ENDTEMPL
Example: Adding In this example, a NORUN statement is added: a NORUN statement TEMPLATE RPT (1,JOBNAME,FREQ(WORKDAYS))
JOB %JOBNAME RUN %FREQ NORUN FIRST WORKDAY OF MONTH SUBAPPL FINRPT ENDJOB ENDTEMPL
Example: Adding In this example, a RUN statement is added: a RUN Statement

TEMPLATE RPT (1,JOBNAME,FREQ(WORKDAYS)) JOB %JOBNAME RUN %FREQ RUN FIRST SATURDAY OF JULY NORUN FIRST WORKDAY OF MONTH SUBAPPL FINRPT ENDJOB ENDTEMPL
Using Templates
215
Using Templates to Define Holidays

About defining holidays
This topic contains some examples of defining holidays to illustrate some of the techniques you can use with templates. This example uses a template to define a static holiday, called CHRISTMAS, for six years. The DEFHOL command defines a holiday for a particular date. Use a template in an ESP Procedure to specify the DEFHOL command and supply the template with different years. In the following example: The name of the template is XMAS and it accepts one positional parameter called 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.
TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START(DEC 25,%YEAR) + FOR(24) CAL(SYSTEM) ENDTEMPL XMAS XMAS XMAS XMAS XMAS XMAS 1998 1999 2000 2001 2002 2003
Example: Defining a static holiday - Part 1
216
Using Templates
Using Templates to Define Holidays, continued

Example: Defining a static holiday - Part 1, continued
Set up an Event to invoke this ESP Procedure and trigger it manually to define your holidays. ESP generates the following commands:
ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) ESP DEFHOL CHRISTMAS START(DEC FOR(24) CAL(SYSTEM) 25,1998) + 25,1999) + 25,2000) + 25,2001) + 25,2002) + 25,2003) +
Example: Defining a static holiday - Part 2
The following example uses REXX to pass information to the template:

TEMPLATE XMAS (1,YEAR) ESP DEFHOL CHRISTMAS START(DEC 25,%YEAR)+ FOR(24) CAL(SYSTEM) ENDTEMPL REXXON DO I=1998 TO 2003 XMAS I END REXXOFF
Using Templates
217
Using Templates to Define Holidays, continued

Example: Defining any holiday using a standard format
This example uses a template for any 24-hour holiday. The template accepts the name of the holiday, the date in mmmdd format (e.g. DEC25), and the year. In this example: The name of the template is ANYHOL and it accepts three positional parameters represented by the variables NAME, DATE and YEAR. These parameters must be passed in the order specified. The body of the template consists of one statement that defines %NAME as a 24-hour holiday, on the %DATE and %YEAR you specify, in the SYSTEM calendar. The ENDTEMPL statement ends the template definition. The template ANYHOL is used with two holidays. The first ANYHOL statement passes the following variables to the template: XMAS for NAME, DEC25 for DATE, and 1998 for YEAR. The second ANYHOL statement passes the following variables: NEW_YEARS for NAME, JAN1 for DATE, and 1999 for YEAR.
TEMPLATE ANYHOL (3,NAME,DATE,YEAR) ESP DEFHOL %NAME START(%DATE %YEAR) + FOR(24) CAL(SYSTEM) ENDTEMPL ANYHOL XMAS DEC25 1998 ANYHOL NEW_YEARS JAN1 1999
This example uses a template for any 24-hour holiday and accepts the date in Example: Defining any any ESP format. holiday using different formats The template takes one positional parameter for the name of the holiday and a date specified as a keyword(value) parameter, represented by DATE(). Whatever data you pass with DATE(), ESP substitutes for %DATE. This allows you to pass the date in any format that ESP recognizes.
TEMPLATE ANYHOL (1,NAME,DATE()) ESP DEFHOL %NAME START(%DATE) FOR(24) CAL(SYSTEM) ENDTEMPL ANYHOL XMAS DATE(DEC 25,1998) ANYHOL NEW_YEARS DATE(JAN 1,1999)
218
Using Templates
Using Templates in Applications

About using templates in Applications
This topic contains some examples of using templates in ESP Applications. It illustrates some of the techniques you can use with templates.
Example: Defining similar jobs - no relationships
In this example, an Application contains a number of print jobs. These jobs: Run daily. Belong to a subApplication called PRTJOBS. Run independently of each other. 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 use a template as follows: The name of the template is PRTJOBS. It accepts one positional parameter for the name of each job. The template contains details for the print job, such as SUBAPPL PRTJOBS and RUN DAILY. ENDTEMPL identifies the end of the template. The template is used for jobs USERA, USERB, ...,USERD.
Using Templates
219
Using Templates in Applications, continued

Example: Defining similar jobs - no relationships, continued
APPL PAYROLL JCLLIB CYB.JOBS.CNTL TEMPLATE PRTJOBS (1,NAME) JOB %NAME SUBAPPL PRTJOBS RUN DAILY ENDJOB ENDTEMPL PRTJOBS PRTJOBS PRTJOBS PRTJOBS USERA USERB USERC USERD
220
Using Templates

Example: Defining similar jobs with relationships
In this example, an ESP Application contains a number of payroll jobs. These jobs: Run daily. Have a job tag of PJOB. May relate to other jobs. The following is a sample definition of this Application:
APPL PAYROLL JCLLIB CYBER.JCLLIB.CNTL JOB PAYROLL1 RUN DAILY TAG PJOB RELEASE (PAYROLL2,PAYROLL3) ENDJOB JOB PAYROLL2 RUN DAILY TAG PJOB RELEASE PAYROLL4 ENDJOB JOB PAYROLL3 RUN DAILY TAG PJOB RELEASE PAYROLL4 ENDJOB JOB PAYROLL4 RUN DAILY TAG PJOB RELEASE PAYROLL5 ENDJOB JOB PAYROLL5 RUN DAILY TAG PJOB ENDJOB
Using Templates
221

Part 1 - Using a template
Because of the similarity of the jobs, you can use a template as follows: The name of the template is PAY. It accepts one positional parameter, JOBNAME, for the name of each job, followed by a keyword (parameter), NEXT(), that represents successor jobs. The template contains details for the payroll job, such as RUN DAILY and TAG PJOB. An IF statement handles job successor information. Since a job may not have successors, the IF statement checks to see if the NEXT parameter is not blank and generates a RELEASE statement. ENDTEMPL identifies the end of the template. The template is used by passing a job name as the first parameter and optional successor information using the NEXT() parameter.
APPL PAYROLL JCLLIB CYBER.JCLLIB.CNTL TEMPLATE PAY (1,JOBNAME,NEXT()) JOB %JOBNAME RUN DAILY TAG PJOB IF NEXT NE THEN RELEASE (%NEXT) ENDJOB ENDTEMPL PAY PAY PAY PAY PAY PAYROLL1 PAYROLL2 PAYROLL3 PAYROLL4 PAYROLL5 NEXT(PAYROLL2,PAYROLL3) NEXT(PAYROLL4) NEXT(PAYROLL4) NEXT(PAYROLL5)
Part 2 Modifying the TEMPLATE statement
This example modifies the TEMPLATE statement to include the frequency as FREQ(DAILY). The template now uses RUN %FREQ to identify a jobs run frequency. Part 3 of this example shows you how you can override this frequency for specific jobs.
APPL PAYROLL JCLLIB CYBER.JCLLIB.CNTL
222
Using Templates

Part 2 - Modifying the TEMPLATE statement, continued
TEMPLATE PAY (1,JOBNAME,FREQ(DAILY),NEXT()) JOB %JOBNAME RUN %FREQ TAG PJOB IF NEXT NE THEN RELEASE (%NEXT) ENDJOB ENDTEMPL PAY PAY PAY PAY PAY PAYROLL1 PAYROLL2 PAYROLL3 PAYROLL4 PAYROLL5 NEXT(PAYROLL2,PAYROLL3) NEXT(PAYROLL4) NEXT(PAYROLL4) NEXT(PAYROLL5)
Part 3 Overriding information
This example shows you how to handle different run frequencies. If the jobs within the Application do not have the same frequency: 1. Set a default run frequency of DAILY in the TEMPLATE statement. 2. Use an IF statement within the body of the template to override the default frequency when required. This allows you to override the frequency when you pass jobs through the template by using the FREQ() parameter. If you do not specify FREQ() for a job that uses the template, ESP uses the default frequency. In this example, all jobs have a frequency of DAILY except for PAYROLL3. This job has a frequency of WEEKDAYS, identified by FREQ(WEEKDAYS).
APPL PAYROLL JCLLIB CYBER.JCLLIB.CNTL TEMPLATE PAY (1,JOBNAME,FREQ(DAILY),NEXT()) JOB %JOBNAME IF FREQ NE THEN RUN %FREQ TAG PJOB IF NEXT NE THEN RELEASE (%NEXT) ENDJOB ENDTEMPL
Using Templates
223

Part 3 - Overriding information, continued
PAY PAY PAY PAY PAY PAYROLL1 PAYROLL2 PAYROLL3 PAYROLL4 PAYROLL5 NEXT(PAYROLL2,PAYROLL3) NEXT(PAYROLL4) FREQ(WEEKDAYS) NEXT(PAYROLL4) NEXT(PAYROLL5)
Example: Part 1 Using subApplications
A template for an ESP Application is not restricted to a single job name. In this example, a template defines a group of jobs. The same group of jobs (PAYA#, PAYB# and PAYC#) runs for different division #s. Each group of jobs is defined to a subApplication. The template, named DIVJOBS, uses one positional parameter for a division number. This is used as the last four characters of each job name and as the last four characters of the subApplication name.
APPL CYBJOBS JCLLIB CYB.JOBS.CNTL TEMPLATE DIVJOBS (1,NUM) SUBAPPL DIV%NUM WAIT JOB PAYA%NUM RUN DAILY RELEASE PAYB%NUM ENDJOB JOB PAYB%NUM RUN WORKDAYS RELEASE PAYC%NUM ENDJOB JOB PAYC%NUM RUN DAILY ENDJOB ENDTEMPL DIVJOBS 1234 DIVJOBS 9876
This results in the following definitions: Jobs PAYA1234, PAYB1234, and PAYC1234 in the DIV1234 subApplication. Jobs PAYA9876, PAYB9876, and PAYC9876 in the DIV9876 subApplication.
224
Using Templates

Example: Part 2 If you want to pass the division number to JCL, you need to use another Passing variables symbolic variable within the scope of the JOB statement. Otherwise, the to JCL
division number always resolves to the last value it was assigned in the Procedure (i.e. 9876 in this example).
In this example, the symbolic variable called DIVISION is assigned the value of NUM within the scope of the PAYA%NUMs JOB statement. During process mode, ESP substitutes the current value of NUM, and passes this value to the JCL it submits for PAYA%NUM.
APPL CYBJOBS JCLLIB CYB.JOBS.CNTL TEMPLATE DIVJOBS (1,NUM) SUBAPPL DIV%NUM WAIT JOB PAYA%NUM RUN DAILY DIVISION=NUM RELEASE PAYB%NUM ENDJOB . . . ENDTEMPL DIVJOBS 1234 DIVJOBS 9876
The following is some sample JCL that uses the %DIVISION parameter:
//PAYA1234 JOB . . . //S1 EXEC PGM=PAYROLL,PARM=%DIVISION //S2 EXEC PGM=PGM2
Using Templates
225

Example: Running an hourly job
In this example, Job ABC needs to run every hour between 8 a.m. and 4 p.m. The job belongs to an ESP Application. To define a job more than once in an Application, you need to qualify each occurrence. This example uses a template to define Job ABC multiple times. The template, called MULTIRUN, takes one parameter representing the number of hours offset from 8 a.m. This offset is used as a job qualifier for uniqueness and as part of the DELAYSUB statement to identify the time dependency relative to 8 a.m. Schedule your Event that invokes this Application prior to 8 a.m.
APPL CYCLE JCLLIB USER01.TESTJOBS.CNTL TEMPLATE MULTIRUN (1,OFFSET) JOB ABC.%OFFSET RUN ANY DELAYSUB 8AM PLUS %OFFSET HOURS ENDJOB ENDTEMPL MULTIRUN MULTIRUN MULTIRUN MULTIRUN MULTIRUN MULTIRUN MULTIRUN MULTIRUN MULTIRUN 0 1 2 3 4 5 6 7 8
This generates the following JOB statements and DELAYSUB times: JOB Statement ABC.0 ABC.1 ABC.2 ABC.3 ABC.4 ABC.5 ABC.6 ABC.7 ABC.8 DELAYSUBTime 8AM PLUS 0 HOURS 8AM PLUS 1 HOURS 8AM PLUS 2 HOURS 8AM PLUS 3 HOURS 8AM PLUS 4 HOURS 8AM PLUS 5 HOURS 8AM PLUS 6 HOURS 8AM PLUS 7 HOURS 8AM PLUS 8 HOURS
226
Using Templates
Advanced Tracking Overview

Introduction
ESPs job tracking facility keeps track of job information in real time. This enables you to monitor information such as the status of a job or the number of queued jobs at any stage in processing. ESP can also track system messages and take action based on those messages. Job monitoring is an additional feature of job tracking that prompts ESP to take certain automatic actions at specified stages of a job. For more information on job monitoring, see Job Monitoring and Alert Processing on page 95. This chapter describes how to: Identify system messages for ESP to intercept and act upon. Define and use manual processing stages (P-Nodes) for jobs. For an introduction to ESPs job tracking facility, see the ESP Users Guide.
In this chapter
This chapter contains the following topics: Topic Tracking System Messages Manipulating the Tracking of Messages Defining Processing Nodes (P-Nodes) Displaying Tracking Information See Page 228 231 233 237
Advanced Tracking
227
Tracking System Messages

About tracking system messages
ESP can intercept and track any system messages as they are written to the JES system messages data set. This happens in real time. Some common system messages ESP can track include: NOT CATLGD IEF142I IEF149I 813-04. Note: The system messages that are intercepted are those that appear in the same job data set as step statistics, and allocation and deallocation messages. These are not the messages which appear in the JES job log, in SYSLOG, or on the operators console. You specify the message identifier, or the portion of the message text, to be tracked and intercepted. A message portion can be searched for in a specific column or column range, if required. Messages can be limited to a specific job or range of jobs. Messages regarding job failure are routed by routing codes, and if it is not apparent within the intercepted message, ESP automatically imbeds the job name into the job failure message for quick reference. After intercepting a message, ESP can take further action such as: Triggering an Event. Cancelling a job. Failing a job with a JCL error or condition code failure. Re-broadcasting the message to a specific terminal or operator as a WTO message. Follow these steps to set up the tracking of system messages: 1 Specify system messages as part of the tracking option on the tracking system. 2 Identify the messages ESP is to track and the action ESP is to take on the tracking system (Master or Slave). Once you have completed these steps, you can display and manipulate system messages. The following topics discuss each of these steps in detail.
Follow-up action
Setting up tracking
228
Advanced Tracking
Tracking System Messages, continued

Step 1: Specify the Tracking Option
As your first step, you must select system messages as a tracking option. There are two methods of telling ESP to track system messages. The first method makes the option a permanent one while the second method applies the option while ESP remains active. Method 1: Check with the person who installed ESP that system messages are a default tracking option at your ESP installation. Method 2: Type the following on the command line on the tracking system:
TRACKOPT SYSMSGS
To identify which system messages ESP intercepts, use the SYSMSGS Step 2: Identify the Messages and command on the tracking system. When you use this command, you can: ESP Action
Specify a message identifier or message text. IEF142I is an example of a message identifier. Optionally specify a unique sequence identifier that is four characters long. When you specify this identifier, precede it with the string ID and enclose it in brackets (). This identifier controls the order of search when ESP is tracking system messages. For example, ESP searches ID(000A) before ID(0001). ESP searches the identifiers until it finds a match or reaches the end of the list. If you do not specify an ID, ESP assigns the next available sequence number to the message. Specify the action ESP must perform after intercepting the message. Optionally specify other tracking control parameters, such as route codes, descriptor codes, the names of jobs for which you want to limit the message interception, and the number of interceptions of the system message to occur before ESP takes the action. You must re-enter SYSMSGS commands whenever you need to restart ESP unless they are coded in an ESP initialization parameter data set. ESP only retains these commands if they are initialized when ESP starts. For more information on installation, refer to the ESP Installation Guide and Reference. If your installation has multiple copies of ESP, each copy has its own definitions of the messages it tracks.
Advanced Tracking
229
Tracking System Messages, continued

Example: Using the SYSMSGS command to track system messages
The following examples illustrate several ways of using the SYSMSGS command to track system messages. The first example tells ESP to trigger the Event CYBER.PAYSTEP after intercepting system message IEF142I during processing of job PAYROLL.
SYSMSGS IEF142I NAME(PAYROLL) EVENT(CYBER.PAYSTEP)
Note: When ESP triggers an Event based on system message interception, no information is passed to the Event regarding the job from which the message originated. If you need to use the job name in the Event, for example, you will need to use a unique Event for that job. In the next example ESP: Intercepts a NOT CATLGD message, starting between column 50 and 60 Cancels the job Routes the message to consoles with route code 2 (by default) Highlights the message on the console monitor (descriptor code 2).
SYSMSGS NOT CATLGD COL(50:60) CANCEL DESC(2)
The third example tells ESP to intercept IEC161I messages for job names beginning with UT and issue a warning message after every 99 occurrences.
SYSMSGS IEC161I NAME(UT-) WARN COUNT(99)
230
Advanced Tracking
Manipulating the Tracking of Messages

You can use different commands to list all tracked system messages, turn About manipulating specifications on and off, or clear IDs that have a definition. The applicable tracked messages commands are: LSYSMSG CLRSYSMS SYSMSGS List system messages. Clear system messages. Enable/disable individual system messages.
The following topics describe each of these commands.

LSYSMSGS: Displaying system messages
The LSYSMSGS command is used to display information on all system messages you request ESP to intercept. This command does not have any parameters. Enter the LSYSMSGS command on the command line in Page mode. The display includes all disabled messages as well as enabled messages. Sample output from the LSYSMSGS command is shown below.
lsysmsgs NOT CATLGD ID(000A), COL(50:60), NAME(UT-), IGNORE IEF142I ID(0001), NAME(PAYROLL), EVENT(CYBER.PAYSTEP) NOT CATLGD 2 ID(0002), COL(50:60), DESC(2), CANCEL IEC149I 813-04 ID(0003), NAME(J-), EVENT(CYBER.ERROR)
CLRSYSMS: Clearing system messages
Use the CLRSYSMS command to clear system messages you asked ESP to intercept. You can clear all messages or selective messages. Enter the CLRSYSMS command on the command line in Page mode. To clear all SYSMSGS IDs that have been defined, use the CLRSYSMS command and specify ID(*), as follows:
CLRSYSMS ID(*)
To clear a specific SYSMSGS ID, use the CLRSYSMS command with a specific ID parameter. The following example clears SYSMSGS ID 0010.
CLRSYSMS ID(0010)
Advanced Tracking
231
Manipulating the Tracking of Messages, continued

SYSMSGS: Enabling system messages
Use the SYSMSGS command to turn system message specifications on and off. To turn the SYSMSGS ID specifications on after someone has turned it off, enter the SYSMSGS command on the command line in Page mode. Use the following format of the command:
SYSMSGS ENABLE ID(nnnn)
Note: When you first use the SYSMSGS command to identify message interception, it takes effect immediately. Use the ENABLE parameter only after a SYSMSGS ID has been disabled. Below is an example of the above format. It enables system message interception identified by ID(0002).
SYSMSGS ENABLE ID(0002)
Disabling system messages
To turn the SYSMSGS ID specifications off, enter the SYSMSGS command on the command line in Page mode. Use the following format of the command:
SYSMSGS DISABLE ID(nnnn)
Below is an example of the above format. It disables system message interception identified by ID(0010).
SYSMSGS DISABLE ID(0010)
232
Advanced Tracking
Defining Processing Nodes (P-Nodes)

About processing Processing Nodes (also known as P-Nodes) are the processing stages of a job. nodes ESP tracks certain P-Nodes automatically, based on the tracking definitions at
the time of ESP installation. In addition, you can add manual nodes to the phases of processing that follow the output stage.
Automatic PNodes
The following P-Nodes are normally defined during installation. ESP tracks information about job processing, automatically, through the following PNodes: INPUT This represents the input queue. At this stage, ESP tracks information such as the number and names of jobs that are on the input queue, waiting for execution. This represents the execution phase. At this stage, ESP tracks information such as the status of the job, system messages, ABENDed jobs, and so forth. This represents the output queue. At this stage, ESP tracks information such as the number and names of jobs that have executed and are waiting in the output queue for printing or additional phases.
EXEC
OUTPUT
Note: ESP does not have to track a job through the output phase. Your installation may have turned off tracking through output. It is not as common to track this phase as it is to track the input and execution phases.
Manual P-Nodes
After, and only after, a job passes through the output phase, you can identify additional P-Nodes for the job. These processing phases may include bursting of output, distribution, and so on. Note: A job does not need to complete any manual phases for a successor job to run. If you need to set up job dependencies with a manual phase of a job, consider using manual tasks in an ESP Application.
Advanced Tracking
233
Defining Processing Nodes (P-Nodes), continued

Defining a manual P-Node
To add a manual P-Node, you must name and define it. 1 Determine a unique name for the P-Node, using the following criteria: Any combination of alphabetic or numeric characters. 16 characters maximum. Do not use the following reserved names: INPUT, EXEC and OUTPUT. 2 Enter a DEFPN command in Line mode, Page mode, or batch to define the P-Node. If necessary, you can restrict who can post a job from a P-Node. The following example illustrates the process of defining a P-Node with restrictive access. Assume you want a P-Node to represent the distribution phase of output. However, only authorized users are to enter the POST command at the end of the distribution phase. Only the following users can enter the POST command: Users at system console 03. Users with ESP user IDs beginning with SCH. The P-Node definition, for this example, looks like this:
DEFPN DISTRIB USERS(SYSCON03,SCH-)
Example: Defining a PNode with restrictive access
Once you have defined the P-Node name, the authorized users can simply type the POST command to signal the end of the distribution phase of output for a job.
Using a P-Node as a job requirement
To indicate the specific P-Nodes through which a job must pass, you must enter the P-Node as part of a job definition or tracking model. The following example uses the PNODES statement in an ESP Procedure to indicate a P-Node requirement. Job MYJOB must be posted through the DISTRIB P-Node.
JOB MYJOB PNODES DISTRIB RUN DAILY ENDJOB
234
Advanced Tracking

Using a P-Node as a job requirement, continued
This example defines tracking model DISTJOBS and specifies that any job using this model must be posted through one manual P-Node called DISTRIB.
DEFTM DISTJOBS PNODE(DISTRIB)
Posting a P-Node ESP automatically recognizes the completion of input, execution and output
phases of a job. However, it cannot tell when a job reaches a manual P-Node or completes processing at a manual P-Node. For example, whenever this type of job runs, an operator must manually specify that processing is complete at a manual P-Node. To specify that processing is complete, enter the POST command. Specify the name of the job and the P-Node. The following example posts MYJOB from the DISTRIB P-Node.
POST MYJOB PNODE(DISTRIB)
You can enter the above command at any of the following locations: from a system console, within a batch job, or during a TSO session. Here is how ESP interprets the POST command: 1 ESP receives the POST command and marks the job as complete. 2 The posting of a P-Node signals ESP to process the job through to the next P-Node, if other P-Nodes are defined for the job. 3 When ESP posts the last P-Node, it marks the job as complete.
Advanced Tracking
235

Setting a default manual P-Node
If you are using a system console or have access to TSO, you can save time by setting up a default P-Node. Once you set the default P-Node, there is no need to specify the P-Node name every time you enter the POST command. You set the default P-Node using the DFPNODE command. The following example sets a default P-Node of BURST and issues a POST command to post a job from this default P-Node.
DFPNODE BURST POST SPLITJOB
For more information on setting the default P-Node, refer to the ESP Command Reference.
Displaying a PNode definition
Use the LISTPN command to display information about P-Node definitions. Sample output from this command is shown below.
listpn distrib P-NODE - DISTRIB DEFINED AT 10.56 ON WED 4MAY94 BY CYBBP01 USERS - SCH-, SYSCON03 HISTFILE - NONE, OWNER(CYBBP01), SEQUENCE(140)
236
Advanced Tracking
Displaying Tracking Information

About displaying Use the following commands to retrieve information about job tracking tracking queues: information
DQ displays the number of jobs in each active P_Node queue. DN displays the job names and job numbers of jobs in P-Node queues. It can also display due times. The DQ and DN commands display INPUT, EXEC, and OUTPUT as well as manual P-Node queues. You can display individual queues or all queues.
The following example displays the DISTRIB P-Node. Example: The DISTRIB P-Node
dn queue(distrib) DISTRIB: MYJOB 06688
Example: Display of all PNodes
The following example displays all P-Nodes.

dn
INPUT: EXEC: BACKUPI1 05321 ESPAAUX, 07631, INIT 02640, DASL TSO ENC120M 07629, ENC120A ENC111M 07981,
OUTPUT: DISTRIB:
02940, 03412, XDCCDF 03492, ASCHINT 04854, ENCBETAM 05131, MS3270 05288, ESPD 06287, COPILOT 06326, ES43XDC 06447, CYBSV01W 06692, CYBSV01W 06694
MYJOB 06688
02943, ASCHINT 03643, ENCBETAX 05132, ES43 06293, INFODEMO 06693,
Advanced Tracking
237
238
Advanced Tracking
Advanced Forecasting Overview
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 is scheduling. Modeling takes this one step further. ESP combines the schedule with what it knows about the scheduling environment to predict what will happen. You define your environment and then ESP creates a picture showing how a future schedule period looks. Modeling generates reports on jobs, resources and exceptions. Modeling allows ESP to forecast the influence of factors such as number of CPUs, initiators and resources. You can use the data shown on the modeling reports for such things as verifying or adjusting your job scheduling criteria, capacity planning and so on.
In this chapter
This chapter contains the following topics: Topic How Modeling Works Limitations of Modeling Setting Up Your Model Examples A Modeling Example With Sample Reports See Page 240 241 242 257 259
239
How Modeling Works
About using modeling
To use modeling, you must define either actual or forecasted systems configurations to the ESP model processor. The model processor simulates the JES selection process based on priority, class and resource availability. Modeling includes the following operations: 1. The model processor ensures all predecessors are complete before a job becomes eligible for execution. 2. The job waits for an initiator to be available on a CPU. The CPU must have the resources the job requires. 3. An available initiator selects the job based on the priority and class of the job. 4. The model processor simulates an average run time for the job (taken from the history data in the scheduled activity data set). 5. The model processor uses the forecasted elapsed time for the job to compute when the initiator and resources become available again. 6. The above operations are repeated for each job you schedule within the model period.
What modeling can forecast
With modeling you can forecast various workload factors. Use modeling to: Forecast the effects of defining too few (or too many) initiators. For example, if there are too few initiators in the same class as a job, JES waits before it can initiate the job. You can also forecast the effects of initiator class changes. Determine the impact of changes to a typical schedule. For example, if you add a new ESP Application, you can determine the projected end time for the jobs in the Application and how this Application will affect other Applications. Uncover potential resource bottlenecks or shortages in resources such as tape drives or sort work space. Examine how much of the system is in use at various points in time. Assist you in capacity planning. For example, you can prevent processing delays due to shortages in DASD or tape drives.
240
Limitations of Modeling
About limitations The data that ESP modeling produces is only as valid as the data you enter into of modeling the processor. Therefore, the models accuracy is dependent on how well the
input data reflects the actual environment for your jobs. When modeling you must make adjustments to accommodate for additional real life factors. Some of the real life factors that modeling cannot take into account are: Recent changes made to JCL. For example, modeling determines elapsed run time according to past history. Other on demand and non-ESP submitted jobs that can affect the forecasted initiator and the availability of resources. Unavailability of some of the resources due to hardware problems.
241
Setting Up Your Model
How to set up your model
Follow these steps to set up your model: Step 1 2 3 4 5 6 7 Action Generate the Scheduled Activity data set. See page 243. Activate the Model Processor. See page 244. Define the model. See page 246. Define your environment. See page 247. Define your report. See page 251. Close the definition and generate the model. See page 255. Examine the model reports. See page 256.
242
Generating the Scheduled Activity Data Set
How to generate a scheduled activity set
Generate a scheduled activity data set that includes all forecasted jobs scheduled to run during a specific time frame. You can use this time frame as your modeling period, or you can request a modeling period covering a smaller window of time. The modeling period must fall within the total time frame of the scheduled activity data set. For example, if the generated data set contains information for a week, the modeling period might cover only a twenty-four hour period during that week. A sample batch job to generate a scheduled activity data set is shown below. The time frame falls between 6 a.m. today and 6 a.m. tomorrow:
//SADJOB1 JOB CYB3000,BP,CLASS=A,MSGCLASS=S, // NOTIFY=CYBBP01,REGION=4M //STEP0010 EXEC ESP,PARM=SAR //SYSPRINT DD SYSOUT=* //SYSIN DD * SADGEN DATASET(ESP.SAD.DATA) FROM(6AM TODAY) TO(6AM TOMORROW)
For more information on generating a scheduled activity data set, refer to the ESP Users Guide.
Bypassing information
You can use the ESPSADG variable in an Application to affect SADGEN processing. This variable is set to 1 during SADGEN processing, otherwise it is set to 0. The following code ignores the MICH31 job definition only during SADGEN processing.
IF ESPSADG=0 THEN DO JOB MICH31 EXTERNAL APPLID(BILLING) RUN WORKDAYS RELEASE MICH32 ENDJOB ENDDO
This may be required when you are modeling Applications from one group that have dependencies in another group that is not being modeled.
243
Activating the Model Processor
How to activate the model processor
Use Line mode, Page mode, or a batch job to activate the model processor. As an alternative, you can define the model in a data set and then use the LOAD command to load the data set. You cannot activate the model processor through ISPF panels or through an ESP Procedure. Activate the model definition processor by typing the MODEL command, using the format shown below. The model processor updates the projected start and end times for jobs in the SAD file. MODEL dsname START(schedule) A detailed explanation of the above syntax follows: MODEL dsname START schedule Invokes the model definition mode. Name of the scheduled activity data set containing scheduled jobs for model period. Keyword indicating start of model period. Time and date of model period, in valid schedule format. If times and dates are missing, the model period starts now and ends twelve hours after starting.
For more information on using the MODEL command, refer to the ESP Command Reference. In addition to invoking the model processor, the following statement specifies that the model period falls between 6 a.m. today and 6 a.m. tomorrow:
MODEL ESP.SAD.DATA START(6AM TODAY ENDING 6AM TOMORROW)
You are now ready to define your modeling environment, using appropriate commands (see step 3 to define the model).
244
Activating the Model Processor, continued
Using a batch job When you are familiar with modeling commands and keywords, you may want
to use a batch job to activate the model processor. To activate the model processor using batch: 1. Invoke ESP from a batch job. 2. Insert the MODEL command to activate the model processor (see How to activate the model processor on page 244). A sample step from a batch job that invokes the model processor is shown below.
//STEP0020 EXEC PGM=ESP,REGION=4M //SYSPRINT DD SYSOUT=* //MODEL1 DD SYSOUT=S //SYSIN DD * DEFPRINT XY1 DDNAME(MODEL1) MODEL ESP.SAD.DATA + START(6AM TODAY ENDING 6AM TOMORROW) . . .
You are now ready to define your model, using appropriate commands (see step 3 to define the model).
245
Defining the Model
How to define the To specify the modeling environment, insert model definition commands or model ESP Procedure statements. These include:
Environment definition commands. ESP Procedural language statements, known as CLANG statements. These are optional. Report definition commands.
246
Defining Your Environment
About your environment
This topic describes those aspects of the environment you can define for a model.
Defining CPUs
A maximum of eight CPUs can exist for each model. The approach to identify CPUs is: Define the maximum number of initiators across all CPUs. Specify the CPU when you manipulate initiators. Specify the CPU when you manipulate resources. The next two topics describe how you identify and manipulate initiators and resources.
Defining initiators
You must use the MAXINITS command to define the maximum number of initiators for the model. This should include initiators across all CPUs. A maximum of 999 initiators can exist for each model. You manipulate initiators in your model process similar to the way you manipulate initiators using JES. Initially the maximum number of initiators you specify on the MAXINITS command are in a drained state. At any time during modeling, you can manipulate initiators on any CPU as listed below: Use the INIT START command to start initiators, and specify the initiator class. Initiators can have one or more execution classes. Use the INIT SET command to alter the class of an initiator. Use the INIT STOP command to drain an initiator. This example defines a maximum of 15 initiators. Initiators 1 through 10 are started and assigned to classes A and B; initiators 11 through 15 are started and assigned to class C.
MAXINITS 15 INIT START(1:10) CLASS(A,B) INIT START(11:15) CLASS(C)
247
Defining Your Environment, continued
Defining resources
You can add, delete, and set resources at any stage in the model process by using the RESOURCE command. The example below adds a threshold resource called CICS to all systems and assigns it a value of 1.
RESOURCE CICS 1 ADD THRESHOLD GLOBAL
The RESOURCE statement in an ESP Procedure, or job documentation member, identifies the resource requirements for a job. Your installation may also use default resources for jobs which are defined in the ESP initialization parameter data set. During modeling, ESP uses this information to determine if a job can be scheduled using available resources. For detailed information on using resources, refer to the ESP Users Guide.
Defining other factors
You can define other factors in your model that influence how your system will process jobs. These factors include adjustment factors for execution and CPU time, job priority, and time periods where environmental factors change. The next few topics describe each of these.
Adjustment factor
ESP estimates a jobs execution time and CPU time based on historical data. An adjustment factor alters these estimates. You can adjust the execution time or CPU time for one or more jobs using the ADJUST command. Adjustments can be positive or negative, and are expressed as a percentage. This may be useful when elapsed run times for jobs vary greatly at different times of the year, such as at year-end. This example increases the execution time by 500% of all jobs whose names start with the prefix PAY.
ADJUST EXECTIME(+500) JOBS(PAY-)
248
Priority
A priority level specifies that certain jobs run before other jobs. You can set the default priority for jobs that do not have a priority specified in their JCL using the DEFPRIO command. Priorities can range from 1 to 15, with 15 being the highest. This example sets a default priority of 5.
DEFPRIO 5
Time
A model sub-period can exist within the full model period. You can use the TIME command to set the start time of a model sub-period. This allows you to change environmental factors in the modeling period at specified times. This example sets an initiator class at 01:00 hours.
TIME 01:00 INIT SET(15) CLASS(X)
Using CLANG statements to define models
Use CLANG (the procedural language for ESP) in your model definitions. The IF...THEN syntax of a CLANG statement lets you allow in advance for criteria changes that occur during ESP processing. For example, time, date and environmental factors can change as ESP processes the workload. For more information on CLANG syntax, refer to the ESP Users Guide.
The examples that follow illustrate the use of CLANG statements in two Example1: CLANG defines different model situations. different start-up times for Assume that JES starts twenty class X initiators each morning at 6:00 a.m. initiators However, on Mondays the start-up time for these initiators changes to 8:00 a.m. The model definition statements look like this:
IF TODAY(MONDAY) THEN TIME 08:00 ELSE TIME 06:00 INIT START(1:20) CLASS(X)
249
Example 2: CLANG defines different dates for start-up of initiators
In this example, six extra initiators start up at 12:00 hours on Fridays only. The model definition statements look like this:
IF TODAY(FRIDAY) THEN DO TIME 12:00 INIT START(20:25) CLASS(ABC) ENDDO
250
Defining Your Report
About defining your report
As part of the model definition process, you must define the reports containing the modeling output. You can use ESP commands to: Define report data files to tell ESP where to direct the output. Define report titles, in addition to the default title (this is optional). Select one or more reports.
Defining report data files
Each report you select must have a separate open file to receive model data. Use the DEFPRINT command to define a report file. ESP can direct output to any of the following: A data set A DD file A SYSOUT class. This example routes output for a report with a logical name of XREF to a DD called RPT1.
DEFPRINT XREF DDNAME(RPT1)
After modeling, you must use the ENDPRINT command to close each data file.
Defining report titles
All reports have a default report title.Users can use the TITLE command to add a maximum of two additional titles per report. Use the following commands to define your own report titles: TITLE 1 Specifies a user-defined title on line 1 of the report. TITLE 2 Specifies a user-defined title on line 2 of the report. The following are the formatting requirements for titles: Specify TITLE 1 before TITLE 2. Specify TITLE 2 before the next DEFPRINT command.
251
Defining Your Report, continued
Example: Defining report titles
In this example, two titles are associated with REPORT1. The %CE function centers each title on a line.
DEFPRINT REPORT1 DATASET(ESP.MODEL.REPORT1) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 %CE(DATA CENTER OPERATIONS)
Selecting the reports
Use the MREPORT command to select the reports containing the modeling output, and specify the time range for each report. ESP can produce the following reports: Description
Scheduled Jobs Cross Reference Projected End Time Report Resource Utilization On Systems Resource Utilization By Job Job Exception Report Dueout Exception Report
Report Name
JOB_REPORT_1 JOB_REPORT_2 RESOURCE_REPORT_1 RESOURCE_REPORT_2 EXCEPTION_REPORT_1 EXCEPTION_REPORT_2
Abbreviation
JR1 JR2 RR1 RR2 ER1 ER2
Note: The recommended data width for all reports is 133 with a record format of FBA. This example requests a Scheduled Jobs Cross Reference report (JOB_REPORT_1) for a 24-hour time range.
MREPORT SCHED1 JOB_REPORT_1 FROM(06:00 TODAY UNTIL 06:00 TOMORROW)
Each of the modeling reports is described below.

252
Scheduled jobs cross-reference report
Definition Name: JOB_REPORT_1 (JR1) Description: cross references all jobs scheduled during reporting period. Report shows all jobs, regardless of specified time intervals. Data includes: Estimated start time of job. The CPU on which the job will execute. Predecessors. Successors. Minimum report width: 133.
Projected end time report
Definition Name: JOB_REPORT_2 (JR2) Description: displays projected end times and dates for jobs scheduled during specified time interval. Data includes: Execution due out time (if applicable to job). Flagging of any job that exceeds due out time. Minimum report width: 100.
Resource utilization by system report
Definition Name: RESOURCE_REPORT_1 (RR1) Description: displays resources the systems will use (for one or all CPUs). Data includes: Resource activity on each CPU at specified time intervals. Percentage of CPU in use at specific time intervals (based on past job histories). Minimum report width: 30.
253

Definition Name: RESOURCE_REPORT_2 (RR2) Resource utilization by job Description: displays the resources that all scheduled jobs will use. Report shows all scheduled jobs requiring resources, regardless of specified time intervals. Data includes: Scheduled start time and date for each job. All resources allocated to a job. All resources defined for scheduled jobs. This list includes resource definitions in ESP procedures or job documentation members and default resources. Minimum report width: 80.
Job exception report
Definition Name: EXCEPTION_REPORT_1 (ER1) Description: displays all jobs that ESP cannot schedule during the model period, regardless of time intervals. Data includes: Reasons why ESP cannot schedule jobs. Reasons can include resources, predecessors, initiators and so forth. All jobs that will miss their execution due out time. Minimum report width: 133.
Dueout exception Definition Name: EXCEPTION_REPORT_2 (ER2) report Description: displays scheduled jobs that will miss their execution due out time
during the model period. Data includes: Execution due out time for each job. Projected end times. Time lapse between due out time and projected end time. Minimum report width: 100.
254
Closing Definition Mode and Generating Model
About ending the After you have defined the model (see previous step) enter the ENDMODEL model definition command. This command ends the model definition mode and invokes the
MODEL generation processor. At the end of your model statements, type the following:
ENDMODEL
After you enter the ENDMODEL command enter an ENDPRINT command to close each of the report data files. This example closes the report data file called JR1RPT.
ENDPRINT JRIRPT
255
Examining the Model Reports
About examining When you run your model, ESP will direct the output to your DEFPRINT files. model reports To view examples of reporting output, refer to A Modeling Example With
Sample Reports on page 259.
256
Examples
Example: Setting The following statements create a Scheduled Activity data set, called up a model ESP.SAD.DATA and define a model. The model:
Directs output to a DD name called MODEL1. Contains two user-defined report titles. Specifies the maximum number of initiators as 4. Starts 4 class A initiators. Creates a JR1 report, starting at 6 a.m. today until 6 p.m. tomorrow.
//SADMOD JOB CYB3000,BP,CLASS=A,MSGCLASS=S, // NOTIFY=CYBBP01,REGION=4M //STEP0010 EXEC ESP,PARM=SAR //SYSPRINT DD SYSOUT=* //SYSIN DD * SADGEN DATASET(ESP.SAD.DATA) FROM(6AM TODAY) TO(6AM TOMORROW) /* //STEP0020 EXEC PGM=ESP,REGION=4M //SYSPRINT DD SYSOUT=* //MODEL1 DD SYSOUT=S //SYSIN DD * DEFPRINT XREF DDNAME(MODEL1) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 %CE(PRODUCTION CONTROL - SCHEDULING DEPT.) MODEL ESP.SAD.DATA + START(6AM TODAY ENDING 6AM TOMORROW) MAXINITS 4 INIT START(1:4) CLASS(A) MREPORT XREF JR1 FROM(6AM TODAY ENDING 6AM TOMORROW) ENDMODEL ENDPRINT XREF /* //
257
Examples, continued
Example: Ignoring job classes
The following is a simple example of the modeling commands to create a Scheduled Jobs Cross-Reference Report (JR1). In this example, initiator classes are ignored by specifying NOCLASS on the MODEL command. Although this does not create a true picture of the environment, the initiator activity has no effect on the job relationships in the JR1 report.
MODEL ESP.SAD.DATA + START(6AM TODAY ENDING 6AM TOMORROW) NOCLASS MAXINITS 999 MREPORT XREF JR1 FROM(6AM TODAY ENDING 6AM TOMORROW) ENDMODEL
258
A Modeling Example With Sample Reports
Overview
The following example demonstrates a practical use of modeling. The example shows statements that define the model, followed by the report output generated by the model.
Example: Model definition statements
The following statements define a model that generates all available ESP model reports.
DEFPRINT JR1REP DATASET(CYB1.MLTEST.MREPORT2) TITLE 1 %CE(CYBERMATION INC.) DEFPRINT JR2REP DATASET(CYB1.MLTEST.MREPORT7) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 %RJ(FORWARD TO DEPT. IS900) DEFPRINT RR1REP DATASET(CYB1.MLTEST.MREPORT3) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 %CE(DATA CENTER OPERATIONS) DEFPRINT RR2REP DATASET(CYB1.MLTEST.MREPORT4) TITLE 1 %CE(CYBERMATION INC.) DEFPRINT ER1REP DATASET(CYB1.MLTEST.MREPORT5) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 %CE(PRODUCTION CONTROL - SCHEDULING DEPT.) DEFPRINT ER2REP DATASET(CYB1.MLTEST.MREPORT6) TITLE 1 %CE(CYBERMATION INC.) TITLE 2 ATTN: FRED BLOGGS MODEL CYB1.MLTEST.SADGEN START(00:00 TOMORROW ENDING 24:00 TOMORROW) MAXINITS 15 ADJUST EXECTIME(+500) JOBS(PROD-,PAY300,ACC-,SORT-) INIT START(1:10) CLASS(A,B) RESOURCE SORTWRK 5000 ADD RENEWABLE RESOURCE PERMDASD 10000 ADD DEPLETABLE RESOURCE SCRATCH 200 ADD DEPLETABLE RESOURCE TAPE3480 10 ADD RENEWABLE RESOURCE NITESHFT ADD THRESHOLD RESOURCE CICS ADD THRESHOLD RESOURCE IMS 2 ADD RENEWABLE TIME 01:00 RESOURCE SCRATCH 50 ADD RESOURCE CICS 0 RESOURCE TAPE3480 2 DEL RESOURCE PERMDASD 5000 ADD DEPLETABLE TIME 01:30 RESOURCE CICS ADD THRESHOLD RESOURCE TAPE3420 2 ADD INIT STOP(8:10)
259
A Modeling Example With Sample Reports, continued
Example: Model definition statements, continued
TIME 08:00 RESOURCE DAYSHIFT ADD THRESHOLD RESOURCE TAPE3420 2 ADD RESOURCE SCRATCH 100 ADD RESOURCE NITESHFT 0 INIT START(10,11) CLASS(IMS99) MREPORT JR1REP JR1 FROM(00:00 ENDING 24:00) MREPORT JR2REP JR2 FROM(00:00 ENDING 24:00) MREPORT RR1REP RR1 FROM(00:00 ENDING 09:00) MREPORT RR2REP RR2 FROM(00:00 UNTIL 24:00) MREPORT ER1REP ER1 FROM(00:00 UNTIL MIDNIGHT) MREPORT ER2REP ER2 FROM(00:00 ENDING 24:00) ENDMODEL ENDPRINT JR1REP ENDPRINT JR2REP ENDPRINT RR1REP ENDPRINT RR2REP ENDPRINT ER1REP ENDPRINT ER2REP
Example: Sample The reports ESP generates from the preceding model definition statements reports appear on the next several pages of this chapter.
260
CYBERMATION INC. SCHEDULED JOBS CROSS REFERENCE FROM 00.00 04/21/94 TO 23.59 04/21/94 PAGE 1 SUCCESSORS -------------------------------04/21 DEMO1.RUN5 DEMONT1 DEMONT1 DEMONT1 DEMONT1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SORTJOBS SADNET1 SADNET1 SADNET1 SORTJOBS SORTJOBS SADNET1 SADNET1 SADNET1 PROD PROD PROD PAYROLL PAYROLL PAYROLL PAYROLL PAYROLL 00.45 00.45 00.46 00.46 00.46 00.41 00.41 00.35 04/21 04/21 04/21 04/21 04/21 04/21 04/21 04/21 00.32 00.31 00.30 00.26 04/21 00.26 04/21 00.24 00.22 00.20 04/21 04/21 04/21 0 0 04/21 04/21 04/21 0 0 0 0 0 0 0 0 PAY200 PAY100 PAY100 PROD10 PROD10 SORTJOB1 SORTJOB1 0 0 0 CYBTEST2 CYBTEST1CYBTEST3 CYBTEST2 PROD20, PROD30 PROD40 PROD50 PAY300, PAY400 PAY210 PAY220 PAY310 PAY500 00.20 04/21 0 0 0 0 00.18 04/21 00.15 04/21 00.15 04/21 00.14 04/21 00.13 04/21 00.13 04/21 0 0 0 0 0 0 00.12 04/21 0 00.11 04/21 0 00.10 04/21 0 00.01 04/21 00.01 04/21 00.01 04/21 00.01 04/21 0DEMO1.RUN1 0DEMO1.RUN1 0DEMO1.RUN1 0DEMO1.RUN1 CYBTEST2 CYBTEST1CYBTEST3 CYBTEST2CYBTEST4, CYBTEST3CYBTEST6 CYBTEST3CYBTEST6 CYBTEST4, CYBTEST6 CYBES012 CYBES011CYBJS010 SORTJOB2, SORTJOB3 CYBES012CYBJS108 CYBJS010CYBJS109 CYBJS108 0 DATE 00.00 CPU PREDECESSORS
JOBNAME DEMONT1
JOB QUAL APP NAME NET NAME TIME
-------
-------- -------- -------- ----- ----- --- ----------------------------------
DEMO1
RUN1
DEMO1.RUN2,
DEMO1.RUN3, DEMO1.RUN4,
DEMO1
RUN2
DEMO1
RUN3
DEMO1
RUN4
DEMO1
RUN5
CYBTEST1
CYBTEST2
CYBTEST3
CYBTEST5
CYBTEST4
CYBTEST5
CYBTEST6
CYBTEST5
CYBTEST7
CYBTEST7
CYBES011
CYBES012
SORTJOB1
CYBJS010
CYBJS108
CYBJS109
SORTJOB2
SORTJOB3
CYBTEST1
CYBTEST2
CYBTEST3
PROD10
PROD20
PROD30
PAY100
PAY200
PAY210
PAY300
PAY400
261
PROD40 PAYROLL PROD PROD PROD PROD ACC99 ACC99 ACC99 PROD PAYROLL PAYROLL PAYROLL APPL1 APPL1 12.37 12.38 15.13 NAVRJE 15.16 04/21 0 NAVRJE 15.15 04/21 0 04/21 0 NAV1 NAV2 04/21 0 AA 04/21 0 09.03 04/21 0 CYBTEST1 CC 09.02 04/21 0 01.32 04/21 0 PAY230, PAY310, PAY400 CYBTEST2 01.31 04/21 0 PAY220 01.30 04/21 0 PAY210 01.30 04/21 0 PROD30 PAY230 PAY500 01.11 04/21 0 ACC5000 01.11 04/21 0 ACC5000 01.05 04/21 0 00.53 04/21 0 PROD40 ACC6100, ACC6200 00.53 04/21 0 PROD40 00.53 04/21 0 PROD40 00.53 04/21 0 PROD40 00.52 04/21 0 PAY300 PAY500
PROD
00.47
04/21
PROD20
PROD60,
PROD70,
PROD80, PROD90
PAY310
PROD60
PROD70
PROD80
PROD90
ACC5000
ACC6100
ACC6200
PROD50
PAY220
PAY230
PAY500
CYBTEST1
CYBTEST2
AA
CC
B2
NAVRJE
NAV1
NAVRJE
262
CYBERMATION INC. DATA CENTER OPERATIONS RESOURCE UTILIZATION ON ALL SYSTEMS FROM 00.00 04/21/90 TO 08.59 04/21/90 CICS GLOBAL -------0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 9700 9700 9500 9290 9290 9290 9290 9290 9290 14290 14290 14290 2 1 10000 2 1 10000 2 1 10000 2 1 10000 200 200 200 200 200 200 194 194 194 194 194 194 194 244 244 244 2 1 10000 200 2 1 10000 200 2 1 10000 200 2 1 10000 200 5000 4550 4550 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 5000 2 1 10000 200 4500 2 1 10000 200 4500 2 1 10000 200 5000 2 1 10000 200 5000 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 1 10000 200 5000 0 2 1 10000 200 5000 0 2 1 10000 200 5000 0 2 1 10000 200 5000 0 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 8 4 4 7 10 10 10 8 8 8 2 1 10000 200 5000 0 10 2 1 10000 200 5000 0 10 2 1 10000 200 5000 0 10 2 1 10000 200 5000 0 10 2 1 10000 200 5000 0 10 -------------------------------------------------1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL GLOBAL DAYSHIFT IMS NITESHFT PERMDASD SCRATCH SORTWRK TAPE3420 TAPE3480 PAGE 1
RESOURCE:
% CPU
CPU:
(ALL)
-----
--------
00.00
00.02
00.04
00.06
00.08
00.10
00.12
00.14
00.16
43
00.18
00.20
41
00.22
00.24
00.26
53
00.28
00.30
00.32
00.34
00.36
00.38
00.40
00.42
00.44
00.46
00.48
00.50
00.52
00.54
00.56
00.58
01.00
01.02
01.04
263
01.06 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 0 1 1 13090 234 5000 0 1 1 13090 234 5000 0 1 1 13090 234 5000 0 1 1 13090 234 5000 0 1 1 13090 234 5000 2 2 2 2 2 0 1 1 13090 234 5000 1 0 1 1 13090 234 5000 1 0 1 1 13090 234 5000 2 0 1 1 13090 234 5000 0 8 8 8 8 8 8 8 8 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 13090 234 5000 0 8 0 1 1 14290 234 5000 0 2 0 1 1 14290 234 5000 0 2
14290
234
5000
01.08
01.10
01.12
01.14
01.16
01.18
01.20
01.22
01.24
01.26
01.28
01.30
01.32
01.34
01.36
01.38
01.40
01.42
01.44
264
CYBERMATION INC. RESOURCE UTILIZATION BY JOB FROM 00.00 04/21/90 TO 23.59 04/21/90 DATE --------------------------------------------------------------------00.20 00.26 00.26 00.35 00.41 00.41 00.45 00.45 00.46 00.46 00.47 00.52 01.05 01.11 01.11 01.30 01.30 01.32 04/21 0 04/21 0 1,TAPE3420 400,SORTWRK 04/21 0 1,TAPE3420 04/21 0 600,PERMDASD 04/21 0 600,PERMDASD 04/21 0 04/21 0 1,IMS 6,TAPE3480, 10,SCRATCH 04/21 0 3,TAPE3480 04/21 0 3,TAPE3480, 1,IMS 04/21 0 2,TAPE3480, 210,PERMDASD 04/21 0 1,TAPE3480, 200,PERMDASD 04/21 0 1,TAPE3480, 6,SCRATCH 04/21 0 300,PERMDASD, 1,IMS 04/21 0 200,PERMDASD, 1,CICS 04/21 0 100,PERMDASD, 1,CICS 04/21 0 04/21 0 04/21 0 500,SORTWRK 100,SORTWRK 300,SORTWRK CPU RESOURCES ----- ----- --PAGE 1
JOBNAME SORTJOBS SORTJOBS SORTJOBS PROD PROD PROD PAYROLL PAYROLL PAYROLL PAYROLL PROD PAYROLL ACC99 ACC99 ACC99 PROD PAYROLL PAYROLL
JOB QUAL APP NAME NET NAME TIME
-------- -------- -------- --------
SORTJOB1
SORTJOB2
SORTJOB3
PROD10
PROD20
PROD30
PAY100
PAY200
PAY210
PAY300
PROD40
PAY310
ACC5000
ACC6100
ACC6200
PROD50
PAY220
PAY500
265
CYBERMATION INC. PRODUCTION CONTROL - SCHEDULING DEPT. JOB EXCEPTION REPORT FOR MODELLING PERIOD 00.00 04/21/90 TO 23.59 04/21/90 REASON -------------- ------------------------------------------00.00 00.00 00.00 00.00 00.00 00.35 PAST DUE OUT NOT SCHEDULED NOT SCHEDULED NOT SCHEDULED NOT SCHEDULED NOT SCHEDULED RESOURCES(S) PREDECESSOR(S) REDECESSOR(S) PREDECESSOR(S) REDECESSOR(S) 04/21/90 00.35 DUE 04/21/90 00.53 EARLIPAYROLL 04/21/90 00.45 PAST DUE OUT 04/21/90 00.46 DUE 04/21/90 01.31 EARLIPAYROLL 04/21/90 00.45 PAST DUE OUT 04/21/90 00.49 DUE 04/21/90 01.32 EARLI04/21/90 01.15 NOT SCHEDULED INITIATORCLASS E REQUIREMENTS PAGE 1
JOBNAME DEMONT2 DEMONT2 DEMONT2 DEMONT2 DEMONT2 PROD 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90
JOB QUAL APP NAME NET NAME SCHED DATE/TIME DETAILS
--------
-------- -------- -------- --------------- -------------
DEMO2
EXEC1
5100,SORTWRK
DEMO2
EXEC2
DEMO2.EXEC1
DEMO2
EXEC3
DEMO2.EXEC1
DEMO2
EXEC4
DEMO2.EXEC1
DEMO2
EXEC5
DEMO2.EXEC1
PROD90
OUT OF EXECUTION
EST PROJECTED START TIME
PAY230
OUT OF EXECUTION
PAY500
OUT OF EXECUTION
BKUP900
REQUIRED
266
CYBERMATION INC. PAGE 1
ATTN: FRED BLOGGS DEVIATION 0:23 0:45 0:43
DUEOUT EXCEPTION REPORT FOR MODELLING PERIOD 00.00 04/21/90 TO 23.59 04/21/90
JOBNAME 04/21/90 00.35 04/21/90 00.46 04/21/90 00.49 04/21/90 01.32 04/21/90 01.31 04/21/90 00.53
JOB QUAL APP NAME NET NAME EXECUTION DUEOUT PROJECTED END
-------- -------- -------- -------- ---------------- -------------- ---------
PROD90
PROD
PAY230
PAYROLL
PAY500
PAYROLL
267
CYBERMATION INC. FORWARD TO DEPT. IS900 PAGE 1 EXECUTION DUEOUT 00.01 00.02 00.02 00.02 00.02 00.11 00.12 00.13 00.14 00.14 00.15 00.16 00.18 00.20 00.22 00.24 00.26 SADNET1 SADNET1 SORTJOBS SORTJOBS SADNET1 SADNET1 PROD PAYROLL PAYROLL PROD PROD PAYROLL PAYROLL PAYROLL PROD PAYROLL PROD 00.52 00.53 00.53 00.59 00.47 00.47 00.47 00.47 00.46 00.46 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 00.41 04/21/90 00.33 00.32 00.32 00.32 04/21/90 04/21/90 04/21/90 04/21/90 00.31 04/21/90 00.26 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90 04/21/90
PROJECTED END TIME REPORT FROM 00.00 04/21/90 TO 23.59 04/21/90
JOBNAME DEMONT1 DEMONT1 DEMONT1 DEMONT1 DEMONT1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SADNET1 SORTJOBS
JOB QUAL APP NAME NET NAME PROJECTED END
-------- -------- -------- -------- -------------- ----------------
DEMO1
RUN1
DEMO1
RUN2
DEMO1
RUN3
DEMO1
RUN4
DEMO1
RUN5
CYBTEST1
CYBTEST2
CYBTEST3
CYBTEST4
CYBTEST5
CYBTEST6
CYBTEST7
CYBES011
CYBES012
CYBJS010
CYBJS108
SORTJOB1
CYBJS109
CYBTEST1
SORTJOB2
SORTJOB3
CYBTEST2
CYBTEST3
PROD10
PAY100
PAY200
PROD20
PROD30
PAY210
PAY400
PAY300
PROD40
PAY310
PROD60
268
PROD70 PROD PROD ACC99 ACC99 ACC99 PAYROLL PAYROLL PAYROLL PROD APPL1 APPL1 12.38 12.39 15.14 NAVRJE 15.17 15.18 15.19 04/21/90 04/21/90 04/21/90 15.16 04/21/90 04/21/90 04/21/90 04/21/90 09.04 04/21/90 09.03 04/21/90 01.36 04/21/90 01.33 04/21/90 00.49 04/21/90 ** PAST DUE OUT ** 01.32 04/21/90 00.46 04/21/90 ** PAST DUE OUT ** 01.31 04/21/90 01.17 04/21/90 01.59 04/21/90 01.17 04/21/90 01.11 04/21/90 00.59 04/21/90 00.35 04/21/90 ** PAST DUE OUT ** 00.59 04/21/90
PROD
00.59
04/21/90
PROD80
PROD90
ACC5000
ACC6100
ACC6200
PAY220
PAY230
PAY500
PROD50
CYBTEST1
CYBTEST2
AA
CC
B2
NAVRJE
NAV1
NAVRJE
NAV2
NAVRJE
NAV3
NAVRJE
269
270
Using REXX with ESP Overview

Introduction
ESP is fully compatible with IBMs high level, procedural language called REstructured eXtended eXecutor language (REXX). 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. This chapter describes how REXX interacts with ESP. A working knowledge of the REXX language and familiarity with REXX execs are prerequisites for reading this chapter. For more information on REXX, refer to the appropriate IBM manuals on REXX. This chapter contains the following topics: Topic About Using REXX Adding REXX to ESP Using ESP Commands Within REXX Assigning REXX Variables to ESP Variables Using CLANG Variables With ESP-REXX Entering ESP-REXX in Multiple Fragments Built-In Functions With CLANG Equivalent Commands and Functions With TSO Equivalent Built-In Functions With No CLANG Equivalent Trapping Output From Commands Inserting Adhoc Request Jobs Using REXX to Build Applications Using REXX to Define Special Days Updating a Symbolic Variable Using REXX Execs See Page 272 274 276 277 278 279 280 282 283 289 294 296 300 301 303
In this chapter
Using REXX with ESP
271
About Using REXX

Benefits of using REXX
You can use REXX to enhance the functions of ESP. REXX statements enable ESP to: Perform looping operations. CLANG uses most forms of language construction, except for looping. Looping enables ESP to perform repetitive actions such as: defining statutory holidays generating ESP Application code purging job output building control cards simulating multiple occurrences of an Event. Trap output. For example, ESP can automatically check the status of an ESP Application by issuing a command and then storing the output in variables. Read from a data set. For instance, you can specify dates for special days in a data set, then have ESP read the data set and define special days. Write to a data set. For example, REXX expressions enable ESP to write a new value of a symbol to a data set. REXX expressions work with ESP in either of the following ways: When REXX expressions are added to ESP, ESP will invoke REXX functions. For example, include REXX expressions in: ESP Procedures for such things as defining workload ESP initialization statements to tailor Initialization Parameters to your systems environment command input including Line mode, Page mode, and batch. You can define REXX execs outside of ESP to invoke ESP commands.
Where to insert REXX expressions
272
Using REXX with ESP
About Using REXX, continued

The ESP Procedure environment is not a TSO environment. You cannot use Limitations of using REXX with commands in an ESP Procedure that require a full TSO environment. An ESP example of such a command is ISPEXEC. There are some limitations to the initialization parameters you can use with REXX. The following parameters cannot be used: ACF2EXIT, APPLBUF, APPLFILE, AUDITLOG, AUTHSTR, AUXAS, CKPT, EXHFILE, GMTCHECK, INDEX, ISCOPT, JOBINDEX, MAXLRECL, QTRACE, QUEUE, RESFILE, RUNMODE, SAFCLASS, SCHDFILE, SMFINT, SMFREC, STRACE, SUBSYS, SVC, SYSID, TIMECHK, TIMEZONE, TRAKFILE, USERDEF. Use of the CALL instruction in REXX is limited; you cannot call an external subroutine.
Using REXX with ESP
273
Adding REXX to ESP

Entering REXXON and REXXOFF statements
To add REXX expressions to ESP, you must turn REXX on and off using CLANG. CLANG is always present as the primary command language in ESP. To imbed REXX expressions within ESPs CLANG, use the following process: 1. Insert a REXXON statement to turn on REXX processing. 2. Insert REXX expressions. 3. Insert a REXXOFF statement to turn off REXX processing. When ESP encounters a REXXON statement, it reads the REXX procedural statements until it encounters a REXXOFF statement. It uses these statements to form a REXX in-storage control block (representing an in-storage execution). The following example illustrates how you can invoke REXX from ESP.
REXXON say This is REXX speaking REXXOFF
Using REXX in ESP Applications You can activate REXX processing at either the generation or processing
stages of an ESP Application. (At the generation stage, ESP generates the Application and creates a record in the APPLFILE. In the processing stage, ESP actually processes the Application.) To invoke or suppress REXX processing at either of the above stages of ESP processing, enter the GEN or PROC keywords after the REXXON statement as follows: Type REXXON GEN PROC or REXXON to turn on REXX in the generation and processing stages of an Application. Use these keywords if you are using REXX to create and process an Application. Type REXXON GEN to turn on REXX in the generation stage only. Use this keyword if you are using REXX to create, but not process, an Application. Type REXXON PROC to turn on REXX in the processing stage only. Use this keywords if you are only using REXX during the processing of an Application.
274
Using REXX with ESP
Adding REXX to ESP, continued

Issuing TSO commands
You can issue TSO commands from ESP when you are in a TSO environment. For example, you can type the following commands in ESP Page mode or use the LOAD command to load the commands from a data set. You cannot use these commands in an ESP Procedure.
REXXON address TSO LISTA address TSO LISTDS CYB.ESP.PROCS MEMBERS REXXOFF
Using REXX with ESP
275
Using ESP Commands Within REXX

About using ESP You can specify ESP commands or statements within REXX. When you are commands entering this type of data, you must format the input as follows: within REXX
If the command or statement contains only constants, enclose the entire expression in single or double quotation marks. The following instruction displays an example of this format:
ESP TRIGGER PROD.BACKUPS ADD
If the command or statement contains a REXX variable, use single or double quotation marks before and after the variable. This allows REXX to automatically substitute the value of the variable. The following instruction displays an example of this format:
ESP AJ jobname INSERT APPL(LEFTOVER.0)
If the command or statement contains a CLANG variable, the variable must be converted to a REXX variable using ESPs built-in CLANGVAR function. Refer to Using CLANG Variables With ESP-REXX on page 278 for more information. The following instruction displays an example of this format:
applname=CLANGVAR(%ESPAPPL)
Continuing commands
When you use REXX within ESP, ESP checks the syntax one line at a time. If you need to generate a command longer than one line, use the following approach: Build the command one line at a time. Concatenate each line with the previous line. Use the concatenated string as the command. The example below illustrates this technique. The command is built using a variable called SS.
REXXON SS = IF JOBONQ(ABC) OR SS = SS JOBONQ(DEF) OR SS = SS JOBONQ(XYZ) THEN REEXEC IN(1) SS REXXOFF
276
Using REXX with ESP
Assigning REXX Variables to ESP Variables

About assigning REXX variables
To assign a REXX variable to an existing ESP variable, use these formatting conventions: If the variable is an integer, enclose the ESP variable name and the equal sign (=) in single quotation marks (). An example of this format appears below:
ESPNUM=Filenum
If the variable is a character string, enclose the entire expression in double quotation marks ( ) and enclose the REXX character string within both single and double quotation marks. An example of this format appears below:
ESPNAME= Rexxname
Using REXX with ESP
277
Using CLANG Variables With ESP-REXX

About using CLANG variables
You cannot use CLANG variables directly. The built-in CLANGVAR function converts a CLANG variable into a REXX variable. The example below assigns the value of an ESP built-in variable (%ESPTRDSN) to a REXX variable called dsname.
dsname=CLANGVAR(%ESPTRDSN)
278
Using REXX with ESP
Entering ESP-REXX in Multiple Fragments

About entering ESP-REXX in multiple fragments
You can turn REXX on and off as many times as necessary within ESPs CLANG. However, if you use CLANG variables within REXX, ESP does not automatically pass the CLANG variables from one REXX fragment to the next REXX fragment. To pass along a CLANG variable, you must save the CLANG variable to REXX using the CLANGVAR function. The following example demonstrates a set of statements in which CLANGVAR passes a CLANG variable between two fragments of REXX. In the statements below, the first REXXON-REXXOFF fragment assigns the REXX variable number to the ESP variable called X. In the second REXXON-REXXOFF fragment, the expression number=CLANGVAR(%X) converts the CLANG variable X to a REXX variable.
REXXON X=Number REXXOFF . . . REXXON Number=CLANGVAR(%X) REXXOFF
Example
Using REXX with ESP
279
Built-In Functions With CLANG Equivalent

About built-in functions with CLANG equivalent
ESP provides a number of built-in functions and commands you can use within REXXON-REXXOFF statements. This topic describes each of these functions and commands. They are grouped in the following three areas: Built-in functions with CLANG equivalent. Commands and functions with TSO equivalent. Built-in functions with no CLANG equivalent. The following table lists built-in ESP-REXX functions and identifies the equivalent built-in functions in ESPs CLANG.
Built-in Function TODAY CLANG Equivalent
REXX functions
Description Tests schedule criteria for todays date. Tests schedule criteria for yesterdays date. Tests schedule criteria for tomorrows date. Calculates number of days between now and a particular date in the future. Calculates number of days between now and a particular date in the past. Calculates the number of days (or workdays, months, years, and so on) between two dates. Checks whether a job or address space is active on the current system. Returns a zero (0=false, not active) or the address space identifier (true, active). Checks whether the jobname you specify has been selected in this ESP Procedure or another ESP Procedure invoked by the same Event. ESP returns 1 for true and 0 for false. Investigates JES queues.
TODAY
YESTERDAY YESTERDAY TOMORROW TOMORROW DAYSTO DAYSFROM DAYSBETW DAYS_TO DAYS_FROM DAYS_BETWEEN
ACTIVE
ACTIVE
SELECTED
SELECTED
JOBONQ
JOBONQ
280
Using REXX with ESP
Built-In Functions With CLANG Equivalent, continued

Example: Using IF logic to set symbolics
The following example uses some built-in functions to set the values of symbols. ESP sets the value of the variable SEASON to SUMMER if the current month is June, July, or August. ESP sets the value of the variable TESTHOL to TRUE if yesterday was a holiday.
Example: Using IF logic to set symbolics, continued

REXXON IF TODAY(JUNE JULY AUGUST) THEN SEASON=SUMMER IF YESTERDAY(HOLIDAY) THEN TESTHOL=TRUE ... REXXOFF
For more information on these functions, refer to the ESP Users Guide.
Using REXX with ESP
281
Commands and Functions With TSO Equivalent

About commands The following table lists ESP-REXX functions and commands with TSO and functions equivalents. with TSO equivalent
Command/ Function ALLOCX FREEX TRAPOUT
TSO Equivalent
ALLOC FREE OUTTRAP
Description Allocates a data set. Frees a data set. Puts lines of command output into a series of numbered variables that have the same prefix. These variables save command output and allow REXX to process the output.
Note the following when using the ALLOCX command: There is no support for SYSOUT in the ALLOCX command. You should check the return code from your ALLOCX command before further processing. ALLOCX and FREEX can only be used within an ESP Procedure. If you have trouble freeing your file, you may need to use ESPs UNALLOC command. If you use the ALLOCX command without specifying a filename, ESP stores the system generated ddname as a REXX symbolic variable called ddname. You can use this variable in the EXECIO and FREEX commands. For example:
ALLOCX DA(MY.DATA.SET) SHR ADDRESS MVS EXECIO 1 DISKR ddname (FINIS
282
Using REXX with ESP
Built-In Functions With No CLANG Equivalent

This topic describes the functions available with REXX under ESP where there About built-in functions with no is no equivalent CLANG function. CLANG equivalent
ASCBADDR function
The ASCBADDR function returns the virtual storage address of the address space control block for a job, started task, or TSO user. The result is an eight character hex string. If the address space is not active, the result is a null string. The syntax is ASCBADDR(jobname) , where jobname is the name of the job, started task, or TSO user. The following example sends a message back to your console indicating the virtual storage address of the address space control block for ESPA.
REXXON ascb=ASCBADDR(ESPA) say ascb of ESPA is ascb REXXOFF
Example: Using the ASCBADDR function
Sample output is shown below:

ascb of ESPA is 00FBC700
ASID function
The ASID function returns the address space identifier of a job, started task, or TSO user. The result is a decimal number. ESP returns either the address space identifier of the job, or a 0 if the jobname is not active. Some operator commands require this information. The syntax is ASID(jobname), where jobname is the name of the job, started task, or TSO user.
Using REXX with ESP
283
Built-In functions With No CLANG Equivalent, continued

Example: Using the ASID function
The following example sends a message back to your console indicating the address space identifier for ESPA.
REXXON addr=ASID(ESPA) say address space of ESPA is addr REXXOFF
Sample output is shown below:

address space of ESPA is 29
JOBONCSF function
The JOBONCSF function returns information about any job that is currently available on the CSF (Consolidated Status Facility). The syntax is:
n=JOBONCSF(jobname,varprefix)
Number of entries returned. n jobname Jobname. You can use wildcards in this field. varprefix String to be used as the prefix to stemmed variables, as dexcribed below. The maximum length of this prefix is 8.
284
Using REXX with ESP
Built-In Functions With No CLANG Equivalent, continued

JOBONCSF function, continued
If JOBONCSF returns data (result > 0), then it will generate stemmed variables in the form ppppvvvvv.i , where pppp is the stemmed variable prefix, vvvvv is the variable name, and i is the numeric stem.
Table of variable names
The variable names are described in the following table.

Variable Name AGENT APPL APPLG BYPASSED COMPLETE CONDCODE
Description agent name Application Application generation number job bypassed job completed completion code
Format string string number 0 for false, 1 for true 0 for false, 1 for true nn, Snnnn for system abend, Unnnn for user abend 0 for false, 1 for true hh.mn yyyy/mm/dd date may be in YMD, MDY or DMY format based on DATEFORM initialization parm string 0 for false, 1 for true 0 for false, 1 for true number string number 0 for false, 1 for true 0 for false, 1 for true
Length Returned 16 8 10* 1 1 5*
CRITICAL_PATH ENDTIME
critical path job job end time
1 19
EVENT EXTERNAL FAILED HC JOBN JOBNO MANUAL OVERDUE_START
Event name external job job failed hold count jobname job number manual job job overdue to start
24 1 1 5* 8 5* 1
Using REXX with ESP
285

Table of variable names, continued
Variable Name OVERDUE_SUBMIT OVERDUE_END PNODE QUAL REQUEST REQUESTED SCHED STARTTIME
Description job overdue to submit job overdue to end processing node job qualifier request job requested job scheduled time job start time
Length Returned 0 for false, 1 for true 1 0 for false, 1 for true string string 0 for false, 1 for true 0 for false, 1 for true hh.mn yyyy/mm/dd hh.mn yyyy/mm/dd -date may be in YMD, MDY or DMY format based on DATEFORM initialization parm string string string J for job (including non-MVS), T for task, L for link string string 1 8 8 1 1 19 19
Format
STATUS SUBAP TAG TYPE
status of job subApplication name tag field type of job
28 8 16 1
USTAT WOBTYPE
user status type of workload object (non-MVS)
28 2
* Length returned varies.
286
Using REXX with ESP

Example
In this example, the JOBONCSF function tells ESP to: Look for a job called BLNG001. Generate variables with the prefix X for each occurrence of the job it finds. Send the value of many of the variables it generates back to your terminal.
REXXON J = JOBONCSF(BLNG001,X) SAY THERE ARE J JOBS DO I SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY SAY END = 1 TO J JOBNAME XJOBN.I JOBNO XJOBNO.I APPL XAPPL.I APPLG XAPPLG.I PNODE XPNODE.I SCHED XSCHED.I STATUS XSTATUS.I HC XHC.I QUAL XQUAL.I TAG XTAG.I ASTTM XSTARTTIME.I AENTM XENDTIME.I EVENT XEVENT.I EXTERNAL XEXTERNAL.I MANUAL XMANUAL.I COMPLETE XCOMPLETE.I ---------
REXXOFF
Using REXX with ESP
287

Sample output from the procedure
The following is a sample output from this Procedure.

THERE ARE 2 JOBS JOBNAME BLNG001 JOBNO 3500 APPL BILLING APPLG 139 PNODE COMPLETE SCHED 09.00.00 31JAN1994 STATUS COMPLETED AT 09.55 31 JAN HC 0 QUAL TAG TAG1 ASTTM AENTM 09.55.23 31JAN1994 EVENT CYB.BILLING EXTERNAL 0 MANUAL 0 COMPLETE 1 --------JOBNAME BLNG001 JOBNO 0 APPL BILLING APPLG 140 PNODE COMPLETE SCHED 09.00.00 01FEB1994 STATUS COMPLETED AT 16.55 01 FEB HC 0 QUAL TAG TAG1 ASTTM AENTM 16.55.22 01FEB1994 EVENT CYB.BILLING EXTERNAL 0 MANUAL 0 COMPLETE 1 ---------
288
Using REXX with ESP
Trapping Output From Commands

About trapping output from commands
The next three examples illustrate ways you can use REXX with CLANG to trap output from a command and perform processing based on the results. The examples are summarized as follows: Example 1 traps the output from an LDSN command and sends the output back to your terminal in a different format. Example 2 traps the output from an LAP command to see if an Application is active. Example 3 traps the output from an SMFSTATS command to monitor SMF data. Criteria The LDSN command displays the names of various ESP data sets. This example uses REXX to trap the output from ESPs LDSN command. The information is sent back to your terminal in the following format:
espfile.1 = CHECKPOINT dataset.1 = CYB1.ES43.CKPT . . .
Example 1: Trapping output from an LSDN command
ESP Procedure Enter the following statements in an ESP Procedure:

REXXON r=trapout(ldsn.) ESP LDSN r=trapout(off) do i=2 to ldsn.0 j=i-1 parse var ldsn.i espfile.j : dataset.j , rol say espfile.j = espfile.j say dataset.j = dataset.j end REXXOFF
Results of ESP Execution ESP issues the LDSN command, traps the output, and sends the information back to your terminal.
Using REXX with ESP
289
Trapping Output From Commands, continued

Example 2: Checking Application status -Part 1
Criteria The criteria for this example are that: ESP issue an LAP command for the -1 generation of the SYSTEMS Application. ESP check if the Application is active and if so, completes it. If the Application is complete, output from the LAP command might look like this:
APPL SYSTEMS GEN 48 COMPLETE CREATED AT 08.28 ON WEDNESDAY JUNE 29TH, 1994 ENDED AT 08.44 ON WEDNESDAY JUNE 29TH, 1994
If the Application is not complete, output from the LAP command might look like this:
APPL SYSTEMS GEN 49 CREATED AT 08.28 ON THURSDAY JUNE 30TH, 1994
ESP Procedure Enter the following statements in the ESP Procedure:

REXXON x=trapout(line.) ESP LAP SYSTEMS.-1 x=trapout(off) Status=SUBWORD(line.1,5) if Status= then ESP APPLJOB ALL COMPLETE APPL(SYSTEMS.-1) REXXOFF
Results of ESP Execution ESP produces the following results: If the previous generation of the SYSTEMS Application is active, ESP issues an APPLJOB command to complete it. If the previous generation of the SYSTEMS Application is complete, ESP takes no action.
290
Using REXX with ESP

Example 2: Checking Application status -Part 2
Criteria Job ABC runs every 5 minutes. If the previous run of the job has not completed, then dont submit the job. To set up this scenario: Set up a one job Application (i.e. EVERY5) to submit job ABC. Schedule an Event every 5 minutes to invoke the Application. During Application generation mode, use REXX to issue an LAP command and check the status of the current generation. If the current generation is not complete, then QUIT. Otherwise, create a new generation of the Application and submit the job.
ESP Procedure Enter the following statements in the ESP Procedure:

REXXON GEN X=TRAPOUT(LINE.) ESP LAP EVERY5.0 X=TRAPOUT(OFF) APSTATUS=SUBWORD(LINE.1,5,1) IF APSTATUS= THEN QUIT REXXOFF APPL EVERY5 JCLLIB PROD.JCL.CNTL JOB ABC RUN ANY ENDJOB
Results of ESP Execution ESP produces the following results: If the current generation of the EVERY5 Application is not complete, ESP quits the ESP Procedure and does not create a new generation of the Application. If the current generation of the EVERY5 Application is complete, ESP creates a new generation of the Application and submits job ABC.
Using REXX with ESP
291

Example 3: Using Criteria REXX with The criteria for this example is that: CLANG to ESP issue the SMFSTATS command every two minutes. This command monitor SMF data displays SMF statistics.
ESP sends a warning message, if the number of job starts does not increase in two minutes. ESP sends a message stating the number of job starts in the previous two minutes, if the number of job starts increase in two minutes. The started task name for ESP be ESP.
ESP Procedure The following ESP Procedure addresses the above criteria:
INTEGER OLDNUM,NEWNUM,DIFF REXXON x=trapout(line.) ESP SMFSTATS y=trapout(off) parse var line.5 num . newnum=num REXXOFF INTEGER X X=2 IF USER1= THEN DO SEND ESP IS STARTING TO MONITOR SMF STATISTICS CN(01) NONDEL SEND TO STOP: SUSPEND CYBER01.SMFSTATS CN(01) NONDEL ENDDO ELSE DO OLDNUM=USER1 DIFF=NEWNUM-OLDNUM IF DIFF=0 THEN SEND # OF JOB STARTS HAS NOT INCREASED IN %X MINUTES CN(01) NONDEL ELSE SEND # OF JOB STARTS HAS INCREASED BY %DIFF IN %X MINUTES CN(01) NONDEL ENDDO OLDNUM=NEWNUM VS F ESP,TRIGGER CYBER01.SMFSTATS USER1(%OLDNUM) AT(NOW PLUS %X MINUTES)
292
Using REXX with ESP

Example: Using REXX with CLANG to monitor SMF data, continued
Event Set up the CYBER.SMFSTATS Event to invoke this ESP Procedure. You will need to trigger the Event manually when you want ESP to start monitoring. Results of ESP Execution ESP executes the above Procedure and sends either a warning message, for example:
# OF JOB STARTS HAS NOT INCREASED IN 2 MINUTES
or a message showing the number of job starts in the previous two minutes, for example:
# OF JOB STARTS HAS INCREASED BY 54 IN 2 MINUTES
Using REXX with ESP
293
Inserting Adhoc Request Jobs

Example: Using Criteria REXX to issue an The criteria for this example are that: APPLJOB to The data set for the request job information be insert request jobs CYB.REQUEST(ADHOC).
The data set contains a list of job names and Application names. The Application name of LEFTOVER be used, if no Application is specified. Sample input is shown below:
ODDJOB1 PAYJOB BIGAPPL LASTJOB
ESP Procedure The following ESP Procedure addresses the above criteria:
REXXON /* allocate dataset with list of jobs and Applications */ ALLOCX DSN(CYB.REQUEST(ADHOC)) SH if rc \= 0 then do SE UNABLE TO ALLOCATE CYB.REQUEST(ADHOC) U(*) REEXEC IN(2) EXIT end address MVS EXECIO * DISKR ddname (STEM INPUTREC. FINIS j=inputrec.0 /* read through the dataset line by line */ /* insert job into Application specified or default */ do i = 1 to j parse upper var inputrec.i jobname applname . if applname= then applname=leftover ESP AJ jobname INSERT APPL(applname) end FREEX FILE( ddname ) REXXOFF
294
Using REXX with ESP
Inserting Adhoc Request Jobs, continued

Example: Using REXX to issue an APPLJOB to insert request jobs, continued
Results of ESP Execution The ESP Procedure reads the data set CYB.REQUESTS(ADHOC) and issues an APPLJOB (AJ) command to insert each job into an Application. Using the sample input, ESP will issue the following commands:
ESP AJ ODDJOB1 INSERT APPL(LEFTOVER) ESP AJ PAYJOB INSERT APPL(BIGAPPL) ESP AJ LASTJOB INSERT APPL(LEFTOVER)
You can review the inserted jobs using the Consolidated Status Facility.
Using REXX with ESP
295
Using REXX to Build Applications

About using REXX to build Applications
The next two examples illustrate ways you can use REXX with CLANG to build ESP Applications. The functions of the sample Applications are as follows: Example 1 builds an ESP Application to execute four sequential jobs. Example 2 builds an ESP Application based on information in a data set. Criteria The criteria for this Application is as follows: The name of the Application is TEST. The jobs include TEST1, TEST2, TEST3, TEST4. ESP selects each job in the Application for execution. The data set CYB.TEST.JCL contains the JCL for these jobs. The member name is the same as the jobname. The jobs should execute sequentially, as shown below.
TEST1
Example 1: Generating an Application of sequential jobs
TEST2
TEST3
TEST4
296
Using REXX with ESP
Using REXX to Build Applications, continued

Example 1: Generating an Application of sequential jobs, continued
ESP Procedure Set up the ESP Procedure like this:

JCLLIB CYB.TEST.JCL APPL TEST REXXON GEN do i=1 to 4 JOB TESTi RUN ANY if i <> 4 then RELEASE TESTi+1 ENDJOB end REXXOFF
In the above ESP Procedure, ESP builds the job relationships and schedules jobs for execution. Results of Executed Procedure When an Event invokes this ESP Procedure, ESP generates the following statements and then begins processing the Application.
JCLLIB CYB.TEST.JCL APPL TEST JOB TEST1 RUN ANY RELEASE TEST2 ENDJOB JOB TEST2 RUN ANY RELEASE TEST3 ENDJOB JOB TEST3 RUN ANY RELEASE TEST4 ENDJOB JOB TEST4 RUN ANY ENDJOB
Using REXX with ESP
297

Criteria Example 2: Generating an The criteria for this example are as follows: Application based on data set The data set CYB01.ESPPROC(MYAPPL) contains a list of jobs and input schedule criteria. Assume CYB01.ESPPROC(MYAPPL) contains the following data:
CYBA DAILY CYBB LAST WORKDAY OF MONTH CYBC
The default schedule for a job is DAILY. The jobs run in the order in which they are listed.
ESP Procedure Enter the following statements in an ESP Procedure:

JCLLIB CYB.JCL REXXON GEN ALLOCX DSN(CYB01.ESPPROC(MYAPPL)) SH if rc \= 0 then do SE UNABLE TO ALLOCATE CYB01.ESPPROC(MYAPPL) U(*) REEXEC IN(2) EXIT end address MVS EXECIO * DISKR ddname (STEM LINE. FINIS if line.0=0 then do SE NO JOBS TO RUN U(*) EXIT end APPL MYAPPL prevjob =
298
Using REXX with ESP

Example 2: Generating an Application based on data set input, continued
do i = 1 to line.0 /* extract jobname and run frequency. */ /* set frequency to daily if it is omitted */ parse upper var line.i jobname schedule if schedule = then schedule = DAILY /* generate the job definition JOB jobname RUN schedule if prevjob \= then AFTER prevjob prevjob = jobname ENDJOB end freex file( ddname ) REXXOFF
*/
In the above ESP Procedure, ESP builds the job relationships and schedules jobs for execution. Results of Executed Procedure When an Event invokes this ESP Procedure, ESP builds the following Application using the data from the CYB01.ESPPROC(MYAPPL) data set.
JCLLIB CYB.JCL APPL MYAPPL JOB CYBA RUN DAILY ENDJOB JOB CYBB RUN LAST WORKDAY OF MONTH AFTER CYBA ENDJOB JOB CYBC RUN DAILY AFTER CYBB ENDJOB
Using REXX with ESP
299
Using REXX to Define Special Days

Example: Defining special days
In this example, an ESP Procedure uses REXX to read each line of a data set containing dates, and then issues a DEFSPEC command for the specified date. Criteria The criteria for this example are that: The data set for the date information be CYB01.DATES. The data set contain a list of dates in the format ddmmmyy. An example of this format is 21DEC95. ESP Procedure Enter the following expressions in an ESP Procedure:
REXXON ALLOCX DA(CYB01.DATES) F(MYINDD) SH if rc \= 0 then do REEXEC IN(1) EXIT end address MVS EXECIO * DISKR MYINDD (STEM LINE. FINIS do i=1 to line.0 Date=line.i ESP DEFSPEC BILL_DAY ON(Date) CAL(SYSTEM) end FREEX FILE(MYINDD) REXXOFF
Results of ESP Execution The ESP Procedure reads the data set CYB01.DATES and issues DEFSPEC commands to define the dates as special days to ESP. The special day name is BILL_DAY. You can review these definitions of special days using option L from ESPs Main Selection Menu.
300
Using REXX with ESP
Updating a Symbolic Variable

You can use REXX to output information to a data set by queueing the Example: Updating a information and using an EXECIO DISKW command. When using this symbolic variable technique you must queue a null line to denote the end-of-file. EXECIO -Part 1 requires that a null line be stacked, like this:
REXXON ALLOCX DA(YOUR.DATASET) SH queue this is line 1 queue this is line 2 queue this is line 3 queue address MVS EXECIO * DISKW ddname (FINIS) FREEX FILE(ddname) REXXOFF
This example illustrates how you can use REXX with CLANG to update the value of a symbolic variable stored in a sequential data set. Criteria The criteria for this example are as follows: The name of the symbolic variable is SWITCH. It is stored on the first (and possibly only) line of the data set. The data set that stores the symbol is CYB01.SYMBOL. The updated value of the symbolic variable is NO. ESP Procedure Enter the following statements in an ESP Procedure:
REXXON ALLOCX DA(CYB01.SYMBOL) F(MYINDD) SH if rc \= 0 then do SE UNABLE TO ALLOCATE CYB01.SYMBOL U(*) REEXEC IN(2) EXIT end queue SWITCH=NO queue address MVS EXECIO 1 DISKW MYINDD (FINIS) FREEX FILE(MYINDD) REXXOFF
Results of Executed Procedure ESP assigns the value of NO to the symbolic variable SWITCH.
Using REXX with ESP
301
Updating a Symbolic Variable, continued

The previous example uses REXX to update the first line in a data set with a Example: Updating a symbolic variable assignment statement. In this example, there are multiple symbolic variable lines in the data set and you must find the particular line you are looking for -Part 2 and update only that line. Criteria The criteria for this example are as follows: The name of the symbolic variable is SWITCH. It can be on any line in the data set but only appears once. The data set that stores the symbol is CYB01.SYMBOL. The updated value of the symbolic variable is NO. ESP Procedure Enter the following statements in an ESP Procedure:
REXXON ALLOCX DA(CYB01.SYMBOL) F(MYINDD) SH if rc \= 0 then do SE UNABLE TO ALLOCATE CYB01.SYMBOL U(*) REEXEC IN(2) EXIT end /* read dataset and look for line with SWITCH */ address MVS EXECIO * DISKR MYINDD (STEM line. FINIS do i=1 to line.0 if pos(SWITCH,line.i) > 0 then leave end /* replace line */ address MVS EXECIO 1 DISKRU MYINDD i (LIFO pull line push SWITCH=NO address MVS EXECIO 1 DISKW MYINDD (FINIS) FREEX FILE(MYINDD) REXXOFF
Results of Executed Procedure ESP assigns the value of NO to the symbolic variable SWITCH.
302
Using REXX with ESP
Using REXX Execs

About REXX execs
You can create REXX execs that invoke ESP. You may find this useful if you are already working with REXX outside of ESP. The next three examples illustrate how you can use a REXX exec to: Define a perpetual holiday date. Generate an ESP history report. Simulate multiple occurrences of a scheduled Event. In this example, a REXX exec defines CHRISTMAS as a holiday every December 25 for the next 10 years. You define it as a 24-hour holiday in the SYSTEM calendar. Below are the REXX statements you enter, the steps in execution, and a description of the output. REXX Statements The REXX statements shown below assume that the subsystem name for ESP is ESP. If your subsystem name for ESP is not ESP, you must specify the subsystem name. For example, specify ESP SUB(ESPA) if the subsystem name for ESP is ESPA. The REXX exec looks like this:
Startyear=1994 do i=0 to 9 Year=Startyear+i Date=25dec||Year queue DEFHOL CHRISTMAS START(Date) FOR(24) CALENDAR(SYSTEM) end queue END ESP
Example 1: Defining a holiday
Steps in Execution During execution, this REXX exec: Queues 10 DEFHOL commands. Queues END to take you out of line mode. Calls the ESP/TSO command processor.
Using REXX with ESP
303
Using REXX Execs, continued

Example 1: Defining a holiday, continued
Input to the Exec The REXX exec takes no parameters. This example has the starting year specified in the REXX exec. Output Output will consist of 10 holiday definitions called CHRISTMAS in the SYSTEM calendar. You can then review the definitions of these holidays using option L from ESPs Main Selection Menu.
Example 2: Generating a history report
In this example, you create a REXX exec that generates a history report. Below are the REXX statements you enter, the steps in execution, and a description of the output. REXX Statements The REXX statements shown below assume that the subsystem name for ESP is ESPA. The REXX exec looks like this:
queue REPORT queue FROM 8AM YESTERDAY queue CRITERIA JOBNAME EQ PROD- , queue DISPLAY JOBNAME JOBNO CMPC APPLSYS queue SORT APPLSYS JOBNAME queue ENDR queue END ESP SUB(ESPA)
Steps in Execution During execution, this REXX exec: Queues 6 history reporting commands. Queues END to take you out of line mode. Calls the ESP/TSO command processor. Input to the Exec The REXX exec takes no parameters. Output Output will consist of a history report reflecting the criteria you specify.
304
Using REXX with ESP

Example 3: Simulating an event multiple times
In this example, the REXX exec simulates an Event multiple times. Below are the REXX statements you enter, the steps in execution, and a description of the output. The REXX exec looks like this:
/* rexx procedure to simulate /* multiple occurrences of an event parse arg Event Count if Event = then exit if Count = then exit x=outtrap(line.) queue NEXT Count Event queue END ESP SUB(ESPA) x=outtrap(off) if line.0 = 1 then do say line.1 exit end lines = line.0 do i=2 to lines if pos(NO MORE,line.i) > 0 then leave parse var line.i . . Sched queue SIMULATE EVENT(|| Event || ) SCH( || Sched ) end queue END
ESP SUB(ESPA)
*/ */
Steps in Execution During execution, this REXX exec: 1. receives the following two variables: A variable (Event) for the name of the simulated ESP Event. A variable (Count) for the number of simulated executions. 2. issues the NEXT command. 3. traps the output from the NEXT command. 4. passes the next scheduled execution information into the SIMULATE command.
Using REXX with ESP
305

Example 3: Simulating an Event multiple times, continued
Input to the Exec Below is a sample of the input to the REXX exec, based on the following assumptions: The name of the exec is MULTISIM. The name of the ESP Event is PROD.PAYROLL. The number of simulated executions is 3. The input looks like this:
MULTISIM PROD.PAYROLL 3
Output Output will consist of the next 3 simulations of the Event.
306
Using REXX with ESP
Using ESP With DJC/JES3 Job Networks Overview

Introduction
If your site is running JES3 or Dependenct Job Control (DJC) you can use ESP to define jobs as part of a job network. The definition is stored in an ESP Procedure. ESP submits all the selected jobs in the network when the ESP Procedure is invoked. DJC job networks are similar to ESP Applications, but do not offer as much flexibility. For additional information about DJC, refer to the DJC Operators Guide, the DJC Systems Programmers Guide and the DJC Users Guide.
In this chapter
This chapter contains the following topics: Topic What Is a Job Network Defining the Job Network Selecting Jobs for Submission Specifying Other DJC Parameters Defining Other Types of Jobs Examples of DJC Networks Submitting Job Networks Statements to Define Job Networks See Page 308 310 321 321 322 324 333 334
Using ESP with DJC/JES3 Job Networks
307
What Is a Job Network

About job networks
In ESP, you can define groups of related jobs as either a DJC/JES3 job network or an Application. ESP uses DJC or JES3 to control initiator level dependencies. At the initiator stage, ESP submits network jobs to the JES queue when the Event is scheduled or triggered. Each job requires a NET control statement in its JCL that identifies: The specific network to which it belongs. The dependent actions that are necessary before JES can initiate the job. DJC allows for job dependencies, including job relationships and resources, to be controlled at the initiator level through the use of NET control statements. These control statements are based on the dependencies you define. When a jobs dependencies have been met, JES releases the job. For more information about ESP Applications, refer to Advanced Use of Applications on page 161, and the ESP Users Guide. Some of the advantages of using ESP with DJC are: The generation of NET control cards automatically. The submission of networks of jobs.
Benefits of using ESP with DJC job networks
ESP performs the following processing steps for jobs in a DJC network: How ESP manages jobs in a 1 ESP places successor jobs in network hold. DJC network 2 Each job in network hold is given a hold count. The count is a number corresponding to the number of immediate predecessors for the job. A job in a network is not eligible to execute if the network hold count exceeds zero.
308
What Is a Job Network, continued

How ESP manages jobs in a DJC network, continued
When a predecessor job terminates successfully, ESP subtracts 1 from the network hold count. For instance, if the network hold count for a job is 3 and a predecessor job terminates successfully, the network hold count decreases to 2. When the network hold count reduces to zero, the job becomes eligible to execute, unless the job is in another type of hold status such as: JES hold dependent job operator hold.
You can display jobs and networks using JES $NET commands. If a job is in network hold, it shows as NET-HOLD when you display the job status. For more information on using these commands, refer to the DJC Operators Guide.
309
Defining the Job Network

About defining the job network
You can use an ESP Procedure to describe a job network to ESP. An ESP Procedure consists of a series of statements that: Identifies the job network. Tells ESP where the JCL for each job is located. Identifies the jobs. Describes the job relationships. Describes when ESP should select the jobs to run. In addition, an ESP Procedure may also indicate which job documentation library will be used, or specify what condition codes will cause a job to fail. Visually, a job network might look like this:
Daily
Friday
Last workday of month
310
Defining the Job Network, continued

About defining the job network, continued
The ESP Procedure statements describing this job network might look like this:
DJCNET PAYDAILY JCLLIB CYBER.DJC.JCL JOB A RELEASE (B,C) JOB B RELEASE D JOB C RELEASE D JOB D RELEASE E JOB E RELEASE F ENDJOB JOB F ENDJOB SELECT (A,B,C,D) IF TODAY(FRIDAY) THEN SELECT E IF TODAY(LAST WORKDAY OF MONTH) THEN SELECT F
The following topics briefly discuss the main steps in defining a job network. For a list of statements you can use to define a DJC Network, see Statements for Defining Job Networks at the end of this chapter. For more detailed descriptions of these statements, refer to the ESP Command Reference.
Identifying the network
To identify the network, enter the DJCNET statement in an ESP Procedure like this:
DJCNET netid
An explanation of the above syntax follows:

netid
Specifies the job network identifier. The maximum length of the netid is 8 characters. The first character cannot be a number. The netid applies unless: You override the netid name with the DJCDATA statement at the job level. Another DJCNET statement with a different netid appears in the same ESP Procedure.
311

Identifying JCL libraries
Use ESP Procedure statements to specify the default JCL libraries you want to use throughout an ESP Procedure. This saves you the task of repeatedly specifying the same information as part of each jobs definition. The scope of a Procedure statement extends from the point at which you specify it, to either the end of the Procedure or to the point at which you specify a corresponding Procedure statement. This way you can change or override job defaults several times during an ESP Procedure, if necessary. The following statements specify defaults: JCLLIB Specifies the JCL library you want to use for all jobs following this statement. 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. Specifies the temporary or override JCL library you want to use as the default for all jobs following this statement. If a library of this type is specified, ESP uses JCL from the temporary or override library for job submission. Otherwise ESP uses JCL from the most recent JCLLIB statement. Use of this statement is optional.
TEMPLIB
The ESP Procedure below has the name NIGHTLY and identifies the default libraries you want to use. The name of the JCL library is PROD.JCL.CNTL and the name of the override library is PROD.OVERRIDE.JCL.
NIGHTLY:ESPPROC JCLLIB PROD.JCL.CNTL TEMPLIB PROD.OVERRIDE.JCL
312

Specifying different JCL libraries
In addition to using the JCLLIB and TEMPLIB default specifications statements, you can also identify the JCL library and optional member name a particular job requires by using the DATASET job statement. For this particular job only, the DATASET statement overrides any default JCL library that you might have previously named in a JCLLIB statement. In the following Procedure the default JCL library is CYBER.JCL.CNTL. Because job J1 contains no library instructions, it uses the default. Job J2 uses the DATASET statement to specify that job J2 should use the alternate library CYBER.ALT.JCL. For job J3 the default is CYBER.JCL.CNTL. However, for job J4 the default changes through another JCLLIB statement and becomes CYBER.JCL.CNTL2.
JCLLIB CYBER.JCL.CNTL JOB J1 RELEASE J2 JOB J2 DATASET CYBER.ALT.JCL RELEASE J3 JOB J3 RELEASE J4 JCLLIB CYBER.JCL.CNTL2 JOB J4 ENDJOB SELECT (J1,J2,J3,J4)
Note: If you want to specify a time period in which temporary JCL is to be used for a job, use a //*UNTIL statement in the jobs JCL. Place this statement before the job card in a JCL member of the temporary library (TEMPLIB). Include a cut-off date for the temporary JCL. ESP will use this JCL up to, but not including the date you specified in the //*UNTIL statement.
Identifying jobs
You must use the JOB statement first to identify the name of a job in an ESP Procedure before identifying job requirements. By default, the job name is the same as the member name of the JCL library being used. To override this, use the MEMBER statement and specify the name of the member that contains the JCL for the job. The job name must match the name specified on the job card.
313

Identifying jobs, continued
In the following example, the JCL for job CYBXA01B is stored in member CYBJOB of the JCL library CYBER.JCL.CNTL.
JCLLIB CYBER.JCL.CNTL JOB CYBXA01B MEMBER CYBJOB
Once the JOB statement has been used to introduce a job to an ESP Procedure, 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 ESP Procedure or outside this ESP Procedure. The JOB statement defines the beginning of the job definition. The ENDJOB statement or another JOB statement signifies the end of a job definition.
Qualifying jobs
ESP lets you qualify job names with a qualifier consisting of up to 8 alphanumeric characters, and separated from the jobname by a period,. Use qualification of job names in an ESP Procedure to: Define duplicate jobs Give a more descriptive name to a job Provide a built-in symbolic variable (ESPJQUAL) representing the qualifier. Duplicate job names are not allowed in a jobnet. You can define duplicate job names in an ESP Procedure by using qualified job names in different job networks. ESP generates the appropriate net release card. Here is an example of a qualified job. The name of the job is MYJOB; the qualifier is RUN1.
JOB MYJOB.RUN1
314

Specifying job relationships
To specify predecessor and successor job relationships, include the appropriate job dependency parameters. A list of job dependency parameters appears below: AFTER Specifies any job(s) which are predecessors to a job and should indicate a release to this job upon its completion. (The default is successful completion). Specifies successors to a job that will be 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. ESP automatically selects the jobs for submission whenever this job is selected for processing. Specifies the names of any other jobs that 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. Specifies the names of any other jobs which must run after this job has executed. ESP automatically selects the jobs for submission whenever this job is selected for processing.
RELEASE PREREQ
COREQ
POSTREQ
Once the appropriate dependency parameters have been defined, ESP can automatically build the necessary NET control cards at submission time. The following are two different ways of coding the same relationship. Method 1
JOB A RELEASE B
Method 2
JOB B AFTER A
315
Selecting Jobs for Submission

About selecting jobs for submission
To select a job for submission you need to do one of the following: Specify the name of the job on a SELECT statement. Specify one or more RUN statements for the job to identify the frequency. Name the job on a POSTREQ, PREREQ or COREQ statement. You can use any combination of these statements in a job network.
The following example shows two different ways of selecting jobs for Example: Selecting jobs for submission. The first example uses a RUN statement for each job. submission using a RUN statement JOB A
RUN DAILY RELEASE B JOB B RUN FRIDAY ENDJOB
This example uses SELECT statements after identifying specific job Example: Selecting jobs for requirements. submission using a SELECT JOB A statement RELEASE B
JOB B ENDJOB SELECT A IF TODAY(FRIDAY) THEN SELECT B
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. Code your NORUN statements after your RUN statements. If you specify a job with a NORUN statement and without a RUN statement, ESP will schedule the job each time the Event executes except when it manages to satisfy the NORUN schedule criteria.
316
Selecting Jobs for Submission, continued

Example: Daily job run except first Monday
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: Using the DESELECT statement
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 a job network 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. ESP then generates the appropriate NET control statements. Consider the following three jobs and their schedule frequencies.
Daily
Friday
Daily
317

Inheriting job relationships, continued
On Fridays, all three jobs execute in order, but on any other day of the week job B does not run. On these days ESP selects jobs A and C and inherits their relationships with B. When A completes successfully it releases C. For information on overriding the inheritance of job relationships refer to Advanced Use of ESP Procedures on page 129.
318

How ESP builds the net control cards
When you define job relationships, as part of a job network in an ESP Procedure, ESP automatically builds the NET control cards required by DJC or JES3 at job submission time. The generated NET control cards contain the following information: Net ID Hold count Successor jobs Parameters that are part of the DJCDATA statement (e.g. DJC resources). When ESP builds the NET control cards, the generated information then controls job execution after ESP submits the job to JES. You do not need to manually code NET statements in the JCL. If job relationships change to accommodate a particular day or period, ESP can rebuild the proper NET control cards based on the new criteria. Use the SIMULATE command to preview how the control cards will look. The SIMULATE command shows you: The jobs ESP selects for submission. The hold counts for each job. The names of the subsequent jobs that any job releases. The JCL (optionally). If jobs already have NET control cards, ESP overrides these cards. If necessary, you can suppress the override feature by entering the OPTIONS statement in the ESP Procedure before defining each of your jobs. This statement has the following format:
OPTIONS NOGENNET
Benefits of building net control cards automatically
Simulating and net control card building
How ESP handles existing control statements
319

Example: Job network definition
The following is a definition of a job network.

DJCNET SIMPLE1 JCLLIB. . . JOB A RELEASE B JOB B RELEASE C ENDJOB JOB C ENDJOB SELECT (A,C) IF TODAY(FRI) THEN SELECT B
ESP then selects jobs according to the scheduling criteria and builds a NET control card using the characteristics of the applicable netid. The two tables below show the results. In each table, HC = number of immediate predecessors, and RL = names of immediate successors. On Friday, ESP selects the following jobs and generates the following NET control cards: JOB A B C NET CONTROL CARD //*NET ID=SIMPLE1,HC=0,RL=B //*NET ID=SIMPLE1,HC=1,RL=C //*NET ID=SIMPLE1,HC=1
On any day other than a Friday, ESP selects the following jobs and generates the following NET control cards: JOB A C NET CONTROL CARD //*NET ID=SIMPLE1,HC=0,RL=C //*NET ID=SIMPLE1,HC=1,HC=1
320
Specifying Other DJC Parameters

About specifying other DJC parameters
Use the DJCDATA statement to specify the parameters you want to appear in the NET control card. You can use the DJCDATA statement in either an ESP Procedure or job documentation member. ESP uses this information to generate the NET control card at the time of job submission. The DJCDATA statement can specify any of the following: DJC resource requirements. NET releases for any DJC/JES job network. A dependent jobnet ID. Actions resulting from a normal or abnormal termination of a job predecessor. Example 1 below illustrates how you can use DJCDATA to specify resource requirements. Example 2 identifies a relationship with a job in another job network.
In this situation, job CICSBKUP cannot execute until the following resources Example 1: DJCDATA are available: specifies tape and system resources Two tape drives. One unit of a resource with the name of CICSDOWN. The example below would apply only to Applications if DJC is installed. The job statements look like this:
JOB CICSBKUP DJCDATA TC(2) RS(1,CICSDOWN)
Example 2: DJCDATA identifies a release to a job in another network
This example uses the DJCDATA statement for job IM99 to indicate that it is to release a job in a different job network. Upon successful completion, job IM99 releases JOBONE in job network OTHERNET. Part of the ESP Procedure looks like this:
JOB IM99 DJCDATA NR(OTHERNET,JOBONE)
321
Defining Other Types of Jobs

Defining external ESP allows you to see up inter-network dependencies. For example, you may jobs have a job in one network which is dependent on a job in another job network.
The process of releasing a job in another network is called a net release. Use the EXTERNAL keyword as part of a JOB statement to identify to ESP that the job is part of another job network. This allows you to set up dependencies between job networks.
Example
In this example, ESP includes job X as part of the job network NET1 on Fridays. Job Z in the job network NET2 waits for job X. Visually, the dependencies look like this:
NET1 A
(job)
NET2 X
(External job)
X
(job)
Z
(job)
The ESP Procedure for NET1 looks like this:

DJCNET NET1 JCLLIB SYS1.JCL JOB A RUN DAILY RELEASE X JOB X RUN FRIDAY DJCDATA NR(NET2,Z) ENDJOB
322
Defining Other Types of Jobs, continued

Defining external jobs, continued
The ESP Procedure for NET2 looks like this:

DJCNET NET2 JCLLIB SYS1.JCL JOB X EXTERNAL RUN FRIDAY RELEASE Z JOB Z RUN DAILY ENDJOB
Defining manual jobs
Use the MANUAL keyword as part of a JOB statement to identify to ESP that a job is to be considered as submitted outside of a job network. As a result ESP does not look for JCL, nor does it build NET control statements for the job. However, ESP does include manual jobs on scheduled activity reports, whenever ESP selects the manual jobs to run.
323
Examples of DJC Networks

About the examples
The next five examples illustrate the following types of DJC network situations: Example 1 shows the generation of NET control cards for a network with static job relationships. Example 2 shows how ESP generates NET control cards for a network with changing job relationships. Example 3 uses existing NET control cards in a JES3 environment. Example 4 shows how to handle jobs on a request basis. Example 5 schedules multiple job networks. The networks use the same job names and inherit dependencies from each other. The name of the network in this example is PAYDAILY. The jobs in this network have the following dependencies: ESP selects Job A for submission. When Job A completes successfully, it releases jobs B and C. When jobs B and C complete successfully, they release job D. Visually the dependencies look like:
Example 1: Building NET control cards for jobs with static relationships
324
Examples of DJC Networks, continued

Example 1: Building NET control cards for jobs with static relationships, continued

DJCNET PAYDAILY JCLLIB CYBER.DJC.JCL JOB A RELEASE (B,C) JOB B RELEASE D JOB C RELEASE D ENDJOB JOB D ENDJOB SELECT (A,B,C,D)
ESP invokes the above Procedure and submits the four jobs to the JES queue. At the same time, ESP generates the following NET control statements: JOB A B C D
Example 2: Building NET control cards for changing job relationships
NET CONTROL CARD //*NET ID=PAYDAILY,HC=0,RL=(B,C) //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=2
The name of the network in this example is PAYDAILY. Jobs A, B, C and D are scheduled daily. Job E is a weekly job and Job F is a monthly job. The job relationships change according to different schedule criteria. The specific job dependencies are: ESP selects Job A for daily submission. When job A completes, it releases jobs B and C. When jobs B and C complete, they release job D. Job E runs only on Fridays and is dependent on job D. Job F runs only on the last workday of the month. It depends on job D every day but Friday. On Friday, it depends on job E.
325

Example 2: Building NET control cards for changing job relationships, continued

A

DJCNET PAYDAILY JCLLIB CYBER.DJC.JCL JOB A RELEASE (B,C) JOB B RELEASE D JOB C RELEASE D JOB D RELEASE E JOB E RELEASE F ENDJOB JOB F ENDJOB SELECT (A,B,C,D) IF TODAY(FRIDAY) THEN SELECT E IF TODAY(LAST WORKDAY OF MONTH) THEN SELECT F Continued on next page
326

ESP generates NET control cards based on the selected jobs. The ESP statements for jobs A,B, and C are the same regardless of the day. The NET control statements for jobs D,E, and F vary. The following tables show the results for all jobs. If today is a Friday but is not the last workday of month: A B C D E F //*NET ID=PAYDAILY,HC=0,RL=(B,C) //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=2,RL=E
//*NET ID=PAYDAILY,HC=1
not applicable
If today is a day other than Friday and is also the last workday of month: A B C D E F //*NET ID=PAYDAILY,HC=0,RL=(B,C) //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=2,RL=F not applicable //*NET ID=PAYDAILY,HC=1
327

If today is both a Friday and the last workday of the month: A B C D E F //*NET ID=PAYDAILY,HC=0,RL=(B,C) //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=1,RL=D //*NET ID=PAYDAILY,HC=2,RL=E //*NET ID=PAYDAILY,HC=1,RL=F //*NET ID=PAYDAILY,HC=1
Example 3: Using This example shows an environment where one JCL member contains JCL for existing NET all jobs in a network. The JCL contains all the necessary NET control cards. In control cards
this situation ESP does not generate any NET control cards. Set up the network so that: ESP submits member CQDAILY (this member contains JCL for MVCQ250, MVCQ260, and MVCQ270). The JCL for the jobs is in MVJCL.CNTL(CQDAILY). The ESP Procedure looks like this:
DJCNET CQDAILY JCLLIB MVJCL.CNTL OPTIONS NOGENNET JOB MVCQ250 MEMBER CQDAILY JOB MVCQ260 MANUAL JOB MVCQ270 MANUAL SELECT (MVCQ250,MVCQ260,MVCQ270)
The third statement, OPTIONS NOGENNET, suppresses ESPs generation of the control cards. The ESP Procedure uses the keyword MANUAL to specify that ESP does not look for the JCL.
328

Example 4: Handling onrequest jobs in a network
This example shows one method of handling situations in which users request jobs on an unscheduled basis. This approach uses integer symbols. Visually, the dependencies look like this:
PAY10
RPT01 Request Jobs RPT02 RPT03 RPT04

REQNET:ESPPROC INTEGER RPT01,RPT02,RPT03,RPT04 /* CHANGE THE FOLLOWING TO A 1 IF JOB IS TO RUN TODAY /* ELSE CHANGE TO 0 RPT01=0 RPT02=1 RPT03=0 RPT04=1 /* END OF USER SCHEDULED JOB SELECTION SECTION JCLLIB CYB.JCL.CNTL DJCNET REQNET JOB JTAC10 RELEASE RPT01 JOB RPT01 RELEASE (RPT02,RPT03,RPT04) ENDJOB RPT02 ENDJOB RPT03 ENDJOB RPT04 ENDJOB SELECT JTAC10 /* SELECT REQUEST JOBS IF RPT01=1 THEN SELECT RPT01 IF RPT02=1 THEN SELECT RPT02 IF RPT03=1 THEN SELECT RPT03 IF RPT04=1 THEN SELECT RPT04
329

Example 4: Handling on-request jobs in a network, continued
In this example, the symbol definitions are in the same ESP Procedure as the job network definition. Alternatively you could include the symbol definitions in any of the following locations: A separate ESP Procedure which ESP invokes from the same Event prior to invoking the job network definition. A symbolic variable library referenced in the corresponding Event. The integer symbols perform the following functions in the Procedure: A separate symbol represents each possible on-request job in the network. When the RPT01 symbol value is equal to 1, ESP selects the job. When the RPT01 symbol value is equal to 0, ESP does not select the job. The same rules apply to RPT02, RPT03, and RPT04. The values of the symbols allow the ESP Procedure to determine which ondemand jobs run when ESP invokes the Procedure. This example assumes that a user must manually reset the symbol values each day. As an alternative, you can use a utility program or REXX to reset the values for the symbols.
330

Example 5: Scheduling multiple job networks
This example has three networks: NETA, NETB, and NETC. The schedule criteria and job dependencies for the networks are: ESP submits the networks NETA, NETB and NETC on Mondays. In other days ESP submits only NETA and NETC. Job A3 in NETA releases the first job in NETB. Job B3 in NETB releases the first job in NETC. Within each network the job dependencies do not change. Visually, the dependencies look like this:
NETA A1
NETB B1
NETC C1
A2
B2
C2
BACKUP
BACKUP
BACKUP
A3
B3
C3
331

Example 5: Scheduling multiple job networks, continued
The ESP Procedure defining the job networks and dependencies looks like this:
ABC:ESPPROC JCLLIB PROD.NET.JCL DJCNET NETA JOB A1 POSTREQ A2 JOB A2 POSTREQ BACKUP.A JOB BACKUP.A POSTREQ A3 JOB A3 RELEASE B1 DJCNET NETB JOB B1 POSTREQ B2 JOB B2 POSTREQ BACKUP.B JOB BACKUP.B POSTREQ B3 JOB B3 RELEASE C1 DJCNET NETC JOB C1 POSTREQ C2 JOB C2 POSTREQ BACKUP.C JOB BACKUP.C POSTREQ C3 ENDJOB JOB C3 ENDJOB /* ON MONDAY, SELECT ALL 3 NETS */ /* ELSE SELECT 1ST AND 3RD NETS */ IF TODAY (MONDAY) THEN SELECT (A1,B1,C1) ELSE SELECT (A1,C1)
RELEASE statements in the ESP Procedure set up relationships between the networks. Because the job relationships do not change within each job network, POSTREQ statements in the ESP Procedure instruct ESP to perform requisite processing.
332
Submitting Job Networks

About submitting Use an ESP Event to submit job networks. The trigger for the Event can be: job networks
a scheduled date and time a data set trigger a job monitor trigger a signal with a scheduled date and time a manual trigger. The following two examples demonstrate how to use an Event to submit a job network. The Event appearing below runs each weekday at 4 p.m. It invokes an ESP Procedure that defines the job network and job relationships. ESP builds the required NET cards. The Event looks like this:
EVENT ID(PROD.PAYDAILY) SCHEDULE 4PM WEEKDAYS INVOKE CYBER.ESP.PROC(PAYDAILY) ENDDEF
Example 1: An Event invokes and ESP procedure to submit a job network
Example 2: An Event submits a job network
In this example there are hard-coded NET statements in the JCL so that DJC can control their execution. You can use SUBMIT statements in an Event if NET cards exist. The Event looks like this:
EVENT ID(USER01.MYJOBS) SUBMIT USER01.TEST.JCL(BP1) SUBMIT USER01.TEST.JCL(BP2) SUBMIT USER01.TEST.JCL(BP3) ENDDEF
333
Statements to Define Job Networks
DJCNET DOCLIB JCLLIB TEMPLIB OPTIONS JOB AFTER RELEASE PREREQ COREQ POSTREQ SELECT DESELECT RUN NORUN DJCDATA MEMBER ENDJOB
Identifies the default job network name for jobs that DJC or JES3 controls. Specifies the default job documentation library to use for all jobs following this statement. Specifies the JCL library to use as the default for all jobs following this statement. Specifies the temporary, or override JCL library, to use as the default for all jobs following this statement. Overrides the default processing options. Identifies the name of the job. The job can have a qualifier. Specifies any jobs that precede a job and that release this job. Specifies any jobs that precede a job and that release this job. Specifies the names of any other jobs that must complete before this job can execute. Specifies the names of any other jobs that ESP must select automatically whenever it selects a job. Specifies the names of any other jobs that must run after a job. Identifies which jobs are to be selected for submission. Overrides previous SELECT statements for specific jobs. Specifies when a job is to be selected for submission. Specifies when a job should not be selected for submission. Specifies DJC parameters for a job. Specifies the JCL member name for a job. Indicates the end of the requirements for a job.
334
Statements to Define Job Networks, continued
INPUTDS DATASET
CCFAIL
DUEOUT MODEL
Identifies an input tape data set for a job. Identifies a specific JCL Library and member (optional) that override the default library, for a particular job only. Identifies a specific JCL Library and member (optional) that override the default library, for a particular job only. Specifies a due-out time for the job from a specific processing node (P-Node). Specifies the name of the tracking model to use for the job. The model you specify here overrides the default tracking model for the job. Specifies the prefix for monitor Events relating to a job. Specifies the names of manual processing nodes through which a job passes before it completes.
MONITOR PNODES
335
336
Using Signals Overview

Introduction
Signals cause an ESP Event to wait for a condition in addition to its schedule criteria before it executes. A signal may represent a manual task, such as the arrival of an input tape, or an automated task, such as the completion of a job. For example, you may have an Event scheduled daily at 4 p.m., but you do not want it to execute if some tape input has not arrived. You can represent the arrival of this tape input with a signal and inform ESP to wait for both the 4 p.m. scheduled time and the signal being marked complete. Signals are only available at the Event level. If you are using an Application and need to set up conditions at the job level for jobs in the Application, the best method is through tasks. For more information about using tasks, refer to the ESP Users Guide.
In this chapter
This chapter contains the following topics: Topic Typical Uses for Signals Defining the Signal Waiting for the Signal to Post Posting a Signal Cycling a Signal Combining Signals and Scheduling Criteria Displaying Signal Information How Pending Signals Work Manual and Automatic Posting of Signals See Page 338 339 340 341 342 343 348 350 352
Using Signals
337
Typical Uses for Signals

About signals
A signal can represent a manual task, such as the arrival of a tape, or an automated task, such as the successful completion of a job. Signals are commonly used with DJC/JES3 networks, which do not offer the flexibility of Applications. The following examples illustrate where you might use signals: In a pre-processing step, such as a job that requires a tape from another site. In an Event that waits on a schedule time and data set activity. In a job execution that waits for the previous run of the same job. In a job execution that waits for multiple runs of another job. In daily ESP processing that depends on processing from a previous day.
TIME
SIGNAL
EVENT
How signals work
This is how signals work: 1. An Event waits for a condition in addition to schedule criteria. 2. You represent the condition with a signal. 3. When the condition is met, you post the signal to mark it complete. 4. You then cycle the signal to create a new generation. A scheduled Event can wait on one or more signals.
Each signal must pass through the following stages: Setting up the signal processing Defining the signal environment Specifying the signal conditions in an Event Posting the signal complete Cycling the signal. A detailed explanation of each follows.
338
Using Signals
Defining the Signal

About defining the signal
To define the signal, use the DEFSIG command in Page mode, Line mode or a batch job. You need to give the signal a name and specify the number of generations the signal has. A signals name has two parts: The prefix, representing an ESP group name or user ID. If the prefix is missing, ESP uses the current default prefix. (This prefix could be your userid or group prefix). A descriptive name, consisting of up to 16 characters including alphanumerics, national characters, and the underscore. The first character must always be a letter. You can also specify the maximum number of generations (cycles) for this signal. Although a single generation may be sufficient for ESP processing, you may want to define more to keep for history purposes. If the number of generations is missing, ESP uses 1 as the default. If you define a signal as having more than one generation, you will need to create or cycle the generations by issuing the SIGCYCLE command. Below are examples of statements that define signals.
Example 1: Defining a signal
Assuming the default prefix is your userid, FRED, the following signal is given the name FRED.SIGNAL1. The signal has a maximum of one generation and ESP refers to it as the current generation (0).
DEFSIG SIGNAL1
Example 2: Defining a signal
This signal, named CYBER.TAPE_INPUT, has a maximum number of five generations referred to as 0 (current), -1, -2, -3, -4.
DEFSIG CYBER.TAPE_INPUT GEN(5)
Changing a signal definition
If you need to change the number of generations in a signal, use the ALTSIG command. This example alters the number of generations of the signal CYBER.TAPE_INPUT to 7.
ALTSIG CYBER.TAPE_INPUT GEN(7)
Using Signals
339
Waiting for the Signal to Post

About waiting for the signal to post
To instruct an Event to wait for posting of the signal, insert the SIGWAIT command in the scheduled Event. You can use more than one SIGWAIT command if the Event is to wait for posting of different signals or different generations of the same signal. Specify the following: The name of the signal that is to post before the Event executes. The generation of the signal that is to post before the Event executes. If the number of generations is missing, ESP uses the current generation number 0 as the default.
Example: Waiting for a signal
Below is an example of an Event command, indicating that the Event must wait for the signal CYBER.TAPE_INPUT to post before this Event can execute.
SIGWAIT CYBER.TAPE_INPUT GEN(0)
340
Using Signals
Posting a Signal
About posting a signal
A signal is posted when all conditions for the signal have been met. Depending on the setup, a signal posts in either of the following ways: Automatically, using a SIGPOST command in an Event, an ESP Procedure, or in batch. Manually, by typing a SIGPOST command in Page mode, Line mode or using batch. ESP does not automatically reset a signals generation number when it posts the current generation. To reset the signal, type SIGCYCLE using any ESP access method. For detailed information on manual and automatic posting, refer to Manual and Automatic Posting of Signals on page 352. When you post a signal, specify: The name of the signal ESP posts as complete. If the prefix is missing, ESP uses the current default prefix. The generation of the signal ESP posts. If you do not insert the number of the generation, ESP uses the current generation as the default. If the maximum number of generations already exists, ESP deletes the oldest generation. Use the LISTSIG command to view the maximum generations permitted.
Example: Posting Below is an example of posting a signal. This command posts the current a signal generation of signal CYBER.TAPE_INPUT.
SIGPOST CYBER.TAPE_INPUT GEN(0)
Using Signals
341
Cycling a Signal
About cycling a signal
Each signal has a generation number. ESP does not automatically reset the generation number of a signal after a signal posts. A cycling process resets the signal. Cycling increments the generation number to the next higher number. Depending on the setup, a signal cycles in either of the following ways: Automatically, using a SIGCYCLE command in an Event. Manually, by typing a SIGCYCLE command in Page mode, Line mode or using a batch job. To cycle a signal, use the SIGCYCLE command and specify the name of the signal. If the maximum number of generations already exists, ESP deletes the oldest generation. The signal definition statement specifies the maximum number of generations. You can view this information using the LISTSIG command. For more information on displaying signals, see Displaying Signal Information on page 348.
Example: Cycling a signal
Below is an example of a statement that cycles a signal called CYBER.TAPE_INPUT.

SIGCYCLE CYBER.TAPE_INPUT
342
Using Signals
Combining Signals and Scheduling Criteria

About combining An Event may need to wait on multiple conditions to be met before execution. signals and You can use both a SCHEDULE command and a SIGWAIT command in your scheduling Event definition. ESP only executes such an Event when the signal posts and criteria
the scheduling criteria has occurred. The following examples use the SCHEDULE and SIGWAIT commands in an Event.
Example 1: Event waits on a schedule and the posting of a signal
1. Define the signal CYBER.WAIT4ME in Page mode, Line mode or using batch. The signal definition looks like this:
DEFSIG CYBER.WAIT4ME GEN(1)
2. Define the schedule conditions and signal waiting conditions for signal CYBER.WAIT4ME. The Event name is CYBER.EVENT2. The Event definition looks like this:
EVENT ID(CYBER.EVENT2) SCHEDULE 20:00 WEEKDAYS SIGWAIT CYBER.WAIT4ME GEN(0) INVOKE CYB.ESP.PROCS(REVDAY) ENDDEF
Assume todays scheduling date is Monday (a weekday), and the signal CYBER.WAIT4ME remains unposted at the scheduled time of 20:00. ESP does not execute the Event at 20:00 because the signal condition has not occurred. The signal goes into a pending status at 20:00 because the scheduling criteria has occurred before the signal has posted. When ESP or a user finally posts the signal, the Event will execute. For more information on pending signals, see About pending signals on page 350.
Example 2: Waiting for schedule criteria and data set activity
Events that contain both signals and scheduling criteria execute only if signal posting and schedule criteria occur. If an Event contains scheduling and data set criteria, it waits on either the schedule or the data set activity. In the following example, you want ESP to wait for multiple data sets before it executes a scheduled Event. To set up this sequence of ESP processing, define the following types of Events: An Event with DSTRIG and SIGPOST commands. An Event with SCHEDULE and SIGWAIT commands. An Event with a SIGCYCLE command.
Using Signals
343
Combining Signals and Schedule Criteria, continued

Example 2: Waiting for schedule criteria and data set activity, continued
20:00
(Time)
PROD.DSN1
(Dataset)
CYBER.EVENT2
(Event)
PROD.DATA
(Signal)
PROD.DSN2
(Dataset)
1. Define a signal with the name of PROD.DATA, using the DEFSIG command. This signal has only one generation. The definition statement looks like this:
DEFSIG PROD.DATA GEN(1)
2. Define an Event CYBER.EVENT1 that waits for both data sets and then posts the signal PROD.DATA. The Event definition statements look like this:
EVENT ID(CYBER.EVENT1) DSTRIG PROD.DSN1 ANYCLOSE MULTIPLE DSTRIG PROD.DSN2 ANYCLOSE MULTIPLE SIGPOST PROD.DATA GEN(0) ENDDEF
3. Define an Event CYBER.EVENT2 that waits for the signal to post and for the schedule criteria. The Event definition statements look like this:
EVENT ID(CYBER.EVENT2) SCHEDULE 20:00 WEEKDAYS SIGWAIT PROD.DATA GEN(0) INVOKE CYBER.ESP.PROCS(REVDAY) ENDDEF
344
Using Signals

Example 2: Waiting for schedule criteria and data set activity, continued
4. Define an Event CYBER.EVENT3 that cycles the signal automatically. The Event definition statements look like this:
EVENT ID(CYBER.EVENT3) SCHEDULE 08:00 WEEKDAYS SIGCYCLE PROD.DATA ENDDEF
Now assume that todays schedule date is Monday (a weekday) and the signal PROD.DATA has not been posted by the time ESP reaches the scheduled processing time of 20:00. ESP does not execute Event CYBER.EVENT1, and interprets the signal as pending. As soon as the data sets in Event CYBER.EVENT1, have been closed, ESP will post the signal PROD.DATA and Event CYBER.EVENT2 will execute. At 8:00 a.m., Event CYBER.EVENT3 will execute to cycle the signal PROD.DATA to reset for the next days processing cycle. You can display signal information for the pending status by displaying the associated Event (CYBER.EVENT2) or using the LISTSIG command. For more information on displaying signals, see Displaying Signal Information on page 348. Also, if you would like Event CYBER.EVENT2 to execute without waiting for the signal, you can trigger it with either a FORCE or SATISFY keyword. For more information on pending signals, see How Pending Signals Work on page 350.
Example 3: Multiple processing runs
In the following example, a job stream is scheduled twice daily, at 11:30 and 13:30. If the first run has not completed by 13:30, then the second run should be cancelled. 1. Schedule an 11:30 Event daily to submit the first group of jobs. The Event definition statements look like this:
EVENT ID(CYBBP01.TR1) SCHEDULE 11.30 WORKDAYS INVOKE CYBBP01.ESPPROC.CLIST(TR1)
Using Signals
345
Combining Signals and Scheduling Criteria, continued

Example 3: Multiple processing runs, continued
2. In the first network, include a job that invokes ESP in batch and issues a SIGPOST to post the signal. The ESP Procedure looks like this:
DJCNET TR1 JCLLIB . . . JOB A RELEASE B JOB B RELEASE C JOB C RELEASE TR1END JOB TR1END ENDJOB SELECT (A,B,C,TR1END)
3. Schedule a 13:30 Event daily to submit the second group of jobs. Include a SIGWAIT command in the Event and logic in the ESP Procedure to check the time. The Event definition statements look like this:
EVENT ID(CYBBP01.TR2) SCHEDULE 13.30 WORKDAYS SIGWAIT CYBBP01.TR1END GEN(0) INVOKE CYBBP01.ESPPROC.CLIST(TR2) SIGCYCLE CYBBP01.TR1END The ESP Procedure looks like this: DJCNET TR2 JCLLIB . . . IF ESPATIME>13.31.00 THEN DO SEND 2ND RUN OF TR CANCELLED AT %ESPATIME CN(01) EXIT ENDDO JOB A RELEASE B JOB B RELEASE C JOB C ENDJOB SELECT (A,B,C) Continued on next page
346
Using Signals

Example 3: Multiple processing runs, continued

11:30
(Time)
PROD.TR1END
(Signal wait)
13:30
(Time)
CYBER.TR1
(Event)
CYBER.TR2
(Event)
TR1END
(Signal post)
ESP produces different results according to the time at which the first group of jobs terminates. If the TR1 jobnet completes prior to 13.30, the TR2 Event executes at 13.30 and ESP submits the TR2 jobnet. If the TR1 jobnet does not complete until after 13.30, the TR2 Event executes at that time and the TR2 jobnet is not submitted.
Using Signals
347
Displaying Signal Information

About displaying Display the signal information using any ESP access method: command in an signal Event, Line mode, Page mode or using a batch job. information
To display signal information, type the LISTSIG command and specify: The name of the signal. If you do not specify the signal prefix, ESP uses the current default prefix. Use a hyphen as a wildcard character (-) if you want to display all signals beginning with a particular prefix. The type of information you want ESP to display. For example, insert ALL if you want all information about a signal, or PENDING if you want information about pending signals only. If there is no condition in the statement, ESP displays summary information. ESP can display the following information on signals: Signal name. Absolute and relative generation numbers. Maximum number of generations.. Exact posting time, posting date, and the userid that posts each generation. Information about pending signals, if applicable, including the time and date at which the signal became pending, the name of the signal, and the associated Events.
Example: Displaying signals
In the following example, each of the statements requests a different type of signal information: Statement 1 requests all information about all generations of the signal called CYBER.PREPROC_COMPLETE.
listsig cyber.preproc_complete CYBER.PREPROC_COMPLETE, MAX GENERATIONS 5, ABSOLUTE GENERATION 1 --GEN 0 CYCLED BY CYBBP01 10.28 FRI29APR94
Statement 2 requests summary information about all signals beginning with the prefix CYBER. To signify this requirement, the statement uses the dash (-) as a wildcard character at the end of the signal prefix.
listsig cyber.SIGNAL-------------------PENDING-# GEN--MAX GEN CYBER.BOB 0 1 1 CYBER.FRANCIS_TEST 1 1 5 CYBER.PREPROC_COMPLETE 0 1 5 --- 3 ENTRIES DISPLAYED
348
Using Signals
Displaying Signal Information, continued

Example: Displaying signals, continued
Statement 3 requests all information about all signals with a prefix of CYBER.
listsig cyber.- all
CYBER.BOB, MAX GENERATIONS 1, ABSOLUTE GENERATION 1 --GEN 0 CYCLED BY CYBBP01 10.47 TUE 9NOV93 CYBER.FRANCIS_TEST, MAX GENERATIONS 5, ABSOLUTE GENERATION 1 --GEN 0 CYCLED BY CYBFM01 17.00 THU 5NOV92 ----EVENT CYBER.FMSIGW PENDING SINCE 10.32WED 25NOV92 CYBER.PREPROC_COMPLETE, MAX GENERATIONS 5, ABSOLUTE GENERATION 2 --GEN 0 CYCLED BY CYBBP01 10.29 FRI29APR94 --GEN -1 CYCLED BY CYBBP01 10.28 FRI29APR94 POSTED BY CYBBP01 10.29 29APR94 --- 3 ENTRIES FOUND
Statement 4 requests information on all pending generations for the signal called CYBER.TAPE_INPUT.
listsig cyber.tape_input pending CYBER.TAPE_INPUT, MAX GENERATIONS 5, ABSOLUTE GENERATION 2 --GEN 0 CYCLED BY CYBBP01 10.29 FRI29APR94 ----EVENT CYBBP01.TESTSIG PENDING SINCE 10.44FRI 29APR94
Using Signals
349
How Pending Signals Work

About pending signals
ESP considers a signal that was unposted at the scheduled execution time to be pending, because it is still outstanding at the scheduled execution time for the Event. ESP automatically adds warning comments to the Event to indicate the signal is pending. As a user, you can control the maximum number of pending signals permitted on a single Event. You can also issue follow-up commands to post the signal. Posting the signal changes the status from pending to posted. The following example illustrates a typical set of comments ESP automatically adds to an Event to warn that signals are pending:
EVENT ID(CYBBP01.TESTSIG) SYSTEM(ES43) REPLACE SCHEDULE 10.44 WORKDAY DAILY STARTING MON 2ND MAY 1994 SIGWAIT CYBER.PREPROC_COMPLETE GEN(0) SEND TEST OF SIGNAL USER(CYBBP01) /* THE FOLLOWING SIGNAL(S) ARE PENDING */ SIGPEND AT(10.44 1994APR29) SIGPNNM CYBER.PREPROC_COMPLETE ABSGEN(2)
ESP warning comments
The ESP comments are on the last three lines of the above example. SIGPEND indicates the time and date the signal became pending. SIGPNNM indicates the name of the pending signal and absolute generation number.
Limiting number of pending signals
To specify the maximum number of pending signals allowed for a single Event, use the MAXPEND keyword on the EVENT command.
EVENT ID . . . MAXPEND(number)
MAXPEND
Maximum number of pending signals ESP allows for the Event. When the quantity of pending signals exceeds this number, ESP deletes the oldest signal.
350
Using Signals
How Pending Signals Work, continued

Example: Defining maximum number of pending signals
The following example illustrates a statement that defines a maximum of two pending signals for an Event.
EVENT ID(PROD.DAILY_JOBS) MAXPEND(2)
If you do not define the maximum number of pending signals for an Event, the cycling process may cause ESP to delete a pending signal. In such situations, ESP sends a warning message advising the operator of a SIGLOST condition.
Triggering an Event that has a pending signal
To trigger an Event that has a pending signal, issue the TRIGGER command manually in Page mode, Line mode or using batch. You can specify: FORCE, to ignore any pending signals. SATISFY, to satisfy pending signals before processing the Event.
Using Signals
351
Manual and Automatic Posting of Signals

A user can enter a SIGPOST command manually to signify that signal About manual and automatic conditions have occurred. This is known as manual posting of a signal. As an posting of signals alternative you can enter SIGPOST commands in Events, ESP Procedures, and in batch jobs, so that ESP automatically posts the signal. The following example shows an Event that requires manual posting of a signal. In this situation an Event submits job JOBX at a scheduled time of 16:00 on weekdays. However, the job cannot run until the operator manually receives an input tape. Follow these steps to set up ESP signal processing: 1. Define a signal with five generations, enabling you to create a new generation of the signal each day for five days. The statement appears as follows:
DEFSIG CYBER.JOBX_TAPE GEN(5)
Example of manual Posting that requires manual receipt of input tape
2. Define the Event for CYBER.JOBX_TAPE and include waiting criteria using the following commands: SCHEDULE - to schedule the execution time SIGWAIT - to signal the Event to wait on a condition SUBMIT - to submit JOBX. The definition statements look like this:
EVENT ID(CYBER.JOBX_TAPE) MAXPEND(5) SYSTEM(ESPX) SCHEDULE 16:00 WEEKDAYS SIGWAIT CYBER.JOBX_TAPE SUBMIT CYBER.JCL(JOBX) ENDDEF
3. Type a SIGPOST command each weekday when the tape arrives. The command looks like this:
SIGPOST CYBER.JOBX_TAPE
The above command indicates to ESP that the signal conditions have occurred. ESP can then trigger the Event and submit JOBX whenever the scheduling criteria has occurred. 4. Cycle the signal by typing the following:
SIGCYCLE CYBER.JOBX_TAPE
352
Using Signals
Manual and Automatic Posting of Signals, continued

Automatic posting
To specify automatic posting of signals, use any of the following methods: A scheduled Event Job monitoring A trailer step in the JCL for the specific job An ESP command in a batch job. To set up automatic posting of signals: 1. Define a signal as described earlier in Setting up the signal processing environment on page 338. 2. Define the signal waiting criteria in a job Event as described in Setting up the signal processing environment on page 338. 3. Define a job monitor Event that executes at a job processing stage and invokes an ESP Procedure (see step 4 for definition of the ESP Procedure). A job monitor Event is a type of Event that checks on the progress of a job at a specific point in processing. For more information on job monitor Events, refer to Job Monitoring and Alert Processing on page 95. 4. Define an ESP Procedure to verify that the job completed successfully and to post the signal (if the job was successful). For more information on defining the ESP Procedure, refer to Sample ESP procedure invoked by job monitor Event on page 354. 5. Cycle the signal as described in Setting up the signal processing environment on page 338. Below is an example of a Job Monitor Event:
EVENT ID(CYBER.JOBA_JOBEND) INVOKE CYBER.ESP.PROCS(SIGNAL) ENDDEF
Using job monitoring to post a signal
Using Signals
353

Sample ESP procedure invoked by job monitor Event
Below is a sample of an ESP Procedure that monitors and posts signals. You may be able to adapt this ESP Procedure to your own requirements.
SIGNAL:ESPPROC C=_COMPLETE SIGNAME=PROD.%MNJOB%C IF MNCMPC EQ 0 THEN DO SIGPOST %SIGNAME EXIT ENDDO SE %SIGNAME NOT POSTED - %MNJOB HAS FAILED USER(BP01)
The job monitor Event invokes the above ESP Procedure. This ESP Procedure then performs the following actions: If the job runs successfully, the ESP Procedure issues a SIGPOST command to post the current generation of a signal with the name of PROD.jobname_COMPLETE. If the job fails, the ESP Procedure sends a message to the user, stating both the name of the signal that did not post and the name of the job that failed. The following example demonstrates how job monitoring can control job executions based on specific conditions.
Example: Job XWEEK conditional on job XDAY
For this example, assume that a job called XWEEK runs once a week on Saturdays. There is also a weekday job called XDAY that runs once daily for five days. However, you do not want XWEEK to run if any of the five runs of XDAY have not completed successfully. Follow these steps to set up the signal conditions: 1. Define a signal with five generations (a separate signal generation for each of the five runs of XDAY). This is how the statement appears:
DEFSIG PROD.XDAY_COMPLETE GEN(5)
354
Using Signals

Example: Job XWEEK conditional on job XDAY, continued
2. Define the Event for the job XWEEK and include the following commands: SCHEDULE - to schedule the execution time of the job XWEEK SIGWAIT - to include signal waits for each of the daily jobs The definition statements might look like this:
EVENT ID(CYBER.WEEKLY) SCHEDULE 16:00 SATURDAYS SIGWAIT PROD.XDAY_COMPLETE SIGWAIT PROD.XDAY_COMPLETE SIGWAIT PROD.XDAY_COMPLETE SIGWAIT PROD.XDAY_COMPLETE SIGWAIT PROD.XDAY_COMPLETE SUBMIT PROD.JCL(XWEEK) ENDDEF
GEN(0) GEN(-1) GEN(-2) GEN(-3) GEN(-4)
Visually the dependencies for the Event look like this:
PROD.XDAY_COMPLETE GEN(0)
(Signal)
PROD.XDAY_COMPLETE GEN(-1)
(Signal)
16.00 SATURDAY
(Signal)
CYBER.WEEKLY
(Event)
(Signal)
(Signal)
Using Signals
355

Example: Job XWEEK conditional on job XDAY, continued
3. Define a job monitor Event that: executes at the end of the job XDAY invokes an ESP Procedure (see step 4). The Event looks like this:
EVENT ID(PROC.XDAY_JOBEND) INVOKE CYB2.ESP.PROC(XDAY) ENDDEF
4. Define an ESP Procedure to perform tasks in the following order: check for successful completion of job XDAY automatically post the signal PROD.XDAY_COMPLETE as complete, if the job runs successfully. The Procedure looks like this:
XDAY:ESPPROC IF MNCMPC EQ 0 THEN + SIGPOST PROD.XDAY_COMPLETE GEN(0) ELSE SEND SIGNAL PROD.XDAY_COMPLETE NOT POSTED U(*)
5. Cycle the signal at the start of each weekday, by typing:

SIGCYCLE PROD.XDAY_COMPLETE
Using a JCL trailer step for automatic posting
As an alternative to job monitoring, use a trailer step in the jobs JCL to post a signal automatically. A trailer step comes at the end of a job. The trailer step must invoke ESP in batch and post the signal automatically with a SIGPOST command.
356
Using Signals

Example: Using a trailer step to Assume the situation is the same as in the previous job monitoring example. post a signal
Eliminate the steps for defining a job monitor Event and ESP Procedure (steps 3 and 4 of the previous job monitoring example). Instead, define a trailer step in the JCL for the job called XDAY. This is how the JCL statements for the trailer step definition look for job XDAY:
//LASTSTEP EXEC PGM=ESP,REGION=4000K //SYSPRINT DD SYSOUT=* //SYSIN DD * SIGPOST PROD.XDAY_COMPLETE
When this step executes, ESP posts the signal PROD.XDAY_COMPLETE as complete.
Using Signals
357
358
Using Signals
GLOSSARY Terms and Descriptions
Alert
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.
Application Application Wait
Audit log
Authorization string
Authorization table
AUTOVAR
Calendar
CCFAIL
CLANG
Glossary
359
Glossary, continued
Condition code
A code indicating the results of processing a job step. Location of a copy of the submitted JCL. An ESP facility for displaying and manipulating the workload. 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 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.
COPYJCL Consolidated Status Facility Descriptor code
DJC
DJC job network
ESP Application External job
Event
Event data set
Event group
EVENTSET
360
Glossary
Glossary, continued
Group
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.
HISTFILE History file
Job index data set
Job monitor
Job tracking
Job tracking definition table Link
Manual job
Model
Page mode
Glossary
361
Glossary, continued
P-Node
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. An addition to the jobs name, used to uniquely identify similar jobs. 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. An item of hardware, a software resource or an abstract condition. 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.
Post
Predecessor job
Qualifier
REXX
Resource
Route code
SAD file
SAF
Schedule
362
Glossary
Glossary, continued
Signal Special day
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 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. An integer or a character string whose value ESP substitutes at processing time. Symbolic variable library; data set(s) members used to store symbolic variables. A facility used to intercept system messages as they are written to the system message data set. A product installed to implement system security. Also known as the host security system or product. An element of an Application that requires completion. For example, a task may represent the checking of a report. A centralized definition of the attributes and processing phases of a group of jobs.
Special period
SubApplication Subsystem
Successor job
Symbolic variable
SYMLIB
System message interception System security product Task
Tracking model
Glossary
363
Glossary, continued
TRAKFILE
Tracking file; a non-VSAM data set used to store job tracking data. 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.
userid
364
Glossary
Symbols
%CE function 37 %ENDEXCL, statement 48 %EXCLUDE statement criteria 79 multiples 81 symbol library 47 %INCLUDE statement copy JCL 81 criteria 79 examples 80 multiples 81 symbol library 47 /*ROUTE statement 70
built-in variables
96
C
calculating the number of weeks in a period Calendar 359 CCCHK statement 72 combinations 75 format of 72 where used 74 CCFAIL 359 CCFAIL statement 77 examples 78 format 77 changing initiators during modeling 247 CLANG 359 combining 142 CLANGVAR 279 CLANGVAR function 278 CLRSYSMS command 231 combining CLANG elements 142 combining signals 343 commands SCAN 94 compound symbolic variables 31 Condition code 360 condition code checking limiting 72 condition codes 71 specifying action 73 specifying success or failure 73 Consolidated Status Facility 360 constants, with symbolic variables 27 continuing processing 73 control card, building 145 control statements 79 changing symbol introducer 82 copying JCL %INCLUDE statement 81 COPYJCL 360 creating longer field length 29 cycling a signal 342 138
A
ABENDs monitoring for 108 adding a restart step 69 ADJUST command 248 Alert definition 359 Alert processing 96 ALERTDEF command 113, 114 Alerts 112 displaying 114 NOTIFY statement 112 steps to use 112 triggering specific Event 116 Application 360 Application Wait 359 Applications running all or part 190 using templates 219 ASCBADDR function 283 ASID function 283 attributes, specifying 162 Audit log 359 Authorization string 359 Authorization table 359 automatic posting of signals 353 automatic SADLOAD command 155 automatic variables default 90 global 89 job specific 89 numbering 88 AUTOVAR 359 default 90 global 89 ISTEP 90 job specific 89 TSTEP 91
D
data set trigger 177 data sets Panvalet 65 DATASET statement 313 DAYS_BETWEEN function 139 default AUTOVAR 90 DEFGROUP command 104 DEFINED function 44 Defining symbol library 45 tracking model for job monitoring defining a job as a node 150 defining holidays 216 defining initiators 247 DEFPRINT command 251
102
B
building a control card 145 built-in symbolic variables 15
Index
365
DEFPRIO command 249 DEFSIG command 339 DEFSPEC command 300 DEFSYML command 45 DEFTM command 102, 104 delay releasing a job 174 dependencies resolving using SAD 154 step-level 202 Dependent Job Control 307 Descriptor code 360 DFPNODE command 236 displaying signals 348 DJC 307, 360 benefits of using with ESP 308 defining external jobs 322 defining manual jobs 323 identifying JCL libraries 312 processing steps 308 using existing NET control cards DJC job network 360 DJCDATA statement 321 DJCNET statement 311
forecasting 239 possibilities 240 formatting functions, built-in
37
G
GENTIME command 21, 132, 133 examples 24 using multiples 23 global AUTOVAR 89 GLOBALVARIABLES 208 Group 361 group name, monitor 104 groups monitor 104
H
328 HISTFILE 361 History file 361 Hold count job in a network 308 holidays defining with templates
216
E
ENDMODEL command 255 ENDPRINT command 251 ENDTEMPL statement 206 ESP Application 360 ESP Procedures invoking 140 invoking from different Events 141 invoking from Event 98 running 140 Event 360 Event data set 360 Event group 360 Events function of monitor or Alert 98 invoking an ESP Procedure 98 monitor 96 triggering with pending signals 351 EVENTSET 360 excluding specific lines of JCL 84 exclusion sign () 84 exclusion statements 48 EXECIO DISKW command 301 external dependencies, resolving 154 External job 360 external job 163 external job with a previous scheduled date 167, 168 external job with the same scheduled date 166 EXTERNAL keyword 322 external links, resolving 155
I
INHERIT 149 inherit all relationships 149 INHERIT attribute 148 INHERIT, on JOB statement 149 INHERIT, on OPTIONS statement 149 inheritance, processing of 149 inherited relationships overriding 148 INIT command 247 initial step automatic variables 90 initiators defining 247 INVOKE command 41 invoking an ESP Procedure 140 invoking templates 213 ISTEP AUTOVARS 90
J
JCL and Panvalet data sets 65 excluding specific lines 84 multiple jobs in one member 328 simulating 93 JES queue, checking job 146 JES3 307 job delaying release of 174 resbumitting following failure 118 job AUTOVAR 89 Job index data set 361 Job monitor 361 job monitor Event
F
failure 73 field length, increasing 29
366
Index
prefix 103 trigger on job step completion 107 job monitor variables in Procedure 114 job monitoring 96, 227 setting up 102 job network defining 310 defining job relationships 319 job networks 308 statements 334 submitting 333 Job tracking 361 job tracking 227 Job tracking definition table 361 JOBATTR statement 162 Jobname 313 JOBONCSF function 284 JOBONQ 146 jobs attributes 162 controlling release of 174 defining as a node 150 external or manual 163 posting bypassed 171 scheduling multiple runs 182 setting priority 249 submitting based on data set activity 188 submitting based on termination 180 submitting on data set closure 188 submitting outside ESP 94 time-based actions 193
maximum number of initiators 247 setting time period 249 using batch job 245 using CLANG 249 what you can forecast 240 modelling activating 244 monitor Event format of name 106 functions of 98 naming 106 prefix in job tracking model 103 monitor Events 96 monitor group name 104 in job statement 105 monitor groups 104 monitor points 101 monitor variables 96 built-in 124 how they work 97 sending message to console 115 monitored information, storing 99 monitoring completion of online system 110 how it works 101 setting resource on online start 110 using generic tracking 103 monitoring for an ABEND 108 monitors group name 104 planning 100 MREPORT command 252 multiple runs, scheduling 182
L
Link 361 links, resolving external 155 listing system messages 231 LOCALVARIABLES 208 longer field length 29 Looping operations 272 LSYSMSGS command 231
N
NET control cards 319 Network hold count 308 NODE keyword 149 NODE keyword on a JOB statement 150 NOINHERIT keyword 152 NOINHERIT, on JOB statement 149 NOINHERIT, on OPTIONS statement 149 NOPOST_OLDEST 163 NOPOST_UNTIL_READY 163 NOPOST_WHILE-WAITING 163 notification of status 179 NOTIFY statement 112 number of weeks in a period, calculating 138 numbering automatic variable 88
M
Manual job 361 manual job 163 manual job that runs multiple times 169 MANUAL keyword 323 Manual P-Nodes 233 manual posting of a signal 352 Model 361 modeling 239 defining CPUs 247 defining model 246 defining report 251 defining your environment 247 ending definition 255 how to create 243 limititations of 241
O
online system, monitoring for completion of 110 online, setting resource based on start of 110 optional predecessors 176 OPTIONS NOINHERIT 150 OPTIONS statement 319 INHERIT 149 overriding inheritance 149
Index
367
P
Page mode 361 Panvalet data sets 65 pending signals 350 P-Node 362 P-Nodes 233 defining manual 234 EXEC 233 INPUT 233 manual 233 OUTPUT 233 Post 362 POST_WHILE_WAITING 163 posting a signal 341 posting external or manual jobs 163 posting of signals, automatic 353 posting options 165 POST-OLDEST 163 Predecessor job 362 predicting schedules 239 prefix 103 priority 249 Procedures recursive 147 processing nodes 233 processing of inheritance 149
Q
Qualifier 362
R
recursive procedures 147 REEXEC statement 146 RELCOUNT statement 176 release controlling 174 Repetitive actions using REXX 272 reporting scheduled activity 239 reports modeling 251 samples 253 selecting 252 TITLE command 251 request job 171 rerunning a subApplication 191 resolving external dependencies 154 resolving external links 155 Resource 362 RESOURCE command 248 RESOURCE statement 248 restarting 69 resubmittin a job using symbolic variables 36 Resubmitting job once following a failure 118 REXX 271, 362 assigning variables 277
benefits of using 272 building ESP Applications 296 built-in functions 280 built-in functions in CLANG 280 commands and functions with TSO equivalent 282 continuing commands 276 defining a holiday 303 defining special days 300 execs 303 functions available with no CLANG equivalent 283 inserting request jobs 294 issuing TSO commands 275 limitations 273 trapping output 289 updating symbolic variable 301 using ESP commands 276 REXX exec simulating Event multiple times 305 REXXOFF statement 274 REXXON GEN 274 REXXON PROC 274 REXXON statement 274 Route code 362 ROUTE XEQ statement 70 routing jobs 70 run certain day of week 131 run every two weeks 130 run on even days 130 run on scheduled hour 133 run on specific workday 132 run specific weeks 131
S
SAD file 362 SAD file, for resolving dependencies 154 SADLINK 155 SADLINK parameter 154 SADLOAD command 155 SADLOAD command, automatic 155 SAF 362 SCAN command 94 Schedule 362 schedule criteria complex 130 day of week 131 every two weeks 130 relative to next month 133 scheduled hour 133 specific weeks 131 specific workday 132 SCHEDULED 163 Scheduled Activity data set, creating 257 scheduled activity data set, creating 243 scheduled activity reporting 239 schedules predicting 239
Index
368
scheduling even days 130 scheduling multiple runs 182 SCOPE parameter 156 SCOPEwith RESOLVE 160 secured symbol, identifying 83 shutdown of system 147 SIGCYCLE 341 SIGCYCLE command 342 Signal 363 how they work 338 signals 337 combining 343 cycling 342 defining 339 displaying 348 how they work 338 manual posting of 352 pending 350 posting 340, 341 posting automatically 353 setting up environment 338 uses for 338 SIGPOST command 341, 352 SIGWAIT command 340, 343 SIMULATE command 93 Simulating Event REXX exec 305 simulating JCL 93 Special day 363 Special period 363 special period 136 calculating number of weeks 138 determine where you are 136 finding absolue number of 139 generate symbolic variable 137 nth workday 137 statements CCCHK 72 step-level dependencies 202 stopping processing 73 SubApplication 363 subApplications 184 bypassing if not started by 200 for different job streams 184 for special requests 186 submitting job networks 333 submitting jobs outside of ESP 94 substring notation examples 28 substring notation, format 28 Subsystem 363 success, specifying 73 Successor job 363 symbol introducer, changing 82 Symbolic variable 363 symbolic variable library 45 access to 46 excluding statements 48
in Events 46 list of 46 symbolic variables Application 59 assigning value to integer 20 assigning values 19 benefits of using 12 built-in 15 built-in date/time 14 concatenating 26 creating date parameter 15 date-qualified data sets 66 day of month 15 day of year 15 defining daily variations 31 defining scheduling criteria 53 defining time dependencies 52 environment 57 format of 13 formatting functions 37 GENTIME 61 in Applications 42 in commands 54 in ESP Procedures 41 in JCL 64 integer 18 interpretation 99 literal strings 27 monitor 96 month 15 multiples 18 next workday 22 prefixes 14 purging output 54 resbumitting a job 36 rules for user-defined 17 sending a message to console 14 setting based on criteria 142 sibstring notation 28 specifying job names 51 storing in Procedure 41 symbol introducer 97 testing 25 time-based 55 to run adhoc jobs 35 types of user-defined 17 undefined 50 USER 33 user-defined, meanings 17 using different introducer 13 using quotations marks 19 where to insert 12 with constants 27 with long values 68 with templates 207 symbolic variables, compound 31 symbols securing 83 SYMLIB 363
Index
369
Synchronizing applications 164 SYSMSGS command 232 System message interception 363 system messages clearing 231 enabling 231 listing 231 system messages, tracking 228 System security product 363
T
Task 363 TEMPLATE statement 206, 208 Templates running an hourly job 226 similar jobs with relationships 221 templates changing 215, 222 checking system activity 211 creating 222 defining holidays 216 defining subApplications 224 ending definition 207 in Applications 219 invoking 213 multiples 214 overriding information 223 passing information to 207, 210 passing variables to JCL 225
setting up 206 starting definition 207 using symbolic variables 207 what they are 205 TIME command 249 TITLE command 251 tracking setting up 228 system messages 228 Tracking model 363 tracking models generic 102 trailer step automatic variables 91 TRAKFILE 364 TSO commands 275 TSTEP AUTOVAR 91
U
undefined symbolic variables 50 USER parameters to resubmit a job 36 USER parameters,running adhoc jobs 35 USER symbolic variables 33 user-defined symbolic variables,types 17 userid 364
V
variables built-in monitor 96
Index
370
Readers Comment Form

We want to hear from you!
Please use this form to communicate your comments about this publication, its organization or subject matter. All comments will be considered when conducting future revisions to the manual. Note: Your comments are provided 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. Page Number
Comment
Do you wish a reply to your comments?
Cybermation will reply to your comments, if you request it. Please provide us with your name and address below. Name Company Address Fax e-mail Note: Please note that comments that justify a reply should be of a more technical nature (i.e. beyond comments about typographical errors).
Mail this form to: Cybermation Inc.
80 Tiverton Court Markham, Ontario L3R 0G4 Attn: Information Development

Or fax it to:
Information Development (905) 479-5474

Esp Advance Dug

Uploaded by

Copyright:

Available Formats

Esp Advance Dug

Uploaded by

Document Information

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 Advance Dug

Uploaded by

Copyright:

Available Formats

What is the document about?

What is the document about?

What are symbolic variables?

What are symbolic variables?

ESP Workload Manager

Advanced Users Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

Using Symbolic Variables

ESP Workload Manager Version 5.2

Advanced Users Guide

Job Monitoring and Alert Processing

Advanced Use of ESP Procedures

Advanced Use of Applications

ESP Workload Manager Version 5.2

Advanced Users Guide

Using REXX with ESP

Using ESP With DJC/JES3 Job Networks

ESP Workload Manager Version 5.2

Advanced Users Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

About This Guide

About This Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

About This Guide, continued

Continued on next page

About This Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

About This Guide, continued

Data sets Members Jobs.

About This Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

New information The following symbolic variables have been added:

About This Guide

ESP Workload Manager Version 5.2

Advanced Users Guide

Using Symbolic Variables Overview

Using Symbolic Variables

ESP Workload Manager Version 5.2

Advanced Users Guide

About Symbolic Variables

Where to insert symbolic variables

Using Symbolic Variables

ESP Workload Manager Version 5.2

Advanced Users Guide

Getting Started With Symbolic Variables

Using Symbolic Variables

ESP Workload Manager Version 5.2

Advanced Users Guide

Using Built-In Symbolic Variables

Format of a built-in symbolic variable name

Understanding the prefixes

Example 1: An EVENT using built-in symbolic variables to send a message

Following is an example of the message on console 1 if this EVENT is triggered at 09.45.07:

Continued on next page

Using Symbolic Variables