IEFUJV — Job Validation Exit

Topics for This Exit Appear as Follows:

Defining the Exit in SMFPRMxx
Controlling the Exit Routine Through the Dynamic Exits Facility
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter Descriptions
Return Specifications
- Registers at Exit
Coded Example of the Exit Routine

IEFUJV receives control at three different points in the converter/interpreter (C/I) processing of an input stream. They are:

Preconversion — before each job control statement (or cataloged procedure) in the input stream is converted.
Postconversion — after all job control statements for a job have been converted.
Postinterpretation — after all job control statements for a job have been interpreted.

For z/OS UNIX System Services, this exit is called only once when each BPXAS initiator is started. It is not called for forked/spawned requests and can not be used to validate them.

A return code from this exit indicates whether job processing is to continue.

At the preconversion point, you might use IEFUJV to:

Validate any accounting fields included in the JOB and EXEC statements (except symbolic parameters) by comparing them to a standard list.
Validate or assign the REGION request.
Validate or assign job TIME and job step TIME parameters.
Control output stream data by using the OUTLIM or SPACE parameters.
Check for authorization to use restricted data sets.
Create user-written records.
Assign the user identification to be included in both the SMF job/step termination record and the SMF job purge record.
Limit the size of temporary data sets handled by VIO.
Require checkpoint/restart for jobs requesting a large amount of processor time.
Enforce installation standards on usage of the ADDRSPC parameter.
Override certain JES initialization parameters (such as designation of where SWA blocks are to be obtained) that are passed to converter routines.

At the postconversion point, you might use IEFUJV to:

Create user-written records.
Assign the user identification to be included in both the SMF job/step termination record and the SMF job purge record.
Override certain JES initialization parameters (such as designation of where SWA blocks are to be obtained) that are passed to converter routines.

At the postinterpretation point, you might use IEFUJV to:

Create user-written records.
Assign the user identification to be included in both the SMF job/step termination record and the SMF job purge record.

Defining the Exit in SMFPRMxx

In the SMF parmlib member (SMFPRMxx), specify IEFUJV on the EXITS option of either the SYS or SUBSYS parameters, depending on the scope of work (system-wide or subsystem-wide) the exit is to affect.

If you use the SUBSYS option, the system invokes the IEFUJV routine only for work running under the subsystems you specify on SUBSYS. If you use the SYS option, the system invokes the IEFUJV routine for work running under any SMF-defined subsystem, such as JES2, JES3, STC, ASCH, OMVS, or TSO.

For more information about coding the EXITS option, see the description of SMFPRMxx in z/OS MVS Initialization and Tuning Reference.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM® has defined the IEFUJV installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFUJV or SYSyyy.IEFUJV. See the description of the SMFPRMxx parmlib member in z/OS MVS Initialization and Tuning Reference for an explanation of the naming conventions for SMF exit routines. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and its exit routines. However, you cannot use the JOBNAME parameter of the SETPROG EXIT command to restrict exit IEFUJV processing to a particular job.

To define IEFUJV to the dynamic exits facility, you must specify the exit in both PROGxx and SMFPRMxx. The system does not call the exit if it is defined in PROGxx only. If you do not plan to use the dynamic exits facility for this exit, you need only define IEFUJV in SMFPRMxx.

If you do not associate any exit routines with exit IEFUJV in PROGxx, the system defaults to using the exit routine name that matches the exit name (IEFUJV).

If you associate exit routines with this exit in PROGxx, the system does not use the default exit routine. If you need the default exit routine, you should explicitly add it to PROGxx.

You can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro or the ABENDNUM parameter of the SETPROG EXIT operator command to limit the number of times the exit routine abnormally ends before it becomes inactive. An abend is counted when both of the following conditions exist:

The exit routine does not provide recovery, or the exit routine does provide recovery but percolates the error
The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system does not disable the exit routine.

Exit Routine Environment

IEFUJV receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0 or 1 (based on the caller's key). When the entry code (contained in word 3 of the input parameter list) is 32, the key is 0.
In AMODE 31.

In a JES2 environment, conversion might take place on one processor and interpretation of the same job on another. Therefore, the IEFUJV exits could receive control on different processors for the same job. In that case, timing comparisons of the job flow would not be valid.

For an interpreter call in a JES2 environment, a security environment must be established if the exit is to obtain access to any protected resources. For example, if a command is to be issued with RACF® OPERCMDS active, pass a user security token (UTOKEN) on the MGCRE macro to establish authority for the user requesting access to the command. See z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU for information about the MGCRE macro.

Exit Recovery

IBM strongly recommends that you set up an ESTAEX recovery routine to handle errors that might occur during the execution of IEFUJV.

An ESTAE-type recovery routine is set up by the module that calls IEFUJV; the recovery routine, if it gets control, will allow the job to continue processing if the exit routine abnormally ends.

Whether or not the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.

Exit Routine Processing

There are two data formats related to JCL statements. The first data format is the JCL "card image." A JCL card image is an 80-character EBCDIC string that represents either an entire JCL statement or a portion of a JCL statement that is continued. The second data format is the C/I text string representation of the JCL statement. The C/I text format consists of an established pattern of hexadecimal codes, or keys, assigned to each parameter or subparameter. See MVS Converter / Interpreter Text Processing for more details about C/I text strings and the appropriate processing exit points.

JES provides several exit points related to JCL card image processing. See z/OS JES2 Installation Exits and z/OS JES3 Customization for additional information about this processing.

Note that IEFUJV receives control following the JES exits related to card image processing. Your installation is responsible for coordinating the processing between IEFUJV and the JES exits.

Note further that if you use the IEFUJV exit to change certain parameters on the JOB statement, the result might be that the internal representation of the JCL card image would reflect the changes while the job itself continues to be processed according to the original JOB statement. For example, if you change the CLASS parameter as part of the exit routine, the job will still run in its original specified class. This applies to both the JES2 and JES3 environments. These other JOB statement parameters have the same restriction: GROUP, MSGCLASS, NOTIFY, PASSWORD, PRTY, SECLABEL, TYPRUN, and USER.

Preconversion processing: IEFUJV receives control at the preconversion processing exit point before each JCL statement card image is converted. The input parameter list provides an indication of the type of JCL statement being processed.

The exit will be invoked multiple times for a continued JCL statement (once per card image). The JCL statement type indicator is the same for each card image of the continued JCL statement.

When modifying a JCL statement, the updated JCL statement must adhere to the JCL syntax as defined in z/OS MVS JCL Reference. The following updates are not permitted at the preconversion processing point:

Do not include additional JCL statements
Do not add continuation card images.
Do not change the operation field on a JCL statement.
Do not change the identifier field on a JCL statement.

If a procedure is used, it is expanded before the IEFUJV exit routine receives control. For example, for a cataloged procedure, the sequence of statements are:

//UJV     JOB
//STEP1   EXEC  PROC=MYPROC
XXMYPROC  PROC
XXSTEP2   EXEC  PGM=...

followed by the other statements of the procedure. Note that the resolved values for symbolic parameters are not passed to the IEFUJV exit routine.

Using IEFUJV for Job Accounting: You might want to use an IEFUJV exit routine for job accounting. If so, consider the following:

For APPC/MVS transaction programs (TPs), IBM recommends that you use IEFUAV instead of IEFUJV to validate accounting information. IEFUAV is the only exit that allows you to validate the accounting information of a TP user at execution time. Even though IEFUJV is invoked when a TP profile is created (specifically, when the profile's JCL statements are processed by the converter/interpreter), the TP user is not known at that time. Therefore, when you need to validate the TP user's accounting information (such as the job name or account number), use the IEFUAV exit routine. See IEFUAV — User Account Validation Exit for more information.
Depending upon the processing to be performed, it may be more efficient to check JOB and EXEC statement accounting fields in the IEFUJI exit routine and the first IEFUSI exit routine, respectively. The accounting fields are passed as parameters to IEFUJI and IEFUSI, making a statement scan routine unnecessary. Either of these exit routines can assign user identification, and the IEFACTRT exit routine can write messages to JOBLOG.
When running JES2, you can use Exit 03, the job statement accounting field scan exit (HASPRSCN), as well as the IEFUJV exit. Because Exit 03 receives control before the IEFUJV exit, do not use the IEFUJV exit to change the following fields of the JOB statement: CLASS, MSGCLASS, NOTIFY, PRTY, PASSWORD and TYPRUN.
If an installation checks JOB statement accounting in the IEFUJV exit for all tasks, the IEFUJV exit should not be taken, unless modified, for started tasks. Started tasks do not have any JOB statement accounting and might be cancelled by the installation exit.

For jobs cancelled by IEFUJV from the converter, only SMF record types 6 and 26 are generated.

Preconversion input limitations: The following information is not made available to this exit routine:

Resolved values for JCL symbolic parameters
JCL COMMAND, Command, and Comment statements
JES2 control statements
JES3 control statements

Postconversion processing: IEFUJV receives control at the postconversion processing point once per job to indicate that the conversion processing for the job has completed.

Postinterpretation processing: IEFUJV receives control at the postinterpretation processing point once per job to indicate that the interpretation processing for the job has completed.

When running JES3, a JES3 user can use JES3 installation exits, in addition to the IEFUJV exit, to write programs to examine and change the results of interpreter processing and allow the job to proceed or to flush the job from the system. For more information about the JES3 installation exits, see z/OS JES3 Customization.

Programming Considerations

When issuing a WTOR macro, specify LONG=YES on the WAIT macro. Do not use a WTO with a routing code of 11 to send a message to the JESYSMSG data set for started tasks or TSO users.

IEFUJV must be reenterable and refreshable because PLPA pages are stolen. That is, they can be paged in but not paged out, and subsequent page-ins overlay any code changes.

To use installation-defined data sets with this exit routine, you must define them with a DD statement in the job entry subsystem cataloged procedure. When running JES2, you must also define the data sets with a DD statement in the initiator cataloged procedure.

IEFUJV cannot access ISAM data sets.

Exit IEFUJV is called multiple times for a job. When you change the exit routine after it has been called at least once, but before all the calls for the job have been made, the job might be rejected because of incorrect JCL. When you rerun the job it will run successfully.

Entry Specifications

The converter/interpreter passes to IEFUJV a list of parameter addresses (in register 1).

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of the parameter list
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of IEFUJV

Parameter Descriptions: Register one points to the following list of addresses:

Word 1

The address of the common exit parameter area. (See Table 1.)

Word 2

When the value pointed to by Word 3 is neither 16 nor 32, Word 2 is the address of the JCL statement card image.

This word is 0 when the value pointed to by word 3 is 16 or 32.

Word 3

The address of a 1-byte area that indicates the specific exit processing point. For preconversion, it also indicates the type of JCL statement being passed to the exit. See Exit Routine Processing for more information. The indicator is one of the following binary values:

Value: Meaning
0: indicates the preconversion exit point; null statement card image.
1: indicates the preconversion exit point; JOB statement card image.
2: indicates the preconversion exit point; EXEC statement card image.
4: indicates the preconversion exit point; DD statement card image.
8: indicates the preconversion exit point; PROC statement card image from cataloged procedure.
16: indicates the postconversion exit point; all JCL has been converted.
32: indicates the postinterpretation exit point; all JCL has been interpreted.
64: indicates the preconversion exit point; JCL definition table defined (JDT) statement card image.
128: indicates the preconversion exit point; extended JCL statement type card image. Extended JCL statement type refers to any new JCL statements defined as of MVS/ESA Version 4. (For possible exceptions see Exit Routine Processing.)

Word 4

This word is 0 when the value pointed to by word 3 is 32.

When the value pointed to by word 3 is not 32, word 4 is the address of the JES initialization parameters that are passed to the converter routine. The address points to the first converter parameter field, which is a 1-byte bit-map defined as follows for bits that are set on:

.......1: Programmer name required.
......1.: Account number required.
.....1..: Indicates that a job is enabled to run with the SWA located in virtual storage above 16 megabytes.

Note: IEFUJV may turn any of these bits on or off at any time except when the value pointed to by word 3 is 32. If a bit is turned on or off more than one time, the final setting of the bit is the one which will be honored.

Note: The account number must not be required in the exit for started task JOB statements because there is no way to put an account number on a started task JOB statement. An accounting number can be required on an EXEC statement in SYS1.PROCLIB.

Word 5

The address of a 4-character area that contains the name of the subsystem for the job being processed. Examples:

ASCH, JES2, JES3 or OMVS - indicates the name of the subsystem that selected the job (For OMVS, see Guideline below.)
STC - indicates a started task
TSO - indicates a time sharing option task
The jobname - used if it is four or fewer characters and none of the others apply

Guideline: The first time after an IPL that a z/OS UNIX fork or spawn occurs, z/OS UNIX creates JCL for a job named BPXYOEJS using a default JOB statement and passes that JCL to the MVS Converter and Interpreter (C/I). For this one job, C/I calls IEFUJV under SUBSYS = OMVS. Job BPXYOEJS does not actually execute. Instead the Interpreter creates SWA blocks for this job and passes them back to z/OS UNIX, which stores them for later use. These SWA blocks will be used by all subsequent forked or spawned address spaces. This means that whatever version of IEFUJV is active when the first fork or spawn occurs will be the only IEFUJV entered for forked or spawned address spaces, even if a new version of IEFUJV is later dynamically activated (through the SETPROG EXIT command). The BPXAS initiators in which the forked or spawned processes run, do go through IEFUJV, but with SUBSYS = STC exit.

Word 6

The address of a 4-byte area that contains the environment indicator associated with the subsystem specified in word 5.

The value that applies to all subsystems is 0.

Value: Meaning
0: Default - “no meaning”

The values that apply to ASCH (APPC Scheduler) are 1, 2, and 3.

Value: Meaning
1: APPC Scheduler Utility TP Add call
2: APPC Scheduler Utility TP Retrieve call
3: APPC Scheduler Utility TP Reconvert call

Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.

Figure 1. IEFUJV Input Parameter Structure

Return Specifications

A return code from IEFUJV indicates whether job processing will continue or be terminated.

If you associate multiple exit routines with IEFUJV, you can specify how the return information is to be handled using the ATTRIB KEEPRC function of the SETPROG EXIT command, the EXIT statement of PROGxx, or CSVDYNEX services. If multiple exit routines match the ATTRIB KEEPRC criteria, the system returns information from the exit routine that finished first.

If you do not specify the ATTRIB KEEPRC function, the system returns the information from the exit routine whose return value was the greatest. If multiple exit routines return with the same highest value, the return information from the exit routine that finished first will be returned.

If you associate multiple exit routines with exit IEFUJV, and any of those exit routines return with a value of 4, job processing will be terminated.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0-14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
Value of 0: Job processing is to continue.
Value of 4: Job processing is to be cancelled.

Coded Example of the Exit Routine

Sample IEFUJV exit routines are provided in SYS1.SAMPLIB in members SMFEXITS and IEEUJV. The routine in SMFEXITS checks the validity of a continued JOB statement and of values supplied for the REGION, PRTY, TIME, and accounting parameters in the JOB statement. The routine uses characters from the account number to index a table that contains allowable values for these parameters. If any value is not valid, the sample IEFUJV routine terminates the job.

The sample in IEEUJV changes the SYSOUT class to SYSOUT=* for jobs in specified JOB classes and for specified SYSOUT classes. Assembled into the exit routine is a list of eligible job classes and a list of eligible SYSOUT classes. Thus, if a job enters the system in one of the specified job classes and contains a DD statement specifying SYSOUT=class, where class is one of the specified SYSOUT classes, then the SYSOUT class will be changed to '*'.