MAREN V12.6 (en)

&pagelevel(4)&pagelevel

The reserve-request exit is executed before a tape is reserved.

This allows the MAREN administrator to perform some of the following actions, for example:

define a range of numbers;
determine locations;
assign values to catalog entry fields or modify these values in advance;
reject free tape requests in certain circumstances;
prevent the reservation of tapes under certain user IDs.

A reservation file created with MARENLM is evaluated before the reserve-request exit.

The following catalog entry fields must not be changed by the reserve-request exit:

LAFUNKFL		Flag for the action to be performed by the program
LAFUNKNM		Name of the calling MAREN components or abbreviated name of the MAREN or MARENADM statement entered
ERRORKEY		Error message key
If a reservation request is issued for a tape determined by ARCHIVE as a result of one of the ARCHIVE statements POOL, SAVE or EXPORT (LAFUNKNM= C’MARENFA2’), the following catalog entry fields must also not be changed:
NUMMANFV		\|nternal catalog entry field for start of number range (archive number)
NUMMANFF		Internal catalog entry field for start of number range (FSEQ)
NUMMEND		Internal catalog entry field for end of number range

If one of these catalog entry fields is changed by the request exit, the loaded program is terminated with message MARCP27.

After control has been returned from the system exit, and before the catalog entry is output to the MAREN catalog, certain other catalog entry fields are changed. This means that any presettings relating to these catalog entry fields performed in the exit have no effect. The following list shows the catalog entry fields involved:

TEMPLOC		Current location
INITFLAG		Initialization flag
ARCHIVNR		VSN
FSEQ		File sequence number
PRUEFZ		Check digit
RESCOUNT		Reservation counter
VSEQ		File section number
STATUS		Tape status
ARCHLEN		Length of the catalog entry
ACCOUNT		Access counter
DOMAIN		Domain

Return codes

The reserve-request exit returns the following information via register 15:

Register contents	Meaning/reaction from MARENCP or MARENUCP
0	The request should be granted. Reservation is carried out. Any changes to the catalog entry made by the exit are taken into account.
4	The request is to be rejected. Reservation is not carried out. The caller receives message `MARCP24` (REQUEST REJECTED BY MAREN ADMINISTRATOR) and the action (e.g. an ADD-FILE-LINK command) or statement involved (e.g. RESERVE-FREE-VOLUMES) is aborted.
8	This value is only evaluated by MARENUCP. The request is rejected by the automatic free tape allocation facility. The operator is responsible for dealing with the corresponding console messages. MARENCP responds in the same way as when return code ’4’ is passed
other	The system responds in the same way as when return code ’4’ is passed.

Preset catalog entry fields

When the catalog entries are transferred to the exit routine, some of the catalog entry fields are preset. This presetting is to a certain extent dependent on whether a free tape is to be transferred via the RESERVE-FREE-VOLUME statement, via the automatic free tape allocation or via an ARCHIVE command. The preset catalog entry fields and their contents are shown in the following table. Catalog entry fields not listed only contain blanks when the exit routine is called.

The structure of the catalog entry and the contents of the individual catalog entry fields are described in section “Volume catalog”. The allocation of the catalog entry fields to the field names of the dummy section of the MARENA macro is described in the appendix on "Statement operands and volume catalog entry fields".

Presettings for the RESERVE-FREE-VOLUME statement (MAREN and MARENADM)

Catalog entry field	Contents passed to the reserve-request exit
OWNERID	In MAREN: ID of caller In MARENADM: USER-ID setting
OWNERACC	In MAREN: Account number of caller In MARENADM: USER-ID setting
XARCHDAT	Current date in ISO4 format
XFREIDAT	Expiration date in ISO4 format If <integer>: the date is calculated from current date + specified reservation period If STD*: the date is calculated from current date + system-specific MAREN parameter DEFAULT-FREE-DATE
FILENM41	FILE-NAME setting If *NONE (default): blanks
DEVICE	Value for DEVICE-TYPE If *STD (default): value of the system-specific MAREN parameter DEFAULT-DEVICE-TYPE
HOMELOC	Value for HOME-LOCATION If *STD (default): value of the system-specific MAREN parameter DEFAULT-HOME-LOCATION
FREELOC	See HOMELOC
TEMPLOC	See HOMELOC
SHARE	USER-ACCESS setting
PASSWORD	In MAREN: PASSWORD setting If NONE (default): 4X'00' In MARENADM: 4X'00' (PASSWORD operand not supported)
FASTATUS	The FASTATUS field indicates the type of free pool. May be one of: X'40' (blank); C'A'; C'T'; C'G'; C'D', C'F'
FREEPOOL	Value for the free tape pool depending on the FASTATUS value: FASTAUS=X'40' -> FREEPOOL=X'40' (blank) FASTAUS=C'A' -> FREEPOOL=X'40' (blank) or NONE FASTAUS=C'T' -> FREEPOOL=TSOS FASTAUS=C'G' -> FREEPOOL=*GLOBAL FASTAUS=C'F' -> FREEPOOL=Free-Pool-Name or blank FASTAUS=C'D' -> FREEPOOL=Directory-Name or blank
BEMERKG	REMARK setting If NONE: blanks
USERFELD	In MAREN: USER-FIELD setting If NONE (default): blanks In MARENADM: blanks (USER-FIELD not supported)
NUMMANFV	FROM setting If *FIRST (default): blanks
NUMMANFF	CL4'0001'
NUMMEND	TO setting If *LAST (default): CL6' 999999'
LATSN	Caller' s TSN
CRJOB	Caller’s job name or blanks (if job name is not specified)
LAFUNKFL	CL2'17' (field must not be modified by the exit)
LAFUNKNM	In MAREN: CL8'RESERVE' In MARENADM: CL8' RESERVE1' (field must not be modified by the exit)

Presettings for automatic free tape allocation

Catalog entry field	Contents passed to the reserve-request exit
OWNERID	Caller' s user ID Exception: in the case of HSMS tasks, user ID under which the HSMS directory is cataloged.
OWNERACC	Caller' s account number Exception: in the case of HSMS tasks, first account number in the TSOSJOIN entry of the user ID under which the HSMS directory is cataloged. In case of SPOOL output to tape: blanks
XARCHDAT	Current date in ISO4 format
XFREIDAT	Expiration date in ISO4 format calculated from current data + system-specific MAREN parameter DEFAULT-FREE-DATE
FILENM41	File name
CRCATID	Catalog ID from file' s path name if system-specific MAREN parameter CID-UID is set Otherwise: blanks
CRUSERID	User ID from file's path name if system-specific MAREN parameter CID-UID is set Otherwise: blanks In the case of an ARCHIVE backup with a directory - alternative to these three fields (FILENM41, CRCATID and CRUSERID)
DIRNAME	Path name of directory used
DEVICE	Specified device type
HOMELOC	– Value of the system-specific parameter DEFAULT-HOME-LOCATION or – Name of the first archive system entered or – Location specification from the MAREN command ADD-MAREN-FILE-ENTRY or location specification from ARCHIVE or HSMS
TEMPLOC	Name of the local system
SHARE	Value of the SHARE operand in the ARCHIVE statement
PASSWORD	4X'00'
FASTATUS	The FASTATUS field indicates the type of free pool. May be one of: X'40' (blank); C'A'; C'T'; C'G'; C'D', C'F'
FREEPOOL	Value for the free tape pool depending on the FASTATUS value: FASTAUS=X'40' -> FREEPOOL=X'40' (blank) FASTAUS=C'A' -> FREEPOOL=X'40' (blank) or NONE FASTAUS=C'T' -> FREEPOOL=TSOS FASTAUS=C'G' -> FREEPOOL=*GLOBAL FASTAUS=C'F' -> FREEPOOL=Free-Pool-Name or blank FASTAUS=C'D' -> FREEPOOL=Directory-Name or blank
NUMMANFV	blanks
NUMMANFF	CL4'0001'
NUMMEND	CL6'999999'
LATSN	Caller' s TSN
CRJOB	Caller’s job name or blanks With HSMS: REQUEST-NAME
LAFUNKFL	CL2'17' (field must not be modified by the exit)
LAFUNKNM	CL8'MARENUCP' (field must not be modified by the exit)
VOLGROUP	Name of the volume group from the MAREN command ADD-MAREN-FILE-ENTRY

Presettings for one of the ARCHIVE statements

POOL DIRECTORY = ..., ADD = (<vsn>,...)
SAVE or EXPORT with TAPES = (<vsn>,...) or TAPES = POOL and there are still free (“AVAILABLE”) tapes in the directory’s tape pool (if TAPES = POOL was specified and the tape pool is empty, reservation takes place via the automatic free tape allocation facility; see the table above).

Catalog entry field	Contents passed to the reserve-request exit
OWNERID	Caller' s user ID
OWNERACC	Caller' s account number
XARCHDAT	Current date in ISO4 format
XFREIDAT	Expiration date in ISO4 format calculated from current data + system-specific MAREN parameter DEFAULT-FREE-DATE
FILENM41	File name
CRCATID	Catalog ID from file's path name if system-specific MAREN parameter CID-UID is set Otherwise: blanks
CRUSERID	User ID from file's path name if system-specific MAREN parameter CID-UID is set Otherwise: blanks In the case of an ARCHIVE backup with a directory - alternative to these three fields (FILENM41, CRCATID and CRUSERID)
DIRNAME	Path name of directory used
DEVICE	Specified device type
SHARE	Value of the SHARE operand in the ARCHIVE statement
PASSWORD	4X'00'
FASTATUS	The FASTATUS field indicates the type of free pool. May be one of: X'40' (blank); C'A'; C'T'; C'G'; C'D', C'F'
FREEPOOL	Value for the free tape pool depending on the FASTATUS value: FASTAUS=X'40' -> FREEPOOL=X'40' (blank) FASTAUS=C'A' -> FREEPOOL=X'40' (blank) or NONE FASTAUS=C'T' -> FREEPOOL=TSOS FASTAUS=C'G' -> FREEPOOL=*GLOBAL FASTAUS=C'F' -> FREEPOOL=Free-Pool-Name or blank FASTAUS=C'D' -> FREEPOOL=Directory-Name or blank
NUMMANFV	Tape' s archive number (field must not be modified by the exit)
NUMMANFF	CL4'0001' (field must not be modified by the exit)
NUMMEND	Tape' s archive number (field must not be modified by the exit)
LATSN	Caller' s TSN
CRJOB	Caller' s job name or blanks
LAFUNKFL	CL2'17' (field must not be modified by the exit)
LAFUNKNM	CL8'MARENFA2' (field must not be modified by the exit)

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

Reserve-request exit MARENEX1

Return codes

Preset catalog entry fields

Presettings for one of the ARCHIVE statements