EXPORT-VOLUME Export tapes from the MAREN catalog

The EXPORT-VOLUME statement has the following functions:

• It labels local tapes as exported in the MAREN catalog;
• It labels foreign tapes as returned to the owner in the MAREN catalog.
  In the case of foreign tapes, the catalog entry is removed from the MAREN catalog.

Format

EXPORT-VOLUME                                                                      Alias: EXV

VOLUME = *BY-FILE(...) / *BY-DIRECTORY(...) / *INTERVAL(...) /
					list-poss(10): <vsn> / *BY- VOLUME-GROUP(...)
	*BY-FILE(...)
		|	FILE-NAME = <filename 1..41 without-cat-user>
		|	,VERSION = *LATEST / <integer -9999..0> / *ALL
		|	,USER-IDENTIFICATION = *OWN / *ALL / <name 1..8>
		|	,TYPE-OF-VOLUMES = *VALID (...) / *OBSOLETE / *ANY
		|		*VALID (...)
		|			|	CLOSE-CHECK = *YES / *NO
	*BY-DIRECTORY(...)
		|	DIRECTORY-NAME = <filename 1..54 without-gen-vers>
		|	,SAVE-FILE-ID = *LATEST / <integer -32767..0> / <composed-name 15..15>
	*INTERVAL(...)
		|	FROM = <vsn>
		|	,TO = <vsn>
		|	,FROM-FSEQ = 1 / <integer 1..9999>
	*BY- VOL UME -GR OUP(...)
		|	VOLUME-GROUP = <text 1..32 without-sep>
,EXPORT-ADDRESS = <c-string 1..50> / *BY-CATALOG
,PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647> / *SECRET
,LAYOUT = *STD / <file-name 1..54 without-gen-vers>

Operands

VOLUME =
Archive numbers of the tapes to be exported.

VOLUME = *BY-FILE(...)
All tapes belonging to a file or a tape set are to be exported.

FILE-NAME = <filename 1..41 without-cat-user>
File name to which a tape set is to be exported.

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 *LATEST. Specifying -1 indicates the penultimate file status, etc.

VERSION = *ALL
Selects all the tapes which exist for the specified file name.

USER-IDENTIFICATION =
This operand selects the user ID to which the tapes are assigned (catalog entry field USER-ID).

USER-IDENTIFICATION = *OWN
Only those tapes with the file name specified in the catalog entry and which are assigned to your own user ID are selected.

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.

CLOSE-CHECK =
This operand allows you to select whether the catalog entry field CLOSE-INDICATOR should be evaluated.

CLOSE-CHECK = *YES
If the CLOSE-INDICATOR catalog entry field is not set to CLOSED for one of the tapes in the selected tape set, the statement is rejected.

CLOSE-CHECK = *NO
The CLOSE-INDICATOR catalog entry field is not evaluated.

TYPE-OF-VOLUMES = *OBSOLETE
If a volume sequence occurs more than once in a tape set, all VSNs 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 in the specified directory (as saved files) are exported.

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 exported are selected using the save file of the directory specified above.

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 = *INTERVAL (...)
All tapes whose archive number lies within the range specified below are processed.

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

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 MAREN program interface.

VOLUME = list-poss(10): <vsn>
Archive numbers of the tapes to be exported.

VOLUME = *BY-VOLUME-GROUP(...)
All tapes of the specified volume group are exported.

VOLUME-GROUP = <text 1..32 without-sep>
Specifies the volume group to which a tape must belong for it to be exported. “*” can be entered as the last character. In this case all volume groups which begin with the specified string are selected.

EXPORT-ADDRESS = <c-string 1..50> / *BY-CATALOG
Mailing address. Specifies the destination to which the tape is to be sent. If the tape is to be picked up personally, any text to this effect can be specified, e.g. “Mailbox G7” .

EXPORT-ADDRESS = *BY-CATALOG
The mailing address defined in the tape's catalog entry is to be used for exporting.

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.

LAYOUT =
Specifies how the export receipt is to be created if the MAREN administrator has not set the EXPORT-RECEIPT parameter to *NO.

LAYOUT = *STD
The export receipt is generated with the default layout.

LAYOUT = <filename 1..54 without-gen-vers>
Layout file. The export receipt is created according to the definitions contained in the layout file by the MAREN administrator.

Notes

• The MAREN administrator can define whether an export receipt is to be created for every export. This receipt is first written to a file and then printed (if desired). The file is saved as $<userid>.MAREN.EXPORT-RECEIPT.<vsn>, where <userid> is the user ID of the calling task. If the file already exists, it is extended, otherwise, it is created. If immediate printing is specified in MAREN, the file is automatically deleted after it has been printed. If a list containing several archive numbers is specified, the file is not printed until the last archive number has been processed. If a tape in a list cannot be exported, the EXPORT statement is aborted.
• If the MAREN administrator has specified that export receipts are to be generated but not immediately printed automatically, what users are to do with the MAREN.EXPORT-RECEIPT.<vsn> file under their user IDs depends on arrangements in the data center.
• When a local tape is exported, the catalog entry field EXPORT-DATE is supplied internally with the current date, and the catalog entry field TEMPORARY-LOCATION is set to CENTRAL.
• When exporting a foreign tape, the catalog entry is deleted from the MAREN catalog. All existing multifile catalog entries with an FSEQ > 1 are likewise deleted.
• If the MAREN catalog contains a temporarily locked tape with the same archive number as the tape to be returned, the export process can only be carried out by the MAREN administrator.
• In the following cases, the statement aborts with an error message and the spin off mechanism is triggered:
• The tape is not in the MAREN catalog;
• The tape is currently being processed;
• The tape is assigned to a foreign user ID in the MAREN catalog, and USER-ACCESS is not ALL-USERS;
• The tape has already been exported;
  Exception: The tape is already at the specified address. In this case, a message is displayed and processing continues as normal.
• The operand EXPORT-ADDRESS=*BY-CATALOG has been specified, but the catalog entry contains no mailing address;
• All the tapes in a tape set are to be exported and one of the selected catalog entries contains the attribute FILE-SEQUENCE > 1 (i.e. the file specified is not the first on the specified tape);
• One of the tapes belonging to the tape set is temporarily locked;
• The tape is assigned to a storage location with the operating mode ROBAR-2. In this case it cannot be moved or exported;
• The tapes are selected using a save file from HSMS, and at least one tape is temporarily locked or at least one tape is being processed or is temporarily locked;
• The file specified in the LAYOUT operand does not exist.

Examples

//export-volume volume=id0101,export-address=c'hamburg'
%  MARM134 GET VOLUME 'ID0101' FROM CENTRAL ARCHIVE
%  MARM170 STATEMENT '//EXPORT-VOLUME' PROCESSED

Tape ID0101 is exported.

//export-volume volume=*by-file(file-name=tape.out),export-addr=*by-cat
%  MARM134 GET VOLUME 'ID0106' FROM CENTRAL ARCHIVE
%  MARM170 STATEMENT '//EXPORT-VOLUME' PROCESSED

All tapes used when the tape file TAPE.OUT was last created are exported. The mailing address contained in the catalog entries of these tapes is to be used.