The IEFDB401 installation exit from the allocation control routine allows an exit routine to
either validate or alter any dynamic allocation request. Control passes to IEFDB401 for all system
and user dynamic allocation requests. See z/OS MVS Programming: Authorized Assembler Services Guide for more information about dynamic allocation.
The user validation routine tests and can modify the dynamic allocation
request, and it indicates through a return code whether or not processing
of the request is to continue. You can use IEFDB401 to:
Control the amount of direct access space requested.
Check for authorization to use specified units.
Check for authorization to use certain data sets.
Check for authorization to hold certain resources for reuse.
Controlling the Exit Routine Through
the Dynamic Exits Facility
IBM® has
defined the IEFDB401 installation exit to the dynamic exits facility.
You can refer to the exit by the name IEFDB401. 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.
If
you do not associate any exit routines with exit IEFDB401 in PROGxx,
the system defaults to using the exit routine name that matches the
exit name (IEFDB401).
If you associate exit routines with IEFDB401
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
IEFDB401
receives control in the following environment:
In supervisor state and under the scheduler's PSW key (key 1).
In AMODE 31 and RMODE ANY.
Exit Recovery
An ESTAE routine
that is established in the calling module provides recovery from errors
encountered in IEFDB401.
Whether or not the exit routine continues
to be invoked depends on the abend processing of the dynamic exits
facility.
Exit Routine Processing
The
dynamic allocation facility passes control to IEFDB401 before doing
any processing on behalf of a dynamic allocation request. It is entered
for all requests, foreground and background. IEFDB401 can test and
modify the dynamic allocation input, and indicate with a return code
whether processing is to continue or if the request is to be terminated. The exit receives control after System Allocation has
completed validation of the passed parameters.
The IBM-supplied
version of IEFDB401 that your routine can replace does no testing
and allows all requests to continue processing.
Programming Considerations
When IEFDB401 receives control, a parameter list is passed via
register 1. Among the parameters are the dynamic allocation request
block and a work area for the addition or modification of text units.
This work area immediately follows the text unit pointer list and
is usually in nonfetch-protected scheduler key storage (subpool 230).
It is in fetch-protected scheduler key storage (subpool 229) only
when the request has a password specification text unit. If text unit
pointers are to be added to the pointer list, they must be added to
the end of the list in the work area. The end-of-list indicator also
must be adjusted. To delete a text unit pointer, zero the text unit
pointer or the text unit key.
Code the exit routine so that it is reentrant.
Entry Specifications
IEFDB401
receives control from dynamic allocation.
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 IEFDB401
Parameter List Contents: Register 1 points to the following parameters:
Pointer to the address of a work area that the exit routine can use. This area is contiguous
with the text unit pointer list so that you can use it to extend the list and provide additional
text units.
Word 3
Address of a fullword that contains the length of the work area (500 bytes).
Word 4
Address of the 8-character job name.
Word 5
Address of the 20-character programmer name.
Word 6
Address of an area that contains accounting information from the JOB statement. The first byte
of this area contains the number of accounting fields; the accounting fields follow this byte. Each
entry for an accounting field contains the length of the field (one byte, hexadecimal), followed by
the field itself. The entry for a null field contains a length of zero.
Word 7
Address of the 8-character step name.
Word 8
Address of the 8-character program name.
Word 9
Address of an area containing accounting information from the EXEC statement. The first byte of
this area contains the number of accounting fields (zero for no fields); the accounting fields
follow this byte. Each entry for an accounting field contains the length of the field (one byte,
hexadecimal), followed by the field itself. The entry for a null field contains a length of
zero.
Figure 1. IEFDB401 Input Parameter Structure
Return Specifications
A return
code from IEFDB401 indicates whether processing of the dynamic allocation
request should continue.
If you associate multiple exit routines
with IEFDB401, 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.
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
0
Dynamic allocation request processing continues.
nonzero
Dynamic allocation request processing is terminated.
Coded Example of the Exit Routine
This
sample exit routine first checks for an allocation verb code. If one
is present, the routine loops through the text unit pointers to find
the end of the text unit list. A return code is set to cancel the
request if the unit description key is set to ‘3380’.
TITLE 'DYNAMIC ALLOCATION INSTALLATION EXIT EXAMPLE'
IEFDB401 AMODE 31
IEFDB401 RMODE ANY
***************************************************************
* *
* $MOD(IEFDB401) *
* *
* DESCRIPTIVE NAME - DYNAMIC ALLOCATION *
* INSTALLATION EXIT EXAMPLE *
* *
* COPYRIGHT = 5665-291 *
* THIS MODULE IS "RESTRICTED MATERIALS OF IBM" *
* (C) COPYRIGHT IBM CORP. 1987 *
* LICENSED MATERIALS - PROPERTY OF IBM. *
* REFER TO COPYRIGHT INSTRUCTIONS *
* FORM NUMBER G120-2083 *
* *
* STATUS = HBB3310 *
* *
* FUNCTION - THE DYNAMIC ALLOCATION FACILITY OF THE CONTROL *
* PROGRAM EXITS TO THIS 'EXIT ROUTINE' BEFORE *
* DOING ANY PROCESSING ON BEHALF OF A DYNAMIC *
* ALLOCATION REQUEST. IT IS ENTERED FOR ALL *
* REQUESTS, FOREGROUND AND BACKGROUND. THIS *
* ROUTINE MAY TEST AND MODIFY THE DYNAMIC *
* ALLOCATION INPUT, AND INDICATE THROUGH A *
* RETURN CODE WHETHER PROCESSING IS TO CONTINUE *
* OR IF THE REQUEST IS TO BE TERMINATED. *
* *
* THE ROUTINE MAY DELETE A TEXT UNIT BY ZEROING *
* THE TEXT UNIT POINTER OR TEXT UNIT KEY. *
* A WORK AREA IS PROVIDED TO FACILITATE THE *
* ADDITION OR MODIFICATION OF TEXT UNITS AND *
* IMMEDIATELY FOLLOWS THE TEXT UNIT POINTER *
* LIST. POINTERS TO ITS ADDRESS AND LENGTH *
* ARE PASSED AS PARAMETERS. THIS AREA IS IN *
* FETCH-PROTECTED SCHEDULER-KEY CORE. IF TEXT *
* UNIT POINTERS ARE TO BE ADDED TO THE POINTER *
* LIST, THEY MUST BE ADDED TO THE END OF THE *
* LIST, (IN THE WORK AREA)AND *
* THE END-OF-LIST INDICATOR MUST BE ADJUSTED. *
* *
* DEPENDENCIES - THIS MODULE RECEIVES CONTROL IN SCHEDULER *
* KEY FROM A PREVIOUS MODULE OF DYNAMIC *
* ALLOCATION. *
* *
* MODULE TYPE - PROCEDURE *
* *
* PROCESSOR - ASSEMBLER H *
* *
* ATTRIBUTES - REFRESHABLE, SCHEDULER KEY, EXTENDED PLPA, *
* SUPERVISOR STATE, AMODE(31), RMODE(ANY) *
* *
* ENTRY POINT - IEFDB401 *
* *
* LINKAGE - STANDARD ENTRY AND EXIT LINKAGE *
* *
* INPUT - REGISTERS - REG0 - IRRELEVANT *
* REG1 - PARAMETER LIST ADDRESS *
* REG2-12 - IRRELEVANT *
* REG13 - SAVE AREA ADDRESS *
* REG14 - RETURN ADDRESS *
* REG15 - ENTRY ADDRESS *
* *
* - DATA - UPON ENTRY REG1 POINTS TO A LIST OF *
* ADDRESSES FOR THE FOLLOWING ITEMS: *
* *
* 1. THE DYNAMIC ALLOCATION REQUEST BLOCK *
* IN SCHEDULER-KEY, FETCH-PROTECTED *
* CORE. *
* 2. A POINTER TO THE WORK AREA THAT *
* FOLLOWS THE TEXT UNIT POINTER LIST. *
* 3. LENGTH OF THE WORK AREA *
* 4. 8-CHARACTER JOB NAME *
* 5. 20-BYTE PROGRAMMER NAME *
* 6. JOB ACCOUNTING INFORMATION - IN THE *
* STANDARD FORMAT PASSED TO SMF EXITS. *
* 7. 8-CHARACTER STEP NAME *
* 8. 8-CHARACTER PROGRAM NAME *
* 9. STEP ACCOUNTING INFORMATION - IN THE *
* STANDARD FORMAT PASSED TO SMF EXITS. *
* *
* EXITS - REGISTERS - REG0-13 - RESTORED *
* REG14 - RETURN ADDRESS *
* REG15 - RETURN CODE *
* *
* - RETURN CODE - 0 - CONTINUE SVC 99 PROCESSING *
* non-0 - TERMINATE SVC 99 PROCESSING *
* *
* - DATA - POSSIBLE CHANGES IN THE DYNAMIC ALLOCATION *
* REQUEST BLOCK, THE TEXT POINTERS, OR THE *
* TEXT UNITS. *
* *
***************************************************************
TITLE 'DYNAMIC ALLOCATION (SVC 99) PARM LIST'
IEFZB4D0
TITLE 'DYNAMIC ALLOCATION KEY TABLE'
IEFZB4D2
TITLE 'DYNAMIC ALLOCATION INSTALLATION EXIT EXAMPLE'
IEFDB401 CSECT
SPACE 1
***************************************************************
* STANDARD REGISTER EQUATES *
***************************************************************
SPACE 1
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
SPACE 1
***************************************************************
* STANDARD INPUT LINKAGE *
***************************************************************
SPACE 1
STM R14,R12,12(R13) SAVE CALLER'S REGISTERS
BALR R12,R0 ESTABLISH ADDRESSABILITY
USING *,R12 TO CSECT
EJECT
***************************************************************
* INITIALIZE RETURN CODE, GET POINTER TO THE PARAMETER LIST *
* AND ESTABLISH ADDRESSABILITY TO THE SVC 99 REQUEST BLOCK. *
***************************************************************
SPACE 1
XR R15,R15 INITIALIZE RETURN CODE
L R9,0(R1) ESTABLISH ADDRESSABILITY TO
USING S99RB,R9 THE SVC 99 REQUEST BLOCK
SPACE 1
***************************************************************
* CHECK FOR AN 'ALLOCATION' VERB CODE, (X'01'), AND IF NOT *
* BRANCH TO CONTINUE THE REQUEST UNCHANGED. ELSE ESTABLISH *
* ADDRESSABILITY TO THE TEXT UNIT POINTER LIST AND CHECK *
* FOR A VALID TEXT UNIT POINTER,non-0,AND THEN CHECK FOR THE *
* END OF THE TEXT UNIT LIST. IF NEITHER OF THE CHECKS PASS, *
* THEN ADJUST THE TEXT UNIT POINTER AND LOOP UNTIL ONE DOES. *
***************************************************************
SPACE 1
CLI S99VERB,S99VRBAL IS THIS AN ALLOCATION VERB CODE?
BNE DB401D BIN TO CONTINUE REQUEST UNCHANGED
L R8,S99TXTPP ESTABLISH ADDRESSABILITY TO
USING S99TUPL,R8 THE TEXT UNIT POINTER LIST
DB401A DS 0H
CLC S99TUPTR,BLANKPTR IS THIS A BLANK/¬LAST TEXT UNIT PTR?
BE DB401B BIY TO CHECK THE NEXT TEXT UNIT PTR
CLC S99TUPTR,LSTBLKPT IS THIS A BLANK/LAST TEXT UNIT PTR?
BE DB401D BIY TO EXIT THE EXIT ROUTINE
B DB401C GO CHECK THE TEXT UNIT CONTENTS
DB401B DS 0H
LA R8,4(,R8) POINT TO NEXT TEXT UNIT POINTER
B DB401A GO CHECK THE NEXT TEXT UNIT POINTER
SPACE 1
***************************************************************
* ESTABLISH ADDRESSABILITY TO THE SVC 99 TEXT UNIT AND CHECK *
* FOR A 'UNIT DESCRIPTION SPECIFICATION' KEY, (X'0015'), AND *
* IF MATCHED CHECK FOR A '3380' PARAMETER. IT THIS MATCHES, *
* SET THE RETURN CODE TO CANCEL THE REQUEST, (X'04'), AND *
* RETURN TO CALLER. IF EITHER OF THESE CHECKS FAIL THEN *
* BRANCH BACK TO CONTINUE THE LOOP OF TEXT UNIT POINTERS. *
***************************************************************
SPACE 1
DB401BB DS 0H
TM S99TUPTR,LSTVALPT IS THIS A VALID LAST TEXT UNIT PTR?
BO DB401D BIY TO EXIT THE EXIT ROUTINE
B DB401B GO GET NEXT TEXT UNIT POINTER
DB401C DS 0H
L R7,S99TUPTR ESTABLISH ADDRESSABILITY TO
USING S99TUNIT,R7 THE SVC 99 TEXT UNIT
CLC S99TUKEY,UNDESKEY IS THIS A UNIT DESCRIPTION KEY?
BNE DB401BB BIN TO CHECK IF LAST TEXT UNIT PTR
CLC PARM3380,S99TUPAR IS THIS A 3380 PARAMETER?
BNE DB401BB BIN TO CHECK IF LAST TEXT UNIT PTR
LA R15,4(,R15) SET RETURN CODE TO CANCEL REQUEST
DB401D DS 0H
EJECT
***************************************************************
* STANDARD EXIT LINKAGE *
***************************************************************
SPACE 1
L R14,12(R13) RESTORE CALLER'S REGISTERS
LM R0,R12,20(R13) EXCEPT REGISTER 15
BR R14 RETURN TO CALLER
DROP R7,R8,R9,R12
SPACE 1
***************************************************************
* DECLARATIONS AND CONSTANTS *
***************************************************************
SPACE 1
PARM3380 DC C'3380' 3380 PARAMETER
BLANKPTR DC F'0' CHECKS FOR A BLANK TEXT UNIT PTR
LSTBLKPT DC X'80000000'
UNDESKEY DC H'21'
LSTVALPT EQU X'80'
END
