Privilege ADA, DA, administrator without domains
This statement can be used by the MAREN administrator to carry out so-called “clear-up” work. The statement generates transport messages MAR4164 (relocation requests).
Tapes which are currently to be found at a TEMPORARY-LOCATION which differs from their permanent location (HOME-LOCATION) are cleared up.
DAs can only execute the statement in their own domain. The DOMAIN operand is thus meaningless for them.
Format
RETURN-VOLUMES Alias: RTV | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
VOLUME =
Archive numbers of tapes to be relocated to their permanent location.
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.
VOLUME = *BY-FILE(...)
All tapes belonging to a file or a tape set are to be relocated.
FILE-NAME = <filename 1..41 without-cat-user>
Specifies the file name for which a tape set is to be cleared up.
VERSION =
This operand can be used to select a specific version (or status) of the specified file.
VERSION = *LATEST
Selects the latest version of the file (i.e. the last one created).
VERSION = <integer -9999..0>
Specifying 0 is equivalent to specifying *LATEST, specifying -1 indicates the penultimate file status, etc.
VERSION = *ALL
Selects all versions which exist for the specified file name.
USER-IDENTIFICATION =
This operand selects the user ID to which the tapes are assigned (archive entry field USER-ID).
USER-IDENTIFICATION = *ALL
The user IDs are not evaluated during selection.
USER-IDENTIFICATION = <name 1..8>
Only those archive numbers which are assigned to the specified user ID are selected.
TYPE-OF-VOLUMES =
This operand selects the volume sequences (catalog entry field VOLUME-SEQUENCE) within a tape set. These numbers are usually unique. Some numbers may be duplicated following a restart.
TYPE-OF-VOLUMES = *VALID
If a volume sequence occurs more than once in a tape set, the one created most recently is selected.
TYPE-OF-VOLUMES = *OBSOLETE
If tape sequence numbers occur more than once for a tape set, all are selected except the one most recently created.
TYPE-OF-VOLUMES = *ANY
The volume sequences for a tape set are not checked to establish whether they occur more than once.
VOLUME = *BY-DIRECTORY(...)
All tapes listed (as saved files) in the specified directory are to be swapped back in again.
DIRECTORY-NAME = <filename 1..54 without-gen-vers>
Name of the directory. Only reserved tapes assigned to the pool of 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 user ID and standard catalog ID can be omitted.
SAVE-FILE-ID =
The tapes that are to be moved are selected via the save file of the ARCHIVE directory specified.
SAVE-FILE-ID = *LATEST
All tapes listed in the last, i.e. most recent save file are selected.
SAVE-FILE-ID = <integer -32767..0>
All tapes listed in the nth save file are selected (the older the save file, the larger the number n). 0 equals *LATEST. Example: if -5 is specified, the tapes are selected from the last save file but five.
SAVE-FILE-ID = <composed-name 15..15>
All tapes in the save file with the specified SAVE-FILE-ID are selected. The SAVE-FILE-ID has the following format: S.yymmdd.hhmmss.
VOLUME = <vsn>
Archive number.
VOLUME = *BY-VOLUME-GROUP(...)
All tapes of the specified volume group are returned.
VOLUME-GROUP = <text 1..32 without-sep>
Name of the volume group. “*” can be entered as the last character. In this case all volume groups which begin with the specified string are selected.
DOMAIN =
The tapes of the selected domain are relocated.
DOMAIN = *ANY
The tapes of the all domains are relocated.
DOMAIN = *OWN
The tapes of the user’s own domain are relocated. The user’s own domain is the domain of the system on which the ADA is currently working or the domain in which he/she has taken over the DA role.
DOMAIN = *STD-DOMAIN
The tapes of the standard domain are relocated.
DOMAIN = <alphanum-name 1..8>
The tapes of the specified domain are relocated.
EXCEPTIONS =
This operand can be used to exclude specific tapes from the clear-up run.
EXCEPTIONS = *NO
There are no exceptions.
EXCEPTIONS = *MARENUCP-USAGE
Tapes provided for MARENUCP by means of the SECURE-FREE-VOLUMES statement are not cleared up.
FROM-LOCATION = *ALL / <alphanum-name 1..8>
Location name or symbolic location name. Specifies the location from which the tapes are to be relocated.
TO-LOCATION =
Location name or symbolic location name. Specifies the location to which tapes are to be relocated.
TO-LOCATION = CENTRAL
The tapes are relocated to the central archive only.
TO-LOCATION = *ALL
The tapes are relocated to all locations.
TO-LOCATION = <alphanum-name 1..8>
The location of an archive system can also be specified. Tapes that are relocated to an archive system are initially assigned the temporary location “CENTRAL”. Only when the tape is actually inserted in the archive system TEMPORARY-LOCATION is assigned the location name of the archive system. The value from the archive catalog field TEMPORARY-LOCATION is also used as an insert for FROM-LOCATION in transport message MAR4164, while the value for HOME-LOCATION is also used for TO-LOCATION.
Thus, a tape which is currently at the location “CENTRAL” is not interpreted as “cleared up”. In this case, the transport message MAR4164 (from “CENTRAL” to “archive system location”) is output.
MESSAGE-DESTINATION = *SYSOUT / list-poss(5): *SYSOUT / *SYSLST / *CONSOLE / *PRINTER / *FILE
Specifies the medium on which transport message MAR4164 is to be output. See notes below.
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 the FILE-NAME operand is specified and one of the selected catalog entries has the attribute FILE-SEQ > 1, processing aborts and an appropriate error message is displayed.
Tapes which have been exported or are currently reserved are not cleared up.
Tapes which are located at an archive system location defined as REMOTE on the local system are not cleared up.
If there are no tape to be cleared up, task switch 30 is set.
Tapes relocated to an archive system location are initially assigned the temporary location “CENTRAL”.
If HOME-LOCATION contains an archive system, TEMPORARY-LOCATION is set to “CENTRAL”.
If MESSAGE-DESTINATION=*PRINTER or =*FILE is specified, all transport messages are written to the file
MAREN.RETURN-VOLUMES. If the file already exists, it is extended, otherwise, it is created.If MESSAGE-DESTINATION=*PRINTER is specified, the file
MAREN.RETURN-VOLUMESis printed and deleted after the last archive number has been processed. Output is directed to the printer specified in the MAREN parameter EXPORT-RECEIPT= *PRINTER (DEVICE-NAME=...). If the statement aborts, the file is not printed. The statement can then be re-entered, the file is updated, and in the event of normal termination, the file containing all the transport messages generated is printed.If MESSAGE-DESTINATION=*PRINTER is specified and the MAREN parameter EXPORT-RECEIPT contains a value other than PRINTER, the statement is rejected with the message
MARM175.The TEMPORARY-LOCATION catalog entry field is set to the value of HOME-LOCATION in the catalog entry.
Any release run should as a rule take place before the clear up run so that tapes which have been released can be immediately relocated to their location for free tapes (FREE-LOC).
In the event of an individual, list, or number range specification, the entire inventory is searched.
In the event of an individual or list specification, the spin off is triggered in the following cases:
The tape has been exported or reserved, does not exist, or is already at its permanent location
The TO-LOCATION specified is different to the HOME-LOCATION of the tape
If the tapes are selected using a save file from HSMS and at least one tape is temporarily locked, the statement is not executed.
Example
return-vol vol=*int(id0001,id1200),mess-dest=(*sysout,*syslst)
|
All tapes from the set of VSNs id0001 to id1200 which are assigned to the permanent location CENTRAL (TO-LOCATION=CENTRAL is the default) but which are currently at another location (FROM-LOCATION=*ALL is the default) are relocated to their permanent location CENTRAL. The transport messages are output to SYSOUT and SYSLST.