ESP Workload Manager: Advanced User's Guide

ESP Workload Manager
Version 5.2
Advanced Users Guide
ESP-AU-02
ii
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.
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.
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.
ESP Workload Manager Version 5.2 Advanced Users Guide
Contents iii
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 J ob 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 J obs to Other J ES Nodes........................................................ 70
Checking Condition Codes.................................................................. 71
Using the CCCHK Statement.............................................................. 72
Using the CCFAIL Statement.............................................................. 77
Including and Excluding J CL.............................................................. 79
Modifying the Symbol Introducer....................................................... 82
Assigning Security to a Symbol .......................................................... 83
Using an Exclusion Sign...................................................................... 84
Using Automatic Variables (AUTOVARS)........................................ 87
Simulating the J CL ESP Submits........................................................ 93
Submitting J obs Outside ESP.............................................................. 94
iv Contents
Job Monitoring and Alert Processing
Comparing Job Monitoring and Alert Processing............................... 96
Functions of J ob Monitoring and Alert Processing............................. 98
Planning for J ob Monitoring and Alert Processing........................... 100
How J ob 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 J obs................................................ 163
Controlling the Release of J obs......................................................... 174
Scheduling Multiple Runs of a J ob.................................................... 182
Using SubApplications...................................................................... 184
Submitting Different J obs 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
Contents v
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 J ob Network...................................................................... 308
Defining the J ob Network.................................................................. 310
Selecting J obs for Submission........................................................... 316
Specifying Other DJC Parameters..................................................... 321
Defining Other Types of J obs............................................................ 322
Examples of DJ C Networks.............................................................. 324
Submitting J ob Networks.................................................................. 333
Statements to Define J ob Networks................................................... 334
vi 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
About This Guide 7
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
This guide is for the scheduler who has experience with ESP and a general
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
8 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 J CL.
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 DJ C or J ES3 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 9
About This Guide, continued
Conventions used
in this guide
This guide uses uppercase letters for naming the following:
Data sets
Members
J obs.
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.
10 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.
Changed
information
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.
New information The following symbolic variables have been added:
ESPSID
ESPSMFID
ESPSUBSYS
CPUSERIAL
CPUMODEL
SYSJ NAME
HWNAME
LPARNAME
VMUSERID
SYSPLEX
SYSNAME
SYSCLONE
ESPDSN.
Using Symbolic Variables 11
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.
In this chapter This chapter contains the following topics:
Topic See Page
About Symbolic Variables 12
Getting Started With Symbolic Variables 13
Using Built-In Symbolic Variables 14
Working With User-Defined Symbolic Variables 16
Working With Undefined Symbolic Variables 50
Specifying J ob 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
12 Using Symbolic Variables
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.
Where to insert
symbolic
variables
You can insert symbolic variables in:
ESP Procedures
J ob Documentation members
Events
J CL
Symbolic variable libraries
ESP Initialization Parameters
USER1,2,3,4 parameters (with TRIGGER and APPLJ OB RESUB
commands)
Text of the TITLE and FOOTING commands of ESP.
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.
Format of
symbolic variable
conventions
Each type of symbolic variable has its own format.
The following conventions apply to all ESP symbolic variables:
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 Explanation
% - Symbolic
Variable Introducer
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
J EAN.
Other Introducers To use a different introducer:
Make a global change to an ESP initialization
parameter or
Change the introducer in the J CL for a single job or
Use a double percentage sign %%.
Single Quotation
Marks ()
Enter at the beginning and end of the symbolic
variable value whenever you assign a value to
symbolic variable name.
For example, P=IEFBR14
End of symbolic
variable
Use any of the following to signify the end of a
symbolic variable name:
A period.
Another separator (such as a space, comma or a semi-
colon).
Another introducer character and symbolic variable.
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.
Format of a
built-in symbolic
variable name
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.
Understanding
the prefixes
Refer to the following for a description of 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 built-
in 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

Prefix Explanation
ESPA Tells ESP to substitute the actual submission value.
ESPS Tells ESP to substitute the scheduled value at the time
of processing.
Using Built-In Symbolic Variables, continued
Example 2: Built-
in symbolic
variables create a
date parameter
This example uses built-in symbolic variables to represent a date parameter
that shows the numbers of the scheduled month, scheduled day, and scheduled
year. Assume you want the format of the date parameter to look like this:
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 Substituted values of April 20, 1998
%ESPSMM%ESPSDD%ESPSYEAR
04011998
Working With User-Defined Symbolic Variables
Overview
Introduction This section explains the two types of user defined symbolic variables and how
they are used.
In this section This section contains the following topics:
Topic See Page
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
Types of User-Defined Symbolic Variables
About user-
defined 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.
Format of user-
defined symbolic
variables
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.
Understanding
user-defined
symbolic
variables
Following are the characteristics or character strings and integers:
Symbolic Variable Explanation
Character 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.
Integer 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.
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
Example 2:
Defining multiple
integer symbolic
variables
You can also declare more than one symbolic variable in the same statement.
The following line declares integer I, WEEK#, and DD:
INTEGER I,WEEK#,DD
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, J OBNAME=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.
Assigning a Value to a Symbolic Variable, continued
Assigning a value
to a defined
integer
An integer variable requires a definition before you can assign a value to it.
The following example shows how you can assign a value to an 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
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.
Format of the
GENTIME
command
Following is the format of the GENTIME command:
GENTIME prefix criteria
Description of
the GENTIME
command
Following is a description of the parts of the GENTIME command:
Field Description
GENTIME Is the command name.
Must be entered in uppercase.
Prefix Is the part of the GENTIME command that you
assign.
Can be from 1 to 8 characters (national characters,
such as #, are acceptable).
Note: The prefixes ESPA and ESPS are reserved for
ESPs built-in symbolic variables and cannot be used in
the GENTIME command.
Criteria 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.
Customizing Date and Time Variables Using GENTIME,
continued
Example of
generating a
date/time
symbolic
variables
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
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
%NWMM%NWDD%NWYY 081099
continued
Using multiple
GENTIME
commands
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
If today is August 12, 1999, the symbolic variable PWKDATE resolves to
August 5, 1999 and PWDDATE resolves to August 4, 1999.
continued
Other examples
using GENTIME
The following table lists some typical schedule criteria for a GENTIME
command. You can adapt the format from these examples for use in your own
GENTIME commands:
Scheduling
Criteria
User
Prefix
GENTIME
Statement
Seven days after
today
OVER GENTIME OVER TODAY PLUS 7
DAYS
Two workdays before
today
PPD GENTIME PPD TODAY LESS 2
WORKDAYS
Previous workday PD GENTIME PD TODAY LESS 1
WORKDAY
Previous day TMSPD GENTIME TMSPD TODAY LESS 1
DAY
Next day TMSND GENTIME TMSND TODAY PLUS 1
DAY
Next workday ND GENTIME ND TODAY PLUS 1
WORKDAY
Two workdays after
today
NND GENTIME NND TODAY PLUS 2
WORKDAY
One week prior to
today
LW GENTIME LW TODAY LESS 1
WEEK
First day of current
month
BGMNTH GENTIME BGMNTH 1ST DAY OF
MONTH STARTING TODAY
Previous month PMNTH GENTIME PMNTH 1ST DAY OF
MONTH LESS 1 MONTH
STARTING TODAY
First day of previous
month
PMNTH1 GENTIME PMNTH1 1ST DAY OF
MONTH STARTING
%PMNTHDATE
continued
Testing date/
Time symbolic
variables
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:
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
GENTIME
The following example shows how to test the generated symbolic variables:
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:
Step Action
1 Enter the GENTIME command with your prefix and criteria.
1 Enter the ECHO command to send the symbolic variables back to
your terminal for display
%PDMM%PDDD%PDYY 091998
Symbolics
Substituted Values on
September 20, 1998
Combining Symbolic Variables with Other Variables
Overview You can combine symbolic variables with the following:
Other variables
Literal character strings
Constants.
Understanding
concatenation of
symbolic
variables
To combine symbolic variables, you concatenate or attach the symbolic
variable to another character or group of characters.
Example 1:
Concatenation of
multiple
symbolic
variables
To assign values to variables V1 and V2, your statements might look like this:
V1=ABC
V2=DEF
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.
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 J anuary, the result is
V5=01PAYROLL.
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.
Format of
substring
notation
The syntax for substring notation is:
%symbolic(start_position:end_position)
Understanding
the format of the
substring
notation
Refer to the following for a description of the parts of the substring format:
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.
Example 1:
Create a shorter
version of the
symbolic variable
In this situation, you want the result to be HIP. To remove the characters at
the end of the symbolic variable name, enter the following:
%LONGWORD(3)
Field Description
symbol The name of the symbolic variable.
start_position The starting position in the symbolic variable.
Note: If end_position is omitted, this represents the
length of the substring, beginning at position 1.
end_position The ending position in the symbolic variable.
Note: This field is optional.
Using Substrings, continued
Example 3:
Creating a longer
symbolic variable
To force a longer field length, ESP can add trailing blanks to the end of the
symbolic variables value.
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.
Example 4:
Substring
notation sets field
length of date
Assume that today is Sunday, September 20,1998. The following table
demonstrates several methods of entering symbolic variable names and the
corresponding values for each symbolic variable:
Symbolic Variable Name Corresponding Values
%ESPADAY SUNDAY
%ESPADATE SUNDAY 20TH
SEPTEMBER 1998
%ESPAMONTH(2) SE
%ESPAYEAR(3:4) 98
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.
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.
Format of
compound
symbolic
variables
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)).
Example of using
compound
symbolic
variables
The following example uses compound symbolic variables to define daily
variations. In this example, you require different tape volume serial numbers
for a job, depending, on the day of the week you schedule a job. Follow these
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 J CL input looks like this:
VOL=SER=%VOLX
Working With Compound Symbolic Variables, continued
Example of using compound symbolic variables, continued
If ESP submits the above J CL on a Tuesday, it produces the following results:
VOLX=`%VOL3'
VOLX=`TAPETUE'
VOL=SER=TAPETUE
VOLX=`%(VOL%ESPSDOW#)'
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 J CL. Each
variable can be up to 80 characters in length.
Example 1:
Sending a
message
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
SEND %USER2 USER(%USER1)
2. Define an Event to invoke the above Procedure, like this:
EVENT ID(USER01.SEND_MESSAGE)
INVOKE CYB.ESP.PROCS(SENDMSG)
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(*****************************)
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
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.
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.
Using built-in
formatting
functions
You can use any of the built-in formatting functions appearing in the following
table:
Function Format of Output
%CE Centers the assigned value within the output.
%RJ J ustifies 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)
%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.
Formatting Symbolic Variable Output, continued
Using built-in formatting functions, continued
Function Format of Output
%EVAL 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
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
Fn Sets a field to a fixed length, with leading zeros preceding the
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).
Zn 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).
Using output format descriptors, continued
Descriptor Explanation
V Sets a field to a variable length with no leading zeros and blank
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.
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.
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 J CL for jobs submitted as part
of this
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 J OB
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.
Application CYB.SYMBOLS(DATES)
APPL BILLING
JCLLIB SYS1.JCL
INVOKE
CYB.SYMBOLS(DATES)
JOB
.
.
.
ENDJOB
GENTIME ND TOMORROW
DATE1=%NDMM%NDDD%NDYY
MYDSN=CYB.ESP.DATA
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
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.
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.
DEFINED Checks to see if a symbolic variable has been defined. It
returns either a 1 for true or a 0 for false.
LENGTH 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.
SUBSTR 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.
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
library
/*************************************************
/* THIS IS THE GLOBAL SYMBOLIC VARIABLE DATA SET*/
/* 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
GENTIME FW FIRST WORKDAY OF MONTH STARTING TODAY
GENTIME LW LAST WORKDAY OF MONTH
GENTIME PWD TODAY LESS 1 WORKDAY
GENTIME NWD TODAY PLUS 1 WORKDAY
Using Symbolic Variable Libraries, continued
Accessing
symbolic variable
libraries
Access to symbolic variable libraries depends on your security system and on
how your system administrator has assigned access to ESP. A system
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.
Referencing
libraries in
Events
You specify symbolic variable libraries in Events using a SYMLIB command.
The following example shows a typical command of this type.
SYMLIB SYMSET1
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.
Viewing lists of
symbolic variable
libraries
You can view lists of symbolic variable libraries that are already defined.
These lists display the following:
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
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 VALUE
J anuary 1st to May 31st ANY OLD DATA
J une 1st to J une 30th VALUE FOR JUNE
J uly 1st to J uly 31st VALUE FOR JULY
August 1st to December 1st ANY OLD DATA
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
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.
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.
Example 1:
Inserting the flag
indicator
In this situation, suppose that you erred when naming the symbolic variable
%ESPSDD. Assume you typed %EXPSDD by mistake. Due to the spelling
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).
Specifying Job Names
Overview You can use symbolic variables in ESP Procedures to specify job names or
parts (i.e. substrings) of job names.
Example: 3rd
and 4th
character
represent data
center code
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
This allows you to use common Procedures that ESP can invoke through
different Events, as shown below.
LAX.DAYJOBS
Event ESP Procedure Jobname
JOB ORLA1234
SFO.DAYJOBS
JOB OR%DC.1234
JOB ORSF1234
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 non-
workdays.
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
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
symbolic variable
to represent
schedule criteria
This example uses a symbolic variable called X_SCHEDULE to represent the
schedule criteria for job X in two different Applications. J ob X is submitted as
part of APPL1 and is external to APPL2.
APPL APPL1
JCLLIB SYS1.JCL
INVOKE CYB.ESP(SCHED)
JOB X
RUN %X_SCHEDULE
ENDJOB
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, J ES, and so
on.).
Example:
Purging Output
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.
INTEGER NUMBER
NUMBER=DAYS_FROM(TODAY LESS 3 WORKDAYS)
VS $PQ,Q=U,A=%NUMBER
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.
Time-based
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 Symbolic
Variable
Description
Date ESPADATE
ESPSDATE
Event date in full.
Example: Sunday 4th January 1998
Year ESPAYY
ESPSYY
ESPAYEAR
ESPSYEAR
Last two digits of the year.
Example:98
Year.
Example: 1998
Month ESPAMM
ESPSMM
ESPAMMM
ESPSMMM
ESPAMONTH
ESPSMONTH
Number of month.
Example:01 for J anuary
First three characters of month.
Example: J an
Name of Month.
Example: J anuary
Day ESPADAY
ESPSDAY
ESPADD
ESPSDD
ESPADDD
ESPSDDD
ESPADOW#
ESPSDOW#
Name of the day
Example: Monday
Number of actual day of month.
Example: 09
J ulian day, or the number day in the year.
Example: 365
Number of day in week, regardless of first day of
week setting in a calendar.
Example: 1 for Sunday, 2 for Monday, etc.
Built-in Symbolic Variables, continued
Time-based symbolic variables, continued
Type Symbolic
Variable
Description
Time ESPATIME
ESPSTIME
Time in 24 hour format.
Example: 14.55.32
Hour ESPAHH
ESPSHH
Hour in 24 hour format.
Example: 14
Minutes ESPAMN
ESPSMN
Minute of hour.
Example: 55
Seconds ESPASS
ESPSSS
Number of seconds past the minute.
Example: 32
Environment
symbolic
variables
These are variables that hold values describing the local or Event environment.
Type Variable Description
Local ESPSID
ESPSMFID
ESPSUBSYS
CPUSERIAL
CPUMODEL
SYSJ NAME
HWNAME
LPARNAME
VMUSERID
SYSPLEX
SYSNAME
SYSCLONE
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
Event ESPDSN
ESPEVENT
ESPGROUP
ESPJ OBN
ESPMEMBER
ESPTRUSR
ESPUSR
Name of the data set that is calling up the
current data line. This symbolic variable
can only be used in J CL.
Name of the Event.
Current ESP group.
Current job name. This symbolic variable
can only be used in J CL.
Name of the library member if any (null if
data set is sequential). This symbolic
variable can only be used in J CL.
ID of the user who triggered the Event.
ID of the user who defined, or last
modified, the Event.
Environment symbolic variables continued
Data set
Trigger Event
ESPTRDSN
ESPTRJ OB
ESPTRVOL
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.
ESP
Procedure
ESPINFOREC
ESPJ QUAL
ESPREEXEC#
ESPSADG
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 DJ C/J ES3 network.
Number of re-executions of an ESP
Procedure.
If SADGEN run=1, otherwise=0.
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.
Application ESPAGEN
ESPAJ OB
ESPAPPL
ESPAPQUAL
ESPASUB#
ESPATAG
ESPCUJ OB
ESPCUQUAL
ESPRRJID
ESPRRJOB
FROMSTEP
RESUB_USER
ROOTJ OBS
TOSTEP
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
Qualifier of the current job in an Application.
This variable is available during Application
J ob number of job being rerun.
J ob 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.
Application symbolic variables, continued
Flags ESP_APPL_GEN
ESP_APPL_PROC
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.
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.
Date prefixDATE Event date in full.
Example: Sunday 4th J anuary 1998
Year prefixYY
prefixYEAR
Last two digits of the year.
Example: 98
Year.
Example: 1998
Month prefixMM
prefixMMM
prefixMONTH
Number of month.
Example: 01 for January
First three characters of month.
Example: J an
Name of month.
Example: J anuary
Day prefixDAY
prefixDD
prefixDDD
prefixDDQL
prefixDOW#
Name of the day of the week.
Example: Monday
Number of actual day of month.
Example: 09
J ulian 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 prefixTIME Time in 24 hour format.
Example: 14.55.32
Hour prefixHH Hour in 24 hour format.
Example: 14
Minutes prefixMN Minute of hour.
Example: 55
Seconds prefixSS Number of seconds past the minute.
Example: 32
Tailoring J CL 63
Tailoring JCL
Overview
Introduction You can selectively tailor the J CL that ESP submits to the J ES internal reader
by entering symbolic variables and control statements in J CL. 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 J ES node, and
add a condition code check step to the J CL it submits by entering statements in
an ESP Procedure.
Topic See Page
Examples of Using Panvalet Data Sets 65
Adding a Restart Step 69
Routing J obs to Other J ES Nodes 70
Checking Condition Codes 71
Using the CCCHK Statement 72
Using the CCFAIL Statement 77
Including and Excluding J CL 79
Modifying the Symbol Introducer 82
Assigning Security to a Symbol 83
Using an Exclusion Sign 84
Using Automatic Variables (AUTOVARS) 87
Simulating the J CL ESP Submits 93
Submitting J obs Outside ESP 94
64 Tailoring J CL
About symbolic
variables
You can use symbolic variables in ESP to modify J CL, reducing or eliminating
the number of manual J CL changes. This saves time and reduces errors.
You may use symbolic variables anywhere in J CL 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.
Tailoring J CL 65
Examples of Using Panvalet Data Sets
About Panvalet
data sets
The use of Panvalet data sets with sequence numbers to hold runtime J CL 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 J CL 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
a date as input
In this example, the J CL contains some ESP built-in symbolic variables to
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 J CL.
//SYSIN DD *
%ESPSMM%ESPSDD%ESPSYY
When ESP submits this J CL for an Event scheduled on J une 9,1998, ESP
substitutes the built-in symbolic variables as shown below.
//SYSIN DD *
%ESPSMM%ESPSDD%ESPSYY
//SYSIN DD *
060998
Original JCL
Substituted JCL on
June 9, 1998
66 Tailoring J CL
Examples of Using Panvalet Data Sets, continued
Example 2: Using
dates to qualify
data set names
Date-qualified data sets are often used in production J CL. You can use ESP
symbolic variables when there is a need to refer to the current and previous
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 J ulian date.
%PREVDATE, to represent the previous workdays J ulian 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 J CL 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,
During ESP processing, the J CL symbolic variables resolve to current values.
If ESP processes the J CL for a scheduled date of Monday, February 21, 1998
(J ulian day 052) and the previous workday is Friday, February 18,1998, the
J CL ESP submits looks like this:
//SYSUT1DD *
//SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D98049,
//SYSUT1DD *
//SYSUT2DD DISP=(NEW,CATLG),DSN=CYB.XYZ.D98052,
You can use ESPs COPYJ CL function to save a copy of this J CL as
submitted. Refer to the ESP Users Guide for more information on this feature.
Tailoring J CL 67
Example 3: Using
different
symbolic
variables in JCL
This example shows how to assign values to different symbolic variables and
how to use them 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 J OBCARD 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
J CL. Here is a sample job with J CL that looks like this:
%JOBCARD
//S1EXEC PGM=MYPGM,PARM=%DATEPARM
//DD DSN=%BIGDSN,DISP=SHR
On December 9, 1998, ESP submits the following J CL:
//JOB1 JOB ACC1,NAME,CLASS=A
//S1EXEC PGM=MYPGM,PARM=12/09/98
//DD DSN=CYBER.JCL.TEMP.LIBRARY,DISP=SHR
68 Tailoring J CL
Example 4: Using
symbolic
variables with
values longer
than their names
When using symbolic variables in J CL, 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:
Here is an example of how ESP may resolve the symbolic variable:
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 J CL for the job.
On May 10,1998, ESP resolves the J CL as follows:
%CCARD resolves to:
LBILDATE=05/09/98,FMTDATE=05/01/98
65 66 67 68 69 70 71 72
% D A T E 0 7
65 66 67 68 69 70 71 72
J A N 1 9 9 4
Tailoring J CL 69
Adding a Restart Step
About adding a
restart step
A restart product may require the insertion of J CL 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 J OB 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
70 Tailoring J CL
Routing Jobs to Other JES Nodes
About routing
jobs
ESP can automatically insert a /*ROUTE statement into the J CL it submits.
This statement routes a job to a different node for execution.
Format for
routing jobs
Include the ROUTE XEQ statement in the job definition, specifying the name
of the J ES node to which you want to route the job.
Example:
Routing a 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
Note: In order to track jobs, or run Applications that have jobs that run across
different J ES nodes, your environment must be set up to track jobs across J ES
nodes. Check with your ESP system administrator before using this feature.
Tailoring J CL 71
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.
72 Tailoring J CL
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:
J obs 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.
Format of the
CCCHK
statement
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
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.
Example 1:
Identifying a
return code from
a step
In the following example, a condition code greater than zero in STEP10 causes
the job to fail:
JOB PAYJOB2
CCCHK STEP(STEP10) RC(1:4095) FAIL
Tailoring J CL 73
Using the CCCHK Statement, continued
Example 2:
Identifying a
return code from
a program
In the following example, a condition code of 12 produced by program
IEBGENER for job PAYJ OB3 is acceptable.
JOB PAYJOB3
CCCHK PROGRAM(IEBGENER) RC(12) OK
Specifying return
codes
The RC parameter on the CCCHK statement identifies good or bad return
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.
Specifying
success or failure
Use one of the following parameters to indicate success or failure:
Specifying the
action
Use one of the following parameters to indicate what action to take:
OK Indicates that the job has not failed. This is the default.
FAIL 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).
CONTINUE Indicates the job should continue processing with the next
step, whether or not the job is considered failed. This is the
default.
STOP Indicates the job should be stopped immediately. No other
steps should be executed.
74 Tailoring J CL
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.
Processing the
CCCHK
command
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. J ob 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 J OB, 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.
Tailoring J CL 75
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:
Adding the
ESPCCCHK step
When ESP submits a job, it adds an ESPCCCHK step that runs as the first 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
...
OK with CONTINUE No action is taken. Processing continues as
if CCCHK is not used.
FAIL with CONTINUE The job is treated as a CCCHK failure, but
normal processing continues and other
failures may be detected.
FAIL with STOP The job is treated as a CCCHK failure and
is stopped immediately.
OK with STOP The job is treated as a CCCHK failure and
is stopped immediately. (It is the same as
FAIL with STOP.)
76 Tailoring J CL
Example 2:
Global and Local
CCCHK
statements
The following local and global 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 8 in any
step for PAYJOB2 is considered to be acceptable and processing continues for
PAYJ OB2.
APPL PAYROLL
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
PAYJ OB3 is acceptable and the job is not flagged as failed and processing
continues for this job.
APPL PAYROLL
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
Tailoring J CL 77
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 J OB
FAILED - J CL ERROR condition. Steps after a bad condition code execute
unless you have COND parameters in the J CL to bypass them.
Note: The CCFAIL statement is limited by what you can do with the COND
parameter in J CL.
Format of the
CCFAIL
statements
The CCFAIL statement has the following syntax:
CCFAIL (STEPNAME,OPERAND,VALUE)
Field Description
stepname Specifies a step name. You must use the exact job or PROC
step name. For procedures, use stepname.procstepname. An
asterisk (*) represents any step.
operator 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.
value The value of the condition code for which you want to check.
78 Tailoring J CL
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.
Example 1: Any
step
This example causes a job to fail if any step gets a condition greater than 4.
CCFAIL (*,GT,4)
The trailer step that ESP adds to a job looks like this:
//ESPCCFCK EXEC PGM=IEFBR14,COND=((4,LT))
Example 2: Using
a PROCSTEP
This statement will cause a job to fail if it gets a condition code greater than
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. J ob 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)
Tailoring J CL 79
Including and Excluding JCL
About including
and excluding
JCL
ESP can include or exclude portions of J CL it submits by using %INCLUDE
and %EXCLUDE statements imbedded in J CL.
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
J CL:
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 J CL, you can use the following criteria with inclusion and exclusion
statements:
Day of week
Date
Time
Event ID
J CL being submitted or J CL being copied to COPYJ CL
Value of a logical expression.
%INCLUDE to begin inclusion
%ENDINCL to end inclusion
%EXCLUDE to begin exclusion
%ENDEXCL to end exclusion
80 Tailoring J CL
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 J CL 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
library
You can use statements so that ESP creates a modified copy of J CL it writes to
a COPYJ CL library.
Assume you want ESP to use a new version of a job card when it writes the
J CL to the COPYJ CL library.
The control statements from the J CL 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
Tailoring J CL 81
Including and Excluding JCL, continued
Copying JCL to a library, continued
The second line states the job card for the submitted J CL. The fourth line states
the job card for the COPYJ CL. When ESP submits this J CL, 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 COPYJ CL library.
When ESP writes the J CL to a COPYJ CL library it removes all control
statements from the data, so that no control statements appear in the data in the
COPYJ CL library.
Using multiple
%INCLUDE
and
%EXCLUDE
statements
You can use multiple %INCLUDE and %EXCLUDE statements in the J CL 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)
%INCLUDE FROM(APRIL 20,1998) TO(AUG 23,1998)
%ENDINCL
82 Tailoring J CL
Modifying the Symbol Introducer
About modifying
the symbol
introducer
The symbol introducer is the character that identifies symbolic variables to
ESP. Normally this character is the percentage sign (%). What if you want to
include percentage signs in your J CL, without ESP interpreting the sign as a
symbol introducer? There are three ways that you can control how ESP
interprets the percentage sign (%) in J CL.
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 J CL, 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 J CL, that is, the //
*ESPSYMBOL statement.
Formatting the
symbol
introducer
The format for inserting the control statement in the J CL 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 J CL:
//*ESPSYMBOL ?
//ABC JOB . . .
?INCLUDE DAY(MONDAY)
//STEP1 EXEC PGM=PGM1,PARM=DATE=?ESPSYY?ESPSDDD
...
?ENDINCL
Tailoring J CL 83
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 J CL submitted to an internal
reader.
ESP does not produce the assigned values when writing J CL to a
COPYJ CL library (that is, symbols remain secured when copied to
COPYJ CL).
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 J CL it submits to the internal reader.
84 Tailoring J CL
Using an Exclusion Sign
About using an
exclusion sign
ESP allows you to assign the exclusion sign () to the end of J CL card images
to exclude specific lines of J CL 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 J CL wherever you want to exclude a J CL
statement.
4. Reference the symbol library in your Event which submits the J CL.
Tailoring J CL 85
Using an Exclusion Sign, continued
Example 1: Using
an exclusion sign
Assume a job consists of three steps. You want ESP to include all steps each
day, except on Mondays and Thursdays. On these days, you do not want ESP
to include STEP1 and STEP3 in the J CL 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 J CL 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 COPYJ CL 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=
86 Tailoring J CL
Using an Exclusion Sign, continued
Example 2: Exclude JCL by using an ESP Procedure, continued
In the J CL, 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 J CL it submits because
the ESP Procedure defines the value as .
Tailoring J CL 87
Using Automatic Variables (AUTOVARS)
About
AUTOVARS
ESP lets you define symbols representing lines of J CL, data, or comments that
ESP automatically includes at the beginning or end of the jobs J CL. 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 J CL statements for activities
such as:
Inserting J OBPARM cards.
Handling condition codes.
Using a restart manager or other product that requires the insertion of J CL
to call the program.
Processing ESP commands in batch.
Defining DJC or J ES3 net control statements in a symbolic variable library.
ESP inserts automatic variables at submission time. If a COPYJ CL library has
been specified, this copy of the J CL 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.
88 Tailoring J CL
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
J ob
Default.
You can include all three conditions in a symbol library or ESP Procedure.
Types of
AUTOVARS
ESP recognizes three types of automatic variables. The type tells ESP where
to include the AUTOVAR in the J CL. The three types are:
Order of
processing
When ESP encounters more than one processing condition for a single job, it
inserts the conditions in this order:
Global, first
J ob-specific, second
Default, last.
Numbering of
AUTOVARS
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
ISTEPnn initial step
NETCnn net control statement
TSTEPnn trailer step
Tailoring J CL 89
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 J OB24ABC, 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
J TOP5196.RUN1.
JTOP5196_ _RUN1_ISTEP=//FSTEP EXEC PGM=LTOP5196
90 Tailoring J CL
Using DEFAULT
AUTOVARS
A default AUTOVAR applies to any job that an Event or Procedure submits,
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
(ISTEPnn)
Use ISTEPnn to insert an initial step before the first EXEC statement of a job.
The following example defines three ISTEP AUTOVARS for J OB1.
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 DJ C or J ES3 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 J OB1 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
Tailoring J CL 91
Using trailer
steps (TSTEPnn)
Use TSTEPnn to insert a trailer step at end of file or before the next job card.
The following example defines a TSTEP AUTOVAR for job CYBER407.
CYBER407_TSTEP1=//LSTEP EXEC PGM=RPTAUDIT,PARM=NO
Example 1:
Defining the first
step in a job
Insert the following three statements, each containing an ISTEP type of
AUTOVAR:
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.
Example 2:
Defining a net
control statement
Insert the following three statements, each containing a NETC type of
AUTOVAR:
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 end-
of-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.
92 Tailoring J CL
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 BADJ OB 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 J CL for the RECOVER job might look like this:
//RECOVER JOB . . .
//S1 EXEC PGM=CLEANUP
When ESP adds the trailer steps, the J CL 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
Example 5:
Adding a trailer
step for handling
condition codes
The first example defines default trailer steps. If the highest job step return
code is 0 or 4, the ESPCCFCK step executes and ESP considers the job
successful. Otherwise, the ESPCCFCK step is bypassed and ESP considers the
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
Tailoring J CL 93
Simulating the JCL ESP Submits
About simulating
the JCL ESP will
submit
You can use the PRINT option of the SIMULATE command to see the J CL
which ESP will submit for a job on any date. ESP displays the J CL at your
terminal or writes it to a data set. You can also invoke a module to scan J CL
during simulation.
Using the
SIMULATE
command
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(*)
This command requests ESP simulate the next occurrence of the Event and
display JCL for MYJ OB. 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
J CL scan exit module. The following command invokes a module called
ABCSCAN to scan J CL during a simulation.
SIMULATE EVENT(PROD.PAYROLL) JCLSCAN(ABCSCAN)
Note: For more information on using the SIMULATE command, refer to the
ESP Command Reference.
94 Tailoring J CL
Submitting Jobs Outside ESP
About submitting
outside ESP
Once you have inserted ESP control statements in J CL, you must use ESP to
submit the job. If you submit the job using another method, such as TSO
SUBMIT, the ESP control statements will cause J CL 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.
Example: Using
the SCAN
command
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 J CL that ESP
would submit on March 31, 1998 for MYJ OB:
SCAN PROD.JCL.CNTL(MYJOB) EVENT(PROD.SUBMYJOB) -
SCHED(31ST MARCH 1998) SYMLIB(ESP.SYMBOLS(MYSYM))
PROD.J CL.CNTL(MYJ OB) tells ESP where it can find the J CL for
MYJ OB.
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.
J ob Monitoring and Alert Processing 95
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.
Topic See Page
Comparing J ob Monitoring and Alert Processing 96
Functions of J ob Monitoring and Alert Processing 98
Planning for J ob Monitoring and Alert Processing 100
How J ob Monitoring Works 101
Setting Up J ob Monitoring 102
Using Alert Processing 112
ESPS Built-in Monitor Variables 124
96 J ob Monitoring and Alert Processing
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
J ob start
Resubmit
Overdue
Abend
Failure
J ob end.
While job monitoring has no restrictions, you must create a specific monitor
Event or generic tracking model to run it. J ob monitoring checks at these
monitor points:
J ob start
Step end
J ob 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.
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
MNJ OBNO 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
MNJ OBNO 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
introducer
character (%)
As with other symbolic variables, use the symbol introducer character at the
beginning of a monitor variable. The symbol introducer tells ESP to interpret
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.
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.
Defining Event
activities
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. J ob monitor and
Alert Events can perform the same tasks as other Events, such as sending
messages, issuing ESP commands, submitting J CL, and invoking an ESP
Procedure.
Invoking ESP
Procedures
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.
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.
Planning for Job Monitoring and Alert Processing
Overview Plan your monitoring requirements in steps, based on jobs that ESP is currently
tracking.
Steps for
planning
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.
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 Activation Point
J OBSTRT Start of the job.
STEPEND At the end of each step in the job. This includes steps
which are bypassed.
J OBEND End of the job.
OVERDUE 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.
PURGE J ob purge, unless NOTRACK_PURGE has been
selected as a tracking option.
POST When the job is posted from a processing stage,
including user-defined P-Nodes.
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 J ob Tracking
Definition Table.
Method 1:
Generic tracking
model
Using this method, you use a tracking model to identify the name of an Event
that you want ESP to trigger when a job reaches a particular step in processing.
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:
The following example defines a tracking model called BADEND. ESP
triggers the Event PROD.ABENDED_J OBS each time a job associated with
this model ABENDs.
DEFTM BADEND JOBABENDEVENT(PROD.ABENDED_JOBS)
JOBABENDEVENT J ob ABEND.
JOBENDEVENT End of job. This includes both normal and
abnormal completions.
JOBFAILEVENT J ob failure including ABENDs and condition
code failures.
JOBSTARTEVENT J ob start.
STEPABENDEVENT Step ABEND.
STEPENDEVENT End of step.
STEPFAILEVENT Step failure including ABENDS and condition
code failures.
Setting Up Job Monitoring, continued
Method 1: Generic tracking model, continued
J obs are associated with a tracking model using a J ob Tracking Definition
Table. For more information on tracking models and J ob 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 J ob
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.
Method 3:
Identify a
monitor group in
a tracking model
Using this method, you identify the prefix of your monitor Event in a job
tracking model. 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. 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.
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
monitor group in
the job
To tell ESP to monitor a job, you must specify a monitor group name in every
job or group of jobs to be monitored.
You can insert the monitor group name in any of the following:
Tracking models
ESP Procedures
J ob 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)
Example:
Defining a
monitor group in
a tracking model
For this example, the name of the tracking model is J OBMON and the
monitor group name is PROD. Type the following command to define the
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
Example:
Defining a
monitor group in
an ESP
Procedure
For example, you have a job called PAYJ OB1 and a monitor group called
PROD. The statements for the ESP Procedure are:
JOB PAYJOB1
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
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:
Example: A
monitor Event
Assume that the monitor group name is PROD, the jobname is PAYJOB1,
and the monitor point is J OBEND. The monitor Event name looks like this:
PROD.PAYJOB1_JOBEND
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.
jobname Insert the complete jobname, for example
PAYROLL1.
_(underscore) Use an underscore as a separator between the jobname
and the monitor point (you cannot insert blank spaces).
monitor point 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.
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.PAYJ OB1_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 %MNJ OB indicates the end
of the symbol name. Otherwise, ESP would treat
%MNJ OB(%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(*)
Example: Monitoring step end, sending message, continued
When PAYJ OB1 is submitted, the jobs tracking model informs ESP to look
for Events with these attributes:
the prefix ESPMON
the jobname PAYJ OB1
an underscore (_)
a monitor point.
In this example, assume ESP finds ESPMON.PAYJOB1_STEPEND. ESP
then executes this Event each time PAYJ OB1 completes a step.
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. J ob 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)
JOB PAYJOB1
MONITOR ESPMON
EVENT ID(ESPMON.ABC_JOBEND)
EVENT ID(ESPMON.DOCJOB_JOBEND)
EVENT ID(ESPMON.PAYJOB1_STEPEND)
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
Example:
Monitoring
online system
completion
In this example, ESP submits a job after a started task TSOVTAM has ended
successfully. J ob monitoring invokes an ESP Procedure to check the return
code. The example assumes that ESP is tracking the started task. Set up job
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.
J ob monitoring invokes an ESP Procedure to set a resource called CICSUP.
The example assumes that ESP is tracking the started task. Set up job
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)
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 MNJ OB
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
Using Alert Processing
About using alert
processing
The Alert feature enables ESP to trigger an Event for all jobs, or only specific
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:
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
NOTIFY
statement
To set up an Alert process in an Application, use the NOTIFY statement with
the ALERT keyword. The NOTIFY statement can refer to all jobs in an
Application or it can be job specific within the scope of a J OB statement.
The format for the NOTIFY statement to use the Alert feature looks like this:
NOTIFY condition ALERT(identifier)
NOTIFY processing_point ALERT(alert_id)
ALERTDEF ADD ID(alert_id) EVENT(event_name)
EVENT ID(event_name)
Using Alert Processing, continued
Step 1: Using the NOTIFY statement, continued
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.
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 Condition that triggers the Alert. This can be one or more of
the following: SUBMIT, J OBSTART, RESUB,
OVERDUE, ABEND, FAILURE, J OBEND.
ALERT Triggers an Event.
identifier 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.
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.
Using symbolic
variables in Alert
processing
In certain cases such as job end monitoring, you can use job monitor variables
in the Procedure for an Alert. For more information on job monitor variables,
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.
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 J OBX 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.
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
processing
triggers specific
Event
This example uses the format ALERT(id). When ESP processes a NOTIFY
command with ALERT (ID), it must first locate a corresponding definition for
ALERT and then trigger the appropriate Event.
In this example, assume ESP triggers an Event whenever a job in the ESP
Application ABENDs. This involves a three-step process.
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
Example 2: Alert processing triggers specific Event, continued
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)
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)
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
.
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
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 MNRRJ OB variable. If MNRRJ OB 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)
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.
Define the Event like this:
EVENT ID(CYB.AFAIL)
INVOKE CYB.ESP(AFAIL)
Example 4: Alert
processing re-
triggers same
Event
This example uses the format ALERT(*) to re-trigger the same Event and ESP
Procedure. The criteria for this example is that the Application should be
marked complete if a task called WAIT4.TAPE has not been marked complete
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
Example 4: Alert processing re-triggers same Event
The ESP Procedure tests the MNJ OB (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 MNJ OB 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 J 1 ends with a return code of 50, ESP bypasses subApplication PATH2.
If J 1 ends with a return code of 0, ESP bypasses subApplication PATH1.
If J 1 ends with a return code other than 0 or 50, ESP sends a message.
Visually, the Application and subApplications look like this:
J1
J2A
J3A
J2Z
J1.RCCHECK
=50 =0 Other
J3Z
send message
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
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.J 1_CHECKEND. This Event is triggered when job J 1 ends.
Example 5: Taking different paths in an Application, continued
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 J 1.CHECK task.
If return code is 50: bypass PATH2 and complete the J 1.RCCHECK task.
Otherwise, send a message to indicate how J 1 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(*)
ESPS Built-in Monitor Variables
MNACCT1 Up to eight characters of the first account number field.
MNACCT2 Up to eight characters of the second account number
field.
MNACCT3 Up to eight characters of the third account number
field.
MNAPPL Application name. This variable is null if the job is not
part of an Application.
MNAPPLGEN Generation number of an Application. This variable is
null if the job is not part of an Application.
MNAUTHS 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.
MNCMPC 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.
ESPS Built-in Monitor Variables, continued
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 J CL, the
result is J CLERROR.
If a job fails because of a completion code error, the
result is CCFAIL.
MNHICMPC Character representation of the highest completion code
from the execution of a step. This is not affected by
ESP generated status codes such as J CLERROR and
CCFAIL.
MNHIRC Highest return code from the execution of a step. This
is not affected by ESP generated status codes such as
J CLERROR and CCFAIL.
MNJOB J obname.
MNJOBTYPE Type of job. The result can be any of the following:
A job.
Started task (STC).
TSO user (TSU).
MNJOBNO J ES job number, expressed as an integer variable.
MNJ OBNO has a value of 0 for a job that has not been
submitted.
MNJSTART J ob start time in the format yyyymmdd, for example,
19931222.
MNMXCMPC Highest completion code, expressed as an alphanumeric
variable. These are the same as the completion codes
for MNCMPC (above).
MNMXRC 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.
MNNETID DJ C network identifier (used only if an ESP Procedure
defines a DJ C network) or J ES3 jobnet.
MNNXN 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 J ES node.
MNPNODE 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 P-
Node. If ESP has purged the job and the job has no
manual P-Nodes, the result is null.
MNPOINT 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.
MNPOSTBY 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.
MNPSTEP J CL procedure step name (used for a step end monitor
point only).
MNPROG Program name (used for a step end monitor point only).
MNQUAL J ob qualifier. If the job does not have a qualifier, this is
set to null.
MNRC 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.
ESPs Built-In Monitor Variables, continued
MNRDRON Time that J ES reads the job into the system, in the
format hh,mm.
MNRDRX Time stamp for reader-on date and time.
MNRRJOB J obname of a job ESP is re-running. It has a value of
null of the job is not a rerun.
MNRRJOBNO J ob number of a job ESP is rerunning (expressed as an
integer variable).
MNSTEP Step name (used for a step end monitor point only).
MNSTEPNO 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 J OBSTRT, STEPEND or J OBEND 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.
Advanced Use of ESP Procedures 129
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.
Topic See Page
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
130 Advanced Use of ESP Procedures
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
job based on even
days
The ESP Procedure in this example tests whether the day of the month is
even and then selects MYJ OB on even days only. ESP selects the job on the
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 MYJ OB.
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 MYJ OB.
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 J uly 11,1998, J uly 25,1998,
and so on. The Procedure determines whether the number of days since J uly
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
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
Example1: 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:
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.
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
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.
JOB MYJOB
GENTIME XX LAST DAY OF MONTH LESS 2 DAYS
RUN %XXDATE LESS 0 WORKDAYS
ENDJOB
Example: Run a
job relative to the
next month
Two workdays prior to the 40th day before the last day of the next month.
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:
J OBA runs at 09:00, 11:00, 13:00, 15:00, 17:00, 19:00, 21:00, 23:00
J OBB 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
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
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 J OBA, AFREQ(5:6)=XX which is not equal to 02. ESP does not
select J OBA.
For J OBB, 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.
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.
Example:
Determine
number of days
relative to a
period
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
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)
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 J anuary, February, March or April, use last year
followed by this year.
For any other month, use current year followed by next year.
Example: Generate symbolic based on special period, continued
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 J anuary through April.
FINANCIAL_YEAR=9899 , from May through December.
Example:
Determine
number of weeks
in 4-4-5 period
This example calculates the number of weeks in a period based on a 4-4-5
cycle. The name of each period is PERIOD445 and there are twelve of these in
a period called FISCAL_YEAR.
IF TODAY(ANYDAY OF 3RD 6TH 9TH 12TH PERIOD445 +
OF FISCAL_YEAR) THEN WKS_PERIOD=5
ELSE WKS_PERIOD=4
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 (J anuary 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
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.
J ob 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.
Testing the
method of
invocation
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 MNJ OBNO >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 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 ESP Procedure Selected
Jobs
USER.DAYJ OBS
Select A
IF ESPEVENT=USER.DAYJ OBS -
THEN SELECT B
A, B
USER.NIGHTJ OBS IF ESPEVENT=USER.NIGHTJ OBS -
THEN SELECT C
A, C
Combining CLANG Elements
About combining
CLANG
elements
This topic contains some examples of combining different 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.
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
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 DCNUM=01 ATL01
(Data set) DC=ATL completed
BARNEY.CAR12.BEDROCK DCNUM=12 COL12
(Data set) DC=COL completed
Example: Build a
control card
This example builds a control card on the last workday of the month. The
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
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'
Checking for a
job in the input
queue
J OBONQ 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 J OBONQ
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 J OBONQ with a REEXEC statement.
Example:
Checking for a
job in the input
queue
This ESP Procedure performs the following functions:
It checks to see if any job with the name RMTJ OB 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 J OBCOUNT. ESP
then puts the resulting values for the job into the symbolic variables
ZJ OBID1, ZJ OBNO1, ZJOBH1, ZJ OBQ1.
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 RMTJ OB is on hold in the input queue, the Procedure issues a J ES
command to release the job.
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
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)
Overriding Inherited Relationships
About inherited
relationships
J obs 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. J ob F runs after job D, as the dependency chain
passes through the unselected job, E.
A
B C
E
F
D
Daily
Friday
Last workday
of month
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 J OB 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 J OB statement, the
specified attribute overrides the default for that job only. Subsequent jobs
revert to the current default attribute unless otherwise specified on their
J OB 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 J OB statement.
Example: Using
an OPTIONS
NOINHERIT
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 . . .
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 J OB 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 J OB statement.
This example shows a job stream consisting of six jobs, with a node at J ob B.
Visually, the job stream looks like this:
B
C D
F
A
E
NODE
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 Job Relationships
J obs A and D J obs A and D run independently, since no relationships
pass through the node.
J obs A, B and E J ob A runs before job B, and job B runs before E (the
node is selected).
J obs A, B and D J obs run in the order of A, B and D since ESP selects the
node.
J obs A, D and F J ob 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.
Using the
NOINHERIT
keyword
You can use a NOINHERIT keyword in a J OB statement to override the
default for that job only. Subsequent jobs revert to the current default unless
otherwise specified on their J OB 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:
B
C D
F
A
E
NOINHERIT
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 Job Relationships
J obs A, B and E J ob A runs before job B, but job E runs independently.
J ob E is not an immediate successor to the selected job
B.
J obs A, C and D J obs A, C and D run independently. No dependencies
pass through the unselected job B.
J obs A, D and F J ob A runs independently because no dependencies pass
through the unselected job B. J ob D runs before F
because job E has the INHERIT attribute.
J obs B, C and F J ob B runs before job C since job C is an immediate
successor. J ob C runs before job F because job E has the
INHERIT attribute.
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 J ob Index data set
and a scheduled activity data set, respectively.
Resolving
dependencies
using a scheduled
activity set
You can request that ESP generate a scheduled activity data file (SAD file).
The SAD file contains information on all jobs or a subset of the jobs. ESP does
not use this file in its normal scheduling; it uses a real time schedule, instead.
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 main-
storage resident look-up table.
SADLINK SAD1 DATASET(PROD.SADDAILY) GROUP(PROD)
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
file
Enter a SADLOAD command to refresh the in-core table whenever there has
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
SADGEN DSN(PROD.SADDAILY)
//S2 EXEC PGM=ESP,COND=(0,NE)
//SYSIN DD *
OPER SADLOAD SAD1
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 J ob 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 J ob 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 J ob X is complete. J ob 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:
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 J OBX. ESP must
ensure that JOBX is complete before releasing JOBA.
J OBB depends on JOBA.
The ESP Procedure, releasing J OB 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
J OBA. If J OBX is scheduled within the specified scope, ESP ensures that
J OBX is complete before releasing J OBA. If J OBX is not scheduled within
the specified scope, ESP does not select J OBX and releases J OBA.
6. ESP checks the J ob Index data set to see if J OBX has been run in the
previous 24 hours. If so, ESP releases J OBA.
/* ESP Initialization Parms */
SADLINK SADWKLY DATASET(`PROD.ESP.SAD')
ESP Address Space
SADWKLY in-core
look-up table
.
.
.
JOBA
JOBB
JOBX
Monday 06:00
CYBER.SAD_CREATE triggers
SADGEN
Tuesday 16:00
CYBER.TEST_EVENT triggers
INVOKE TESTPROC
PROD.ESP.SAD
.
.
.
JOBA
JOBB
JOBX
JOBX
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)
1
2
3
4
5
6
Summary of
options
The following chart summarizes the different options you have for using
SCOPE and RESOLVE.
Option Description
SCOPE without RESOLVE Instructs ESP to look back in the J ob 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.
RESOLVE without SCOPE Instructs ESP to look at the scheduled
activity data set to resolve the dependency.
ESP automatically selects the job if it is
found.
RESOLVE with SCOPE Instructs ESP to look at the scheduled
activity data set within the specified scope.
ESP automatically selects the job if it is
found.
Advanced Use of Applications 161
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.
Topic See Page
Changing J ob Attributes 162
Posting of External and Manual Jobs 163
Controlling the Release of J obs 174
Scheduling Multiple Runs of a J ob 182
Using SubApplications 184
Submitting Different J obs 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
162 Advanced Use of Applications
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 J OB 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.
The JOBATTR
statement
To define a job with different attributes, use the J OBATTR statement. This
statement lets you change any attributes of a job within the scope of the J OB
statement or in job documentation. Attributes include the keywords you can
use on the J OB statement.
Example:
Changing a job
attribute
In the following example, J ob ABC runs daily. On Mondays, it is a request job.
JOB ABC
RUN DAILY
IF TODAY(MONDAY) THEN JOBATTR REQUEST
ENDJOB
Example:
Negating a job
attribute
In the following example, J ob 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, J ob 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
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.
Controlling the
posting of
external and
manual jobs
The following table summarizes these posting options:
Option Where It Can
Be Used
Description
POST-OLDEST TRACKOPT;
APPL statement
Posts the job in the oldest
active generation of the
Application in which the job
has not been marked.
NOPOST_OLDEST TRACKOPT;
APPL statement
Posts the job in all active
generations of the
Application in which the job
has not been marked
complete. This is the
default.
NOPOST_UNTIL_READY APPL statement Does not post the job until
its dependencies are met.
POST_WHILE_WAITING APPL statement Posts the job even if it is
waiting - status is
APPLWAIT, SUBAPPL
WAIT, or
J OB_ANCESTOR_WAIT.
NOPOST_WHILE-
WAITING
APPL statement Does not post the job if it is
waiting - status is
APPLWAIT, SUBAPPL
WAIT, or
J OB_ANCESTOR_WAIT.
SCHEDULED J OB statement Indicates a range for the
scheduled time of the Event
that submits the job; trigger
time is used for non-
scheduled Events.
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 DJ C/J ES3 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.
When job A completes, ESP marks the job complete based on the posting
option.
A A
THISAPPL.1 THISAPPL.2
(External) (External)
(APPLWAIT)
B B
Example: Using different posting options, continued
Example:
Waiting on an
external job with
the same
scheduled date
In this example, job B runs Monday, Wednesday and Friday, and job A runs
everyday. Job B depends on the job A which is scheduled for the same day.
Visually, the dependencies look like this:
JOB A EXTERNAL SCHEDULED(TODAY)
RELEASE B
RUN MON WED FRI
ENDJOB
JOB B
RUN MON WED FRI
ENDJOB
Posting Options Application in which Job Marked
Completed
POST_OLDEST THISAPPL.1
NOPOST_OLDEST THISAPPL.1, THISAPPL.2
POST_WHILE_WAITING THISAPPL.1, THISAPPL.2
NOPOST_WHILE_WAITING THISAPPL.1
NOPOST_UNTIL_READY THISAPPL.1, THISAPPL.2
A B
A
A B
Monday
Tuesday
Wednesday
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 SUNJ OB on Sundays and it depends on the
successful completion of job SATJ OB which ESP schedules on Saturdays.
SATJOB and SUNJ OB belong to different Applications.
JOB SATJOB EXTERNAL SCHEDULED(YESTERDAY)
RUN SUNDAY
RELEASE SUNJOB
ENDJOB
JOB SUNJOB
RUN SUNDAY
ENDJOB
SATJOB
SUNJOB
Saturday
Sunday
Example: Waiting on an external job with a previous scheduled date - different Application,
continued
On Sunday you want to select job SATJ OB as an external predecessor to job
SUNJ OB. When ESP builds this Application it checks to see if SATJ OB from
the previous day (YESTERDAY) is complete.
If yesterdays SATJ OB is complete, ESP posts the external job complete.
If yesterdays SATJ OB 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 SUNJ OB
on Sundays and it depends on the successful completion of job SATJ OB which
ESP schedules on Saturdays. SATJ OB and SUNJ OB belong to different
generations of the same Application.
Since the jobs belong to the same Application, you need to use the JOBATTR
statement to change SATJ OBs 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 SATJ OB reflects
when the job is scheduled (Saturday) and when the external relationship needs
to be built (Sunday).
SATJOB
SUNJOB
Saturday
Sunday
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 SATJ OB from
the previous day (YESTERDAY) is complete.
If yesterdays SATJ OB is complete, ESP posts the external job complete.
If yesterdays SATJ OB 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. J ob B can run after the first successful run of job X that completes
after midnight.
Visually, the flow of jobs looks like this:
X
B
X X
(23:15) (00:15) (01:15)
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:
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.
Completion Time for Job Results
11:15 p.m. (23:15) This run of job X does not post complete in
the Application since the job does not
become ready until midnight.
12:15 a.m. (00:15) J ob X posts complete in the Application.
1:15 a.m. (01:15) This run of job X does not post complete in
the Application as it will already have been
marked complete.
Example: Waiting for another job to complete, continued
Visually the flow looks like this:
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
A
B
C
MANUALLY
SUBMITTED
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
a bypassed job in
another
Application
In this example, a job in one Application must wait on an on-request job in
another Application. The request job may or may not be requested.
J ob A is an on-request job in Application APPL1. J ob B is in Application
APPL2 and must wait until job A completes successfully or is bypassed.
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:
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
A
CHECK.A
WAIT4.A
B
APPL1 APPL2
(task)
(link)
(REQUEST job)
(job)
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
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
JOB WAIT4.A TASK
RUN DAILY
RELEASE B
ENDJOB
JOB B
RUN DAILY
ENDJOB
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.
Example:
Delaying release
based on time
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.
Controlling the Release of Jobs, continued
Example: Delaying release based on time, continued
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
A
B
C
If time < 06.23 then wait 5 minutes
If time is between 06:45 and 07:30
then wait until 07:30
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.
Example:
Optional job
dependency
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:
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
A B
D
C
OR OR
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.
Example:
Optional data set
trigger
dependency
In this example, job ABC cannot run until one of two data sets,
PAYROLL.MASTERA or PAYROLL.MASTERB, has been created.
Whichever one is created first, causes ESP to submit job ABC. The
Application does not need to wait for the other data set before it completes.
Visually the dependencies look like this:
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.
FILEA FILEB
ABC
OR
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.
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
Releasing a job based on predecessor termination, continued
An example is shown below.
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 PAYJ OB1 terminates abnormally, ESP submits job RECOVER
If PAYJ OB1 terminates normally, ESP submits job PAYJ OB2.
Visually the dependencies look like this:
A
B
Any
Termination
JOB A
RELEASE (B(U))
PAYJOB1
RECOVER PAYJOB2
Abnormal
Termination
Normal
Termination
PAYJOB1
RECOVER PAYJOB2
Abnormal
Termination
Normal
Termination
Example: Job based on how a particular job terminates, continued
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.
Scheduling Multiple Runs of a Job
About scheduling
multiple runs
You can use ESP to dynamically insert a job into an Application multiple times
in a day. J ob 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 MYJ OB.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 MYJ OB.STOPSUB.
3. Schedule an Event prior to 8 a.m. to invoke the ESP Procedure.
Example:
Scheduling
multiple runs of a
job
Here is a sample ESP Procedure.
APPL THISAPPL
/*
/* 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
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 MYJ OB.HOURLY task.
Note: Another method for handling this scenario is to use templates. Refer to
Using Templates on page 205 for more information.
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.
Using
subApplications
for different job
streams
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).
A
B C
X
Y
Z
D
DEFAULTS STREAM1 STREAM2
MASTER
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 J CL library. It
looks like this:
APPL MASTER
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
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.
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.
A
B
C
X
Y
Z
OR
NORMAL
SUBAPPL
SPECIAL
SUBAPPL
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)
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 RUNJ OB 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 J OBNAME symbolic
variable in accordance with the data set that closed.
Data Set Name JOBNAME
YOUR.FIRST.DATASET A
YOUR.SECOND.DATASET B
YOUR.THIRD.DATASET C
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)
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.
Example:
Options when
triggering an
Event called
PROD.PAYROLL
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. J ob selection and scheduled dates are based on yesterdays
date.
TRIGGER PROD.PAYROLL AT(4PM YESTERDAY) ADD
Trigger time is last Friday. Since this time has past, ESP will trigger the Event
immediately. J ob 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
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:
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 J CL 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.
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)
RUNSUB
DEFAULTS
(ESP Procedure)
(ESP Procedure)
PROD.RUN_SUBAPPL
(Event)
%USER1
(ESP Procedure)
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.
DEFAULTS
(ESP Procedure)
TRIGGER PROD.RUN_SUBAPPL ADD USER1(`SUBAPPL1')
SUBAPPL1
(ESP Procedure)
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.
Taking Action Based on Time, continued
Example: Requesting different jobs based on the time of predecessor completion, continued
A
B
C
D
E
CHECK.TIME
<15:00 >=15:00
F
Example: Requesting different jobs based on the time of predecessor completion, continued
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
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:
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
KEYPUNCH.DATA
CHECK.TIME
NEXTJOB
(task)
(task)
(job)
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. NEXTJ OB 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.
Example:
Sending a
message based on
an incomplete
task
In this example, each of two tasks must complete by a certain time. Otherwise,
ESP completes the task and sends a message.
Visually, the job relationships look like this:
DC1.RECEIVED
DC1.MESSAGE
FIRSTJOB
DC2.RECEIVED
DC2.MESSAGE
DC1.RECEIVED
DC1.MESSAGE
FIRSTJOB
DC2.RECEIVED
DC2.MESSAGE
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
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
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.
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.
APPL ABC
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
A B
C
CUT-OFF
8PM
A B
C
CUT-OFF
8PM
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:
A
B
C
CHECK.STATUS
SUBAPPL
LOWPRIO
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
J ob 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.
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: Step-
level
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.
A.STEP0010
B
(task)
(job)
Step end monitor Event
(Event)
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)
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 (J UMPTO %MNJ OB).
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
EXIT
B:
EXIT
COMPLETE:
ESPNOMSG AJ %MNJOB..%MNSTEP COMPLETE APPL(ABC.0)
Using Templates 205
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.
Topic See Page
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
206 Using Templates
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 PRTJ OBS 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 PRTJ OBS statement
passes USERA to the PRTJ OBS template and ESP substitutes this value for
%NAME. The second PRTJOBS statement passes USERB to the PRTJ OBS
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.
Using Templates 207
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 PAYJ OBS. 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.
208 Using Templates
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:
Example: Using a
template variable
In the following example, the name of the template is XMAS, it accepts one
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 J CL, for example), you need to assign it to a non-template
variable within the scope of a J OB 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.
LOCALVARIABLES The variables are used only within the body of
the template. This is the default and should
normally be used.
GLOBALVARIABLES The variables may be used within, and outside,
the body of the template.
Using Templates 209
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
the template
definition
Use the ENDTEMPL statement to end the template definition.
The following statement ends a template definition:
ENDTEMPL
210 Using Templates
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.
Example:
Passing data
In the following example, the data USERA is passed to the template called
PRTJ OBS. ESP substitutes the value USERA for the symbolic variable
%NAME within the template.
.
.
.
ENDTEMPL
PRTJOBS USERA
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:
Using Templates 211
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(IMSPROD) THEN +
SEND IMSPROD IS ACTIVE U(FRED)
ELSE SEND IMSPROD IS NOT ACTIVE U(FRED)
212 Using Templates
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,
%J OBNAME:
TEMPLATE STATUS (1,JOBNAME)
IF ACTIVE(%JOBNAME) THEN +
SEND %JOBNAME IS ACTIVE U(FRED)
ELSE SEND %JOBNAME IS NOT ACTIVE U(FRED)
ENDTEMPL
STATUS CICS1066
STATUS CICS1215
STATUS CICS1492
STATUS IMSPROD
Using Templates 213
Working With Templates
About working
with templates
This topic describes how to:
Invoke templates.
Use multiple templates.
Change template definitions.
Invoking
templates
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
214 Using Templates
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
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
Using Templates 215
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
a SUBAPPL
statement
In this example, a SUBAPPL statement is added:
TEMPLATE RPT (1,JOBNAME,FREQ(WORKDAYS))
JOB %JOBNAME
RUN %FREQ
SUBAPPL FINRPT
ENDJOB
ENDTEMPL
Example: Adding
a NORUN
statement
In this example, a NORUN statement is added:
JOB %JOBNAME
RUN %FREQ
NORUN FIRST WORKDAY OF MONTH
SUBAPPL FINRPT
ENDJOB
ENDTEMPL
Example: Adding
a RUN Statement
In this example, a RUN statement is added:
JOB %JOBNAME
RUN %FREQ
RUN FIRST SATURDAY OF JULY
NORUN FIRST WORKDAY OF MONTH
SUBAPPL FINRPT
ENDJOB
ENDTEMPL
216 Using Templates
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.
Example:
Defining a static
holiday - Part 1
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.
ESP DEFHOL CHRISTMAS START(DEC 25,%YEAR) +
FOR(24) CAL(SYSTEM)
ENDTEMPL

XMAS 1998
XMAS 1999
XMAS 2000
XMAS 2001
XMAS 2002
XMAS 2003
Using Templates 217
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 25,1998) +
FOR(24) CAL(SYSTEM)
FOR(24) CAL(SYSTEM)
FOR(24) CAL(SYSTEM)
FOR(24) CAL(SYSTEM)
FOR(24) CAL(SYSTEM)
FOR(24) CAL(SYSTEM)
Example:
Defining a static
holiday - Part 2
The following example uses REXX to pass information to the template:
ESP DEFHOL CHRISTMAS START(DEC 25,%YEAR)+
FOR(24) CAL(SYSTEM)
ENDTEMPL

REXXON
DO I=1998 TO 2003
XMAS I
END
REXXOFF
218 Using Templates
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, J AN1
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
Example:
Defining any
holiday using
different formats
This example uses a template for any 24-hour holiday and accepts the date in
any ESP format.
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)
Using Templates 219
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 PRTJ OBS.
Run independently of each other.
The following is a sample definition of this Application:
APPL PAYROLL
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 PRTJ OBS. It accepts one positional parameter
for the name of each job.
The template contains details for the print job, such as SUBAPPL
PRTJ OBS and RUN DAILY.
ENDTEMPL identifies the end of the template.
The template is used for jobs USERA, USERB, ...,USERD.
220 Using Templates
Using Templates in Applications, continued
Example: Defining similar jobs - no relationships, continued
APPL PAYROLL
JOB %NAME
SUBAPPL PRTJOBS
RUN DAILY
ENDJOB
ENDTEMPL
PRTJOBS USERA
PRTJOBS USERB
PRTJOBS USERC
PRTJOBS USERD
Using Templates 221
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 PJ OB.
May relate to other jobs.
The following is a sample definition of this Application:
APPL PAYROLL
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
222 Using Templates
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,
J OBNAME, 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 PJ OB. 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
TEMPLATE PAY (1,JOBNAME,NEXT())
JOB %JOBNAME
RUN DAILY
TAG PJOB
ENDJOB
ENDTEMPL
PAY PAYROLL1 NEXT(PAYROLL2,PAYROLL3)
PAY PAYROLL2 NEXT(PAYROLL4)
PAY 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
Using Templates 223
Part 2 - Modifying the TEMPLATE statement, continued
TEMPLATE PAY (1,JOBNAME,FREQ(DAILY),NEXT())
JOB %JOBNAME
RUN %FREQ
TAG PJOB
ENDJOB
ENDTEMPL
PAY 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
TEMPLATE PAY (1,JOBNAME,FREQ(DAILY),NEXT())
JOB %JOBNAME
IF FREQ NE THEN RUN %FREQ
TAG PJOB
ENDJOB
ENDTEMPL
224 Using Templates
Part 3 - Overriding information, continued
PAY PAYROLL3 FREQ(WEEKDAYS) NEXT(PAYROLL4)
PAY 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 DIVJ OBS, 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
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:
J obs PAYA1234, PAYB1234, and PAYC1234 in the DIV1234
subApplication.
J obs PAYA9876, PAYB9876, and PAYC9876 in the DIV9876
subApplication.
Using Templates 225
Example: Part 2
Passing variables
to JCL
If you want to pass the division number to J CL, you need to use another
symbolic variable within the scope of the J OB statement. Otherwise, the
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 J OB statement. During
process mode, ESP substitutes the current value of NUM, and passes this value
to the J CL it submits for PAYA%NUM.
APPL CYBJOBS
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 J CL that uses the %DIVISION parameter:
//PAYA1234 JOB . . .
//S1 EXEC PGM=PAYROLL,PARM=%DIVISION
//S2 EXEC PGM=PGM2
226 Using Templates
Example:
Running an
hourly job
In this example, J ob 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 J ob 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 0
MULTIRUN 1
MULTIRUN 2
MULTIRUN 3
MULTIRUN 4
MULTIRUN 5
MULTIRUN 6
MULTIRUN 7
MULTIRUN 8
This generates the following J OB statements and DELAYSUB times:
JOB Statement DELAYSUBTime
ABC.0 8AM PLUS 0 HOURS
Advanced Tracking 227
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.
J ob 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.
Topic See Page
Tracking System Messages 228
Manipulating the Tracking of Messages 231
Defining Processing Nodes (P-Nodes) 233
Displaying Tracking Information 237
228 Advanced Tracking
Tracking System Messages
About tracking
system messages
ESP can intercept and track any system messages as they are written to the J ES
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 J ES 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.
Follow-up action After intercepting a message, ESP can take further action such as:
Triggering an Event.
Cancelling a job.
Failing a job with a J CL error or condition code failure.
Re-broadcasting the message to a specific terminal or operator as a WTO
message.
Setting up
tracking
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.
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
Step 2: Identify
the Messages and
ESP Action
To identify which system messages ESP intercepts, use the SYSMSGS
command on the tracking system. When you use this command, you can:
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.
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)
Manipulating the Tracking of Messages
About
manipulating
tracked messages
You can use different commands to list all tracked system messages, turn
specifications on and off, or clear IDs that have a definition. The applicable
commands are:
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)
LSYSMSG List system messages.
CLRSYSMS Clear system messages.
SYSMSGS Enable/disable individual system messages.
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)
Defining Processing Nodes (P-Nodes)
About processing
nodes
Processing Nodes (also known as P-Nodes) are the processing stages of a job.
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 P-
Nodes
The following P-Nodes are normally defined during installation. ESP tracks
information about job processing, automatically, through the following P-
Nodes:
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.
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.
EXEC 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.
OUTPUT 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.
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.
Example:
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-)
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. J ob MYJ OB must be posted through the
DISTRIB P-Node.
JOB MYJOB
PNODES DISTRIB
RUN DAILY
ENDJOB
Using a P-Node as a job requirement, continued
This example defines tracking model DISTJ OBS 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 MYJ OB 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.
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 P-
Node 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)
Displaying Tracking Information
About displaying
tracking
information
Use the following commands to retrieve information about job tracking
queues:
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.
Example: The
DISTRIB P-Node
The following example displays the DISTRIB P-Node.
dn queue(distrib)
DISTRIB: MYJOB 06688
Example:
Display of all P-
Nodes
The following example displays all P-Nodes.
dn
INPUT: BACKUPI1 05321
EXEC: ESPAAUX, 07631, TSO 07629, ENC120A 07981,
INIT 02640, ENC120M 02940, ENC111M 02943,
DASL 03412, XDCCDF 03492, ASCHINT 03643,
ASCHINT 04854, ENCBETAM 05131, ENCBETAX 05132,
MS3270 05288, ESPD 06287, ES43 06293,
COPILOT 06326, ES43XDC 06447, INFODEMO 06693,
OUTPUT: CYBSV01W 06692, CYBSV01W 06694
DISTRIB: MYJOB 06688
Advanced Forecasting 239
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.
Topic See Page
How Modeling Works 240
Limitations of Modeling 241
Setting Up Your Model 242
Examples 257
A Modeling Example With Sample Reports 259
240 Advanced Forecasting
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
J ES 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 com-
pute 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 exam-
ple, 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.
Limitations of Modeling
About limitations
of modeling
The data that ESP modeling produces is only as valid as the data you enter into
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 fore-
casted initiator and the availability of resources.
Unavailability of some of the resources due to hardware problems.
Setting Up Your Model
How to set up
your model
Follow these steps to set up your model:
Step Action
1 Generate the Scheduled Activity data set. See page 243.
2 Activate the Model Processor. See page 244.
3 Define the model. See page 246.
4 Define your environment. See page 247.
5 Define your report. See page 251.
6 Close the definition and generate the model. See page 255.
7 Examine the model reports. See page 256.
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
//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.
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:
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).
MODEL Invokes the model definition mode.
dsname Name of the scheduled activity data set containing
scheduled jobs for model period.
START Keyword indicating start of model period.
schedule 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.
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
//MODEL1 DD SYSOUT=S
//SYSIN DD *
DEFPRINT XY1 DDNAME(MODEL1)
MODEL ESP.SAD.DATA +
. . .
You are now ready to define your model, using appropriate commands (see
step 3 to define the model).
Defining the Model
How to define the
model
To specify the modeling environment, insert model definition commands or
ESP Procedure statements. These include:
Environment definition commands.
ESP Procedural language statements, known as CLANG statements. These
are optional.
Report definition commands.
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 J ES. 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)
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 ADJ UST 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-)
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 J CL 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.
Example1:
CLANG defines
different start-up
times for
initiators
The examples that follow illustrate the use of CLANG statements in two
different model situations.
Assume that J ES starts twenty class X initiators each morning at 6:00 a.m.
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)
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
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:
The following are the formatting requirements for titles:
Specify TITLE 1 before TITLE 2.
Specify TITLE 2 before the next DEFPRINT command.
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.
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:
Note: The recommended data width for all reports is 133 with a record format
of FBA.
This example requests a Scheduled J obs Cross Reference report
(J OB_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.
Description Report Name Abbreviation
Scheduled J obs Cross Reference J OB_REPORT_1 J R1
Projected End Time Report J OB_REPORT_2 J R2
Resource Utilization On Systems RESOURCE_REPORT_1 RR1
Resource Utilization By J ob RESOURCE_REPORT_2 RR2
J ob Exception Report EXCEPTION_REPORT_1 ER1
Dueout Exception Report EXCEPTION_REPORT_2 ER2
Scheduled jobs
cross-reference
report
Definition Name: J OB_REPORT_1 (J R1)
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: J OB_REPORT_2 (J R2)
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.
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 his-
tories).
Resource
utilization by job
Definition Name: RESOURCE_REPORT_2 (RR2)
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 defini-
tions in ESP procedures or job documentation members and default
resources.
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.
Dueout exception
report
Definition Name: EXCEPTION_REPORT_2 (ER2)
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.
Closing Definition Mode and Generating Model
About ending the
model definition
After you have defined the model (see previous step) enter the ENDMODEL
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 J R1RPT.
ENDPRINT JRIRPT
Examining the Model Reports
About examining
model reports
When you run your model, ESP will direct the output to your DEFPRINT files.
To view examples of reporting output, refer to A Modeling Example With
Sample Reports on page 259.
Examples
Example: Setting
up a model
The following statements create a Scheduled Activity data set, called
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 J R1 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
//SYSIN DD *
SADGEN DATASET(ESP.SAD.DATA) -
FROM(6AM TODAY) TO(6AM TOMORROW)
/*
//STEP0020 EXEC PGM=ESP,REGION=4M
//MODEL1 DD SYSOUT=S
//SYSIN DD *
DEFPRINT XREF DDNAME(MODEL1)
TITLE 2 %CE(PRODUCTION CONTROL - SCHEDULING DEPT.)
MAXINITS 4
INIT START(1:4) CLASS(A)
MREPORT XREF JR1 -
FROM(6AM TODAY ENDING 6AM TOMORROW)
ENDMODEL
ENDPRINT XREF
/*
//
Examples, continued
Example:
Ignoring job
classes
The following is a simple example of the modeling commands to create a
Scheduled J obs Cross-Reference Report (J R1). 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 J R1 report.
START(6AM TODAY ENDING 6AM TOMORROW) NOCLASS
MAXINITS 999
MREPORT XREF JR1 -
FROM(6AM TODAY ENDING 6AM TOMORROW)
ENDMODEL
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)
DEFPRINT JR2REP DATASET(CYB1.MLTEST.MREPORT7)
TITLE 2 %RJ(FORWARD TO DEPT. IS900)
DEFPRINT RR1REP DATASET(CYB1.MLTEST.MREPORT3)
TITLE 2 %CE(DATA CENTER OPERATIONS)
DEFPRINT RR2REP DATASET(CYB1.MLTEST.MREPORT4)
DEFPRINT ER1REP DATASET(CYB1.MLTEST.MREPORT5)
TITLE 2 %CE(PRODUCTION CONTROL - SCHEDULING DEPT.)
DEFPRINT ER2REP DATASET(CYB1.MLTEST.MREPORT6)
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)

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
reports
The reports ESP generates from the preceding model definition statements
appear on the next several pages of this chapter.
2
6
1

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

S
C
H
E
D
U
L
E
D

J
O
B
S

C
R
O
S
S

R
E
F
E
R
E
N
C
E

F
R
O
M

0
0
.
0
0

0
4
/
2
1
/
9
4

T
O

2
3
.
5
9

0
4
/
2
1
/
9
4

P
A
G
E

1
J
O
B
N
A
M
E
J
O
B

Q
U
A
L

A
P
P

N
A
M
E

N
E
T

N
A
M
E

T
I
M
E

D
A
T
E

C
P
U

P
R
E
D
E
C
E
S
S
O
R
S

S
U
C
C
E
S
S
O
R
S
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-

-
-
-
-
-

-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
D
E
M
O
1
R
U
N
1
D
E
M
O
N
T
1
0
0
.
0
0

0
4
/
2
1
0

D
E
M
O
1
.
R
U
N
2
,
D
E
M
O
1
.
R
U
N
3
,

D
E
M
O
1
.
R
U
N
4
,
D
E
M
O
1
.
R
U
N
5
D
E
M
O
1
R
U
N
2
D
E
M
O
N
T
1
0
0
.
0
1

0
4
/
2
1
0
D
E
M
O
1
.
R
U
N
1
D
E
M
O
1
R
U
N
3
D
E
M
O
N
T
1
0
0
.
0
1

0
4
/
2
1
0
D
E
M
O
1
.
R
U
N
1
D
E
M
O
1
R
U
N
4
D
E
M
O
N
T
1
0
0
.
0
1

0
4
/
2
1
0
D
E
M
O
1
.
R
U
N
1
D
E
M
O
1
R
U
N
5
D
E
M
O
N
T
1
0
0
.
0
1

0
4
/
2
1
0
D
E
M
O
1
.
R
U
N
1
C
Y
B
T
E
S
T
1
S
A
D
N
E
T
1
0
0
.
1
0
0
4
/
2
1

0
C
Y
B
T
E
S
T
2
C
Y
B
T
E
S
T
2
S
A
D
N
E
T
1
0
0
.
1
1
0
4
/
2
1

0
C
Y
B
T
E
S
T
1
C
Y
B
T
E
S
T
3
C
Y
B
T
E
S
T
3
S
A
D
N
E
T
1
0
0
.
1
2
0
4
/
2
1

0
C
Y
B
T
E
S
T
2
C
Y
B
T
E
S
T
4
,
C
Y
B
T
E
S
T
5
C
Y
B
T
E
S
T
4
S
A
D
N
E
T
1
0
0
.
1
3
0
4
/
2
1

0
C
Y
B
T
E
S
T
3
C
Y
B
T
E
S
T
6
C
Y
B
T
E
S
T
5
S
A
D
N
E
T
1
0
0
.
1
3
0
4
/
2
1

0
C
Y
B
T
E
S
T
3
C
Y
B
T
E
S
T
6
C
Y
B
T
E
S
T
6
S
A
D
N
E
T
1
0
0
.
1
4
0
4
/
2
1

0
C
Y
B
T
E
S
T
4
,

C
Y
B
T
E
S
T
5
C
Y
B
T
E
S
T
7
C
Y
B
T
E
S
T
7
S
A
D
N
E
T
1
0
0
.
1
5
0
4
/
2
1

0
C
Y
B
T
E
S
T
6
C
Y
B
E
S
0
1
1
S
A
D
N
E
T
1
0
0
.
1
5
0
4
/
2
1

0
C
Y
B
E
S
0
1
2
C
Y
B
E
S
0
1
2
S
A
D
N
E
T
1
0
0
.
1
8
0
4
/
2
1

0
C
Y
B
E
S
0
1
1
C
Y
B
J
S
0
1
0
S
O
R
T
J
O
B
1
S
O
R
T
J
O
B
S
0
0
.
2
0
0
4
/
2
1

0
S
O
R
T
J
O
B
2
,

S
O
R
T
J
O
B
3
C
Y
B
J
S
0
1
0
S
A
D
N
E
T
1
0
0
.
2
0
0
4
/
2
1

0
C
Y
B
E
S
0
1
2
C
Y
B
J
S
1
0
8
C
Y
B
J
S
1
0
8
S
A
D
N
E
T
1
0
0
.
2
2
0
4
/
2
1

0
C
Y
B
J
S
0
1
0
C
Y
B
J
S
1
0
9
C
Y
B
J
S
1
0
9
S
A
D
N
E
T
1
0
0
.
2
4
0
4
/
2
1

0
C
Y
B
J
S
1
0
8
S
O
R
T
J
O
B
2
S
O
R
T
J
O
B
S
0
0
.
2
6
0
4
/
2
1

0
S
O
R
T
J
O
B
1
S
O
R
T
J
O
B
3
S
O
R
T
J
O
B
S
0
0
.
2
6
0
4
/
2
1

0
S
O
R
T
J
O
B
1
C
Y
B
T
E
S
T
1
S
A
D
N
E
T
1
0
0
.
3
0
0
4
/
2
1

0
C
Y
B
T
E
S
T
2
C
Y
B
T
E
S
T
2
S
A
D
N
E
T
1
0
0
.
3
1
0
4
/
2
1

0
C
Y
B
T
E
S
T
1
C
Y
B
T
E
S
T
3
C
Y
B
T
E
S
T
3
S
A
D
N
E
T
1
0
0
.
3
2
0
4
/
2
1

0
C
Y
B
T
E
S
T
2
P
R
O
D
1
0
P
R
O
D
0
0
.
3
5
0
4
/
2
1

0
P
R
O
D
2
0
,

P
R
O
D
3
0
P
R
O
D
2
0
P
R
O
D
0
0
.
4
1
0
4
/
2
1

0
P
R
O
D
1
0
P
R
O
D
4
0
P
R
O
D
3
0
P
R
O
D
0
0
.
4
1
0
4
/
2
1

0
P
R
O
D
1
0
P
R
O
D
5
0
P
A
Y
1
0
0
P
A
Y
R
O
L
L
0
0
.
4
5
0
4
/
2
1

0
P
A
Y
3
0
0
,

P
A
Y
4
0
0
P
A
Y
2
0
0
P
A
Y
R
O
L
L
0
0
.
4
5
0
4
/
2
1

0
P
A
Y
2
1
0
P
A
Y
2
1
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1

0
P
A
Y
2
0
0
P
A
Y
2
2
0
P
A
Y
3
0
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1

0
P
A
Y
1
0
0
P
A
Y
3
1
0
P
A
Y
4
0
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1

0
P
A
Y
1
0
0
P
A
Y
5
0
0
2
6
2
P
R
O
D
4
0
P
R
O
D
0
0
.
4
7
0
4
/
2
1

0
P
R
O
D
2
0
P
R
O
D
6
0
,

P
R
O
D
7
0
,
P
R
O
D
8
0
,

P
R
O
D
9
0
P
A
Y
3
1
0
P
A
Y
R
O
L
L
0
0
.
5
2
0
4
/
2
1

0
P
A
Y
3
0
0
P
A
Y
5
0
0
P
R
O
D
6
0
P
R
O
D
0
0
.
5
3
0
4
/
2
1

0
P
R
O
D
4
0
P
R
O
D
7
0
P
R
O
D
0
0
.
5
3
0
4
/
2
1

0
P
R
O
D
4
0
P
R
O
D
8
0
P
R
O
D
0
0
.
5
3
0
4
/
2
1

0
P
R
O
D
4
0
P
R
O
D
9
0
P
R
O
D
0
0
.
5
3
0
4
/
2
1

0
P
R
O
D
4
0
A
C
C
5
0
0
0
A
C
C
9
9
0
1
.
0
5
0
4
/
2
1

0
A
C
C
6
1
0
0
,

A
C
C
6
2
0
0
A
C
C
6
1
0
0
A
C
C
9
9
0
1
.
1
1
0
4
/
2
1

0
A
C
C
5
0
0
0
A
C
C
6
2
0
0
A
C
C
9
9
0
1
.
1
1
0
4
/
2
1

0
A
C
C
5
0
0
0
P
R
O
D
5
0
P
R
O
D
0
1
.
3
0
0
4
/
2
1

0
P
R
O
D
3
0
P
A
Y
2
2
0
P
A
Y
R
O
L
L
0
1
.
3
0
0
4
/
2
1

0
P
A
Y
2
1
0
P
A
Y
2
3
0
P
A
Y
2
3
0
P
A
Y
R
O
L
L
0
1
.
3
1
0
4
/
2
1

0
P
A
Y
2
2
0
P
A
Y
5
0
0
P
A
Y
5
0
0
P
A
Y
R
O
L
L
0
1
.
3
2
0
4
/
2
1

0
P
A
Y
2
3
0
,

P
A
Y
3
1
0
,

P
A
Y
4
0
0
C
Y
B
T
E
S
T
1
A
P
P
L
1
0
9
.
0
2
0
4
/
2
1

0
C
Y
B
T
E
S
T
2
C
Y
B
T
E
S
T
2
A
P
P
L
1
0
9
.
0
3
0
4
/
2
1

0
C
Y
B
T
E
S
T
1
A
A
1
2
.
3
7
0
4
/
2
1
0

C
C
C
C
1
2
.
3
8
0
4
/
2
1
0
A
A
B
2
1
5
.
1
3
0
4
/
2
1
0
N
A
V
R
J
E
N
A
V
R
J
E
1
5
.
1
5
0
4
/
2
1

0
N
A
V
1
N
A
V
1
N
A
V
R
J
E
1
5
.
1
6
0
4
/
2
1

0
N
A
V
R
J
E
N
A
V
2
2
6
3

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

D
A
T
A

C
E
N
T
E
R

O
P
E
R
A
T
I
O
N
S

R
E
S
O
U
R
C
E

U
T
I
L
I
Z
A
T
I
O
N

O
N

A
L
L

S
Y
S
T
E
M
S

F
R
O
M

0
0
.
0
0

0
4
/
2
1
/
9
0

T
O

0
8
.
5
9

0
4
/
2
1
/
9
0

P
A
G
E

1

R
E
S
O
U
R
C
E
:

%

C
P
U

C
I
C
S

D
A
Y
S
H
I
F
T

I
M
S

N
I
T
E
S
H
F
T

P
E
R
M
D
A
S
D

S
C
R
A
T
C
H

S
O
R
T
W
R
K

T
A
P
E
3
4
2
0

T
A
P
E
3
4
8
0

C
P
U
:

(
A
L
L
)

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

G
L
O
B
A
L

-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

0
0
.
0
0

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
0
2

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
0
4

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
0
6

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
0
8

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
1
0

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
1
2

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
1
4

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
1
6

4
3

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
1
8

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
2
0

4
1

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
2
2

9

1

0

2

1

1
0
0
0
0

2
0
0

4
5
0
0

0

1
0

0
0
.
2
4

8

1

0

2

1

1
0
0
0
0

2
0
0

4
5
0
0

0

1
0

0
0
.
2
6

5
3

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
2
8

0

1

0

2

1

1
0
0
0
0

2
0
0

4
5
5
0

0

1
0

0
0
.
3
0

0

1

0

2

1

1
0
0
0
0

2
0
0

4
5
5
0

0

1
0

0
0
.
3
2

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
3
4

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
3
6

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
3
8

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
4
0

0

1

0

2

1

1
0
0
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
4
2

0

1

0

1

1

9
7
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
4
4

0

1

0

1

1

9
7
0
0

2
0
0

5
0
0
0

0

1
0

0
0
.
4
6

0

1

0

1

1

9
5
0
0

1
9
4

5
0
0
0

0

8

0
0
.
4
8

0

1

0

0

1

9
2
9
0

1
9
4

5
0
0
0

0

4

0
0
.
5
0

0

1

0

0

1

9
2
9
0

1
9
4

5
0
0
0

0

4

0
0
.
5
2

0

1

0

1

1

9
2
9
0

1
9
4

5
0
0
0

0

7

0
0
.
5
4

0

1

0

1

1

9
2
9
0

1
9
4

5
0
0
0

0

1
0

0
0
.
5
6

0

1

0

1

1

9
2
9
0

1
9
4

5
0
0
0

0

1
0

0
0
.
5
8

0

1

0

1

1

9
2
9
0

1
9
4

5
0
0
0

0

1
0

0
1
.
0
0

0

0

0

1

1

1
4
2
9
0

2
4
4

5
0
0
0

0

8

0
1
.
0
2

0

0

0

1

1

1
4
2
9
0

2
4
4

5
0
0
0

0

8

0
1
.
0
4

0

0

0

1

1

1
4
2
9
0

2
4
4

5
0
0
0

0

8
2
6
4

0
1
.
0
6

0

0

0

1

1

1
4
2
9
0

2
3
4

5
0
0
0

0

2

0
1
.
0
8

0

0

0

1

1

1
4
2
9
0

2
3
4

5
0
0
0

0

2

0
1
.
1
0

0

0

0

1

1

1
4
2
9
0

2
3
4

5
0
0
0

0

2

0
1
.
1
2

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
1
4

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
1
6

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
1
8

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
2
0

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
2
2

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
2
4

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
2
6

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
2
8

0

0

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

0

8

0
1
.
3
0

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8

0
1
.
3
2

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

1

8

0
1
.
3
4

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

1

8

0
1
.
3
6

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8

0
1
.
3
8

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8

0
1
.
4
0

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8

0
1
.
4
2

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8

0
1
.
4
4

0

1

0

1

1

1
3
0
9
0

2
3
4

5
0
0
0

2

8
2
6
5

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

R
E
S
O
U
R
C
E

U
T
I
L
I
Z
A
T
I
O
N

B
Y

J
O
B

F
R
O
M

0
0
.
0
0

0
4
/
2
1
/
9
0

T
O

2
3
.
5
9

0
4
/
2
1
/
9
0

P
A
G
E

1

J
O
B
N
A
M
E

J
O
B

Q
U
A
L

A
P
P

N
A
M
E

N
E
T

N
A
M
E

T
I
M
E

D
A
T
E

C
P
U

R
E
S
O
U
R
C
E
S

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-

-
-
-
-
-

-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
S
O
R
T
J
O
B
1
S
O
R
T
J
O
B
S
0
0
.
2
0
0
4
/
2
1

0
5
0
0
,
S
O
R
T
W
R
K
S
O
R
T
J
O
B
2
S
O
R
T
J
O
B
S
0
0
.
2
6
0
4
/
2
1

0
1
0
0
,
S
O
R
T
W
R
K
S
O
R
T
J
O
B
3
S
O
R
T
J
O
B
S
0
0
.
2
6
0
4
/
2
1

0
3
0
0
,
S
O
R
T
W
R
K
P
R
O
D
1
0
P
R
O
D
0
0
.
3
5
0
4
/
2
1
0

1
0
0
,
P
E
R
M
D
A
S
D
,

1
,
C
I
C
S
P
R
O
D
2
0
P
R
O
D
0
0
.
4
1
0
4
/
2
1
0

2
0
0
,
P
E
R
M
D
A
S
D
,

1
,
C
I
C
S
P
R
O
D
3
0
P
R
O
D
0
0
.
4
1
0
4
/
2
1
0

3
0
0
,
P
E
R
M
D
A
S
D
,

1
,
I
M
S
P
A
Y
1
0
0
P
A
Y
R
O
L
L
0
0
.
4
5
0
4
/
2
1

0
1
,
T
A
P
E
3
4
8
0
,

6
,
S
C
R
A
T
C
H
P
A
Y
2
0
0
P
A
Y
R
O
L
L
0
0
.
4
5
0
4
/
2
1

0
1
,
T
A
P
E
3
4
8
0
,

2
0
0
,
P
E
R
M
D
A
S
D
P
A
Y
2
1
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1

0
2
,
T
A
P
E
3
4
8
0
,

2
1
0
,
P
E
R
M
D
A
S
D
P
A
Y
3
0
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1

0
3
,
T
A
P
E
3
4
8
0
,

1
,
I
M
S
P
R
O
D
4
0
P
R
O
D
0
0
.
4
7
0
4
/
2
1
0

3
,
T
A
P
E
3
4
8
0
P
A
Y
3
1
0
P
A
Y
R
O
L
L
0
0
.
5
2
0
4
/
2
1

0
1
,
I
M
S
A
C
C
5
0
0
0
A
C
C
9
9
0
1
.
0
5
0
4
/
2
1
0

6
,
T
A
P
E
3
4
8
0
,

1
0
,
S
C
R
A
T
C
H
A
C
C
6
1
0
0
A
C
C
9
9
0
1
.
1
1
0
4
/
2
1
0

6
0
0
,
P
E
R
M
D
A
S
D
A
C
C
6
2
0
0
A
C
C
9
9
0
1
.
1
1
0
4
/
2
1
0

6
0
0
,
P
E
R
M
D
A
S
D
P
R
O
D
5
0
P
R
O
D
0
1
.
3
0
0
4
/
2
1
0

1
,
T
A
P
E
3
4
2
0
P
A
Y
2
2
0
P
A
Y
R
O
L
L
0
1
.
3
0
0
4
/
2
1

0
1
,
T
A
P
E
3
4
2
0
P
A
Y
5
0
0
P
A
Y
R
O
L
L
0
1
.
3
2
0
4
/
2
1

0
4
0
0
,
S
O
R
T
W
R
K
2
6
6

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

P
R
O
D
U
C
T
I
O
N

C
O
N
T
R
O
L

-

S
C
H
E
D
U
L
I
N
G

D
E
P
T
.

J
O
B

E
X
C
E
P
T
I
O
N

R
E
P
O
R
T

F
O
R

M
O
D
E
L
L
I
N
G

P
E
R
I
O
D

0
0
.
0
0

0
4
/
2
1
/
9
0

T
O

2
3
.
5
9

0
4
/
2
1
/
9
0

P
A
G
E

1

J
O
B
N
A
M
E

J
O
B

Q
U
A
L

A
P
P

N
A
M
E

N
E
T

N
A
M
E

S
C
H
E
D

D
A
T
E
/
T
I
M
E

D
E
T
A
I
L
S

R
E
A
S
O
N

R
E
Q
U
I
R
E
M
E
N
T
S
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
D
E
M
O
2
E
X
E
C
1
D
E
M
O
N
T
2
0
4
/
2
1
/
9
0
0
0
.
0
0

N
O
T

S
C
H
E
D
U
L
E
D
R
E
S
O
U
R
C
E
S
(
S
)
5
1
0
0
,
S
O
R
T
W
R
K
D
E
M
O
2
E
X
E
C
2
D
E
M
O
N
T
2
0
4
/
2
1
/
9
0
0
0
.
0
0

N
O
T

S
C
H
E
D
U
L
E
D
P
R
E
D
E
C
E
S
S
O
R
(
S
)
D
E
M
O
2
.
E
X
E
C
1
D
E
M
O
2
E
X
E
C
3
D
E
M
O
N
T
2
0
4
/
2
1
/
9
0
0
0
.
0
0

N
O
T

S
C
H
E
D
U
L
E
D
R
E
D
E
C
E
S
S
O
R
(
S
)
D
E
M
O
2
.
E
X
E
C
1
D
E
M
O
2
E
X
E
C
4
D
E
M
O
N
T
2
0
4
/
2
1
/
9
0
0
0
.
0
0

N
O
T

S
C
H
E
D
U
L
E
D
P
R
E
D
E
C
E
S
S
O
R
(
S
)
D
E
M
O
2
.
E
X
E
C
1
D
E
M
O
2
E
X
E
C
5
D
E
M
O
N
T
2
0
4
/
2
1
/
9
0
0
0
.
0
0

N
O
T

S
C
H
E
D
U
L
E
D
R
E
D
E
C
E
S
S
O
R
(
S
)
D
E
M
O
2
.
E
X
E
C
1
P
R
O
D
9
0
P
R
O
D
0
4
/
2
1
/
9
0
0
0
.
3
5
P
A
S
T

D
U
E

O
U
T
0
4
/
2
1
/
9
0

0
0
.
3
5

D
U
E
O
U
T

O
F

E
X
E
C
U
T
I
O
N

0
4
/
2
1
/
9
0

0
0
.
5
3

E
A
R
L
I
-
E
S
T

P
R
O
J
E
C
T
E
D

S
T
A
R
T

T
I
M
E
P
A
Y
2
3
0
P
A
Y
R
O
L
L
0
4
/
2
1
/
9
0
0
0
.
4
5
P
A
S
T

D
U
E

O
U
T
0
4
/
2
1
/
9
0

0
0
.
4
6

D
U
E
O
U
T

O
F

E
X
E
C
U
T
I
O
N

0
4
/
2
1
/
9
0

0
1
.
3
1

E
A
R
L
I
-
E
S
T

P
R
O
J
E
C
T
E
D

S
T
A
R
T

T
I
M
E
P
A
Y
5
0
0
P
A
Y
R
O
L
L
0
4
/
2
1
/
9
0
0
0
.
4
5
P
A
S
T

D
U
E

O
U
T
0
4
/
2
1
/
9
0

0
0
.
4
9

D
U
E
O
U
T

O
F

E
X
E
C
U
T
I
O
N

0
4
/
2
1
/
9
0

0
1
.
3
2

E
A
R
L
I
-
E
S
T

P
R
O
J
E
C
T
E
D

S
T
A
R
T

T
I
M
E
B
K
U
P
9
0
0
0
4
/
2
1
/
9
0
0
1
.
1
5
N
O
T

S
C
H
E
D
U
L
E
D
I
N
I
T
I
A
T
O
R
C
L
A
S
S

E
R
E
Q
U
I
R
E
D
2
6
7

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

A
T
T
N
:

F
R
E
D

B
L
O
G
G
S

D
U
E
O
U
T

E
X
C
E
P
T
I
O
N

R
E
P
O
R
T

F
O
R

M
O
D
E
L
L
I
N
G

P
E
R
I
O
D

0
0
.
0
0

0
4
/
2
1
/
9
0

T
O

2
3
.
5
9

0
4
/
2
1
/
9
0

P
A
G
E

1

J
O
B
N
A
M
E

J
O
B

Q
U
A
L

A
P
P

N
A
M
E

N
E
T

N
A
M
E

E
X
E
C
U
T
I
O
N

D
U
E
O
U
T

P
R
O
J
E
C
T
E
D

E
N
D

D
E
V
I
A
T
I
O
N

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-

P
R
O
D
9
0

P
R
O
D

0
4
/
2
1
/
9
0

0
0
.
3
5

0
4
/
2
1
/
9
0

0
0
.
5
3

0
:
2
3

P
A
Y
2
3
0

P
A
Y
R
O
L
L

0
4
/
2
1
/
9
0

0
0
.
4
6

0
4
/
2
1
/
9
0

0
1
.
3
1

0
:
4
5

P
A
Y
5
0
0

P
A
Y
R
O
L
L

0
4
/
2
1
/
9
0

0
0
.
4
9

0
4
/
2
1
/
9
0

0
1
.
3
2

0
:
4
3
2
6
8

C
Y
B
E
R
M
A
T
I
O
N

I
N
C
.

F
O
R
W
A
R
D

T
O

D
E
P
T
.

I
S
9
0
0

P
R
O
J
E
C
T
E
D

E
N
D

T
I
M
E

R
E
P
O
R
T

F
R
O
M

0
0
.
0
0

0
4
/
2
1
/
9
0

T
O

2
3
.
5
9

0
4
/
2
1
/
9
0

P
A
G
E

1

J
O
B
N
A
M
E

J
O
B

Q
U
A
L

A
P
P

N
A
M
E

N
E
T

N
A
M
E

P
R
O
J
E
C
T
E
D

E
N
D

E
X
E
C
U
T
I
O
N

D
U
E
O
U
T

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
D
E
M
O
1
R
U
N
1
D
E
M
O
N
T
1
0
0
.
0
1

0
4
/
2
1
/
9
0
D
E
M
O
1
R
U
N
2
D
E
M
O
N
T
1
0
0
.
0
2

0
4
/
2
1
/
9
0
D
E
M
O
1
R
U
N
3
D
E
M
O
N
T
1
0
0
.
0
2

0
4
/
2
1
/
9
0
D
E
M
O
1
R
U
N
4
D
E
M
O
N
T
1
0
0
.
0
2

0
4
/
2
1
/
9
0
D
E
M
O
1
R
U
N
5
D
E
M
O
N
T
1
0
0
.
0
2

0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
1
S
A
D
N
E
T
1
0
0
.
1
1
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
2
S
A
D
N
E
T
1
0
0
.
1
2
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
3
S
A
D
N
E
T
1
0
0
.
1
3
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
4
S
A
D
N
E
T
1
0
0
.
1
4
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
5
S
A
D
N
E
T
1
0
0
.
1
4
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
6
S
A
D
N
E
T
1
0
0
.
1
5
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
7
S
A
D
N
E
T
1
0
0
.
1
6
0
4
/
2
1
/
9
0
C
Y
B
E
S
0
1
1
S
A
D
N
E
T
1
0
0
.
1
8
0
4
/
2
1
/
9
0
C
Y
B
E
S
0
1
2
S
A
D
N
E
T
1
0
0
.
2
0
0
4
/
2
1
/
9
0
C
Y
B
J
S
0
1
0
S
A
D
N
E
T
1
0
0
.
2
2
0
4
/
2
1
/
9
0
C
Y
B
J
S
1
0
8
S
A
D
N
E
T
1
0
0
.
2
4
0
4
/
2
1
/
9
0
S
O
R
T
J
O
B
1
S
O
R
T
J
O
B
S
0
0
.
2
6
0
4
/
2
1
/
9
0
C
Y
B
J
S
1
0
9
S
A
D
N
E
T
1
0
0
.
2
6
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
1
S
A
D
N
E
T
1
0
0
.
3
1
0
4
/
2
1
/
9
0
S
O
R
T
J
O
B
2
S
O
R
T
J
O
B
S
0
0
.
3
2
0
4
/
2
1
/
9
0
S
O
R
T
J
O
B
3
S
O
R
T
J
O
B
S
0
0
.
3
2
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
2
S
A
D
N
E
T
1
0
0
.
3
2
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
3
S
A
D
N
E
T
1
0
0
.
3
3
0
4
/
2
1
/
9
0
P
R
O
D
1
0
P
R
O
D
0
0
.
4
1
0
4
/
2
1
/
9
0
P
A
Y
1
0
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1
/
9
0
P
A
Y
2
0
0
P
A
Y
R
O
L
L
0
0
.
4
6
0
4
/
2
1
/
9
0
P
R
O
D
2
0
P
R
O
D
0
0
.
4
7
0
4
/
2
1
/
9
0
P
R
O
D
3
0
P
R
O
D
0
0
.
4
7
0
4
/
2
1
/
9
0
P
A
Y
2
1
0
P
A
Y
R
O
L
L
0
0
.
4
7
0
4
/
2
1
/
9
0
P
A
Y
4
0
0
P
A
Y
R
O
L
L
0
0
.
4
7
0
4
/
2
1
/
9
0
P
A
Y
3
0
0
P
A
Y
R
O
L
L
0
0
.
5
2
0
4
/
2
1
/
9
0
P
R
O
D
4
0
P
R
O
D
0
0
.
5
3
0
4
/
2
1
/
9
0
P
A
Y
3
1
0
P
A
Y
R
O
L
L
0
0
.
5
3
0
4
/
2
1
/
9
0
P
R
O
D
6
0
P
R
O
D
0
0
.
5
9
0
4
/
2
1
/
9
0
2
6
9
P
R
O
D
7
0
P
R
O
D
0
0
.
5
9
0
4
/
2
1
/
9
0
P
R
O
D
8
0
P
R
O
D
0
0
.
5
9
0
4
/
2
1
/
9
0
P
R
O
D
9
0
P
R
O
D
0
0
.
5
9
0
4
/
2
1
/
9
0
0
0
.
3
5

0
4
/
2
1
/
9
0

*
*

P
A
S
T

D
U
E

O
U
T

*
*
A
C
C
5
0
0
0
A
C
C
9
9
0
1
.
1
1
0
4
/
2
1
/
9
0
A
C
C
6
1
0
0
A
C
C
9
9
0
1
.
1
7
0
4
/
2
1
/
9
0
A
C
C
6
2
0
0
A
C
C
9
9
0
1
.
1
7
0
4
/
2
1
/
9
0
0
1
.
5
9

0
4
/
2
1
/
9
0
P
A
Y
2
2
0
P
A
Y
R
O
L
L
0
1
.
3
1
0
4
/
2
1
/
9
0
P
A
Y
2
3
0
P
A
Y
R
O
L
L
0
1
.
3
2
0
4
/
2
1
/
9
0

0
0
.
4
6

0
4
/
2
1
/
9
0

*
*

P
A
S
T

D
U
E

O
U
T

*
*
P
A
Y
5
0
0
P
A
Y
R
O
L
L
0
1
.
3
3
0
4
/
2
1
/
9
0

0
0
.
4
9

0
4
/
2
1
/
9
0

*
*

P
A
S
T

D
U
E

O
U
T

*
*
P
R
O
D
5
0
P
R
O
D
0
1
.
3
6
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
1
A
P
P
L
1
0
9
.
0
3
0
4
/
2
1
/
9
0
C
Y
B
T
E
S
T
2
A
P
P
L
1
0
9
.
0
4
0
4
/
2
1
/
9
0
A
A
1
2
.
3
8
0
4
/
2
1
/
9
0
C
C
1
2
.
3
9
0
4
/
2
1
/
9
0
B
2

1
5
.
1
4
0
4
/
2
1
/
9
0
N
A
V
R
J
E
N
A
V
R
J
E
1
5
.
1
6
0
4
/
2
1
/
9
0
N
A
V
1
N
A
V
R
J
E
1
5
.
1
7
0
4
/
2
1
/
9
0
N
A
V
2
N
A
V
R
J
E
1
5
.
1
8
0
4
/
2
1
/
9
0
N
A
V
3
N
A
V
R
J
E
1
5
.
1
9
0
4
/
2
1
/
9
0
2
7
0
Using REXX with ESP 271
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.
Topic See Page
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 J obs 294
Using REXX to Build Applications 296
Using REXX to Define Special Days 300
Updating a Symbolic Variable 301
Using REXX Execs 303
272 Using REXX with ESP
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.
Where to insert
REXX
expressions
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.
About Using REXX, continued
Limitations of
using REXX with
ESP
The ESP Procedure environment is not a TSO environment. You cannot use
commands in an ESP Procedure that require a full TSO environment. An
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, J OBINDEX,
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.
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.
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 ESP Commands Within REXX
About using ESP
commands
within REXX
You can specify ESP commands or statements within REXX. When you are
entering this type of data, you must format the input as follows:
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
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 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)
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.
Example 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
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.
REXX functions The following table lists built-in ESP-REXX functions and identifies the
equivalent built-in functions in ESPs CLANG.
Built-in
Function
CLANG Equival ent
Description
TODAY TODAY Tests schedule criteria for todays date.
YESTERDAY YESTERDAY Tests schedule criteria for yesterdays date.
TOMORROW TOMORROW
Tests schedule criteria for tomorrows date.
DAYSTO DAYS_TO Calculates number of days between now
and a particular date in the future.
DAYSFROM DAYS_FROM
Calculates number of days between now
and a particular date in the past.
DAYSBETW DAYS_BETWEEN Calculates the number of days (or
workdays, months, years, and so on)
between two dates.
ACTIVE ACTIVE
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).
SELECTED SELECTED
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.
J OBONQ J OBONQ
Investigates J ES queues.
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 J une, J uly, 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.
Commands and Functions With TSO Equivalent
About commands
and functions
with TSO
equivalent
The following table lists ESP-REXX functions and commands with TSO
equivalents.
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
Command/
Function
TSO
Equivalent
Description
ALLOCX ALLOC Allocates a data set.
FREEX FREE Frees a data set.
TRAPOUT OUTTRAP 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.
Built-In Functions With No CLANG Equivalent
About built-in
functions with no
CLANG
equivalent
This topic describes the functions available with REXX under ESP where there
is no equivalent CLANG function.
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.
Example: Using
the ASCBADDR
function
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
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.
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 J OBONCSF function returns information about any job that is currently
available on the CSF (Consolidated Status Facility).
The syntax is:
n=JOBONCSF(jobname,varprefix)
n Number of entries returned.
jobname J obname. 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.
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
Description Format Length
Returned
AGENT
agent name string 16
APPL
Application string 8
APPLG
Application
generation number
number 10*
BYPASSED
job bypassed 0 for false, 1 for true 1
COMPLETE
job completed 0 for false, 1 for true 1
CONDCODE
completion code nn, Snnnn for system
abend, Unnnn for user
abend
5*
CRITICAL_PATH
critical path job 0 for false, 1 for true 1
ENDTIME
job end time hh.mn yyyy/mm/dd -
date may be in YMD,
MDY or DMY format
based on
DATEFORM
initialization parm
19
EVENT
Event name string 24
EXTERNAL
external job 0 for false, 1 for true 1
FAILED
job failed 0 for false, 1 for true 1
HC
hold count number 5*
J OBN
jobname string 8
J OBNO
job number number 5*
MANUAL
manual job 0 for false, 1 for true 1
OVERDUE_START
job overdue to
start
0 for false, 1 for true
Table of variable names, continued
* Length returned varies.
Variable Name
Description Format Length
Returned
OVERDUE_SUBMIT
job overdue to
submit
0 for false, 1 for true 1
OVERDUE_END
job overdue to end 0 for false, 1 for true 1
PNODE
processing node string 8
QUAL
job qualifier string 8
REQUEST
request job 0 for false, 1 for true 1
REQUESTED
requested job 0 for false, 1 for true 1
SCHED
scheduled time hh.mn yyyy/mm/dd 19
STARTTIME
job start time hh.mn yyyy/mm/dd
-date may be in
YMD, MDY or
DMY format based
on DATEFORM
initialization parm
19
STATUS
status of job string 28
SUBAP
subApplication
name
string 8
TAG
tag field string 16
TYPE
type of job J for job (including
non-MVS), T for
task, L for link
1
USTAT
user status string 28
WOBTYPE
type of workload
object (non-MVS)
string 2
Example In this example, the J OBONCSF 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 = 1 TO J
SAY JOBNAME XJOBN.I
SAY JOBNO XJOBNO.I
SAY APPL XAPPL.I
SAY APPLG XAPPLG.I
SAY PNODE XPNODE.I
SAY SCHED XSCHED.I
SAY STATUS XSTATUS.I
SAY HC XHC.I
SAY QUAL XQUAL.I
SAY TAG XTAG.I
SAY ASTTM XSTARTTIME.I
SAY AENTM XENDTIME.I
SAY EVENT XEVENT.I
SAY EXTERNAL XEXTERNAL.I
SAY MANUAL XMANUAL.I
SAY COMPLETE XCOMPLETE.I
SAY ---------
END

REXXOFF
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
---------
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.
Example 1:
Trapping output
from an LSDN
command
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
.
.
.
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.
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
ESP produces the following results:
If the previous generation of the SYSTEMS Application is active, ESP
issues an APPLJ OB command to complete it.
If the previous generation of the SYSTEMS Application is complete, ESP
takes no action.
Example 2:
Checking
Application
status -Part 2
Criteria
J ob 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
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.
Example 3: Using
REXX with
CLANG to
monitor SMF
data
Criteria
The criteria for this example is that:
ESP issue the SMFSTATS command every two minutes. This command
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)
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.
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
Inserting Adhoc Request Jobs
Example: Using
REXX to issue an
APPLJOB to
insert request
jobs
Criteria
The data set for the request job information be
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
Inserting Adhoc Request Jobs, continued
Example: Using REXX to issue an APPLJOB to insert request jobs, continued
The ESP Procedure reads the data set CYB.REQUESTS(ADHOC) and
issues an APPLJ OB (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 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.
Example 1:
Generating an
Application of
sequential jobs
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.J CL contains the J CL for these jobs.
The member name is the same as the jobname.
The jobs should execute sequentially, as shown below.
TEST2
TEST4
TEST1
TEST3
Using REXX to Build Applications, continued
Example 1: Generating an Application of sequential jobs, continued
ESP Procedure
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
Example 2:
Generating an
Application
based on data set
input
Criteria
The criteria for this example are as follows:
The data set CYB01.ESPPROC(MYAPPL) contains a list of jobs and
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
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 =
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.
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 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 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
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.
Updating a Symbolic Variable
Example:
Updating a
symbolic variable
-Part 1
You can use REXX to output information to a data set by queueing the
information and using an EXECIO DISKW command. When using this
technique you must queue a null line to denote the end-of-file. EXECIO
requires that a null line be stacked, like this:
REXXON
ALLOCX DA(YOUR.DATASET) SH
queue this is line 1
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 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
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
ESP assigns the value of NO to the symbolic variable SWITCH.
Updating a Symbolic Variable, continued
Example:
Updating a
symbolic variable
-Part 2
The previous example uses REXX to update the first line in a data set with a
symbolic variable assignment statement. In this example, there are multiple
lines in the data set and you must find the particular line you are looking for
and update only that line.
Criteria
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
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
ESP assigns the value of NO to the symbolic variable SWITCH.
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.
Example 1:
Defining a
holiday
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
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 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
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.
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
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.
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.
Using ESP with DJ C/J ES3 J ob Networks 307
Using ESP With DJC/JES3 Job Networks
Overview
Introduction If your site is running J ES3 or Dependenct J ob Control (DJ C) 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.
DJ C job networks are similar to ESP Applications, but do not offer as much
flexibility. For additional information about DJ C, refer to the DJC Operators
Guide, the DJC Systems Programmers Guide and the DJC Users Guide.
Topic See Page
What Is a J ob Network 308
Defining the Job Network 310
Selecting J obs for Submission 321
Specifying Other DJ C Parameters 321
Defining Other Types of J obs 322
Examples of DJ C Networks 324
Submitting J ob Networks 333
Statements to Define J ob Networks 334
308 Using ESP with DJ C/J ES3 J ob Networks
What Is a Job Network
About job
networks
In ESP, you can define groups of related jobs as either a DJ C/J ES3 job network
or an Application.
ESP uses DJ C or J ES3 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 J CL that
identifies:
The specific network to which it belongs.
The dependent actions that are necessary before J ES can initiate the job.
DJ C 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, J ES releases the job.
For more information about ESP Applications, refer to Advanced Use of
Applications on page 161, and the ESP Users Guide.
Benefits of using
ESP with DJC
job networks
Some of the advantages of using ESP with DJ C are:
The generation of NET control cards automatically.
The submission of networks of jobs.
How ESP
manages jobs in a
DJC network
ESP performs the following processing steps for jobs in a DJ C network:
1 ESP places successor jobs in network hold.
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.
What Is a Job Network, continued
How ESP manages jobs in a DJC network, continued
3 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.
4 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:
J ES hold
dependent job operator hold.
You can display jobs and networks using J ES $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.
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 J CL 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:
A
B C
E
F
D
Daily
Friday
Last workday
of month
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 DJ C Network, see Statements
for Defining J ob 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 DJ CNET 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 DJ CNET statement with a different
netid appears in the same ESP Procedure.
Identifying JCL
libraries
Use ESP Procedure statements to specify the default J CL 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:
The ESP Procedure below has the name NIGHTLY and identifies the default
libraries you want to use. The name of the J CL library is PROD.J CL.CNTL
and the name of the override library is PROD.OVERRIDE.J CL.
NIGHTLY:ESPPROC
JCLLIB PROD.JCL.CNTL
TEMPLIB PROD.OVERRIDE.JCL
JCLLIB Specifies the J CL library you want to use for
all jobs following this statement. When ESP
encounters a J OB statement for a job, it uses
the J CL member in the J CLLIB with the same
name as the job.You can use the MEMBER
statement to override this action.
TEMPLIB Specifies the temporary or override J CL
library you want to use as the default for all
jobs following this statement. If a library of
this type is specified, ESP uses J CL from the
temporary or override library for job
submission. Otherwise ESP uses J CL from
the most recent J CLLIB statement. Use of this
statement is optional.
Specifying
different JCL
libraries
In addition to using the J CLLIB and TEMPLIB default specifications
statements, you can also identify the J CL 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 J CL library
that you might have previously named in a J CLLIB statement.
In the following Procedure the default J CL library is CYBER.J CL.CNTL.
Because job J1 contains no library instructions, it uses the default. J ob J 2 uses
the DATASET statement to specify that job J 2 should use the alternate library
CYBER.ALT.J CL. For job J 3 the default is CYBER.J CL.CNTL. However, for
job J4 the default changes through another J CLLIB statement and becomes
CYBER.J CL.CNTL2.
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 J CL is to be
used for a job, use a //*UNTIL statement in the jobs J CL. Place this statement
before the job card in a J CL member of the temporary library (TEMPLIB).
Include a cut-off date for the temporary J CL. ESP will use this J CL up to, but
not including the date you specified in the //*UNTIL statement.
Identifying jobs You must use the J OB 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 J CL library being used. To override this, use
the MEMBER statement and specify the name of the member that contains the
J CL for the job. The job name must match the name specified on the job card.
Identifying jobs, continued
In the following example, the JCL for job CYBXA01B is stored in member
CYBJ OB of the J CL library CYBER.J CL.CNTL.
JOB CYBXA01B
MEMBER CYBJOB
Once the J OB 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 J OB statement defines the beginning of the job definition. The ENDJ OB
statement or another J OB 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 (ESPJ QUAL) 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 MYJ OB; the
qualifier is RUN1.
JOB MYJOB.RUN1
Specifying job
relationships
To specify predecessor and successor job relationships, include the appropriate
job dependency parameters. A list of job dependency parameters appears
below:
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
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).
RELEASE Specifies successors to a job that will be released upon its
completion. (The default is successful completion).
PREREQ Specifies the names of any other jobs that must be
complete before this job can be allowed to execute. ESP
automatically selects the jobs for submission whenever
this job is selected for processing.
COREQ 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.
POSTREQ 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.
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.
Example:
Selecting jobs for
submission using
a RUN statement
The following example shows two different ways of selecting jobs for
submission. The first example uses a RUN statement for each job.
JOB A
RUN DAILY
RELEASE B
JOB B
RUN FRIDAY
ENDJOB
Example:
Selecting jobs for
submission using
a SELECT
statement
This example uses SELECT statements after identifying specific job
requirements.
JOB A
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.
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
J obs 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.
B
C
A Daily
Friday
Daily
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.
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 DJ C or
J ES3 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 DJ CDATA statement (e.g. DJC resources).
Benefits of
building net
control cards
automatically
When ESP builds the NET control cards, the generated information then
controls job execution after ESP submits the job to J ES. You do not need to
manually code NET statements in the J CL. If job relationships change to
accommodate a particular day or period, ESP can rebuild the proper NET
control cards based on the new criteria.
Simulating and
net control card
building
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 J CL (optionally).
How ESP
handles existing
control
statements
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
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:
On any day other than a Friday, ESP selects the following jobs and generates
the following NET control cards:
JOB NET CONTROL CARD
A //*NET ID=SIMPLE1,HC=0,RL=B
B //*NET ID=SIMPLE1,HC=1,RL=C
C //*NET ID=SIMPLE1,HC=1
A //*NET ID=SIMPLE1,HC=0,RL=C
C //*NET ID=SIMPLE1,HC=1,HC=1
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 DJ CDATA 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 DJ CDATA
statement can specify any of the following:
DJ C resource requirements.
NET releases for any DJ C/J ES 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 DJ CDATA to specify resource
requirements. Example 2 identifies a relationship with a job in another job
network.
Example 1:
DJCDATA
specifies tape and
system resources
In this situation, job CICSBKUP cannot execute until the following resources
are available:
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 DJ CDATA statement for job IM99 to indicate that it is
to release a job in a different job network. Upon successful completion, job
IM99 releases J OBONE in job network OTHERNET.
Part of the ESP Procedure looks like this:
JOB IM99
DJCDATA NR(OTHERNET,JOBONE)
Defining Other Types of Jobs
Defining external
jobs
ESP allows you to see up inter-network dependencies. For example, you may
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 J OB 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. J ob Z in the job network NET2 waits for job X.
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
A
X
X
Z
NET1 NET2
(External job)
(job) (job)
(job)
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 J CL, 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.
Examples of DJC Networks
About the
examples
The next five examples illustrate the following types of DJ C 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 J ES3 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.
Example 1:
Building NET
control cards for
jobs with static
relationships
The name of the network in this example is PAYDAILY. The jobs in this
network have the following dependencies:
ESP selects J ob A for submission.
When J ob 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:
A
B C
D
Examples of DJC Networks, continued
Example 1: Building NET control cards for jobs with static relationships, continued
DJCNET PAYDAILY
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 J ES queue.
At the same time, ESP generates the following NET control statements:
Example 2:
Building NET
control cards for
changing job
relationships
The name of the network in this example is PAYDAILY. J obs A, B, C and D
are scheduled daily. J ob E is a weekly job and J ob F is a monthly job. The job
relationships change according to different schedule criteria. The specific job
dependencies are:
ESP selects J ob A for daily submission.
When job A completes, it releases jobs B and C.
When jobs B and C complete, they release job D.
J ob E runs only on Fridays and is dependent on job D.
J ob 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.
A //*NET ID=PAYDAILY,HC=0,RL=(B,C)
B //*NET ID=PAYDAILY,HC=1,RL=D
C //*NET ID=PAYDAILY,HC=1,RL=D
D //*NET ID=PAYDAILY,HC=2
Example 2: Building NET control cards for changing job relationships, continued
DJCNET PAYDAILY
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
A
B C
E
D
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:
If today is a day other than Friday and is also the last workday of month:
D //*NET ID=PAYDAILY,HC=2,RL=E
E //*NET ID=PAYDAILY,HC=1
F not applicable
D //*NET ID=PAYDAILY,HC=2,RL=F
E
not applicable
F //*NET ID=PAYDAILY,HC=1
If today is both a Friday and the last workday of the month:
Example 3: Using
existing NET
control cards
This example shows an environment where one JCL member contains J CL for
all jobs in a network. The J CL contains all the necessary NET control cards. In
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 J CL for the jobs is in MVJ CL.CNTL(CQDAILY).
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 J CL.
D //*NET ID=PAYDAILY,HC=2,RL=E
E //*NET ID=PAYDAILY,HC=1,RL=F
F //*NET ID=PAYDAILY,HC=1
Example 4:
Handling on-
request 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.
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
RPT01
PAY10
RPT03
Request
Jobs
RPT02 RPT04
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 on-
demand 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.
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.
J ob A3 in NETA releases the first job in NETB. J ob B3 in NETB releases
the first job in NETC.
Within each network the job dependencies do not change.
A2
A3
A1
NETA NETB NETC
BACKUP
B2
B3
B1
BACKUP
C2
C3
C1
BACKUP
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.
Submitting Job Networks
About submitting
job networks
Use an ESP Event to submit job networks. The trigger for the Event can be:
a scheduled date and time
a data set trigger
a job monitor trigger
a signal with a scheduled date and time
a manual trigger.
The following two examples demonstrate how to use an Event to submit a job
network.
Example 1: An
Event invokes
and ESP
procedure 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 2: An
Event submits a
job network
In this example there are hard-coded NET statements in the JCL so that DJ C
can control their execution. You can useSUBMIT statements in an Event if
NET cards exist. The Event looks like this:
EVENT ID(USER01.MYJOBS)
SUBMIT USER01.TEST.JCL(BP1)
ENDDEF
Statements to Define Job Networks
DJCNET Identifies the default job network name for jobs that
DJ C or JES3 controls.
DOCLIB Specifies the default job documentation library to use
for all jobs following this statement.
JCLLIB Specifies the J CL library to use as the default for all
jobs following this statement.
TEMPLIB Specifies the temporary, or override J CL library, to use
as the default for all jobs following this statement.
OPTIONS Overrides the default processing options.
JOB Identifies the name of the job. The job can have a
qualifier.
AFTER Specifies any jobs that precede a job and that release
this job.
RELEASE Specifies any jobs that precede a job and that release
this job.
PREREQ Specifies the names of any other jobs that must
complete before this job can execute.
COREQ Specifies the names of any other jobs that ESP must
select automatically whenever it selects a job.
POSTREQ Specifies the names of any other jobs that must run
after a job.
SELECT Identifies which jobs are to be selected for submission.
DESELECT Overrides previous SELECT statements for specific
jobs.
RUN Specifies when a job is to be selected for submission.
NORUN Specifies when a job should not be selected for
submission.
DJCDATA Specifies DJ C parameters for a job.
MEMBER Specifies the J CL member name for a job.
ENDJOB Indicates the end of the requirements for a job.
Statements to Define Job Networks, continued
INPUTDS Identifies an input tape data set for a job.
DATASET Identifies a specific J CL Library and member (optional)
that override the default library, for a particular job
only.
CCFAIL Identifies a specific J CL Library and member (optional)
that override the default library, for a particular job
only.
DUEOUT Specifies a due-out time for the job from a specific
processing node (P-Node).
MODEL 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.
MONITOR Specifies the prefix for monitor Events relating to a job.
PNODES Specifies the names of manual processing nodes
through which a job passes before it completes.
Using Signals 337
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.
Topic See Page
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
338 Using Signals
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 DJ C/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.
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.
Setting up the
signal processing
environment
Each signal must pass through the following stages:
Defining the signal
Specifying the signal conditions in an Event
Posting the signal complete
Cycling the signal.
A detailed explanation of each follows.
TIME
EVENT
SIGNAL
Using Signals 339
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)
340 Using Signals
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)
Using Signals 341
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
a signal
Below is an example of posting a signal. This command posts the current
generation of signal CYBER.TAPE_INPUT.
SIGPOST CYBER.TAPE_INPUT GEN(0)
342 Using Signals
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
Using Signals 343
Combining Signals and Scheduling Criteria
About combining
signals and
scheduling
criteria
An Event may need to wait on multiple conditions to be met before execution.
You can use both a SCHEDULE command and a SIGWAIT command in your
Event definition. ESP only executes such an Event when the signal posts and
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.
344 Using Signals
Combining Signals and Schedule Criteria, continued
Example 2: Waiting for schedule criteria and data set activity, continued
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:
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:
SIGWAIT PROD.DATA GEN(0)
INVOKE CYBER.ESP.PROCS(REVDAY)
ENDDEF
CYBER.EVENT2
20:00
PROD.DATA
(Event)
(Signal)
(Time)
PROD.DSN1
(Dataset)
PROD.DSN2
(Dataset)
Using Signals 345
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:
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)
346 Using Signals
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
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)
Using Signals 347
Example 3: Multiple processing runs, continued
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.
A
B
C
A
B
C
TR1END
CYBER.TR1 CYBER.TR2
11:30 13:30 PROD.TR1END
(Event) (Event)
(Signal wait) (Time) (Time)
(Signal post)
348 Using Signals
Displaying Signal Information
About displaying
signal
information
Display the signal information using any ESP access method: command in an
Event, Line mode, Page mode or using a batch job.
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
Using Signals 349
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 -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
----EVENT CYBBP01.TESTSIG PENDING SINCE 10.44FRI 29APR94
350 Using Signals
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.
ESP warning
comments
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)
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.
Using Signals 351
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.
352 Using Signals
Manual and Automatic Posting of Signals
About manual
and automatic
posting of signals
A user can enter a SIGPOST command manually to signify that signal
conditions have occurred. This is known as manual posting of a signal. As an
alternative you can enter SIGPOST commands in Events, ESP Procedures, and
in batch jobs, so that ESP automatically posts the signal.
Example of
manual Posting
that requires
manual receipt of
input tape
The following example shows an Event that requires manual posting of a
signal.
In this situation an Event submits job J OBX 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)
2. Define the Event for CYBER.J OBX_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)
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 J OBX whenever the scheduling
criteria has occurred.
4. Cycle the signal by typing the following:
SIGCYCLE CYBER.JOBX_TAPE
Using Signals 353
Manual and Automatic Posting of Signals, continued
Automatic
posting
To specify automatic posting of signals, use any of the following methods:
A scheduled Event
J ob monitoring
A trailer step in the JCL for the specific job
An ESP command in a batch job.
Using job
monitoring to
post a signal
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 J ob Monitor Event:
EVENT ID(CYBER.JOBA_JOBEND)
INVOKE CYBER.ESP.PROCS(SIGNAL)
ENDDEF
354 Using Signals
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)
Using Signals 355
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 GEN(0)
SIGWAIT PROD.XDAY_COMPLETE GEN(-1)
SUBMIT PROD.JCL(XWEEK)
ENDDEF
Visually the dependencies for the Event look like this:
CYBER.WEEKLY
(Event)
PROD.XDAY_COMPLETE GEN(0)
(Signal)
PROD.XDAY_COMPLETE GEN(-1)
(Signal)
(Signal)
(Signal)
(Signal)
16.00
SATURDAY
356 Using Signals
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).
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 J CL 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.
Using Signals 357
Example: Using a
trailer step to
post a signal
Assume the situation is the same as in the previous job monitoring example.
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 J CL for the job called XDAY.
This is how the J CL statements for the trailer step definition look for job
XDAY:
//LASTSTEP EXEC PGM=ESP,REGION=4000K
//SYSIN DD *
SIGPOST PROD.XDAY_COMPLETE
When this step executes, ESP posts the signal PROD.XDAY_COMPLETE as
complete.
358 Using Signals
Glossary 359
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.
Application See ESP Application.
Application Wait A status in which the execution of an Application
has to wait until a previous generation of the
Application completes.
Audit log An audit trail of ESP activity. It stores information
on administration activities, operator commands,
and application and Event processing.
Authorization string One of four job related fields that is used to
identify the ownership of a job.
Authorization table A table ESP may use to control access to job
tracking data.
AUTOVAR Automatic variable; a variable used to represent an
initial or trailer job step, or DJ C net card.
Calendar A collection of definitions of holidays, special
days and special periods that are unique to your
installation.
CCFAIL Abbreviation for condition code fail. CCFAIL
statements define conditions which, if met, should
cause the job to fail.
CLANG Control language. This is a high level
programming language developed for ESP.
360 Glossary
Glossary, continued
Condition code A code indicating the results of processing a job
step.
COPYJCL Location of a copy of the submitted J CL.
Consolidated Status
Facility
An ESP facility for displaying and manipulating
the workload.
Descriptor code A one or more digit code used to describe the
characteristics of a message to an MVS console.
DJC Dependent J ob Control; a Cybermation product
used to control resources and job networks at the
initiator level.
DJC job network A group of related jobs where dependencies are
controlled at the initiator level.
ESP Application A group of related jobs and tasks.
External job A job defined in an ESP Procedure that ESP
submits from another Procedure.
Event A basic unit of work to ESP. An Event starts an
active function such as sending a message or
invoking an ESP Procedure.
Event data set A VSAM data set where ESP stores Event
definitions.
Event group Group of ESP Events with the same Event prefix
(first name).
EVENTSET Event data set.
Glossary 361
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.
HISTFILE History file.
History file A VSAM data set used to store historical
information.
Job index data set A VSAM data set used to store an index to the
most recent executions of a job.
Job monitor An ESP facility for monitoring a jobs progress at
any stage of processing and for taking action at
significant points.
Job tracking An ESP facility to track job data in real time as
jobs are processed.
Job tracking definition
table
A table used to specify the characteristics of jobs,
STCs and TSUs you want to track.
Link A task in an Application that does not require
manual completion.
Manual job A job which ESP does not submit as part of either
an ESP application or a DJ C/J ES3 job network.
Model A definition of your environment (e.g. CPUs,
initiators, resources).
Page mode A method to communicate with ESP using ISPF,
producing scrollable output from ESP.
362 Glossary
Glossary, continued
P-Node Processing node. A processing stage through

which a job must pass during its time on the
system.
Post To mark complete. For example, you can post a
job complete.
Predecessor job Any job that must complete before another job can
be released.
Qualifier An addition to the jobs name, used to uniquely
identify similar jobs.
REXX 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.
Resource An item of hardware, a software resource or an
abstract condition.
Route code A one or more digit code used to route a message
to an MVS console.
SAD file Scheduled activity data set file; a sequential data
set ESP uses to store scheduled activity
information on jobs.
SAF 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.
Schedule A list of Events to execute, sorted in time
sequence.
Glossary 363
Glossary, continued
Signal A manual or automated task used for scheduling.

Special day A day with special significance for scheduling at
your installation.
Special period A period of processing with special significance
for scheduling your installation. An example is a
fiscal month.
SubApplication A group of jobs within an Application.
Subsystem An MVS facility that ESP uses to manage and
control requests among its components.
Successor job Any job that depends on the completion of another
job before it can be released.
Symbolic variable An integer or a character string whose value ESP
substitutes at processing time.
SYMLIB Symbolic variable library; data set(s) members
used to store symbolic variables.
System message
interception
A facility used to intercept system messages as
they are written to the system message data set.
System security
product
A product installed to implement system security.
Also known as the host security system or product.
Task An element of an Application that requires
completion. For example, a task may represent the
checking of a report.
Tracking model A centralized definition of the attributes and
processing phases of a group of jobs.
364 Glossary
Glossary, continued
TRAKFILE Tracking file; a non-VSAM data set used to store

job tracking data.
userid A short (8 bytes or less) field used to identify a
system user. It can represent an actual person or an
active program, job or routine.
Index 365
Symbols
%CE function 37
%ENDEXCL, statement 48
%EXCLUDE statement
criteria 79
multiples 81
symbol library 47
%INCLUDE statement
copy J CL 81
criteria 79
examples 80
multiples 81
symbol library 47
/*ROUTE statement 70
A
ABENDs
monitoring for 108
adding a restart step 69
ADJ UST command 248
Alert
definition 359
Alert processing 96
ALERTDEF command 113, 114
Alerts 112
displaying 114
NOTI FY 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
ASI D 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
B
building a control card 145
built-in symbolic variables 15
built-in variables 96
C
calculating the number of weeks in a period 138
Calendar 359
CCCHK statement 72
combinations 75
format of 72
where used 74
CCFAI L 359
CCFAI L 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 J CL
%INCLUDE statement 81
COPYJ CL 360
creating longer field length 29
cycling a signal 342
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 102
defining a job as a node 150
defining holidays 216
defining initiators 247
DEFPRINT command 251
366 Index
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 J ob Control 307
Descriptor code 360
DFPNODE command 236
displaying signals 348
DJ C 307, 360
benefits of using with ESP 308
defining external jobs 322
defining manual jobs 323
identifying J CL libraries 312
processing steps 308
using existing NET control cards 328
DJ C job network 360
DJ CDATA statement 321
DJ CNET statement 311
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 J CL 84
exclusion sign () 84
exclusion statements 48
EXECI O DI SKW 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
F
failure 73
field length, increasing 29
forecasting 239
possibilities 240
formatting functions, built-in 37
G
GENTIME command 21, 132, 133
examples 24
using multiples 23
global AUTOVAR 89
GLOBALVARI ABLES 208
Group 361
group name, monitor 104
groups
monitor 104
H
HISTFILE 361
History file 361
Hold count
job in a network 308
holidays
defining with templates 216
I
I NHERI T 149
inherit all relationships 149
I NHERI T attribute 148
INHERI T, on J OB statement 149
I NHERI T, on OPTI ONS statement 149
inheritance, processing of 149
inherited relationships
overriding 148
I NI T command 247
initial step automatic variables 90
initiators
defining 247
INVOKE command 41
invoking an ESP Procedure 140
invoking templates 213
I STEP AUTOVARS 90
J
J CL
and Panvalet data sets 65
excluding specific lines 84
multiple jobs in one member 328
simulating 93
J ES queue, checking job 146
J ES3 307
job
delaying release of 174
resbumitting following failure 118
job AUTOVAR 89
J ob index data set 361
J ob monitor 361
job monitor Event
Index 367
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
J ob tracking 361
job tracking 227
J ob tracking definition table 361
J OBATTR statement 162
J obname 313
J OBONCSF function 284
J OBONQ 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
L
Link 361
links, resolving external 155
listing system messages 231
LOCALVARIABLES 208
longer field length 29
Looping operations 272
LSYSMSGS command 231
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
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
N
NET control cards 319
Network hold count 308
NODE keyword 149
NODE keyword on a J OB statement 150
NOINHERI T keyword 152
NOINHERIT, on J OB statement 149
NOINHERI T, on OPTI ONS statement 149
NOPOST_OLDEST 163
NOPOST_UNTI L_READY 163
NOPOST_WHI LE-WAITI NG 163
notification of status 179
NOTI FY statement 112
number of weeks in a period, calculating 138
numbering automatic variable 88
O
online system, monitoring for completion of 110
online, setting resource based on start of 110
optional predecessors 176
OPTIONS NOI NHERI T 150
OPTIONS statement 319
I NHERI T 149
overriding inheritance 149
Index 368
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_WHI LE_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
TI TLE 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
SADLI NK 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 369
scheduling
even days 130
scheduling multiple runs 182
SCOPE parameter 156
SCOPEwith RESOLVE 160
secured symbol, identifying 83
shutdown of system 147
SI GCYCLE 341
SI GCYCLE 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
SI GPOST command 341, 352
SI GWAI T command 340, 343
SI MULATE command 93
Simulating Event
REXX exec 305
simulating J CL 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 J CL 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
SYMLI B 363
Index 370
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 J CL 225
setting up 206
starting definition 207
using symbolic variables 207
what they are 205
TI ME command 249
TI TLE 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
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.
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.
Note: Please note that comments that justify a reply should be of a more
technical nature (i.e. beyond comments about typographical errors).
Page
Number Comment
Name
Company
Address
Fax
e-mail
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 Workload Manager: Advanced User's Guide

Uploaded by

Document Information

Original Title

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 Workload Manager: Advanced User's Guide

Uploaded by

Copyright:

Available Formats

ESP Workload Manager

Group A high-level index, to which specific users are

P-Node Processing node. A processing stage through

Signal A manual or automated task used for scheduling.

TRAKFILE Tracking file; a non-VSAM data set used to store

You might also like