Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
IEFUJV — Job Validation Exit z/OS MVS Installation Exits SA23-1381-00 |
|
Topics for This Exit Appear as Follows:
IEFUJV receives control at three different points in the converter/interpreter (C/I) processing of an input stream. They are:
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:
At the postconversion point, you might
use IEFUJV to:
At the postinterpretation point, you might
use IEFUJV to:
Defining the Exit in SMFPRMxxIn 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 FacilityIBM® 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:
Exit Routine EnvironmentIEFUJV
receives control in the following environment:
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 RecoveryIBM 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 ProcessingThere 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:
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:
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 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:
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 ConsiderationsWhen 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 SpecificationsThe 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.
Parameter Descriptions: Register one points
to the following list of addresses:
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 SpecificationsA 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.
Coded Example of the Exit RoutineSample 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 '*'. |
Copyright IBM Corporation 1990, 2014
|