RESERVE-FREE-VOLUME Reserve free tapes

This statement reserves tapes from the free pool with the name *NO for the user’s own user ID. The tape can be assigned specified protection attributes. Catalog entry fields can be assigned values.

Format

RESERVE-FREE-VOLUME                                                    Alias: RSFV

NUMBER-OF-VOLUMES = 1 / <integer 1..32767>
,SELECT = *STD / *BY-ATTRIBUTES(...)
	*BY-ATTRIBUTES(...)
		|	VOLUME = *ALL / *INTERVAL(...)
		|		*INTERVAL(...)
		|			|			FROM = *FIRST / <vsn>
		|			|	,TO = *LAST / <vsn>
		|	,DEVICE-TYPE = *STD / <structured-name 1..8>
		|	,HOME-LOCATION = *STD / <alphanum-name 1..8>
,PROTECTION = *STD / *PARAMETERS(...)
	*PARAMETERS(...)
		|	PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> /
		|				<integer -2147483648..2147483647> / *SECRET
		|	,USER-ACCESS = *OWNER-ONLY / *FOREIGN-READ-ONLY / *ALL-USERS
		|	,FREE-DATE = *STD / <date> / <integer 0..32767 days>
,FILE-NAME = *NONE / <filename 1..41 without-cat-user>
,VOLUME-GROUP = *NONE / <text 1..32 without-sep>
,REMARK = *NONE / <c-string 1..24>
,REMARK-2 = *NONE / <c-string 1..10>
,REMARK-3 = *NONE / <c-string 1..12>
,USER-FIELD = *NONE / <c-string 1..54>
,OUTPUT = *SYSOUT / *NONE / <filename 1..54> / <filename 1..54 without-gen-vers>(...)
	<filename 1..54 without-gen-vers>(...)
		|	FORMAT = *MAREN-STRUCTURE / *CSV(...)
		|		*CSV(...)
		|			|	SEPARATOR = *SEMICOLON / *COMMA
					|	,HEADER-LINE = *Y ES / *NO
		|	,SEND-BY-MAIL = *NO / *YES(...)
		|		*YES(...)
		|			|	TO = *USER (...)
		|			|		*USER (...)
		|			|			|      USER-IDENTIFICATION = *OWN / <name 1...8>
		|			|	,SUBJECT = *STD /<c-string 1...256>
		|			|	,DELETE-FILE = *NO / *YES / *DESTROY
,STRUCTURE-OUTPUT = *NONE / <composed-name 1..255> (...)
	<composed-name 1..255> (...)
		|	WRITE-MODE = *REPLACE / *EXTEND

Operands

NUMBER-OF-VOLUMES = 1 / <integer 1..32767>
Number of tapes. Specifies how many free tapes are to be reserved.

SELECT =
Specifies the criteria to be used to select free tapes.

SELECT = *STD
The standard criteria listed below are used.

SELECT = *BY-ATTRIBUTES(...)

VOLUME =
Specifies a number range from which free tapes are to be selected.

VOLUME = *ALL
All tapes are processed.

VOLUME = *INTERVAL(...)
All tapes whose archive number lies within the range specified below are processed.

FROM = *FIRST
All tapes are processed, starting with the lowest available archive number.

FROM = <vsn>
Archive number. All tapes whose archive number is greater than or equal to the specified archive number are processed.

TO = *LAST
All tapes are processed up to the highest existing archive number.

TO = <vsn>
Archive number. All tapes whose archive number is less than or equal to the specified archive number are processed.

DEVICE-TYPE =
Device type.

DEVICE-TYPE = *STD
The tapes are of the default device type defined by the MAREN administrator.

DEVICE-TYPE = <structured-name 1..8>
Device type. For a list of possible entries (depending on the BS2000 version), see manual “System Installation” [6].

HOME-LOCATION = *STD / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the archive from which the free tapes are to be selected.

HOME-LOCATION = *STD
The selection is made from the default location defined by the MAREN administrator.

PROTECTION =
Protection attributes of the tapes.

PROTECTION = *STD
The standard criteria listed below are used.

PROTECTION = *PARAMETERS(...)

PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647> / *SECRET
Password. The previously valid password must be entered here if the tape is protected by a password.

PASSWORD = *NONE
No password is specified.

PASSWORD = *SECRET
Requests a blanked-out input field for the password. Entries in this field are not visible on the screen. This operand value can only be specified in unguided dialog. In guided dialog, the field provided for entering passwords is always blanked out.

USER-ACCESS =
Specifies whether foreign user IDs may access the tape.

USER-ACCESS = *OWNER-ONLY
Access to the tape is possible only under the own user ID.

USER-ACCESS = *FOREIGN-READ-ONLY
Only read access to the tape is possible under a foreign user ID.

USER-ACCESS = *ALL-USERS
Unrestricted access to the tape is possible under a foreign user ID.

FREE-DATE =
Expiration date of the tape. Up to this date, the tape remains reserved for the given user ID.

FREE-DATE = *STD
The reservation period defined by the MAREN administrator applies.

FREE-DATE = <date>
Date in the format yyyy-mm-dd.

FREE-DATE = <integer 0..32767 days >
Time specification in days (reservation period). MAREN adds this number to the current date to generate the expiration date.

FILE-NAME = *NONE / <filename 1..41 without-cat-user>
Name of the file which is subsequently to be written to the tape.

VOLUME-GROUP = *NONE / <text 1..32 without-sep>
Specifies the volume group to which the newly reserve tape is assigned. When *NONE is specified, it is not assigned to a volume group.

REMARK = *NONE / <c-string 1..24>
Comment text. This catalog entry field is output in response to the MAREN statement SHOW-VOLUME-ATTRIBUTES.

REMARK-2 = *NONE / <c-string 1..10>
Comment text. This catalog entry field is output in response to the MAREN statement SHOW-VOLUME-ATTRIBUTES.

REMARK-3 = *NONE / <c-string 1..12>
Comment text. This catalog entry field is output in response to the MAREN statement SHOW-VOLUME-ATTRIBUTES.

USER-FIELD = *NONE / <c-string 1..54>
Comment text. This catalog entry field may contain any user-specific data, e.g. name, department.

OUTPUT =
Determines the output medium for the catalog entries. Output to SYSOUT is the default.

OUTPUT = *SYSOUT
Output is directed to SYSOUT.

OUTPUT = *NONE
No output takes place. This specification only makes sense for structured output in an S variable (see the STRUCTURE-OUTPUT operand).

OUTPUT = <filename 1..54>
Only for specifying a file generation.
Output is directed to the specified file generation in MAREN format. Passwords are overwritten with C'$$$$'. Only the number of records written is displayed on SYSOUT.

OUTPUT = <filename 1..54 without-gen-vers>(...)
Name of the SAM output file to which all selected catalog entries are to be written. Passwords are overwritten with C'$$$$'. Only the number of records written is displayed on SYSOUT. The output format and transfer by email can also be specified.

FORMAT =
Determines the format of the output file.

FORMAT = *MAREN-STRUCTURE
Output takes place in MAREN format.

FORMAT = *CSV(...)
Output takes place in CSV (comma separated value) format. Files in CSV format can be read in so that the columns are retained, and they can be processed further with a spreadsheet program (e.g. EXCEL).

SEPARATOR = *SEMICOLON / *COMMA
Determines the separator which is to be set between the various output values. The default separator is a semicolon (;). Optionally a comma (,) can be used as the separator.

HEADER-LINE = *YES / *NO
Specifies whether a header line should be output to name the output columns. The default is *YES, i.e. the header line is output. The header line contains the names of the attributes.

SEND-BY-MAIL = *NO / *YES(...)
Specifies whether the output file should be sent by email. The default is *NO, i.e. it is not sent by email. Transfer by email takes place only if the file to be sent contains at least one entry.

SEND-BY-MAIL = *YES(...)
The output file should be sent as an email attachment. The recipient is addressed by means of his/her user ID, i.e. the email address is taken from the user entry concerned.

TO = *USER(...)
Details of transfer by email:

USER-IDENTIFICATION = *OWN / <name 1...8>
Specifies the user ID. The recipient’s email address is taken over from this user entry. If the user entry contains more than one email address, all the addresses are taken over as recipients. The default is *OWN, i.e. the caller’s user ID.

SUBJECT = *STD /<c-string 1...256>
Determines the content of the email’s “Subject” field. The default is *STD, i.e. MAREN uses a standard text.

DELETE-FILE = *NO / *YES / *DESTROY
Specifies whether the file should be automatically deleted after it has been sent. The default is *NO, i.e. the file is not deleted. *YES causes the file to be deleted after it has been sent. *DESTROY also causes it to be deleted, and the memory space is overwritten with binary zeros.

STRUCTURE-OUTPUT =
Controls the structured output in S variables.

STRUCTURE-OUTPUT = *NONE
No structured output takes place.

STRUCTURE-OUTPUT = <composed-name 1..255> (...)
Name of the S variable to be used for the structured output.

WRITE-MODE =
Determines whether the output should replace or extend the current content of the S variables.

WRITE-MODE = *REPLACE
The current content of the S variable is replaced by the new output.

WRITE-MODE = *EXTEND
The new output extends the current content of the S variable.

Notes

The RESERVE-FREE-VOLUME statement is not absolutely essential to reserve a free tape for the user's own ID, since reservation from the pool of free tapes takes place automatically when SCRATCH tapes are requested at FILE or EOV processing time. Nevertheless, this statement is useful in the following instances:

• At an early point in time, it can be ensured that any free tapes will be readily available.
• If no RETENTION-PERIOD is specified in the FILE command/macro, an reservation period deviating from the default value can be entered for this function.
• The user-specific catalog entry fields, such as the password or remarks field, can be filled out.

Example

//reserve-free-volume protection=*par(free-date=<date>),remark='my tape'
%  MARM127 VOLUME 'IDY015' RESERVED FOR USER ID 'USER1'

This statement reserves a tape with the default device type set by the MAREN administrator and defines an expiration date for it.

//reserve-free-volume num-of-vol=2,select=*by-attr(dev-type=tape-c4),prot=*par(free-date=200,user-acc=*all)
%  MARM127 VOLUME 'IDY020' RESERVED FOR USER ID 'USER1'
%  MARM127 VOLUME 'IDY031' RESERVED FOR USER ID 'USER1'
%  MARM120 TOTAL OF 2 MAREN CATALOG ENTRIES PROCESSED

This statement reserves two tapes of the type TAPE-C4. It is flagged in the catalog entry as being shareable without restrictions and reservation period of 200 days.

Output in S variables

This statement supports the structured output in S variables (controlled by the STRUCTURE-OUTPUT operand).

Further information on S variables is provided in the “Commands” manual [3].

 

Output information	Name of the S variable	T	Contents
Access counter (8-digit) It is incremented each time the tape is accessed.	var(*LIST).ACCESS-COUNT	S	<integer 0..99999999>
Creation date	var(*LIST).CRE-DATE	S	yyyy-mm-dd
Creation job name For HSMS request name	var(*LIST).CRE-JOB-NAME	S	’’ <name 1..8>
Creation time	var(*LIST).CRE-TIME	S	hh:mm:ss
Device type	var(*LIST).DEV-TYPE	S	<structured-name 1..8>
Name of an directory (with catalog ID and user ID) which contains the tape.	var(*LIST).DIR-NAME	S	<filename 1..54 >
Displays whether the tape contains the directory which was also saved	var(*LIST).DIR-ON-VOL	S	*NO *YES
Status (exported or not)	var(*LIST).EXPORTED	S	*NO *YES
First archive number of the MF/MV set	var(*LIST).FIRST-VOL	S	<vsn>
File name of a tape file Without catalog ID and user ID	var(*LIST).F-NAME	S	<filename 1..41>
Expiration date of the tape Specifies when the reservation of the tape for a user ID can be terminated	var(*LIST).FREE-DATE	S	yyyy-mm-dd
Release location A tape is moved to this location during the clear-up run	var(*LIST).FREE-LOCATION	S	<alphanum-name 1..8>
Name of the free tape pool in which this tape is located or in which it should be located when it is shared	var(*LIST).FREE-POOL	S	*NO
File sequence number (4-digit)	var(*LIST).F-SEQ	S	<integer 1..9999>
Standard location	var(*LIST).HOME-LOCATION	S	<alphanum-name 1..8>
Name of the system with last access	var(*LIST). LAST-ACCESS-HOSTNAM	S	<alphanum-name 1..8>
Date of the last access	var(*LIST).LAST-ACCESS-DATE	S	yyyy-mm-dd
User ID of the last access	var(*LIST).LAST-ACCESS-USER-ID	S	<name 1..8>
Password	var(*LIST).PASS	S	*NONE *YES
Remark field	var(*LIST).REMARK	S	<c-string 1..24>
Reservation counter (4-digit) This counter is incremented with each new reservation of the tape	var(*LIST).RESERV-COUNT	S	<integer 0..9999>
Reservation date Date on which a tape is reserved	var(*LIST).RESERV-DATE	S	yyyy-mm-dd
SAVE-FILE-ID (HSMS) or SAVE-VERSION (ARCHIVE)	var(*LIST).SFID	S	<c-string 1..15>
Number of subtask for parallel save run in HSMS	var(*LIST).SUBSAVE	S	<integer 0..15>
Number of subsequent tape within a parallel save run in HSMS	var(*LIST).SUBSEQ	S	<integer 0..999>
Shareability of the tape	var(*LIST).USER-ACCESS	S	OWNER-ONLY FOREIGN-READ ALL-USERS
Account number	var(*LIST).USER-ACCOUNT	S	<alphanum-name 1..8>
User field. Data such as name and department or data relevant for operations scheduling can be entered here.	var(*LIST).USER-FIELD	S	<c-string 1..54>
User ID of the owner	var(*LIST).USER-ID	S	<name 1..8>
Tape archive number	var(*LIST).VOL	S	<vsn>
Volume group	var(*LIST).VOL-GROUP	S	<text 1..32>
Volume sequence number	var(*LIST).VOL-SEQ	S	<integer 1..255>
Tape status F = FREE P = PRIVATE R = RESERVED D = DEFECT	var(*LIST).VOL-STA-1	S	F/P/R/D