Privilege ADA, DA, administrator without domains
This statement reserves tapes from the free pool with the name *NO for the user’s own user ID. The tape can be assigned specific protection attributes. Catalog entry fields can be assigned values.
DAs can only execute the statement in their own domain. The DOMAIN operand is thus meaningless for them.
Format
RESERVE-FREE-VOLUME Alias: RSFV | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
USER-IDENTIFICATION = <name 1..8>
User ID to which the volume is to be assigned.
ACCOUNT = *NONE / <alphanum-name 1..8>
Account number of the specified user ID.
NUMBER-OF-VOLUMES = 1 / <integer 1..32767>
Number of tapes. Specifies how many free tapes are to be reserved.
SELECT = *STD / *BY-ATTRIBUTES
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 (DEFAULT-DEVICE-TYPE) whose value was specified with the MODIFY-MAREN-PARAMETERS statement.
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 permanent location defined by the MAREN administrator.
PROTECTION =
Tape protection attributes
PROTECTION = *STD
The default values described below are used.
PROTECTION = *PARAMETERS(...)
USER-ACCESS =
Specifies whether foreign user IDs may access the tape.
USER-ACCESS = *OWNER-ONLY
Access to the tape is possible only under the specified 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. MAREN internally 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.
DOMAIN =
Defines the domain for which the free tapes are reserved.
DOMAIN = *STD-DOMAIN
Free tapes are reserved for the standard domain.
DOMAIN = *OWN
Free tapes are reserved for the user’s own domain. The user’s own domain is the domain of the system on which the ADA is currently working.
DOMAIN = <alphanum-name 1..8>
Free tapes are reserved for the specified domain.
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.
OUTPUT =
Determines the output medium. 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 catalog entry fields.
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 statement is aborted and the spin off mechanism triggered if a specified device type is not permitted or the expiration date is before the current date. The spin off mechanism is likewise triggered if NUMBER-OF-VOLUMES has not been reached.
Tapes that have not yet been “cleared up” (HOME-LOCATION is not the same as TEMP-LOCATION) can only be reserved on the local system on which they are located.
The archive catalog entry fields ADMINISTRATOR-FIELD, ADMINISTR-FIELD-2, AUDIT, INITIALIZATION and ACCESS-COUNT remain unchanged. The value of RESERVATION-COUNT is incremented by 1.
With the DEVICE-TYPE operand, no distinction is made between TAPE-C5 and TAPE-C6. Consequently, a type TAPE-C5 tape can be reserved when a type TAPE-C6 tape is requested.
Example
//reserve-free-volume user=user2,acc=acc1,dev-type=tape-c4
|
A tape of type TAPE-C4 is reserved for the user ID USER2 under the account number acc1. The reservation period corresponds to the DEFAULT-FREE-DATE operand. The tape is not shareable and the comment field of the archive record contains no catalog entry.
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 [5].
| 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 a 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 for access | 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 | <integer0..15> |
| Number of subsequent tape within a parallel save run in HSMS | var(*LIST).SUBSEQ | S | <integer0..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 | var(*LIST).USER-FIELD | S | <c-string 1..54> |
| User ID of the owner | var(*LIST).USER-ID | S | <name 1..8> |
| Tape VSN | var(*LIST).VOL | S | <vsn> |
| Volume group | var(*LIST).VOL-GROUP | S | <text 1..32> |
| Volume sequence number (4-digit) | 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 |