FILES Select files in restoration runs

The FILES statement has two different formats, one for saving files and one for restoring files. The FILES statement for restoring files is described here; the FILES statement for saving files is described in the section "FILES Select files in save runs".

In the FILES statement you must specify the files which are to be restored or listed in an ARCHIVE run, together with the associated volumes.
More than one FILES statement can be entered. This is useful if several TO statements are to be specified, since only one TO entry is permitted per FILES statement.

The NAME and EXCEPT operands can be entered several times, but only one EXCEPT operand may be entered for each NAME operand.

The processing of the FILES statements and NAME operands by ARCHIVE is described in the section "Parallel and serial processing".

F[ILES]

[ [NA[ME] = [ { filename / (filename[ ,THRU = filename],...) /
                                       (filename[ ,RENAME = filename],...)] ] }
[,EX[CEPT] = { filename / (filename[ ,THRU = filename],...) } ] ] ...

[,TO = { PUBLIC / vsn/(vsn,...),DEVICE = device type,...) } ]

[,ORIGIN = { vsn / (vsn,...) / PUBLIC } ]

NAME =
The files to be read in or listed are specified in the NAME operand. The possible specifications are dependent on the value of the CATID parameter.

• The following applies to runs with PARAM CATID=NO:

  A catalog ID may be specified only in the RENAME operand; otherwise, the statement will be rejected.

  If the NAME operand is omitted:

  • All files are written into the default pubset of the user ID.

  • If the user has the TSOS privilege, the files of all user IDs are written to their respective default pubsets.

• The following applies to runs with PARAM CATID=YES:

  If no catalog ID is specified, the catalog ID of the default pubset of the relevant user ID is added to the file name.
  If a specified user ID has no entry in the JOIN file of the home pubset, this leads to an error. The files are not read in.
  It is also possible to specify only the catalog ID (e.g. NAME=:c:), in which case all files belonging to the user ID are restored which come from the catalog with the specified ID.

  If the NAME operand is omitted:

  • All files belonging to the appropriate user ID are restored to the pubset from which they were saved.

  • If the user has the TSOS privilege, the files of all user IDs are restored to the pubset from which they were saved.

NAME = filename
This may be a partially or fully qualified file name.

NAME = (filename,...)
When more than one file name is specified, the file names must be enclosed in parentheses.

NAME = (filename,THRU=filename)
The specification “THRU” permits a range of files to be defined. All files with names lying alphabetically between the specified file names (both inclusive) are then addressed.
The file names must be specified in the same format (fully or partially qualified).

If you use alias names, you must take care when using the THRU operand: the range of file names is calculated from the range output by the alias catalog.

In a run with PARAM CATID=YES, all accessed files must be on the same pubset, i.e. the catalog IDs of the two files in filename,THRU=filename must be the same.

NAME = (filename,RENAME=filename)
Files are renamed using the RENAME operand. The name in RENAME replaces the original name (NAME=...). If the name is partially qualified, the specified part is changed.Catalog entries saved with CATONLY=YES cannot be renamed.

If the RENAME specification would result in an invalid DMS file name, it is rejected.

If ARCHIVE is not running under the TSOS privilege, only files under the user's own ID may be renamed in RESTORE runs.
With IMPORT runs, files can also be transferred from foreign user IDs to the user's own ID and renamed, provided they have previously been saved via EXPORT.

If a catalog ID :c: is specified for the new file name (filename, RENAME=:c:filename), the following applies to runs with PARAM CATID=YES:
all referenced files with the current standard catalog ID of the user ID in question are restored to the pubset with the catalog ID :c:.

If a catalog ID :c: is specified for the old file name (:c:filename, RENAME=filename), the following applies to runs with PARAM CATID=YES:
all referenced files with the catalog ID :c: belonging to the user ID in question are restored to the current default pubset.
In the case of PARAM CATID=NO, the specification of a catalog ID (target pubset) is only possible with RENAME.

In save runs with CATONLY=YES, you can rename the catalog ID.

It is possible to specify user IDs instead of file names ($userid1., RENAME=$userid2.):

• The following applies to runs with PARAM CATID=YES:

  All files belonging to the current standard catalog ID of $userid1 are restored to the default pubset of $userid2. If you are not working with the TSOS privilege, $userid2 must be the same as the LOGON user ID.

• In the case of PARAM CATID=NO, all files of $userid1 are restored to the default pubset of $userid2.
  

EXCEPT = filename / (filename,THRU=filename)
This specifies the files or range of files that should be excluded from the file list specified by the NAME operand.
Only one EXCEPT operand may be specified per NAME operand.

An EXCEPT operand not preceded by a NAME operand references all the files in the user ID or, in the case of the system support, all the files in the system.
Two consecutive EXCEPT operands are not permitted. They must be separated by at least one NAME operand, which may also be empty.

The same rules apply to the specification of file names in the EXCEPT operand as in the NAME operand.

Examples

*FILES EXCEPT=HUGO1

This statement causes all the files under the user ID in question or, if the user has the TSOS privilege, all the files in the system, to be restored with the exception of HUGO1.

*FILES EXCEPT=(HUGO1,HUGO2,HUGO7)

This statement causes all the files under the user ID in question or, if the user has the TSOS privilege, all the files in the system, to be restored with the exception of HUGO1, HUGO2 and HUGO7.

*FILES EXCEPT=HUGO1
*FILES EXCEPT=HUGO2
*FILES EXCEPT=HUGO7

In contrast to the previous example, this sequence of statements causes all the files under the relevant user ID(s) to be restored three times, as follows:

• the first time, all files except the file HUGO1

• the second time, all files except the file HUGO2

• the third time, all files except the file HUGO7

In this case all the tapes have to be wound from beginning to end three times.

TO =
This specifies the output volumes.

All the volumes for the files in a FILES statement should be mounted beforehand, otherwise they will be requested during the run.

TO = (vsn,...),DEVICE=type
All files specified in the NAME operand are written to the specified VSNs.Under DEVICE the disk type must be specified.

TO = PUBLIC
All the files, including those saved from private disks, are written to public volumes. 

If the TO operand is omitted in a RESTORE run, all the files saved from private volumes are restored to their original volumes.

Files saved from public volumes are restored to public volumes.

In IMPORT runs without specification of the TO operand, the files are restored to public volumes unless otherwise specified.

If ISAM files with separate volumes for index and data are restored in a RESTORE run, the TO operand must not be specified, or at least two private disks must be specified. The index is then read to the first, the data to the second disk.

When catalog entries are being restored, the TO operand is ignored.

ORIGIN =
This operand permits you to specify that only those files are restored which were either wholly or partially on the specified volume(s) at the time of the save run.

In a restoration run with FROM=LATEST,STATE, ARCHIVE first requests all volumes on which all files were last saved. However, restoration only takes place from those volumes containing files to which the ORIGIN operand applies.

In the case of file generation groups (FGGs) it should be noted that the restoration of an FGG index with REPLACE=YES causes any existing file group with the same name to be completely deleted, but that only the file generations and the FGG index which had extents on the specified disks will be restored.
Generations on other disks which were thus lost must subsequently be restored individually.

ORIGIN = vsn / (vsn,...)
This specifies the volume serial numbers of private disks for volume-oriented restoration. Specification of public disks is not permitted.

ORIGIN = PUBLIC
This specifies public volumes for volume-oriented restoration.