Privilege ADA, DA, administrator without domains
This statement outputs information on free tapes to SYSOUT. The catalog entries of the free tapes can be written to an output file. The file can also be created in CSV format to permit spreadsheet processing. An output file can be sent by email.
DAs can only execute the statement in their own domain. The DOMAIN operand is thus meaningless for them.
Format
SHOW-FREE-VOLUMES Alias: SHFV | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
VOLUME =
Archive numbers of tapes about which information is required.
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.
FROM-FSEQ = 1 / <integer 1..9999>
File sequence number of the FROM operand. Specifies the precise file sequence number at which processing is to begin. This operand is relevant only if the statement is issued via the program interface.
FREE-LOCATION = *ALL / <alphanum-name 1..8>
Location name or symbolic location name. All catalog entries with the specified location for free tapes are processed.
FREE-LOCATION = *ALL
All locations for free tapes are processed.
DEVICE-TYPE =
Device type.
DEVICE-TYPE = *STD
All tapes of the default device type (DEFAULT-DEVICE-TYPE) whose value was specified in the MODIFY-MAREN-PARAMETERS statement are listed.
DEVICE-TYPE = *ALL-TAPES
All tapes are displayed (see notes on "SHOW-FREE-VOLUMES Show information about free tapes").
DEVICE-TYPE = <structured-name 1..8>
Device type. For a list of possible entries (depending on the BS2000 version), see manual “System Installation” [6].
USAGE =
Specifies whether, on output of the catalog entries, a selection is to be made on the basis of the reservation type of free tapes. Reservation is effected either explicitly via the RESERVE-FREE-VOLUME statement or implicitly via the automatic free tape allocation facility MARENUCP.
USAGE = *ANY
The catalog entries of all free tapes are to be output, regardless of their reservation type.
USAGE = *BY-MARENUCP
The catalog entries of free tapes which can only be reserved via the automatic free tape allocation facility (MARENUCP) are to be output.
FREE-POOL =
Selects the catalog entries to be made available on the basis of the free tape pool.
FREE-POOL = *NO
Only free tapes assigned to the *NO free tape pool are selected.
FREE-POOL = *GLOBAL
Only free tapes assigned to the *GLOBAL free tape pool are selected.
FREE-POOL = *TSOS
Only free tapes assigned to the *TSOS free tape pool are selected.
If aliases are specified for the *NO, *GLOBAL or *TSOS values, then these operand values will be expanded to their full length for compatibility reasons (e.g. *GL is expanded to *GLOBAL).
FREE-POOL = <filename 1..54 without-gen-vers>
Only free tapes assigned to the free tape pool for HSMS/ARCHIVE applications using the specified directory are selected. If this directory is located under a remote user ID, both the user ID and the catalog ID must be entered. The user's own ID and standard catalog ID can be omitted.
FREE-POOL = <text 2..32 without-sep>
Specifies the name of a free tape pool. The name of the free tape pool must begin with “*” followed by at least one character from A-Z or 0-9. The characters “.”, “-” and “_” are permitted, but not at the end and not next to each other. “*” can be entered as the last character. In this case all catalog entries in all free tape pools will be listed, which begin with the specified character string. The sort criteria will apply only within the individual free tape pools.
DOMAIN =
Specifies the domain whose free tapes are shown.
DOMAIN = *ANY
Free tapes of all domains are shown.
DOMAIN = *OWN
Free tapes of the user’s own domain are shown. The user’s own domain is the domain of the system on which the ADA is currently working.
DOMAIN = *STD-DOMAIN
Free tapes of the standard domain are shown.
DOMAIN = <alphanum-name 1..8>
Specifies the domain whose free tapes are shown.
If domains are used, the DA is shown free tapes either from the standard domain or from his/her own domain. This is dependent on which value the domain-specific FREE-VOLUMES operand has. The ADA is shown free tapes of the domain which is specified with the DOMAIN operand.
SORT-MODE =
Specifies the catalog entry field by which output should be sorted.
SORT-MODE = *VOLUME
The catalog entries are sorted according to archive numbers.
SORT-MODE = *RESERVATION-COUNT
The catalog entries are sorted according to the reservation counter.
SORT-MODE = *LAST-ACCESS-DATE
The catalog entries are sorted according to the date of the last access.
SORT-MODE = *FREE-DATE
The catalog entries are sorted according to the date of the last release.
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, such as MARENADM STATEMENT SHOW-FREE-VOLUMES, FILENAME: <filename>.
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.
OVERFLOW-CONTROL =
Type of screen overflow control in interactive mode.
OVERFLOW-CONTROL = *BY-PROGRAM
Control by the program: after eighteen catalog entries have been processed, a message is displayed inquiring whether the current operation is to be continued or aborted.
OVERFLOW-CONTROL = *BY-SYSTEM
Control by BS2000: screen overflow control is based entirely on the system parameter TCHOFLO or the value set in the MODIFY-TERMINAL-OPTIONS command.
Notes
If a sort criterion other than *VOLUME is chosen (e.g. SORT-MODE=*FREE-DATE), the value *STD is used instead of *ALL-TAPES for the DEVICE-TYPE operand for further processing. As a result, not all tapes are displayed, but just all tapes of the default device type, which makes sense.
Depending on how many tapes there are in the specified number range, the output of catalog entries may be very time-consuming. This is particularly true if a sort criterion other than *VOLUME is selected. It is therefore advisable to use a batch process for output or to access the MAREN catalog directly (run the program under the catalog ID or user ID TSOS).
The spin off mechanism is triggered if the specified location for free tapes is incorrect or if no free tape has been found in the specified range.
Examples
//show-free-volumes
The catalog entries of all free tapes with the specified default device type are output. After every eighteen entries, the user is asked whether listing should be terminated or continued.
//show-free-volumes volume=*interval(from=id0,to=id9),output=list.freevol.2
| |
% | MARM119 FILE 'LIST.FREEVOL.2' WITH 30 RECORDS CREATED |
All free tapes with the default device type whose archive numbers lie within the range id0 to id9 are listed. Output is directed to the file list.freevol.2.
//show-free-volumes volume=*all
|
The catalog entries of all free tapes (default device type) assigned to a free tape pool for HSMS/ARCHIVE applications under any user ID are output.
Meaning of the catalog entry fields:
| VOLUME | VSN |
| DEV-T | Device type |
| FREE-LOC | Location for free tapes |
| U | USAGE reservation flag U indicates that reservation is possible only via MARENUCP. |
| RESC | Reservation counter |
| L-A-HOST | Name of the system with last access |
| L-A-DATE | Date of the last access |
| FREE-DATE | Expiration date |
| L-A-USER | User ID of the last access |
| ADM-FIELD | Remark field |
|
All free tapes with the default device type whose archive numbers lie within the range id0 to id1 are listed.
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 | <filename 1..54> *NO *GLOBAL *TSOS |
| 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 |
| Comment field which should be filled with a meaningful text | var(*LIST).REMARK | S | <c-string 1..24> |
| Reservation counter 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 VSN | var(*LIST).VOL | S | <vsn> |
| Volume group Only has a valid value with reserved tapes, otherwise it is undefined. | 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 |