Configure the EASY/Exit JES2 environment to enforce rule-based policies for JES2. This topic describes installation steps for EASY/Exit JES2 interface stubs, how to enable exits, variables available to JES2 exits, sample rules, and debugging tips.
EASY/Exit can receive control and enforce rule-based policies for the JES2 subsystem. The JES2 environment is entered when EASY/Exit receives control at one of the JES2 system exit points (for example, JES Exit 2, JES Exit 4/54, JES Exit 20/50).
Rule processing in the JES2 environment can be used to validate or
change JCL parameters such as REGION and
CLASS, alter JCL and JECL statements, set system
affinity to direct jobs to desired systems, change the scheduling
environment (SCHENV), and perform other functions.
The JES2 environment may be invoked multiple times as a job progresses
through the Job Entry Subsystem. On each entry to
EASY/Exit, the &ENV variable
will be set to JES2 and the &ENVS
(subenvironment) variable will be set to the name of the JES2 exit point
(for example, EXIT4, EXIT20).
Enabling the JES2 environment for EASY/Exit
EASY/Exit communicates with JES2 via interface stub modules that are defined to JES2 as ordinary JES2 exits. These stubs communicate with the DIF started task to run the EASY/Exit policy rules, keeping the main DIF and EASY/Exit modules independent of JES.
This section discusses the steps necessary to install the EASY/Exit stub modules and the control statements required in the JES2 parmlib to activate the exits.
Before EASY/Exit can receive control in the JES2 environment, copy the EASY/Exit JES2 stub modules into the JES2 load library (typically SYS1.SHASLNKE).
//*****************************************************
//* COPY THE JES 1.X MODULES TO THE JES LOAD LIBRARY
//*****************************************************
//JCOPY EXEC PGM=IEBCOPY,REGION=4M
//INDD DD DSN=DTS.R71.LOADLIB,DISP=SHR
//OUTDD DD DSN=SYS1.SHASLNKE,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT3 DD SPACE=(CYL,(1,1)),UNIT=SYSALLDA
//SYSUT4 DD SPACE=(CYL,(1,1)),UNIT=SYSALLDA
//SYSIN DD *
COPYMOD INDD=((INDD,R)),OUTDD=OUTDD
S M=EXT901C /* last 2 characters indicate JES release */
S M=EXT911C /* last 2 characters indicate JES release */
S M=EXT921C /* last 2 characters indicate JES release */
/*
Note: the last two characters of the stub module name correspond to the JES release. For example, for JES 1.11 use EXT901B, EXT911B, EXT921B. For JES 1.12 use EXT901C, etc.
Identify the EASY/Exit interface modules to JES2 and indicate where JES2 should load them. Two methods are available:
- Add
LOADMODstatements to the JES2 PARM member (for example JES2PARM in SYS1.PARMLIB), or - Issue
$ADD LOADMODstatements via the JES2 Dynamic Exits facility.
The following examples show the statements you must add (method 1) or the JES commands to issue (method 2):
/* Method 1: JES2PARM (parmlib) */
LOADMOD(EXT901C),STORAGE=PVT
LOADMOD(EXT911C),STORAGE=CSA
LOADMOD(EXT921C),STORAGE=PVT
/* Method 2: JES2 Dynamic Exits */
$ADD LOADMOD(EXT901C),STORAGE=PVT
$ADD LOADMOD(EXT911C),STORAGE=CSA
$ADD LOADMOD(EXT921C),STORAGE=PVT
Ensure the stub module names correspond to those copied into the JES2 load library. The table below lists example stub module names by JES release.
Table 8-1. JES2 Stub Module Names
| JES version EXT Stub Module Names |
|
If LOADMOD statements are placed into the JES2 parmlib, JES2 must be cold-started (IPL) the first time so it reads the initialization statements and loads the exits. Once the parmlib is updated and JES2 cold-started, subsequent changes to EASY/Exit rules only require refreshing the rules in DIF, for example:
F DIF,REFRESH EXT
If the exits are loaded dynamically using $ADD, no cold-start is required.
After loading the stub modules (via LOADMOD or $ADD LOADMOD), the exit points must be activated in JES2. Two methods are available:
-
Place an
EXITstatement in the JES2 initialization parmlib member, for example:EXIT(50) ROU=E9150,STATUS=ENABLED(requires JES2 cold start). -
Issue the JES2 trace/activation command to enable the exit without changing the parmlib:
$TEXIT(50),ROU=E9150,ENABLEThis does not require a cold start.
The exit routine names vary by exit number. The table below lists the exit numbers and routine names.
Table 8-2. JES2 Exit Numbers and Routine Names (partial)
| Exit Number | Exit Point Name |
| 1 | E9001 |
| 2 | E9002 |
| 3 | E9003 |
| 4 | E9004 |
| 6 | E9206 |
| 7 | E9007 |
| 9 | E9109 |
| 10 | E9010 |
| 11 | E9011 |
| 12 | E9112 |
| 13 | E9013 |
| 14 | E9014 |
| 15 | E9015 |
| 16 | E9016 |
| 17 | E9017 |
| 18 | E9018 |
| 19 | E9019 |
| 20 | E9020 |
| 21 | E9021 |
| 22 | E9022 |
| 24 | E9024 |
| 26 | E9026 |
| 27 | E9027 |
| 36 | E9136 |
| 37 | E9137 |
| 38 | E9038 |
| 39 | E9039 |
| 40 | E9040 |
| 41 | E9141 |
| 42 | E9142 |
| 43 | E9143 |
| 44 | E9044 |
| 45 | E9145 |
| 46 | E9046 |
| 47 | E9047 |
| 49 | E9049 |
| 50 | E9150 |
| 51 | E9051 |
| 52 | E9152 |
| 53 | E9153 |
| 54 | E9154 |
| 55 | E9155 |
| 56 | E9156 |
| 57 | E9157 |
To invoke EASY/Exit rules in JES2, include a DEFENV statement in the rule set to enable the JES2 environment, for example:
DEFENV JES2 MODE(ACTIVE)
EASY/Exit and Workload Manager (WLM) integration
The z/OS Workload Manager (WLM) provides Resource Affinity Scheduling (Scheduling Environments) to ensure jobs requiring specific resources are selected only on processors where those resources are available.
EASY/Exit rules can assign a scheduling environment to a job or dynamically change resource states. Assigning a scheduling environment to a job (override the JOB card SCHENV) must be done in JES2 Exit 20 or JES Exit 50 (End-of-Input). Setting WLM resource states may be done in any EASY/Exit environment.
To set a WLM resource state, set the EASY/Exit variables &WLM_RESNAME and &WLM_RESSTAT (values: ON, OFF, or RESET).
Alternatively, issue the WLM console command via DIF:
F WLM,RESOURCE=resourcename,ON | OFF | RESET
The following variables are available in most JES2 subenvironments. Additional variables may be available in specific exit subenvironments (see those sections). Standard DIF variables such as &JOBNAME, &SYSID, &DATE, &TIME, etc., are also available.
Table 8-3. Variables for the EASY/Exit JES2 Environment (partial)
| Name | Values | Description |
| JOBNAME | 1-8 chars | Name of the job, STC, or TSO user |
| JOBTYPE | BATCH, TSU, or STC | Type of job |
| SYSNAME | 1-4 chars | System id |
| STEPNO | 1-nnnn | Current step number |
| GROUP | 1-8 chars | RACF group |
| NOTIFY | 1-8 chars | NOTIFY= parameter from JCL |
| CLASS | 1 char | Job class |
| PNAME | 1-8 chars | Programmer name |
| ACCTN | Job accounting field | |
| ROOMN | 1-4 chars | Room number |
| TYPRUN | SCAN, COPY, or HOLD | Type of execution |
| NOJID | 1-8 chars | Original job id |
| SUBMITTER | 1-8 chars | Original job submitter |
| NXNDE | 1-8 chars | Network execution node |
| JUSID | 1-8 chars | Userid from JOB card |
| JESAFF | 1-30 chars | System affinity |
| JESUSRID | 1-8 chars | Userid |
| JESRC | 1-nnnn | Return code from JES exit to system |
| JESSCHEV | 1-16 chars | WLM Scheduling Environment name |
| RACF_U_OWNER | 1-8 chars | RACF ownerid |
| RACF_U_DFLTRGRP | 1-8 chars | RACF default group |
| RACF_U_PGMRNAME | 1-8 chars | RACF programmer name |
| SCANSTRING1/2/3 | 1-30 chars | Character strings to scan for in JCL |
| STRING1FOUND / STRING2FOUND / STRING3FOUND | Y or N | Indicates whether the corresponding scan string was found |
| WLM_RESNAME | 1-16 chars | WLM resource name |
| WLM_RESSTAT | ON, OFF, or RESET | WLM resource status |
JES2 exit 4/54 is invoked after each JCL or JECL statement has been read but before interpretation (not invoked for JOB statements or internal reader statements). At this point rules can:
- Cancel or purge the job (for violating JCL standards)
- Add new parameters or statements to JCL
- Add continuation statements
- Trigger actions such as starting a job or sending a message when encountering particular statements
The &CARD_IMAGE variable holds the current 80-character JCL or JECL card image. You can examine portions of the card, e.g.:
IF &CARD_IMAGE(1,8) = '//SYSUT2' THEN ...
IF &CARD_IMAGE(1,9) = '/*JOBPARM' THEN ...
To search and replace strings, use FIND_STRINGn and &REPL_STRINGn variables:
IF &JOBNAME = MYJOB
THEN SET &FIND_STRING1 = 'PAGES=4000'
SET &REPL_STRING1 = 'PAGES=50'
Examples — Exit 4/54
DEFRULE NOTIFRULE IF &ENVS = EXIT4
&CARD_IMAGE(1,9) = '/*JOBPARM'
THEN SET &SCAN_STRING1 = 'NOTIFY=USERA'
SET &REPL_STRING1 = 'NOTIFY=USERB'
Convert undesired JCL statements to comments by inserting '//*' in the first three characters of the statement.
DEFRULE COMM
IF &CARD_IMAGE(3,7) = (JOBCAT,STEPCAT)
THEN SET &CARD_IMAGE(3,3) = '**'
Use exit 54 to scan EXEC statements for program names (for example IEFBR14 or IEBGENER) and set scan strings via &SCAN_STRINGn. If a match is found, &STRINGFOUND is set; then use exit 50 to change job class before job dispatch.
DEFENV JES2 MODE(ACTIVE)
DEFRULE J54JOB
IF &ENV = JES2 &ENVS = EXIT54 &JOBNAME = SJP* &J54STMV = EXEC
THEN SET &SCAN_STRING1 = 'PGM=IEFBR14'
SET &SCAN_STRING2 = 'PGM=IEBGENER'
DEFRULE J50JOB
IF &ENV = JES2 &ENVS = EXIT50 &JOBNAME = SJP* &STRINGFOUND = Y &CLASS NE N
&CLASS NE O &CLASS NE X
THEN ISSUE WRITEMSG(V2)
SET &CLASS = O
DEFMSG V2
'JOB CLASS &CLASS CHANGED TO O FOR MOVE FOR DB2' WTORC(2,11)
Exit 9 receives control when a job exceeds limits defined in JES2 init parms or JCL (output records, lines, bytes, pages). EASY/Exit rules can determine which limit was exceeded, override system default actions, suppress warnings, change increments before next warning, or terminate the job.
Exit 9 is not entered if an OUTLIM= on a SYSOUT DD controls the limit; in that case IEFUSO is entered and EASY/Exit receives control in the OUTLIM environment (see z/OS Exits chapter).
The EASY/Exit interface module for Exit 9 must be loaded in LPA or CSA (not private). Use STORAGE=CSA in the LOADMOD; example:
LOADMOD(EXT911C) STORAGE=CSA
EXIT(9) ROU=E9109,STATUS=ENABLED
(or dynamically:)
$ADD LOADMOD(EXT911E),STORAGE=CSA
$TEXIT(9),ROU=E9109,ENABLE
Table 8-4. Variables for the JES2 Exit09 Sub-Environment
| Name | Values | Description |
| TRANSPGM | YES | NO | Program is transaction-processing |
| J9COND | CARDS | LINES | PAGES | BYTES | Type of SYSOUT output exceeded |
| J9LINES | 1-nnnnnn | Number of lines output so far |
| J9PAGES | 1-nnnnnn | Number of pages output so far |
| J9BYTES | 1-nnnnnn | Number of bytes output so far |
| J9IND | CANCEL | DUMP | WARN | (null) | Subparameter on JOB or /*JOBPARM indicating action (read-only). To change, set J9RESP. |
| J9RESP | CANCEL | DUMP | WARN | Action EASY/Exit returns to JES |
| J9SUPP | YES | NO | Suppress $HASP375 warning message |
| J9RECS_INC | 1-nnnnnn | Additional allowed records/lines/cards before next limit |
| J9PAGES_INC | 1-nnnnnn | Additional allowed pages before next limit |
| J9BYTES_INC | 1-nnnnnn | Additional allowed bytes before next limit |
Examples — EXIT09
Allow additional 10,000 lines for class A jobs when current lines ≤ 30,001 and suppress earlier $HASP375 messages.
DEFRULE ARULE IF &CLASS = A
&J9COND = LINES &J9LINES LE 30001
THEN SET &J9SUPP = YES
SET &J9RECS_INC = 10000
Terminate jobs with names starting with TEST (S722 abend) when they exceed limits; for jobs starting with PROD only issue a warning.
DEFRULE BRULE
IF &JOBNAME = TEST* THEN SET &J9RESP = CANCEL
IF &JOBNAME = PROD* THEN SET &J9RESP = WARN
JES2 exit 20 (or exit 50 on z/OS 1.7+) is invoked after all JCL has been read and interpreted but before the job is initiated. Use it to:
- Fail a job for incorrect CLASS or other standard violations
- Change the job CLASS to meet standards
- Change the execution node or system affinity (
SYSAFF) - Change the scheduling environment (
SCHENV) - Set job priority
- Suppress output for a job terminated by the exit
Note: Exit 50 exists on z/OS 1.7 and higher; lower releases use exit 20.
Variables for EXIT20 / EXIT50 (partial)
| Name | Values | Description |
| JESAFF | 1-8 chars | System affinity (equivalent to specifying /*SYSAFF= in JCL) |
| JESAFFNO | 1-32 | JES identifier for the target system |
| JESXNODE | Execution node | |
| JESUSRID | 1-8 chars | Submitting userid |
| JESSCHEV | 1-8 chars | z/OS Scheduling Environment |
| JESRC | 1-16 | Return code EASY/Exit returns to JES |
| RACF_U_OWNER | 1-8 chars | RACF userid associated with job |
| RACF_U_DFLTRGRP | 1-8 chars | RACF default group |
| RACF_U_PGMRNAME | 1-20 chars | RACF programmer name from JCL |
Examples — EXIT20 / EXIT50
Direct jobs submitted by RACF groups APPL or TAPPL to system SYSA. Jobs with names beginning PRDX are directed to SYSB.
DEFRULE JOBAFF
IF &RACF_U_DFLTGRP = (APPL,TAPPL) THEN SET &JESAFF = SYSA
IF &JOBNAME = PRDX* THEN SET &JESAFF = SYSB
Enforce naming and class conventions; fail jobs not meeting standards.
DEFRULE CLASRULE
IF &JOBNAME = C* &CLASS NE C THEN SET &JCLFAIL = YES ISSUE
IF &JOBNAME = T* THEN SET &CLASS = T
Assign a scheduling environment so the job waits until the environment is available on a processor (example sets APPL8).
DEFRULE SCHEDRUL
IF &JOBNAME = PRX34* THEN SET &SCHENV = APPL8
This is the same scan pattern shown previously: set &SCAN_STRINGn in exit 54 and detect it in exit 50 to change the job class.
Exit 40 is invoked for each SYSOUT dataset prior to creating control blocks. Use rules to change SYSOUT class, route output to other nodes, change forms attributes, and more.
Table 8-6. Variables for the JES2 Exit 40 Sub-Environment
| Name | Values | Description |
| J40LINES | 1-nnnnn | Data set record count |
| J40DNODE | 1-nn | Destination node number |
| J40DRMT | 1-nn | Remote number |
| J40USER | 1-8 chars | Dataset destination/userid |
| J40PNAME | 1-8 chars | Procstep name |
| J40SNAME | 1-8 chars | Step name |
| J40CLASS | 1 char | Output class of dataset |
| J40COPYS | 1-nn | Number of output copies |
| SYSOTYPE | SPIN | NONSPIN | UNSPUN | SYSOUT type |
Examples — EXIT40
DEFRULE CLSRULE
IF &JOBNAME = PRD3* &ENVS = EXIT40 &J40CLASS = C
THEN SET &J40CLASS = A
DEFRULE CLSRULE
IF &ENVS = EXIT40
IF &J40DNODE NE 0 /* remote destination */
&J40LINES GT 10000
THEN SET &J40DNODE = 0 /* redirect to local node */
Common problems occur when EASY/Exit does not seem to receive control. To debug:
Ensure the EXT8xxx modules are copied into the JES2 load library and the correct LOADMOD and EXIT statements are present in the JES2PARM member (referenced by the HASPPARM DD in the JES2 catalogued procedure). Use JES2 command $DEXIT to check whether an exit is loaded and enabled.
Include a DEFENV JES2 MODE(ACTIVE) statement in your EASY/Exit rule set to enable JES2 environment processing. Exits disabled by JES2 ($TEXITn,DISABLE) will prevent EASY/Exit from receiving control for those exits.
&ENV or &ENVS?
Rule processing by default stops after the first satisfied condition. As a best practice, test &ENV and &ENVS in rules to ensure they run in the intended environment/subenvironment.
In JES2 the //EXTTRACE DD DUMMY is not useful because rules execute while JCL is still being processed. Instead, add a rule to enable tracing dynamically for specific jobs, for example:
DEFRULE TRACRUL CONTINUE(NEXTIF) IF &ENV = JES2 &JOBNAME = MYJOB
THEN SET &RULE_TRACEACT = YES
SET &RULE_PALLACT = YES
/* Optionally route trace messages to console */
DEFPROD MSG(WTORC(2,11))
//EXTTRACE DD DUMMY for jobs that need debugging. You may need to temporarily add a WTO route code in your DEFPROD statement to ensure trace messages appear on the console.