Z/OS exits - syncsort_cobol_migration_manager - syncsort_clone_center - syncsort_space_recovery_system - syncsort_scc_monitor - syncsort_simulate_2000 - syncsort_allocation_control_center - Latest

Automate z/390 Functions

EASY/Exit provides an easy-to-use, rule-based facility to automate the use of the system exits provided by z/OS, OS/390, and earlier versions of MVS systems. Using the standard system exit points, EASY/Exit replaces complex, difficult-to-maintain assembler code with self-explanatory rules. Each z/OS exit is known to EASY/Exit as an "environment". The exits can be enabled or disabled through the use of the z/OS SETPROG EXIT console command. SETPROG EXIT may be automatically invoked at startup or shutdown of EASY/Exit by placing the command in the EXTINIT or EXTTERM members in the DIF parmlib data set.

When a change is made to the EASY/Exit rules for any of the z/OS environments, it is not necessary to reissue the SETPROG EXIT command. All that is required is to refresh the rules via a REFRESH command to the DIF started task:

F DIF,REFRESH EXT

For example:

SYS(NOINTERVAL,NODETAIL,EXITS(IEFUJP,IEFUSO,IEFUSI,IEFUJV))

When changes are made to the SMFPRMxx parmlib member, the updates are made effective by the MVS console command SET SMF=xx.

This chapter describes the EASY/Exit environments that receive control during z/OS processing. These environments can be divided into the following categories:

• Job Resource Limits Exceeded - this includes environments which receive control and can take action when job or step CPU time or wait time limits are exceeded or when the output limit for a SYSOUT dataset is reached. The EASY/Exit rules in these environments can be used to examine the type of job and step being executed and can extend the limits if needed.
• Job Execution Control - this includes a number of the z/OS SMF exit-based environments which receive control at the start and end of a job or a job step. In these environments, the EASY/Exit rules can establish values for REGION size or other values, can change the contents of JCL statements ’on-the-fly’ and can write information to the DIF log or to SMF records for later analysis if desired.
• Device Allocation Control - these environments receive control when a disk or tape unit or volume is unavailable to a job and can take automatic actions such as bringing devices online or allowing jobs to wait, without the need for operator intervention.
• Automatic Class Selection (SMSACS) Control - EASY/Exit allows installations to use simple IF-THEN-ELSE rules to override the result of ACS routine execution, assigning classes according to dataset characteristics, programming, tables, or other resources that are not available to the ACS routines. EASY/Exit can also receive control prior to ACS routine execution to alter the read-only variables accessed by the ACS routines, eliminating the need for multiple logic paths through ACS and simplifying ACS code. For more information, refer to SMSACS - The Automatic Class Selection Environments.
• SMF Record Writer Control - The IEFU83 environment receives control whenever an SMF record is about to be written to the SMF buffers. The environment is not entered if the SMF record type has been suppressed by options set in the SMFPRMxx member of SYS1.PARMLIB, or if the SMF record is being written via a branch entry to SMFEWTM. This environment can be used to suppress particular types or subtypes of SMF records, optionally filtering by variables such as job name, job type, system id, or dataset name. For more information, refer to IEFU83 – SMF Record Writer Environment.
• SMF Dataset-Full or SWITCH SMF Command Control - The IEFU29 and IEFU29L environments receive control whenever an SMF dataset is full and the system switches to the next available SMF dataset, or when a SWITCH SMF command is issued. For more information, refer to IEFU29 and IEFU29L – SMF Switch Environments.

Preventing X22 Abends

Jobs which exceed the amount of resources which they are allowed to use in z/OS systems fail with ’x22’ abends. A job which uses more than its allotted CPU time, for example, will fail with a S322 abend, while one which waits for an excessive period of time will fail with a S522 abend.

While these failures are sometimes due to loops, invalid waits, or other conditions, often they occur simply because of unusual loads on the system - month-end or year-end processing for example, or a tape which takes an unusually long time to retrieve. When such jobs fail, a time-consuming and costly process of determining the cause of the error, modifying the JCL, and resubmission and rerunning of the job must be performed.

EASY/Exit allows the administrator to define policies which determine whether installation limits for CPU time, wait time, or amount of output may be overridden for particular jobs. EASY/Exit rules can be specified which identify jobs which should be allowed to use additional resources instead of abending. Thus, the EASY/Exit environments which receive control when job or step resource limits are exceeded provide the administrator a flexible way to enforce limits on resource use while at the same time prevent undesired failures and allowing important jobs to continue processing.

The following are the environments which can receive control when resource limits are exceeded:

• The JOB_CPU environment receives control whenever the overall CPU TCB time limit for a batch job or TSO user has expired. The EASY/Exit administrator can establish policies that allow the job to fail, extend the allowable CPU time, or take other actions, such as issuing WTOs or WTORs or system commands. If no action is taken, the job is allowed to abend with a S322 error. For more information, examine “IEFUTL - The JOB_CPU and STEP_CPU Environments”.
• The STEP_CPU environment receives control whenever the step-level CPU TCB time limit for a batch job or TSO user has expired. (If there is no limit on CPU usage for the step, this environment does not receive control). The EASY/Exit administrator can establish policies that allow the job to fail, extend the allowable CPU time, or take other actions, such as issuing WTOs or WTORs or system commands. If no action is taken, the step is allowed to abend with a S322 error. For more information, examine “IEFUTL - The JOB_CPU and STEP_CPU Environments”.
• The JOB_WAIT environment receives control whenever the continuous wait time limit for a job or step has been exceeded. The EASY/Exit administrator can establish policies which allow the job to fail, extend the allowable wait time, or take other actions, such as issuing WTOs or WTORs or system commands. If no action is taken, the step is allowed to abend with a S522 error. For more information, examine “IEFUTL - The JOB_WAIT Environment”.
• The OUTLIM environment receives control whenever the SYSOUT line limit for a dataset has been exceeded. The EASY/Exit administrator can establish policies allowing the job to fail, extend the allowable SYSOUT limit, or take other actions, such as issuing WTOs or WTORs or system commands. If no action is taken, the step is allowed to abend with a S722 error. For more information, examine “IEFUSO - The OUTLIM Environment”.

Controlling REGION, Dataspace, and Hiperspace Use

The IEFUSI exit is entered at the beginning of every job step. The STEP_START environment can be used to examine the step’s requirements for REGION size, data space use, hiperspace use, and if desired, can limit the use of these resources or cancel the job. The STEP_START environment can be used to enforce systemwide policies on the use of main storage resources by job name, step name, time of day, or other criteria. Records can be written to SMF, to the DIF log, or to other files to provide a record of resource use. Messages and other notifications can be sent to TSO users or system administrators to warn of potential error conditions or over utilization of resources. The step may also be cancelled if, for example, it does not meet installation standards. For more information, examine “IEFUSI - The STEP_START Environment”.

Intercept and Control Jobs

The following are the environments which can receive control during job processing:

• JOB_VALIDATE - receives control during converter-interpreter processing of the JCL for a job. The JOB_VALIDATE environment allows the administrator to examine and, if necessary modify the JCL prior to execution to establish and enforce installation standards for REGION, TIME, SYSOUT limits, and similar variables. This environment also allows the administrator to keep records of which jobs have run, write messages to SMF, the DIF log, or TSO users, or trigger other actions based upon the selection of the job for execution. For more information, examine “IEFUJP - JOB_PURGE Environment”.
• JOB_START - the IEFUJI exit is entered when a job has been selected for execution and is about to be initiated. The JOB_START environment can be used to examine the job name, accounting information, and other variables, and write records to the DIF log or to SMF, write messages to TSO users or administrators, and allow the job to execute. The job may also be cancelled if, for example, it does not meet installation standards. For more information, examine “IEFUJI - JOB_START Environment”.
• JOB_END and STEP_END - the IEFACTRT exit is entered whenever a job or step is terminated, either normally or abnormally. The JOB_END and STEP_END environments can be used to examine variables such as job and step name, return code, and others, and write records to the DIF log or to SMF, to issue WTORs to the operator to document the reason for a failure, or take other actions. For more information, examine “IEFACTRT - JOB_END and STEP_END Environments”.
• JOB_PURGE - receives control after all output for a job has been processed, all SYSOUT data has been output, and the job or TSO session is about to be purged from the system. This environment also allows the administrator to keep records of which jobs have run, of TSO logoffs, write messages or data records to SMF or the DIF log, or to TSO users, or trigger other actions based upon the completion of job output processing. The EASY/Exit rules may also be used to suppress writing of the SMF type 26 (job purge) record, if desired. For more information, examine “IEFUJP - JOB_PURGE Environment”.

Allocation Environment Exits and Actions

There are four environments which receive control prior to the issuance of WTORs which prompt the operator to decide whether a job should be cancelled or should wait for unavailable resources, whether volumes and devices should be brought online, and if so, which ones. While the system allocation parameters in the ALLOCxx member of SYS1.PARMLIB provide a default action that the system will take in these situations, ALLOCxx often does not provide sufficient power or flexibility to meet an installation’s needs. Exit points are available which allow custom-written exits to handle these situations, but as is often the case, the exits are rarely used due to the difficulty and effort required to constantly test, maintain, and upgrade the code. The EASY/Exit rules provide a flexible alternative, allowing installations to use the full power of the allocation exit points within z/OS, without the need to test and maintain system-level complex assembler code.

The chart below shows the four allocation environments within EASY/Exit, and the WTORs that can be intercepted and suppressed or automatically acted upon.

The following are the environments which can receive control during device and volume allocation:

Managing Offline or In-Use Devices

The ALLOC_OFFLINE environment is entered whenever a device required for a job is offline or is in use by another job. The ALLOC_OFFLINE environment (also referred to here as the Offline Device environment) receives control prior to the issuance of any WTORs for the allocation, and can be used to prevent or automatically respond to WTORs and to extend or override any default policy for offline devices specified in the ALLOCxx member of SYS1.PARMLIB. Using the EASY/Exit rules for the ALLOC_OFFLINE environment, administrators can automatically bring required devices online, allow jobs to wait, or cancel jobs which are waiting for devices in accordance with a centrally controlled policy. For more information, examine “ALLOC_OFFLINE Environment”.

Managing the Use of Specifically-Required Devices

The ALLOC_SPEC_WAIT environment receives control whenever a job must wait for a specific, hardcoded device or volume (as opposed to one of a class or group of devices) to become available before it can continue. Normally, the operating system will issue a WTOR prompting the operator to either cancel the job or allow the job to wait for the device to become available. Using the EASY/Exit rules in the ALLOC_SPEC_WAIT environment, administrators can automatically bring required devices online, allow jobs to wait, or cancel jobs which are waiting for devices in accordance with a centrally controlled policy. For more information, examine “ALLOC_SPEC_WAIT Environment”.

Managing the Use of Required Volumes

The ALLOC_VOL_ENQ environment receives control when a job must wait for a volume or volumes to become available before ENQueueing on the volumes and continuing. By default, the system issues WTORs to prompt the operator to decide whether the job should wait for the ENQ or whether it should be cancelled. Using the EASY/Exit rules specified for the ALLOC_VOL_ENQ environment, the administrator can provide a flexible and customized policy for which actions should be taken when a job must wait for a volume enqueue. The ALLOC_VOL_ENQ environment allows installations to manage the response to the WTORs issued when a volume enqueue cannot be obtained. For more information, examine “ALLOC_VOL_ENQ Environment”.

Managing Volume Mounts

The ALLOC_VOL_MOUNT environment receives control whenever a volume must be mounted and the system must prompt the operator to mount the volume. Often, the prompt is due to dynamic allocation of a tape dataset used for backup, but any allocation which requires a device be mounted can result in such a prompt. The ALLOC_VOL_MOUNT environment can be used to automatically take actions in response to the need for mounting of a volume. The WTOR can be suppressed and the job cancelled, or the operator can be prompted to mount the volume, based upon the selection criteria defined in the EASY/Exit rules. For more information, examine “ALLOC_VOL_MOUNT Environment”.

IEFUTL - The JOB_CPU and STEP_CPU

The JOB_CPU and STEP_CPU environments are entered whenever the TCB time limit for a job or step is exceeded and the job or step is about to fail with a S322 abend.

The JOB_CPU and STEP_CPU environments can be used to automatically extend TCB time limits for a particular job or step, by any amount specified by the EASY/Exit rules. The EASY/Exit rules can also be used to issue a WTOR to the operator, if desired, to allow the operator to determine whether a job or step should be allowed additional CPU time, and if so, how much. Execution of the problem program is suspended while the JOB_CPU or STEP_CPU environments are in control.

If the EASY/Exit rules specify that the time limit is to be extended, it is extended only for the current step. The JOB_CPU or STEP_CPU environment may be entered again if the time limit is exceeded again during subsequent steps. The JOB_CPU and STEP_CPU environments receive control only when the job or step is running under a TCB. They do not receive control if the time limit is exceeded while in SRB mode.

The JOB_CPU and STEP_CPU environments receive control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the JOB_CPU and STEP_CPU environments, the IEFUTL exit point must be active and the EXTUTL exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the JOB_CPU and STEP_CPU environments:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYS.IEFUTL,MOD=EXTUTL,FIRST

In order to ensure that EXT’s use of the IEFUTL exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUTL,MOD=EXTUTL

Variables for the JOB_CPU and STEP_CPU

The following variables are available for use in the JOB_CPU and STEP_CPU environments. The variables listed are all read-only variables except ADD_TIME, which can be set by the rules language to a numeric value of additional CPU seconds.

Table 4-2. Variables for the JOB_CPU and STEP_CPU Environments

Examples for the JOB_CPU and STEP_CPU Environments

Example 1 - Allow Additional CPU time for critical jobs running over the weekend.

In this example, jobs whose names begin with the characters ’PR’ (indicating, perhaps, an important production job) are allowed up to 5 minutes of additional CPU time, in one-minute increments, if the job is executing on a Saturday or Sunday. During the week, the normal CPU time limitations apply. A copy of this rule can be found in member EXTCPEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE MORETIME IF &JOBNAME = PR* &JOBSDAY = (SATURDAY, SUNDAY) &JOB_CPU_EXT LT 4 &ENV = &JOB_CPU THEN SET &ADD_TIME = 60 ISSUE WRITEMSG(USERMSG) DEFMSG USERMSG 'WARNING: &JOBNAME CPU TIME WAS EXTENDED BY 60 SECONDS'

Example 2 - Specify CPU Time Limits for Jobs in Various Systems

In this example, batch jobs which execute on the ’SYSB’ system which are about to fail get an additional two minutes of CPU time. Batch jobs running on ’SYSC’ get an additional three minutes. TSO users and started tasks are unaffected. A copy of this rule can be found in member EXTCPEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE SYSBRULE IF &JOBTYPE = JOB &SYSID = 'SYSB' &ENV = (JOB_CPU,STEP_CPU) THEN SET &ADD_TIME = 120 IF &JOBTYPE = JOB &SYSID = 'SYSC' &ENV = (JOB_CPU,STEP_CPU) THEN SET &ADD_TIME = 180

IEFUTL - The JOB_WAIT Environment

The JOB_WAIT environment is entered whenever the continuous wait time limit for a job is exceeded and the job is about to fail with a S522 abend.

The JOB_WAIT environment can be used to automatically extend wait time limits for a particular job, by any amount specified by the EASY/Exit rules. The EASY/Exit rules can also be used to issue a WTOR to the operator, if desired, to allow the operator to determine whether a job or step should be allowed to continue waiting.

If the EASY/Exit rules specify that the wait time limit is to be extended, it is extended only for the current step. The JOB_WAIT environment may be entered again if the continuous wait time limit is exceeded again during the step, or during subsequent steps.

The JOB_WAIT environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the JOB_WAIT environment, the IEFUTL exit point must be active and the EXTUTL exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the JOB_CPU and STEP_CPU environments:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYS.IEFUTL,MOD=EXTUTL,FIRST

In order to ensure that EXT’s use of the IEFUTL exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUTL,MOD=EXTUTL

Variables for the JOB_WAIT Environment

The following variables are available for use in the JOB_WAIT environment. The variables listed are all read-only variables except ADD_TIME, which can be set by the rules language to a numeric value of additional seconds.

Table 4-3. Variables for the JOB_WAIT Environment

Examples for the JOB_WAIT Environment

Example 1 - Allow Additional WAIT Time for Batch Jobs

In this example, batch jobs which meet a particular job naming convention are allowed to wait an additional 10 minutes before the system terminates the job with a S522 abend.

DEFRULE WAITMORE IF &JOBNAME = TPJOB* &JOBTYPE = JOB &JOB_WAIT_EXT EQ 1 &ENV = JOB_WAIT THEN SET &ADD_TIME = 600 ELSE ISSUE WRITEMSG(ERRMSG) DEFMSG ERRMSG 'WARNING: JOB &JOBNAME WAIT TIME WAS EXTENDED BY 10 MINUTES BUT STILL FAILED' USER(STGADM)

Example 2 - Allow the Operator to Increase Wait Time or CPU Time to Avoid an Abend

The following example demonstrates the use of the DEFVAR statement to define the content of a WTOR message and the use of a user-defined DIF variable (&USRFLDN1) to contain the response. If a job is about to fail with a S522 abend because the wait time limit for the job has been exceeded, or a S322 abend because the CPU time limit has been exceeded, the operator is prompted to supply the additional time increment. The &ENV variable used in the message indicates whether it is the JOB_WAIT time, JOB_CPU time, or STEP_CPU time that was exceeded. A copy of this rule can be found in member EXTWTEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFVAR MORETIME "USRFLDN{1}" NUMERIC OPER(WRITEMSG(OP1)) DEFRULE R1 IF &ENV = (JOB_WAIT,JOB_CPU,STEP_CPU) &JOBNAME = SOMEJOB* &JOBTYPE = (JOB,STC) THEN ISSUE WRITEMSG(OP1) SET &INCREMENT = &MORETIME DEFMSG OP1 "MAX &ENV EXCEEEDED. ENTER ADDITIONAL SECONDS (1-9999)TO AVOID ABEND, OR 0 TO TERMINATE"

Example 3 - Override TSO Timeout Defaults

In this example, TSO users belonging to the ’SYSTEMS’ RACF group are prevented from being automatically logged off when the TSO timeout limit expires. Storage administrators and ’PROD’ users may remain idle and logged on for an additional 2 hours. A copy of this rule can be found in member EXTWTEX3 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE NOLOGOF IF &JOBTYPE = TSU &RACF_GRP = SYSTEMS &ENV = JOB_WAIT THEN SET &ADD_TIME = 3600 IF &JOBTYPE = TSU &JOBNAME = (STGAD*,PROD*) &JOB_WAIT_EXT LT 1 &ENV = JOB_WAIT THEN SET &ADD_TIME = 7200

IEFUSO - The OUTLIM Environment

The OUTLIM environment is entered whenever the SYSOUT limit (the OUTLIM= value) for the number of lines to be printed for a spooled dataset is exceeded and the job is about to fail with a S722 abend.

The OUTLIM environment can be used to automatically increase the number of output lines allowed for a particular DD statement, by any amount specified by the EASY/Exit rules. The EASY/Exit rules can also be used to issue a WTOR to the operator, if desired, to allow the operator to determine whether a the job should be allowed to use additional resources or whether it should be allowed to fail.

The OUTLIM environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the OUTLIM environment, the IEFUSO exit point must be active and the EXTUSO exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the OUTLIM environment:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYS.IEFUSO,MOD=EXTUSO,FIRST

In order to ensure that EXT’s use of the IEFUSO exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUSO,MOD=EXTUSO

Variables for the OUTLIM Environment

The following variables are available for use in the OUTLIM environment. The variables listed are all read-only variables except ADD_LINES, which can be set by the rules language to a numeric value of additional lines.

Table 4-4. Variables for the OUTLIM Environment

Examples for the OUTLIM Environment

Example 1 - Increase the number of SYSOUT lines allowed for Batch Jobs on SYSB

In this example, the number of output lines allowed for SYSOUT output in a particular batch job is increased by 5000. This might be useful, if, for example, the number of output lines is normally limited by the OUTLIM= parameter on the JCL, but the value needs to be overridden for a particular job. A copy of this rule can be found in member EXTOUEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE MORELINES IF &JOBNAME = SJP* &JOBTYPE NE TSU &LINE_EXTENSIONS EQ 1 &SYSID = SYSB THEN SET &ADD_LINES = 5000

IEFUSI - The STEP_START Environment

The IEFUSI exit is entered at the beginning of every job step. The STEP_START environment can be used to examine the step’s requirements for REGION size, data space use, hiperspace use, and if desired, can limit the use of these resources or cancel the job. The STEP_START environment can be used to enforce systemwide policies on the use of main storage resources by job name, step name, time of day, or other criteria. Records can be written to SMF, to the DIF log, or to other files to provide a record of resource use. Messages and other notifications can be sent to TSO users or system administrators to warn of potential error conditions or over utilization of resources. The step may also be cancelled if, for example, it does not meet installation standards.

The STEP_START environment receives control at the start of each step, before any datasets are allocated, under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the STEP_START environment, the IEFUSI exit point must be active and the EXTUSI exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTUSI environment:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYS.IEFUSI,MOD=EXTUSI,FIRST

In order to ensure that EXT’s use of the IEFUSI exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUSI,MOD=EXTUSI

Controlling REGION Use

The STEP_START environment can be used to limit the amount of private area storage that may be requested by programs. The total amount of private area storage that can be used is &REGION_LIMIT_LO for the private area below 16MB and &REGION_LIMIT_HI for the private area above 16MB. The default region size is set by either the JCL or MVS default (the &REGION value). It may be overridden by setting &REGION_SIZE_LO (for the region below 16MB) or &REGION_SIZE_HI (for the region above 16MB).

The &REGION_SIZE values should be set somewhat lower than the &REGION_LIMIT values. This will prevent programs which do large variable-length GETMAINs from using all of the private area storage in the region.

If the EASY/Exit rules do not set a value for &REGION_SIZE_LO or &REGION_SIZE_HI, then the MVS defaults remain in effect, i.e., the REGION value from the JCL or JES defaults is used as the region size. If the rules do not set limits (&REGION_LIMIT_LO and &REGION_LIMIT_HI), then the MVS defaults remain in effect. The MVS defaults allow a region limit of the REGION size plus 64K for below-the-line storage and a limit of 32MB for above-the-line storage. Region size and region limit are defined and described in the MVS Initialization and Tuning Guide, SA22-7591.

Variables for the STEP_START Environment

The following variables are available for use in the STEP_START environment.

Table 4-5. Variables for the STEP_START Environment

Examples for the STEP_START Environment

Example 1 - Ensure Sufficient Region for Batch Jobs

For batch jobs meeting a specified naming convention, if less than 4M of region is requested on the JOB or EXEC statement, then set the actual region available to 4M below the 16M line and 48M above the 16M line. An additional 2M of storage may be obtained by GETMAINs below the 16M line once the 4M region is used up. An additional 16M of storage may be obtained by GETMAINs above the 16M line once the 48M is used. (The region size is set less than the region limit value in order to ’reserve’ some space and prevent programs which issue very large variable-length GETMAINS from using all of the storage in the region. A copy of this rule can be found in member EXTUSEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.)

DEFRULE REGRULE IF &JOBNAME = PJ471* &JOBTYPE = JOB &REGION LT 4096 THEN SET &REGION_SIZE_LO = 4096 SET &REGION_LIMIT_LO = 6144 SET &REGION_SIZE_HI = 49152 SET &REGION_LIMIT_HI = 65536

Example 2 - Prevent Use of REGION=0M by Applications

Jobs which specify REGION=0M are essentially allowed to issue GETMAINs up to the entire available size of the private area. This example prevents the use of REGION=0M and sets the region size to 6M (below-the-line) and 32M (above-the-line) for application jobs. An additional 2MB is allowed for below-the-line GETMAINs when the below-the-line REGION is exhausted. An SMF record is written so that the storage administrator can identify these applications. A copy of this rule can be found in member EXTUSEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE ZEROMEG IF &JOBNAME = P* &JOBTYPE NE (STC) &REGION = 0 THEN SET &REGION_SIZE_LO = 6144 SET &REGION_LIMIT_LO = 8192 SET &REGION_SIZE_HI = 32768 SET &REGION_LIMIT_HI = 32768 ISSUE WRITESMF(SMFZERO) DEFSMF SMFZERO 'JOB &JOBNAME REQUESTED REGION=0M. CHANGED TO 6M'

Example 3 - Limit the Use of Hiperspace During Production Batch Hours

In this example, the use of hiperspace by batch jobs during daytime hours is restricted. A maximum of 5 dataspace and/or hiperspaces may be created by a job, and the maximum size of all dataspace/hiperspaces for the job may not exceed 16 megabytes. At night, the restrictions are lifted. (The restriction also does not apply to system-state or system-key programs, which may always use unlimited amounts of hiperspace and dataspace). A copy of this rule can be found in member EXTUSEX3 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE DAYRULE IF &JOBTYPE = JOB &CURTIME(1,2) GT 09 /* AFTER 9 AM */ &CURTIME(1,2) LT 17 /* BEFORE 5 PM */ THEN SET &MAX_SHARE_SIZE = 16384 SET &MAX_SHARE_NO = 5

IEFUJV - JOB_VALIDATE Environment

The JOB_VALIDATE environment receives control during converter-interpreter processing of the JCL for a job. The JOB_VALIDATE environment allows administrators to use the EASY/Exit rules to examine and if necessary modify the JCL prior to execution to establish and enforce installation standards. Because the JOB_VALIDATE environment receives control for each JCL statement, the JCL can be validated to ensure that jobs run in the correct class, use the correct values for MSGCLASS, REGION, TIME, SYSOUT, and so on. This environment also allows the administrator to keep records of which jobs have been submitted for execution in which classes, identify types of JCL use, write messages to SMF, the DIF log, or TSO users when standards violations are identified, or trigger other actions based upon the contents of the JCL.

The JOB_VALIDATE environment receives control prior to execution of the job, at one of three different points during converter-interpreter processing. The 'subenvironment' variable (ENVS) indicates which point is in control:

When &ENVS=PRECONV, the JCL has not yet been converted, and the &CARD_IMAGE variable contains a copy of the raw JCL statement being processed. This variable may be examined to find the values of variables such as MSGCLASS or DSNAME, and may be changed via SET statements if needed. If a SET statement in the EASY/Exit rules changes the contents of the &CARD_IMAGE variable, the modified statement replaces the existing statement in the JCL. (New JCL statements cannot be added, however). The EASY/Exit rules are entered in the PRECONV subenvironment once for each JCL statement in the job. During the PRECONV environment, the &SMFXUSRNx and &SMFXUSRCx variables can be used to hold numeric counters or character strings. The values set in &SMFXUSRNx and SMFXUSRCx are preserved from one entry to the EASY/Exit rules in the JOB_VALIDATE environment to the next.

During the PRECONV subenvironment, (i.e., when JCL statements are being processed), the &STMT_TYPE variable indicates the type of JCL statement, such as JOB, EXEC, or DD, being processed.

It may be useful to include a check in the rules to determine whether the current control statement is continued, since not all of the variables for a particular statement (e.g., VOLSER, UNIT, DSNAME, etc.) will be known until the last statement image is encountered. The value of the &CONTINUED variable will be YES if the statement is continued onto another card image. The value of &CONTINUED will be NO if the entire control statement is contained on one card image or if the current card image is not continued.

When &ENVS=POSTCONV, all of the JCL for the job has been converted. Unlike the PRECONV environment, which is entered for each control statement, the POSTCONV environment is entered only once. At this point in processing, the value of the &CARD_IMAGE variable will be null. It may be useful in this environment for the rules to check flags or values which were previously set in &SMFXUSRNx and SMFXUSRCx and take actions such as issuing messages, writing SMF or log records, or determining whether to allow the job to continue.

When &ENV=POSTINTR, all of the JCL for the job has been converted and interpreted, and the job is about to be scheduled for execution. Like the POSTCONV environment, the POSTINTR environment is entered only once.

Enabling the JOB_VALIDATE Environment

The JOB_VALIDATE environment runs under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the JOB_VALIDATE environment, the IEFUJV exit point must be active and the EXTUJV exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTUJV environment:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFUJV,MOD=EXTUJV

In order to ensure that EXT's use of the IEFUJV exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUJV,MOD=EXTUJV

The SMFPRMxx member of SYS1.PARMLIB must also indicate that the IEFUJV exit is to get control. The SYS or SUBSYS statement in SMFPRMxx indicates for which systems the IEFUJV exit (and other SMF exits) are to receive control. The SYS or SUBSYS statement in SMFPRM is typically of a form such as the following:

SYS(TYPE(0:255),EXITS(IEFU83,IEFU84,IEFACTRT,IEFUJV,IEFUSI,IEFUJI,IEFU29),NOINTERVAL,NODETAIL)

In order for EASY/Exit to receive control in the JOB_VALIDATE environment, the IEFUJV parameter must be specified on the appropriate SYS or SUBSYS statement in SMFPRMxx.

Finally, a DEFENV statement must be present in the EASY/Exit rules in order to enable the JOB_VALIDATE environment. The DEFENV statements normally appear first after the DEFPROD statement, if any, in the EASY/Exit rules. The DEFENV statement for this environment should be of the form:

DEFENV JOB_VALIDATE MODE(ACTIVE)

Variables for the JOB_VALIDATE Environment

The following variables may be specified in the EASY/Exit rules in the JOB_VALIDATE environment. Some other variables may also be available for use which are not documented here. This includes many of the fields documented in Tables 6-4, 6-7, and 6-8 of the DIF Rule Language Programming Guide. If a variable you need does not appear in the table below, please contact DTS Software Technical Support - we may be able to provide such a variable or other functionality.

Certain keyword parameters on the JOB statement can be examined and validated but cannot be changed via the EASY/Exit rules in the JOB_VALIDATE environment. These parameters are CLASS, GROUP, MSGCLASS, NOTIFY, PASSWORD, PRTY, SECLABEL, TYPRUN, and USER. If it is necessary to use the EASY/Exit rules to change any of these variables on the JOB statement, this should be done using EASY/Exit in the JES Environment (JES Exit 6 or 20).

Messages written via the ISSUE WRITEMSG statement in the EASY/Exit rules during the JOB_VALIDATE environment should not specify a routing code of 11 (write-to-programmer) for started tasks or TSO users (batch jobs are ok. If no routing code is specified, ISSUE WRITEMSG may always be used). Routing code 14 is recommended for the JOB_VALIDATE environment. If a message must be issued for a started task or TSO user, use a routing code other than 11 (preferably 14), or direct the message to the DIF log or an SMF record via the SMFRID or LOGDD parameters of the DEFMSG rule statement.

Table 4-6. Variables for the JOB_VALIDATE environment.

Examples for the JOB_VALIDATE Environment

Example 1 - Dynamically Alter JCL Variables Such as DSN, UNIT, and REGION

This example shows the use of the JOB_VALIDATE environment to change dataset names, unit names, and volume serial numbers by scanning the JCL prior to converter/interpreter processing and substituting the desired values. In this example, references to datasets whose names begin with 'PROD.EAST' are replaced with 'PROD.AREA17', and allocations for 'UNIT=3480' are replaced with 'UNIT=3590'. A copy of this rule can be found in member EXTJVEX1 in the SCC sample library.

DEFENV JOB_VALIDATE MODE(ACTIVE) DEFRULE DSNUNIT IF &JOBNAME = PRODX* /* FOR PRODUCTION JOBS */ &ENVS = PRECONV /* BEFORE JCL CONVERSION */ &STMT_TYPE = DD /* DD STATEMENT */ THEN SET &SCAN_STRING1 = 'DSN=PROD.EAST' SET &REPL_STRING1 = 'DSN=PROD.AREA17' SET &SCAN_STRING2 = 'UNIT=3480' SET &REPL_STRING2 = 'UNIT=3590'

Example 2 - Dynamically Change the Program Name to be Executed

In this example, the name of a program which is about to be executed is changed to a different program name. In this case, program P3497QXR is changed to program IEFBR14, effectively removing the old program from the system. A copy of this rule can be found in member EXTJVEX2 in the SCC sample library.

DEFENV JOB_VALIDATE MODE(ACTIVE) DEFRULE NULLPGM IF &ENVS = PRECONV /* BEFORE JCL CONVERSION */ &STMT_TYPE = EXEC /* EXEC STATEMENT */ THEN SET &SCAN_STRING1 = 'PGM=P3497QXR' SET &REPL_STRING1 = 'PGM=IEFBR14'

Example 3 - Prevent Jobs from Executing in the Wrong Class

In this example, some test jobs (those with jobnames beginning with 'T1') are never allowed to run in class B. At the same time, other test jobs (those with jobnames beginning with 'T2') must run in classes B, C, or D if the time is between midnight and 6:00AM. A copy of this rule can be found in member EXTJVEX3 in the SCC sample library. Note that job CLASS cannot be changed at IEFUJV time, since JES has already begun processing the job. CLASS can be dynamically changed in EASY/Exit using JES2 Exit 20.

DEFENV JOB_VALIDATE MODE(ACTIVE) DEFRULE TESTJOBS IF &ENVS = PRECONV /* BEFORE JCL CONVERSION */ &STMT_TYPE = JOB /* JOB STATEMENT */ &JOBNAME = T1* /* TEST JOBS OF TYPE 1 */ &CLASS = B /* SUBMITTED FOR CLASS B */ THEN SET &JCLFAIL = YES /* WILL BE FAILED */ ISSUE WRITEMSG(ER1) /* WITH AN ERROR MESSAGE */ EXIT /* NO FURTHER PROCESSING */ IF &ENVS = PRECONV /* BEFORE JCL CONVERSION */ &STMT_TYPE = JOB /* JOB STATEMENT */ &JOBNAME = T2* /* TEST JOBS OF TYPE 2 */ &CLASS NE (B,C,D) /* NOT IN PROPER CLASS */ &CURTIME(1,5) GT '18:00' /* AFTER 6 PM */ &CURTIME(1,5) LE '23:59' /* BEFORE MIDNIGHT */ THEN SET &JCLFAIL = YES /* WILL BE FAILED */ ISSUE WRITEMSG(ER2) /* WITH AN ERROR MESSAGE */ EXIT /* NO FURTHER PROCESSING */ DEFMSG ER1 'TEST JOB &JOBNAME MUST RUN IN CLASS B' DEFMSG ER2 'JOB &JOBNAME MUST RUN IN CLASS B/C/D IN THE EVENING'

Example 4 - Ensure that Certain Jobs Include a Step Executing Program PTOTAL

In this example, the JCL for each EXEC statement is examined to ensure that at least one step of a certain production job includes an execution of program PTOTAL. This example sets a flag in the &SMFXUSRC1 variable at PRE-CONV time to indicate that a step containing the program name has been found. At POSTCONV time, the flag is examined to see whether any of the steps included the program. A copy of this rule can be found in member EXTJVEX4 in the SCC sample library.

DEFENV JOB_VALIDATE MODE(ACTIVE) DEFRULE FINDPGM IF &JOBNAME NE PROD* THEN CONTINUE SCANNING AT NEXTRULE IF &ENVS = PRECONV /* BEFORE JCL CONVERSION */ &STMT_TYPE = EXEC /* EXEC STATEMENT */ &PGM = PTOTAL /* DESIRED PROGRAM */ THEN SET &SMFXUSRC1(1,1) = 'Y' /* INDICATE FOUND */ IF &ENVS = POSTCONV /* AFTER JCL CONVERSION */ &SMFXUSRC1(1,1) NE 'Y' /* WAS PROGRAM FOUND? */ THEN SET &JCLFAIL = YES /* IF NOT, FAIL */ ISSUE WRITEMSG(ERR) /* WITH AN ERROR MESSAGE */ EXIT /* NO FURTHER PROCESSING */ DEFMSG ERR 'JOB MUST CONTAIN A PGM=TESTX STEP'

Tracing, Debugging, and Displaying Variable Values

When writing EASY/Exit rules, it may be useful to know the value of EASY/Exit variables at various points in processing, or to obtain a trace of the EASY/Exit rules logic. There are several different ways of obtaining this information.

Using the EXTTRACE Logic Trace

If a JOB, EXEC, or DD statement has a name field beginning with the characters EXT-TRACE, EASY/Exit rules logic tracing will be performed. The trace output will show each EASY/Exit IF-THEN-ELSE comparison and the values of the variables involved. In the JOB_VALIDATE environment, the trace messages will be placed in the JES log data-set as part of an IEF196I message. Tracing will begin at the point where the EXTTRACE statement is encountered and will continue until all the JCL has been processed. Note that because the rules are executed for each JCL statement, there may be quite a bit of output.

Using the Rules to Display Variables

It may be useful simply to use the messaging facilities in the EASY/Exit rules to display the contents of variables of interest. For example, the following rule could be used to display the value of the management class, unit name, and dispositions for a particular dataset. This has the advantage of limiting the output to just the desired information. If the rules logic is in question, however, then an EXTTRACE logic trace (above) may be necessary. The CONTINUE(NEXTIF) clause on the DEFULE statement in the example indicates that processing should continue with the next IF statement or rule after processing for this rule is complete.

DEFRULE TESTRULE CONTINUE(NEXTIF) IF &JOBNAME = MYJOB /* FOR THIS JOB */ &STMT_TYPE = DD /* A DD STATEMENT */ &CONTINUED = NO /* LAST OR ONLY LINE */ &DSNAME = SOME.DATA.SET /* FOR DESIRED DSN */ THEN ISSUE WRITEMSG(M1) DEFMSG M1 'MCLAS=&MGMTCLAS UNITN=&UNITNAME DISP=&DISP1 &DISP2 DISP3'

IEFUJI - JOB_START Environment

The IEFUJI exit is entered when a job has been selected for execution and is about to be initiated. The JOB_START environment can be used to examine the job name, accounting information, and other variables, and write records to the DIF log or to SMF, write messages to TSO users or administrators, and allow the job to execute. The job may also be cancelled if, for example, it does not meet installation standards.

The JOB_START environment receives control prior to execution of the job, under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the JOB_START environment, the IEFUJI exit point must be active and the EXTUJI exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTUJI environment:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYS.IEFUJI,MOD=EXTUJI,FIRST

In order to ensure that EXT’s use of the IEFUJI exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUJI,MOD=EXTUJI

Variables for the IEFUJI Environment

The following variables are available for use in the JOB_START environment. The variables listed are all read-only variables except JCLFAIL, which can be set by the rules language to fail a job.

Table 4-7. Variables for the JOB_START Environment

Examples for the JOB_START Environment

Example 1 - Notify the Operator When a Job is Selected for Execution

In this example, a WTOR is issued to notify the operator that a specified job is about to begin execution. The operator must reply to the message to indicate that the requested action has been taken. The job will remain in 'STARTING' status until the message is replied to. A copy of this rule can be found in member EXTUJEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFVAR REPLYVAR "USRFLDN{1}" OPER(WRITEMSG(ACTMESS)) DEFRULE R1 IF &JOBNAME = A3472Q THEN ISSUE WRITEMSG(ACTMESS) SET &USRFLDC1 = &REPLYVAR DEFMSG ACTMESS "JOB A3472Q IS SELECTED. YOU MAY NOW START REMOTE SUBSYSTEM NUMBER 341. REPLY ANY CHAR TO CONTINUE"

Example 2 - Fail a Job with Incorrect Account Information

This example checks to see that the correct job accounting information has been entered on the JOB statement. If an incorrect account code is found, the job is cancelled with a JCL error. A copy of this rule can be found in member EXTUJEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE ACCTRULE IF &JOBNAME = PRD* &ACCT{2} NE (ZB2*,A4,X3947A,SS*) THEN SET &JCLFAIL = YES

IEFACTRT - JOB_END and STEP_END

The IEFACTRT exit is entered whenever a job or step is terminated, either normally or abnormally. The JOB_END and STEP_END environments can be used to examine variables such as job and step name, return code, and others, and write records to the DIF log or to SMF, to issue WTORs to the operator to document the reason for a failure, or take other actions.

The JOB_END and STEP_END environments are entered only if the appropriate types of SMF records are being recorded, as specified in the SMFPRMxx member of SYS1.PARMLIB. The table below shows the type of record which is produced, and for which the JOB_END and STEP_END environments are entered, for each type of job.

Table 4-8. SMF record types for IEFACTRT

The IEFACTRT exit may be entered multiple times for a single job or step. This will occur if the data for an SMF record exceeds 32K bytes in length, or if multiple SMF record types (4, 5, 30, 34, 35, etc.) are being recorded. Since the EASY/Exit rules are run each time IEFACTRT is invoked, it may be useful to test the &ENVS variable for the SMF record type to ensure that the EASY/Exit rules are only invoked when required. The EASY/Exit rules may also be used to suppress certain types of SMF records by setting the SMFSUPP variable to 'YES'.

The JOB_END and STEP_END environments receive control at the termination of the job or step under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the JOB_END and STEP_END environments, the IEFACTRT exit point must be active and the EXTTRT exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTTRT environment:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFACTRT,MOD=EXTTRT,FIRST

In order to ensure that EXT’s use of the IEFACTRT exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFACTRT,MOD=EXTTRT

'Flowerbox' Output - Step and Job Termination Statistics

In many installations, the IEFACTRT exit is used to provide formatted output in the form of 'flowerbox' statistics at the end of each step in a job and at job termination. The statistics are obtained from the SMF type 30 record (subtype 4 for step termination and subtype 5 for job termination). The 'flowerbox' display is usually written to the JES Messages dataset and provides detailed at-a-glance information about the step and job. Information written often includes resource-consumption statistics such as CPU and elapsed time used, EXCP count, paging details, and more.

Although nearly every installation uses IEFACTRT to provide some sort of 'flowerbox' step and job termination output, such in-house-written exit routines are virtually never reviewed and almost never updated. Very few installations have the time or expertise to perform such tasks, and as result, rely on IEFACTRT routines that may not have been recompiled in years. Despite their prominent position in the output of every job in the system, the step and job termination statistics at many installations may be limited, misleading, and out-of-date. Fortunately, EASY/Exit's IEFACTRT 'flowerbox' formatting routines are available to provide more complete, up-to-date, useful data from the SMF 30 records. With EASY/Exit, the installation no longer has to worry about reviewing exit code or keeping up with changes in SMF record layouts. The EASY/Exit rule language can be used to provide step and job termination statistics with a couple of simple keywords.

Writing SMF Type 30 Records

The SMF type 30 record is written at the completion of each step (subtype 4) and job (sub-type 5). It contains detailed statistical information about resources used by the step or job, including information about datasets used. The IEFACTRT exit receives control when each SMF type 30 record is written, and can be used to write the statistical information to the JES datasets so that it is easily visible and accessible to users. Generally, a short, one-line summary is written to the JES Log Dataset (JESMSGLG) for each step, and more detailed, comprehensive statistical information is written to the JES Messages (JESYSMSG) dataset.

JES Log Dataset

The JES Log Dataset (JESMSGLG) is normally the first of the JES datasets associated with a job, and the IEFACTRT exit can be used to write a single-line statistical entry for each step and for the job as a whole, so that failed steps and basic information can be seen at a glance. Sample JESMSGLG output for EASY/Exit's IEFACTRT processing is shown below (note that device connect time was not measured in this example as this facility was not available on the system in which the job was run):

15.16.44 JOB07244 IEF404I TESTJOB - ENDED - TIME=15.16.44

15.16.44 JOB07244 -*TOTALS* 32 00:00:00.00 00:00:00.31 00:00:00.00 00:00:01.16 400 BATCH

JES Messages Dataset

The JES Messages Dataset (JESYSMSG) is usually the third JES dataset and can be used by IEFACTRT to provide detailed statistical information from the SMF type 30 record for each step and for the job as a whole. In addition to step-level resource information, EXCP counts and other I/O information are available at the DD level. A sample JESYSMSG output for EASY/Exit's IEFACTRT processing is shown below (note that device connect time was not measured in this example as this facility was not available on the system in which the job was run).

************************************************************************************************************************************
*		*
*	STEP TERMINATION STATISTICS	*
*		*
*	JOB NAME : TESTJOB START TIME: 15:16:43.83 SERV UNITS: 79 PAGE-INS : 0 BLOCKS XFR: 93 *
*	JES JOB ID: JOB07244	END TIME : 15:16:44.32	CPU SERV :	58	PAGE-OUTS :	0	TPUTS :	0	*
*	JOB CLASS : A	ELAP TIME : 00:00:00.49	SRB SERV :	3	PAGE-STEAL:	0	TGETS :	0	*
*	PROCSTEP :	STEP CPU : 00:00:00.06	I/O SERV :	8	VIO PAGIN :	0	DEV CONN :	00:00:00.00	*
************************************************************************************************************************************

Easy-Exit Rules for Step and Job Termination Statistics

The EASY/Exit rules required to enable step and job termination statistics to be written to JESMSGLG and JESYSMSG are very simple. All that is needed are DEFENV statements to enable the STEP_END and JOB_END environments and an OPTION parameter to cause the statistics to be written to the desired JES datasets. A sample EXTRULES member is shown below.

DEFENV STEP_END MODE(ACTIVE) OPTION(JESMSGSTATS,JESLOGSTATS) DEFENV JOB_END MODE(ACTIVE) OPTION(JESMSGSTATS,JESLOGSTATS)

Dynamic Exits Facility

EASY/Exit uses the system's Dynamic Exits facility to activate the IEFACTRT routines used to write the step and job statistics. In order to start EASY/Exit's IEFACTRT routines when EASY/Exit starts, the following statement should be added to the EXTINIT member of the dataset allocated to the //PARMLIB DD in the DIF started task:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFACTRT,MOD=EXTTRT,FIRST

In addition, the following statement should be added to the EXTTERM member of the dataset allocated to the //PARMLIB DD in the DIF started task, so that the EASY/ExitIEFACTRT is removed when EASY/Exit is stopped:

OPERCMD SETPROG EXIT,DELETE,EN=SYS.IEFACTRT,MOD=EXTTRT

Additional Dataset Level Step Termination I/O Statistics

If an installation is collecting SMF records for type 14, type 15, and type 64, Easy-Exit can write additional dataset-level statistics at step termination.

These additional statistics provide I/O information at the DD level for each sequential dataset opened or VSAM dataset closed during the step. The additional information is written following the standard SMF type 30 statistics that Easy-Exit writes at end of step. Sample output for the type 14/15/64 record information is shown below.

SMF record semantics:

• type 14 — written at OPEN for input for sequential datasets
• type 15 — written at OPEN for output for sequential datasets
• type 64 — written at CLOSE for VSAM datasets

Sample Non-VSAM I/O Statistics

************************************************************************************************************************************
*	STEP I/O STATISTICS BY DDNAME: NON-VSAM	*
* DDNAME	DEVICE	VOLSER	OPNTYP	OPNCT	DSO	OPTCD	RFM	LRECL	BLKSZ	BUFNO	BLKCT	EXT	TRKALC	TRKUSD	TRKRLS	*
* SYSUT2	3590	500025	OUTPUT	1	PS		FB	80	32,720	0	1	0	0	0	0	*
* SYSUT1	3390	A3RES1	INPUT	1	PS		FB	80	27,920	0	1	1	3,731	0	0	*
************************************************************************************************************************************

Sample VSAM I/O Statistics

************************************************************************************************************************************
*	STEP I/O STATISTICS BY DDNAME: VSAM	*
*	DDNAME	COMPONT	CLOSED	LEVELS EXTENTS RECORDS DELETES INSERTS UPDATES RETRIEV FREESPC CISPLIT CASPLIT EXCPCNT	*
* SORTOUT	DATA	1	0	1	2,145	0	0	0	0 645,120	0	0	11	*
* SORTOUT	INDEX	1	1	1	1	0	0	0	0	38,400	0	0	3	*
************************************************************************************************************************************

Easy-Exit Rules for Additional Step Termination I/O Statistics

The additional statistics above are produced when Easy-Exit processing in the IEFUSI exit creates a dataset-level table that is referenced by the IEFU83 and IEFACTRT exits. Therefore, the IEFUSI and IEFU83 exits must be enabled in Easy-Exit to obtain the additional statistics that will be written at IEFACTRT time.

Example control statements to enable the exits and I/O statistics:

DEFPROD IOSTATS(YES)
DEFENV STEP_START MODE(ACTIVE)
DEFENV IEFU83 MODE(ACTIVE)
DEFENV JOB_END MODE(ACTIVE) OPTION(JESMSGSTATS,JESLOGSTATS)
DEFENV STEP_END MODE(ACTIVE) OPTION(JESMSGSTATS,JESLOGSTATS)

Dynamic Exits Facility

Easy-Exit uses the system Dynamic Exits facility to activate the IEFACTRT, IEFU83, and IEFUSI routines used to write the additional statistics. To start these routines when Easy-Exit starts, add the following statement(s) to the EXTINIT member of the dataset allocated to the //PARMLIB DD in the DIF started task:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFACTRT,MOD=EXTTRT,FIRST
OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFU83,MOD=EXTU83,FIRST
OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFUSI,MOD=EXTUSI,FIRST

To remove the Easy-Exit routines when Easy-Exit is stopped, add the following statements to the EXTTERM member of the same dataset:

OPERCMD SETPROG EXIT,DELETE,EN=SYS.IEFACTRT,MOD=EXTTRT
OPERCMD SETPROG EXIT,DELETE,EN=SYS.IEFU83,MOD=EXTU83
OPERCMD SETPROG EXIT,DELETE,EN=SYS.IEFUSI,MOD=EXTUSI

Type 14, 15 and 64 SMF Records

For Easy-Exit to write the additional statistical information to JESMSGLG and JESYSMSG for type 14, type 15, and type 64 records, the system must be configured to collect those SMF record types.

Ensure that SMFPRMxx includes a statement that enables the required record types, for example:

SYS(TYPE(14,15,64))

or another equivalent SYS(...) statement that includes type 14, type 15, and type 64.

Variables for the JOB_END and STEP_END Environments

The following variables are available for use in the JOB_END and STEP_END environments. The variables listed are all read-only variables except JCLFAIL and SMFSUPP.

Table 4-9. Variables for the JOB_END and STEP_END Environments

IEFUJP - JOB_PURGE Environment

The JOB_PURGE environment receives control after all output for a job has been processed, all SYSOUT data has been processed, and the job or TSO session is about to be purged from the system. This environment also allows the administrator to keep records of which jobs have run, of TSO logoffs, write messages or data records to SMF or the DIF log, or to TSO users, or trigger other actions based upon the completion of job output processing. The EASY/Exit rules may also be used to suppress writing of the SMF type 26 (job purge) record, if desired.

The JOB_PURGE environment runs under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the STEP_START environment, the IEFUJP exit point must be active and the EXTUJP exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTUJP environment:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFUJP,MOD=EXTUJP,FIRST

In order to ensure that EXT’s use of the IEFUJV exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYS.IEFUJP,MOD=EXTUJP

Variables for the JOB_PURGE environment

The following variables are available for use in the JOB_PURGE environment.

Table 4-10. Values for the JOB_PURGE Environment

Examples for the JOB_PURGE Environment

Example 1 - Start Other Processes when a Job’s Output is Complete

In this example, once the output is complete for a job and job is about to be purged from the system, the JOB_PURGE environment is used to issue a console ’START’ command to initiate a started task. A copy of this rule can be found in member EXTJPEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE PJOB
IF &JOBNAME = A3742X &ENV = JOB_PURGE THEN ISSUE OPERCMD(C1) DEFCMD C1 "START H4BACKUP" CN(0)

ALLOC_OFFLINE Environment

The ALLOC_OFFLINE environment is entered whenever a device required for a job is offline or is in use by another job. The ALLOC_OFFLINE environment (also referred to here as the Offline Device environment) receives control prior to the issuance of any WTORs for the allocation, and can be used to prevent or automatically respond to WTORs and to extend or override any default policy for offline devices specified in the ALLOCxx member of SYS1.PARMLIB. Using the EASY/Exit rules for the ALLOC_OFFLINE environment, administrators can automatically bring required devices online, allow jobs to wait, or cancel jobs which are waiting for devices in accordance with a centrally controlled policy.

The ALLOC_OFFLINE environment can be used to automatically vary selected devices online in response to allocation requests or prevent the use of offline devices by selected jobs or datasets. Selected jobs can be instructed to wait for unavailable devices if they are in use or offline. Jobs waiting for unavailable devices may wait holding resources or without holding resources. If desired, a customized WTOR can be issued to prompt the operator to make devices available, or the installation default policy can be used.

The ALLOC_OFFLINE environment can be used to automatically react to situations in which the following messages would normally be issued by z/OS:

• IEF157E jobname, stepname, ddname NEEDS nn UNITS FOR...
• IEF238D jobname, REPLY 'device name', 'WAIT', OR 'CANCEL'
• IEF244I jobname, stepname, UNABLE TO ALLOCATE nn UNITS
• IEF433D jobname, WAIT REQUESTED, REPLY 'HOLD' OR 'NOHOLD'

The ALLOC_OFFLINE environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the ALLOC_OFFLINE environment, the IEF_ALLOC_OFFLN exit point must be enabled and the EXTIEFO exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTIEFO environment:

OPERCMD SETPROG EXIT,ADD,EN=IEF_ALLC_OFFLN,MOD=EXTIEFO,FIRST

In order to ensure that EXT’s use of the EXTIEFO exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EN=IEF_ALLC_OFFLN,MOD=EXTIEFO

When the Offline Device Environment is Entered

The ALLOC_OFFLINE environment is entered whenever a device, such as a tape unit or a DASD volume, is required by a job, but the available units that could satisfy the request are either offline or in use by other jobs. If the ALLOC_OFFLINE environment is not in use, MVS prompts the operator via a WTOR unless the policy in the ALLOCxx member of SYS1.PARMLIB specifies otherwise. Using the ALLOC_OFFLINE environment, you can establish policies for offline or in-use devices that are more flexible, understandable, and easier to maintain than the systemwide defaults. The EASY/Exit rules executed during the ALLOC_OFFLINE environment allow installations to tailor the use of offline or in-use devices to meet their specific needs.

Variables for the Offline Device Environment

The following variables are available for use by the EASY/Exit rules in the ALLOC_OFFLINE environment. The default for the &ALLOC_ACTION variable is 'DEFAULT', i.e., the installation's default policy specified in the ALLOC00 member of SYS1.PARMLIB is to be used if it exists.

If the &ALLOC_ACTION variable is set to ONLINE, i.e., devices are to be brought online in response to the allocation request, the first eligible device is brought online. This may cause the environment to be reentered for the next volume if more than one device is needed to satisfy the request. If the value for &ALLOC_ACTION is set to ONLINE, and no devices can be brought online, then the installation default action is taken.

Table 4-11. Variables for the Offline Device Environment

Examples for the Offline Device environment

Example 1 - Prevent Waits for Offline UNITNAME=CART Units on SYSB During Production Hours

This example examines the device type, unit name, system ID, and time of day to determine whether the system should be allowed to prompt the operator to vary a required tape device online. On this system, such devices may not be varied online during production hours (08:00 to 17:00).

A copy of this rule can be found in member EXTAOEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

        DEFRULE NOWAIT
        IF &SYSID = SYSB &DDTYPE = TAPE &UNITNAME = CART &CURTIME(1,2) GE '08' &CURTIME(1,2) LE '17' THEN SET &ALLOC_ACTION = CANCEL ISSUE WRITEMSG(CMSG)
        DEFMSG CMSG 'JOB &JOBNAME REQUEST FOR CART UNIT CANCELLED'
      

Example 2 - Specify Which Jobs May Bring Devices Online and Which Must Wait, or be Cancelled

The following rule demonstrates how the Offline Device environment can be used to establish policies for jobs. It shows:

• which jobs are to wait for devices
• which jobs may bring offline devices online (if available)
• which jobs should be cancelled if they must wait for a device

        DEFRULE OFFLRULE IF &JOBNAME = PROD* &JOBTYPE = JOB THEN DO
          IF &OK_ONLINE = YES THEN SET &ALLOC_ACTION = ONLINE ELSE DO
            IF &OK_WAIT = YES THEN SET &ALLOC_ACTION = WAIT ISSUE WRITEMSG(WAITMSG) ELSE SET &ALLOC_ACTION = CANCEL WRITEMSG(CANMSG) END
          END
        IF &JOBNAME = TEST* &JOBTYPE = JOB THEN DO
          IF &OK_WAIT = YES &SCRATCH_COUNT LE 2 THEN SET &ALLOC_ACTION = WAIT ISSUE WRITEMSG(WAITMSG) ELSE SET &ALLOC_ACTION = CANCEL ISSUE WRITEMSG(CANMSG)
        END
        DEFMSG WAITMSG 'PRODUCTION JOB &JOBNAME WAITING FOR DEVICES'
        DEFMSG CANMSG 'JOB &JOBNAME CANCELLED - DEVICES UNAVAILABLE'
      

ALLOC_SPEC_WAIT Environment

The ALLOC_SPEC_WAIT environment receives control whenever a job must wait for a specific, hardcoded device or volume (as opposed to one of a class or group of devices) to become available before it can continue.

Normally, the operating system will issue a WTOR prompting the operator to either cancel the job or allow the job to wait for the device to become available. Using the EASY/Exit rules in the ALLOC_SPEC_WAIT environment, administrators can automatically bring required devices online, allow jobs to wait, or cancel jobs which are waiting for devices in accordance with a centrally controlled policy.

The ALLOC_SPEC_WAIT environment can be used to manage the use of specifically-requested offline devices by selected jobs or datasets. Jobs can be instructed to wait for the devices, or the system can be allowed to issue the WTOR to prompt the operator. Jobs waiting for unavailable devices may wait holding resources or without holding resources. If desired, a customized WTOR can be issued to prompt the operator to make devices available, instead of or in addition to the WTOR issued by the system, or the installation default policy can be used to determine whether the job should continue to wait for the device.

The ALLOC_SPEC_WAIT environment can be used to automatically react to the following messages that are issued by the operating system when a job must wait for a specific volume or device to become available:

• IEF238D REPLY 'device name', 'WAIT', or 'CANCEL'
• IEF244I UNABLE TO ALLOCATE 'nn' UNITS(S). AT LEAST 'nn' ALLOCATED OR OFFLINE UNITS ARE NEEDED'
• IEF433D - WAIT REQUESTED -- REPLY HOLD OR NOHOLD
• IEF488I - MUST WAIT FOR A UNIT, OR VOLUME ON UNIT

The ALLOC_SPEC_WAIT environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the ALLOC_SPEC_WAIT environment, the IEF_SPEC_WAIT exit point must be enabled and the EXTIEFW exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTIEFW environment:

OPERCMD SETPROG EXIT,ADD,EN=IEF_SPEC_WAIT,MOD=EXTIEFW,FIRST

In order to ensure that EXT’s use of the EXTIEFW exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EN=IEF_SPEC_WAIT,MOD=EXTIEFW

Variables for the ALLOC_SPEC_WAIT Environment

The following variables are available for use by the EASY/Exit rules in the ALLOC_SPEC_WAIT environment. The default for the &ALLOC_ACTION variable is 'DEFAULT'.

Table 4-12. Variables for the ALLOC_SPEC_WAIT Environment

Examples for the ALLOC_SPEC_WAIT Environment

Example 1 - Allow Only Certain Production Jobs to Wait for Specific Volumes Without Operator Prompt

In this example, production jobs are allowed to wait while holding resources for volumes beginning with the characters ’PAY’. No WTOR is issued to the operator. Other jobs take the action specified in the ALLOCxx member of SYS1.PARMLIB, if any. A copy of this rule can be found in member EXTAWEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE PAYRULE IF &JOBNAME = P* &VOLSER = PAY* THEN SET &ALLOC_ACTION = WAITHOLD ELSE SET &ALLOC_ACTION = DEFAULT

Example 2 - Control the Use of Specific Devices

In this example, jobs which must wait for devices beginning with address 056x are allowed to wait without holding resources if the jobname begins with ’RMT’. For other jobs, the operator is prompted to decide whether the job should wait for the device or be cancelled. A copy of this rule can be found in member EXTAWEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE UNITRULE IF &JOBNAME EQ RMT* &UNITADDC = 056* THEN SET &ALLOC_ACTION = WAITNOH IF &UNITADDC = 056* THEN SET &ALLOC_ACTION = WTOR

ALLOC_VOL_ENQ Environment

The ALLOC_VOL_ENQ environment receives control when a job must wait for a volume or volumes to become available before ENQueueing on the volumes and continuing. By default, the system issues WTORs to prompt the operator to decide whether the job should wait for the ENQ or whether it should be cancelled. Using the rules defined in EASY/Exit for the ALLOC_VOL_ENQ environment, the administrator can decide, for each job, whether the job is to wait or to be cancelled, or whether the system is to be allowed to issue the WTOR, or whether the default action specified in the ALLOCxx member of SYS1.PARMLIB is to be used.

The ALLOC_VOL_ENQ environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the ALLOC_VOL_ENQ environment, the IEF_VOL_ENQ exit point must be enabled and the EXTIEFE exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTIEFE environment:

OPERCMD SETPROG EXIT,ADD,EN=IEF_VOLUME_ENQ,MOD=EXTIEFE,FIRST

In order to ensure that EXT’s use of the EXTIEFE exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EN=IEF_VOLUME_ENQ,MOD=EXTIEFE

Variables for the ALLOC_VOL_ENQ Environment

The following variables are available for use by the EASY/Exit rules in the ALLOC_VOL_ENQ environment. The default for the &ALLOC_ACTION variable is 'DEFAULT'.

Table 4-13. Variables for the ALLOC_VOL_ENQ Environment

Examples for the ALLOC_VOL_ENQ Environment

Example 1 - Cancel Non-Production Jobs Which Must Wait for Multiple Volumes

In this example, a job which is waiting to ENQ on more than 5 volumes is cancelled, unless it is a production job, in which case it is allowed to wait, and a notification is sent to the storage administrator. A copy of this rule can be found in member EXTAVEX1 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFRULE VOLRULE IF &ENV NE ALLOC_VOL_ENQ THEN CONTINUE AT NEXTRULE IF &JOBNAME NE P* &NVOL GT 5 THEN SET &ALLOC_ACTION = CANCEL IF &NVOL LT 5 OR &JOBNAME = P* THEN SET &ALLOC_ACTION = WAITVOLS ISSUE WRITEMSG(M1) DEFMSG M1 'JOB &JOBNAME WAITING FOR VOLUME &VOLSER' USER(STGADM)

ALLOC_VOL_MOUNT Environment

The ALLOC_VOL_MOUNT environment receives control whenever a volume must be mounted and the system must prompt the operator to mount the volume. Often, the prompt is due to dynamic allocation of a tape dataset used for backup, but any allocation which requires a device to be mounted can result in such a prompt. The ALLOC_VOL_MOUNT environment can be used to automatically take actions in response to the need for mounting of a volume. The WTOR can be suppressed and the job cancelled, or the operator can be prompted to mount the volume, based upon the selection criteria defined in the EASY/Exit rules. In addition, the EASY/Exit rules can take other actions, such as notifying TSO users or administrators of the need for a mount, and can create SMF records or write to the DIF Log file in order to keep a record of mount request for later analysis.

The ALLOC_VOL_MOUNT environment can be used to automatically react to the following messages that are issued by z/OS when a job must wait for a specific volume or device to become available:

• IEF233A MOUNT VOLUME 'volser'
• IEF233D MOUNT VOLUME 'volser' OR RESPOND TO IEF455D MESSAGE
• IEF455D MOUNT 'volser' ON DEVICE 'device' FOR 'jobname' OR REPLY 'NO'

The ALLOC_VOL_MOUNT environment receives control under the MVS Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the ALLOC_VOL_MOUNT environment, the IEF_VOLUME_MNT exit point must be enabled and the EXTIEFM exit must have been enabled via a SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the data set allocated to the PARMLIB DD in the DIF started task. The following statement should be included in EXTINIT in order to enable the EXTIEFM environment:

OPERCMD SETPROG EXIT,ADD,EN=IEF_VOLUME_MNT,MOD=EXTIEFM,FIRST

In order to ensure that EXT’s use of the EXTIEFM exit point is terminated when EASY/Exit is stopped, the following statement should be included in the EXTTERM member of the DIF PARMLIB DD data set:

OPERCMD SETPROG EXIT,DELETE,EN=IEF_VOLUME_MNT,MOD=EXTIEFM

Variables for the ALLOC_VOL_MOUNT Environment

The following variables are available for use by the EASY/Exit rules in the ALLOC_VOL_MOUNT environment. The default for the &ALLOC_ACTION variable is 'DEFAULT'.

Table 4-14. Variables for the ALLOC_VOL_MOUNT Environment

Examples for the ALLOC_VOL_MOUNT Environment

Example 1 - Prevent Mounts for TSO Users Except Storage Administrators

The following example prevents mounts for any TSO user whose userid does not begin with the characters 'ADM'. All other requests for mounting of a volume from a TSO userid are rejected.

DEFRULE TSORULE IF &JOBTYPE = TSU &JOBNAME NE ADM* THEN SET &ALLOC_ACTION = CANCEL ELSE SET &ALLOC_ACTION = WTOR

Example 2 - Allow PRODxx Volumes to be Mounted Only on SYSB

In this example, jobs that attempt to mount volumes beginning with the characters 'PROD' on any system other than SYSB are cancelled, and a message is sent to the storage administrator.

DEFRULE BRULE IF &VOLSER = PROD* &SYSID NE SYSB THEN SET &ALLOC_ACTION = CANCEL ISSUE WRITEMSG(WRNMSG)
DEFMSG WRNMSG 'JOB &JOBNAME INVALID MOUNT ON &SYSID'

SMSACS - The Automatic Class Selection Environments

The DFSMS component of z/OS provides control over datasets during their life cycle through the use of four SMS 'constructs' - the Data Class, Storage Class, Management Class, and Storage Group. The first three apply to individual datasets, and serve to provide a means of classifying, or grouping, datasets with similar characteristics. The fourth construct, Storage Group, applies to DASD or tape volumes, not datasets, and provides a means of grouping volumes together so that they can be managed in the same manner. Each of the constructs describes a dataset or volume in terms of certain characteristics:

• Data Class - describes the physical characteristics of a dataset, such as primary and secondary space required, dataset type (sequential, partitioned, VSAM, etc.), logical record length, and so on.
• Storage Class - describes the resource requirements for a dataset, such as the I/O response time required, whether the device assigned to the dataset must be capable of instantaneous copy, and so on.
• Management Class - describes the life cycle characteristics of the dataset - how many backup copies must be created, how long each copy should be retained, when the dataset expires, etc.
• Storage Group - describes a group of volumes having similar characteristics and which should be managed together.

At the time of its creation, each dataset may be assigned a data class, management class, storage class, and storage group by the DFSMS Automatic Class Selection (ACS) routines. The ACS routines use a REXX-like syntax to examine the characteristics of the dataset being allocated (typically dataset name, requested size, and so on). SET statements within the ACS routines then assign the desired SMS construct (Data Class, Storage Class, Management Class, or Storage Group) to the dataset. Once assigned, the construct names (except for storage group) are recorded in the dataset's catalog entry. They do not change unless the dataset is deleted and recreated, backed-up and restored, migrated and recalled, or renamed.

The ACS routine syntax is limited in scope. It can only examine certain variables associated with the dataset, and cannot perform processing such as table lookups or RACROUTEs, or call other programs or subsystems. The input variables to the ACS routines cannot be changed or overridden by the ACS routines themselves or by external processes. Without EASY/Exit, the only way to accomplish these tasks is to write assembler-language ACS exits. There are three ACS exits - IGDACSDC (data class), IGDACSMC (management class), IGDACSSC (storage class), and one exit which receives control prior to ACS execution - IGDACSXT, used primarily by tape management systems. There is no exit for the ACS storage group routine. The ACS exits receive control in key zero and are entered for the creation of every dataset in the system, both SMS and non-SMS-managed. They are critical routines which require an IPL when changed.

Few installations nowadays have the time, expertise, and nerve to depend upon in-house-written exits for such critical processing. However, the limited capabilities of the ACS routines sometimes do not provide enough functionality for installations that need to do more than simple assignment of data, management, and storage classes. This is where EASY/Exit comes in. EASY/Exit allows installations to use simple IF-THEN-ELSE rules to override the result of ACS routine execution, assigning classes according to dataset characteristics, programming, tables, or other resources that are not available to the ACS routines. EASY/Exit can also receive control prior to ACS routine execution to alter the read-only variables accessed by the ACS routines, eliminating the need for multiple logic paths through ACS and simplifying ACS code.

The EASY/Exit rules receive control in one of two environments. The PRE_SMSACS environment receives control prior to ACS execution. In this environment, the EASY/Exit rules can examine, test, and set any of the ACS read-only or read-write variables. These variables are then used when the ACS routines are executed. Most of the other EASY/Exit dataset allocation variables can also be examined and tested in this environment. The SMSACS environment receives control after ACS routine execution. Although any of the read-only or read-write variables can be examined, tested, or set in this environment, the only variables which it makes sense to change are the SMS read-write variables - data class, storage class, management class, and storage group.

Variables for the PRE_SMSACS and SMSACS Environments

The following variables are available for use in the PRE_SMSACS and SMSACS environments. Most of the other variables related to dataset allocation in the various tables in this manual (&JOBNAME, &DSNAME, &QUALn, &KEYLEN, etc.) can also be used; however, the ACS routines will use only those variables prefixed with SMSACS_.

Table 4-15. Variables for the PRE_SMSACS and SMSACS Environments

Examples for the Automatic Class Selection Environments

Example 1 - Assign Storage Class Based on RACF Attributes

DEFENV SMSACS MODE(ACTIVE) RULES(ALWAYS) DEFRULE SUPR
IF &DSNAME = PROD.** &SMSACS_XMODE = TSO &RSPEC = YES THEN SET &STORCLAS = SUPER
  

The ordinary DFSMS ACS routines do not have access to the dataset disposition coded in the JCL.

In this example, for any dataset allocated with an abnormal termination disposition of:

• CATLG
• KEEP

the management class is changed to MUSTBKUP to ensure that a backup is always available for these critical datasets.

A copy of this rule can be found in member EXTACEX2 in the SCC sample library: DTS.R71.SLyyddd.SAMPLIB.

DEFENV SMSACS MODE(ACTIVE) RULES(ALWAYS) DEFRULE BKUPRULE
IF &DISP3 = (CATLG, KEEP) THEN SET &MGMTCLAS = MUSTBKUP
  

IEFU83 – SMF Record Writer Environment

The IEFU83 environment receives control whenever an SMF record is about to be written to the SMF buffers. The environment is not entered if the SMF record type has been suppressed by options set in the SMFPRMxx member of SYS1.PARMLIB, or if the SMF record is being written via a branch entry to SMFEWTM. This environment can be used to suppress particular types or subtypes of SMF records, optionally filtering by variables such as job name, job type, system id, or dataset name. You might, for example, want to limit SMF record collection for some record types to particular times of the day or particular jobs.

The IEFU83 environment runs under the Dynamic Exits facility. In order for the EASY/Exit rules to receive control in the IEFU83 environment, the IEFU83 exit point must be active and the EXTU83 exit name must have been enabled via SETPROG EXIT operator command. This command may be automatically issued at the time EASY/Exit is started by including it in the EXTINIT member of the dataset allocated to the PARMLIB DD in the DIF started task. The following statement(s) should be included in EXTINIT in order to enable the IEFU83 environment for both started tasks and batch jobs/TSO sessions:

OPERCMD SETPROG EXIT,ADD,EN=SYS.IEFU83,MOD=EXTU83,FIRST
OPERCMD SETPROG EXIT,ADD,EN=SYSSTC.IEFU83,MOD=EXTU83,FIRST

Termination statements to stop the use of the IEFU83 environment should also be placed in the EXTTERM member of the DIF PARMLIB, e.g.:

OPERCMD SETPROG EXIT,DELETE,EN=SYS.IEFU83,MOD=EXTU83
OPERCMD SETPROG EXIT,DELETE,EN=SYSSTC.IEFU83,MOD=EXTU83

Variables for the IEFU83 Environment

The following variables are available for use in the IEFU83 environment. Also, if a type 14/15 SMF record (OPEN/CLOSE) is being written, other variables such as &DSNAME, &PSPACE, &SSPACE, &VOLSER, and so on, may be available.

Table 4-16. Variables for the IEFU83 Environment

Examples for the IEFU83 Environment

Example 1 – Suppress Dynamic DD Records for TSO Users

TSO users may perform a large number of dynamic allocations, resulting in many Dynamic DD (type 40) records, since a record is created for each unallocation, concatenation, or deconcatenation request. This example suppresses the creation of SMF type 40 records for all users except those whose userids begin with 'TSEAST'.

        DEFENV IEFU83 MODE(ACTIVE) DEFRULE SUPP40
        IF &ENV = IEFU83 /* IF SMF WRITER */ &ENVS = TYPE40 /* DYNAMIC DD RECORD */ &JOBNAME NE TSEAST* /* PROPER TSO ID */ THEN SET &SMFSUPP = YES /* THEN SUPPRESS SMF */
      

Example 2 – Suppress or Allow Some Record Types and Subtypes for Started Tasks

In this example, SMF record type 120 (Websphere Application Server) records are allowed for all started tasks except those whose names begin with:

• MQ*
• M1*
• MH*

        DEFENV IEFU83 MODE(ACTIVE) DEFRULE STCRULE
        IF &ENV = IEFU83 /* IF SMF WRITER */ &JOBTYPE = STC /* STARTED TASK */ &SMF_RECTYPE = 120 /* WEBSPHERE RECORD */ THEN DO
        IF &SMF_SUBTYPE = 1 THEN SET &SMFSUPP = YES
        IF &JOBNAME = (MQ*, M1*, MH*) THEN SET &SMFSUPP = YES END
      

IEFU29 and IEFU29L – SMF Switch Environments

The IEFU29 and IEFU29L environments receive control whenever an SMF dataset is full and the system switches to the next available SMF dataset, or when a SWITCH SMF command is issued.

The IEFU29 exit is entered when SMF is using SYS1.MANx datasets (dataset mode). The IEFU29L exit is entered when SMF is using logstreams (logstream mode).

The IEFU29 and IEFU29L exits can be used to issue WTOs or WTORs to prompt operators to run jobs or take other actions when an SMF dataset is full (IEFU29) or when a switch occurs (IEFU29 or IEFU29L).

The exits can also be used to automatically perform actions such as:

• submit jobs or started tasks to dump the contents of the SMF datasets
• clear the SMF datasets
• off-load the SMF logstreams
• other automated actions

The IEFU29 and IEFU29L environments receive control under the Dynamic Exits facility. In order for the EASY/Exit rules to receive control in these environments, the exit points must be active and the exit(s) must have been enabled by a SETPROG EXIT operator command.

This command may be automatically issued at the time EASY/Exit starts by including it in the EXTINIT member of the dataset specified by the PARMLIB DD in the DIF started task. The following statements can be included in EXTINIT to automatically enable the IEFU29 or IEFU29L environments:

OPERCMD SETPROG EXIT,ADD,EXITNAME=SYSSTC.IEFU29,MOD=EXTU29,FIRST
OPERCMD SETPROG EXIT,ADD,EXITNAME=SYSSTC.IEFU29L,MOD=EXTU29L,FIRST

To ensure that EXT’s use of the IEFU29 and IEFU29L exit points is terminated when EASY/Exit stops, include the following statements in the EXTTERM member of the DIF PARMLIB DD dataset:

OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYSSTC.IEFU29,MOD=EXTU29
OPERCMD SETPROG EXIT,DELETE,EXITNAME=SYSSTC.IEFU29L,MOD=EXTU29L

Variables for the IEFU29 and IEFU29L Environments

The following variables may be used in the IEFU29 and IEFU29L environments. In addition, most of the other relevant EASY/Exit variables (date, time, environment name, and so on) may also be used.

Table 4-17. Variables for the IEFU29 and IEFU29L Environments

Examples for the IEFU29 and IEFU29L Environments

Example 1 – Automatically Start SMF Dumping

The example below shows the use of the IEFU29 environment to automatically run a job which dumps and clears the SMF dataset when IEFU29 receives control, either because the dataset is full or a SWITCH SMF command was issued. The sample rule set is shown below, followed by the started task which is initiated by the EASY/Exit rules. Any SMF dataset-full or switching messages are suppressed and EASY/Exit messages are issued instead. By default, the EASY/Exit messages are issued to the console.

DEFENV IEFU29 MODE(ACTIVE) 
DEFRULE DUMPSMF
SET &EXIT_RC = 4 
  /* SUPPRESS IEE362A,362I,391A,392I */
ISSUE OPERCMD(C1) 
  /* START STC TO PROCESS SMF FILE */
ISSUE WRITEMSG(M1) 
  /* INDICATE WE STARTED THE DUMP JOB */
DEFMSG M1 'EASY/EXIT STARTED SMF DUMP JOB'
DEFCMD C1 'S SMFDUMP,MAN='&DSNAME'' CN(0)

Sample SMFDUMP Procedure

//SMFDUMP PROC MAN='SYS1.MAN1'
//*
//* CLEAR SMF DATASET
//*
//DUMP1 EXEC PGM=IFASMFDP,REGION=1M
//INDD1 DD DSN=&MAN,DISP=SHR
//DUMPOUT DD DUMMY
//SYSPRINT DD SYSOUT=X
//SYSIN DD DSN=ADCD.&SYSVER..PARMLIB(DUMPMAN),DISP=SHR