With the aid of three exit points, it is possible to control and monitor use of the “open file” function, regardless of whether the OPEN occurs in a user program, a utility routine (e.g. LMS, EDT) or during the processing of a system command (START-PROGRAM).
Security exit (039): systems support can reject the OPEN call before it is executed.
Request exit (041): systems support can reject the OPEN call before it is executed. The file to be opened is defined either from the task file table or from the FCB.
Return exit (040): the file is already open, and the exit routine can neither prevent nor rescind the opening. All the functions of the return exit can also be performed by the security exit.
The following information is transferred to the exit routine:
R1 = A($DOCSYS parameter area) R12 = A(TPR program manager) R13 = A(save area of calling component) R14 = A(indirect return) R15 = A(exit routine)
Notes
Registers 12, 13 and 14 must not be destroyed by the exit routine.
Depending on the value of the AUDIT indicator, the 039/040 exits can carry out certain monitoring activities in the catalog entry (see "File access monitoring").
If either of exits 039/040 is activated, the BS2000 Data Management System (DMS) has already opened the file. The catalog entry for the opened file is still locked in exits 039 and 041. If a programming error causes the exit routine to be hung up or enter a loop without terminating abnormally, the file remains locked until the end of the session. (If it was terminated abnormally, this would lead to abnormal task termination and the file would be released.)
In exit 040 the catalog entry for the opened file has already been released.
The exit routine is allowed to reopen files on its own authority. Any problems resulting from recursive call nesting must be dealt with by the exit routine itself.
When working under the TSOS user ID it is possible, in the case of tape files, to use these exits and corresponding exit routines to monitor and keep a record of the use of tapes. This enables you to implement your own tape management facility.
If the attempt to open the file is rejected, the user receives either message DMS0D10 on SYSOUT or error code X’0D10’ in the ID1ECB field of the FCB:
% DMS0D10 SYSTEM ADMINISTRATOR HAS RESTRICTED USE OF OPEN MACRO. The activated system exit routine has rejected the OPEN command or macro. The program is continued with the EXLST exit OPENER, if defined, otherwise it is aborted.
If there is an error in the exit base mechanism, message DMS0D15 is displayed on the console and then processing continues.
% DMS0D15 CALLING BASE MECHANISM OF SYSTEM EXIT '(&00)' RESULTS IN ERROR CODE '(&01)' (&00): exit number. (&01): error code of $SYSX interface
Exit routines and EXLST exits
The exit routines described above and the EXLST exits that can be connected during OPEN processing are executed in the order shown in the diagram below (if they are present):
Parameter area
The layout of the exit parameter area can be generated with the $DOCSYS macro.
$DOCSYS MF=D
MFTST MF=D,PREFIX=D,MACID=OCS,ALIGN=F, C
DMACID=OCS,SUPPORT=(D,C,M,L),DNAME=OCS_MDL
DOCS_MDL DSECT ,
*,##### PREFIX=D, MACID=OCS #####
* parameterarea description
DOCSHDR FHDR MF=(C,DOCS),EQUATES=NO Standardheader
DOCSHDR DS 0A
DOCSFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER
*
DOCSIFID DS 0A 0 INTERFACE IDENTIFIER
DOCSFCTU 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
DOCSFCT DS AL1 2 FUNCTION NUMBER
DOCSFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER
*
DOCSRET DS 0A 4 GENERAL RETURN CODE
DOCSSRET DS 0AL2 4 SUB RETURN CODE
DOCSSR2 DS AL1 4 SUB RETURN CODE 2
DOCSSR1 DS AL1 5 SUB RETURN CODE 1
DOCSMRET DS 0AL2 6 MAIN RETURN CODE
DOCSMR2 DS AL1 6 MAIN RETURN CODE 2
DOCSMR1 DS AL1 7 MAIN RETURN CODE 1
DOCSFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH
*
* main return codes
DOCSNOER EQU 0 no error detected
DOCSRREJ EQU 4 request rejected
*
DOCSFCB@ DS A address of P1-FCB
DOCS# EQU *-DOCSHDR
Security exit (039)
The return code for the calling system module is transferred in the standard header of the $DOCSYS parameter area in the DOCSMRET field:
Return code: DOCSNOER = X'0000' = no error
Return code: DOCSRREJ = X'0004' = OPEN is to be rejected
The security exit is not activated if OPEN is rejected due to an invalid file name.
Return exit (040)
The return exit is activated even if OPEN is rejected due to an invalid file name.
The exit routine cannot send a return code to the system module.
Request exit (041)
The return code for the calling system module is transferred in the standard header of the $DOCSYS parameter area in the DOCSMRET field:
Return code: DOCSNOER = X'0000' = no error
Return code: DOCSRREJ = X'0004' = OPEN is to be rejected