CLOSE exits (042/043)

Two exits are offered for the CLOSE (= “close file”) function. For tape files, the corresponding exit routines can be used under the TSOS user ID to monitor and keep a record of the use of tapes, and thus to implement an individual tape file management facility.

• The request exit is activated at the beginning of CLOSE processing. In the case of magnetic tape files the tape is positioned behind the last data block processed. End-offile labels have not yet been processed.

• The return exit routine is called at the end of CLOSE processing. In the case of magnetic tape files the tape is positioned between the two tape marks which serve as delimiters at the end of a file; for files with standard labels, this position is behind the EOF labels.

In both cases the address of the exit parameter list is transferred to the exit routine. It is therefore possible to access further information from the P1 FCB, P2 FCB or the CVT (Current Volume Table).

The following information is passed 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.

• If the return code in the parameter area of the exit base mechanism is not equal to 0, 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 
  

Sources of information

The following table contains notes on accessing information which can be processed effectively by the exit routines:

Information	DSECT		Name	is in	Note
Exit parameter list	$DOCSYS	A		Register 1
P1-FCB	IDFCB	A	P1FCB-ADDRESS	Exit parameter list
P2-FCB	IDFC2	A	D1P2LNK	P1-FCB
CVT	DMACVT	A	D2CVTAD	P2-FCB
VSN	DMADR	I	DRVVSN	TFT	with RDTFT macro
Device access right	DMACVT	I	DCVRID	CVT	is not available with the CLOSE return exit
Labels	DTVOL DTHT1 DTHT2 DTHT3	A A	D2LGINF D2LGINF	P2-FCB P2-FCB	return exit request exit
Total number of block counters for file		I	D2THPGN	P2-FCB	only for SAM andCLOSE return exit
Block counters for tape		I I	DIHPGNR D1BLK# / DIBLK#	P2-FCB P1-FCB / P2-FCB	BLKSIZE=STD BLKSIZE (STD,n) (all are for SAM only)

I = Information is contents of “Name” field
A= Address of information in “Name” field

Exit routines and EXLST exits

The exit routines described above and the EXLST exits that can be connected during CLOSE processing are executed in the order shown in the diagram below (if they are present):

Return exit (042)

The exit routine cannot send return codes to the system module.

Request exit (043)

The exit routine cannot send return codes to the system module.

In the case of output files on tape, the file labels VOL1, HDR1, HDR2 and HDR3 written with OPEN can be accessed via the address in the D2LGINF field in the P2 FCB. The length of the addressed area is 4 x 80 = 320 bytes.

When the request exit routine is called, no value has been specified for the block counter.

 

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