Two exit points are provided for ERASE processing, a request exit and a return exit. They each contain one job.
A job is always one of the commands DELETE-FILE, DELETE-FILE-GROUP, DELETE-FILE-GENERATION, DELETE-SYSTEM-FILE, EXPORT-FILE or the ERASE macro, or any catalog entry that is to be processed by ERASE.
File generation groups, however, are special cases. Here the catalog entries of the generations do not form separate jobs. Rather, the file generation group as a whole is regarded as a job.
In the case of the request exit the exit routine can check the job and reject it if appropriate. If monitoring is to be performed by the return exit routine, the AUDIT indicator from the catalog entry must be saved.
The program branches to the return exit once the job has been processed. This exit routine can check the DMS error code and initiate any monitoring action that may be necessary.
In register 1 both exits contain a pointer to a structure that is described by the EX060 macro and stored in the working area of the calling system module.
If systems support wishes to implement monitoring measures in the exit routine that depend on the AUDIT value in the catalog entry, this information must already be provided at the request exit, since after a successful deletion (at the return exit) the catalog entry is normally no longer available.
The field for the file name is 80 bytes long. This field should be cleared in the exit routine before the name is provided, as it might otherwise contain smudge characters. If the field is not cleared, the end criterion for the file name must be requested (X’40’).
Return exit (060)
The following information is passed to the exit routine:
R1 = A(EX060 exit parameter area) R12 = A(TPR program manager) R13 = A(save area of calling component) R14 = A(indirect return) R15 = A(exit routine)
The return exit serves to indicate the success of an erase job. It is not called if the request exit routine has rejected the ERASE request.
Whenever this exit is called, field &p.RET of the ERASE parameter area contains the return code supplied during erasure or attempted erasure. If no error occurs, it contains the value X’00000000’. The ERASE parameter area is addressed via the MAXEPL field. The MAXFLC field contains the value contained by the corresponding MAXFLC field of the request exit. If MAXFLC is zero, the return exit of a command or macro is involved, and &p.RET contains the generic error code.
The exit routine cannot send a return code to the system module. The return from the return exit routine is followed by the return from ERASE processing. The exit routine must set the value X'70000' or X'0004' for the maincode in the standard header of the parameter area. If the maincode contains any other value, the following message appears on the console:
% DMS06B9 CALLING SYSTEM EXIT (&00) RESULTS IN ERROR CODE (&01)
Request exit (061)
The register settings are the same as for the return exit.
Control branches to the request exit exactly once per ERASE job. Before this happens, the EX060 parameter block is supplied with the following values:
MAXEPL points to the ERASE parameter area (see above); MAXFLC contains a counter, which starts at zero with every command or macro request and is incremented by one with every new job.
The return code for the calling system module is sent in the maincode of the standard header of the exit parameter area. The following values are possible:
X'0000' | ERASE processing is performed with the ERASE parameter area, which may have been modified by the exit routine. |
X'0004' | The ERASE request is rejected with error code X'0514'. DMS0514 USE OF SPECIFIED COMMAND OR 'ERASE' MACRO RESTRICTED BY SYSTEM ADMINISTRATOR. COMMAND OR MACRO REJECTED. |
other | Same as for X'0004'; in addition the following message is displayed on the console:
|
Note
Registers 12, 13 and 14 must not be destroyed by the exit routine.
DSECT
EX060 MF=D
MFTST MF=D,PREFIX=D,MACID=MAX,ALIGN=F, C
DMACID=MAX,SUPPORT=(D,C,L),DNAME=MAXMDL
DMAXMDL DSECT ,
*,##### PREFIX=D, MACID=MAX #####
* Parameterarea
DMAXHDR FHDR MF=(C,DMAX),EQUATES=NO Standard-Header
DMAXHDR DS 0A
DMAXFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER
*
DMAXIFID DS 0A 0 INTERFACE IDENTIFIER
DMAXFCTU DS AL2 0 FUNCTION UNIT NUMBER
* BIT 15 HEADER FLAG BIT,
* MUST BE RESET UNTIL FURTHER NOTICE
* BIT 14-12 UNUSED, MUST BE RESET
* BIT 11-0 REAL FUNCTION UNIT NUMBER
DMAXFCT DS AL1 2 FUNCTION NUMBER
DMAXFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER
*
DMAXRET DS 0A 4 GENERAL RETURN CODE
DMAXSRET DS 0AL2 4 SUB RETURN CODE
DMAXSR2 DS AL1 4 SUB RETURN CODE 2
DMAXSR1 DS AL1 5 SUB RETURN CODE 1
DMAXMRET DS 0AL2 6 MAIN RETURN CODE
DMAXMR2 DS AL1 6 MAIN RETURN CODE 2
DMAXMR1 DS AL1 7 MAIN RETURN CODE 1
DMAXFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH
*
DMAXFLC DS F File Counter
DMAXEPL DS A Addr der ERASE-PL
DMAX# EQU *-DMAXHDR
The MAXEPL field contains a pointer to a version 3 parameter area. If a version 3 ERASE has been requested, the area is a copy of the original parameter area. If a version 0, version 1, or version 2 ERASE has been requested, the old format is converted to the new format. It is impossible to access the original parameter area.
ERASE parameter list
The DSECT for the ERASE parameter area can be generated as follows:
[name] ERASE MF=D[,PREFIX=prefix/*],VERSION=3
The ERASE parameter area must be generated in the format valid as of BS2000/OSD-BC V3.0 (VERSION=3). All exit routines which access the ERASE parameter area have to be adapted to handle this new format.