FILES Select files in save runs

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

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

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

The way in which ARCHIVE processes the FILES statements and NAME operands is described in detail in the section "Parallel and serial processing".

F[ILES]

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

[,FR[OM] = { PUBLIC / PRDISC / PRTAPE / vsn / (vsn,...) /
                     svid[,(vsn,...),...],DEVICE = TAPE-C4 / device type /
                     SV,(vsn,...),...,DEVICE =TAPE-C4 / device type } ]

NAME =
The files to be saved 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:

  No catalog ID may be entered, since the statement will otherwise be rejected. Only the catalog of the default pubset of the relevant user ID is searched.

  If the NAME operand is omitted:

  • All files which are cataloged in the default pubset of the user ID are saved.

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

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

  A catalog ID can be specified in the file name. If no catalog ID is specified, the catalog ID of the default pubset of the relevant user ID is added to the file name.
  It is also possible to specify only the catalog ID (e.g. NAME=:c:), in which case all files belonging to the user ID and under the specified catalog ID are saved.

  If the NAME operand is omitted:

  • All files under the relevant user ID on all available pubsets on which this ID is entered are saved.

  • If the user has the TSOS privilege, all cataloged files of all locally imported pubsets are saved. When copying save data, all the user's files are copied.
    If the user has the TSOS privilege, all saved files are copied. 

  If only the catalog ID is specified, then:

  • All files of the related user ID are saved with the specified catalog ID.All cataloged files with the specified catalog ID are saved with the TSOS privilege.

  • When saved files are copied, all of the user's files with the specified catalog ID are copied.
    If the user has the TSOS privilege, all saved files of all user IDs with the specified catalog ID are copied.

  If, however, a fully or partially qualified file name is specified with the TSOS privilege, then:

  • Only the files with the specified catalog ID (default: default catalog ID) from the user ID TSOS are saved.

NAME = filename
If you are not working with the TSOS privilege, you can process shareable files belonging to other users with EXPORT if the operand ATTRIBUTES=RESET is specified.

NAME = (filename,...)
A series of 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).

Notes

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

• 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.

NAME = (filename,RENAME=filename)
You can rename files with the RENAME operand. This operand is supported only for EXPORT runs without a directory (DIRECTORY=NONE) and for disk files.
It is not valid for catalog entries which have been saved with CATONLY=YES or for file generations.

For a renamed file, the entry ERASE=YES (ALL, ALLP, ...) is ignored with a warning message. The file is exported but not deleted.

The name in the RENAME operand replaces the original name (NAME=...).
If the name is partially qualified, only the part which is specified is modified.
If ARCHIVE is not running with the TSOS privilege, only files under the user's own ID can be renamed.
If the RENAME specification would result in an invalid DMS file name, it is rejected.

It is sound practice to start EXPORT runs with RENAME using PARAM CATID=NO; in this case, specification of a catalog ID is not permitted.

If files of several pubsets are to be exported using PARAM CATID=YES, the following applies:

• If a catalog ID :c: is specified (filename, RENAME=:c:filename) in a new file name, all addressed files with the standard catalog ID of the user ID in question are written to the EXPORT volume using the catalog ID :c:.

• If a catalog ID :c: is specified in the old file name (:c:filename, RENAME=filename), all files concerned are written to the EXPORT volume using the same catalog ID :c:.

It is possible to specify user IDs instead of the file names ($userid1., RENAME=$userid2.). The following applies to runs with PARAM CATID=YES.

• All files under the current standard catalog ID of $userid1 are written to the EXPORT volume with $userid2.

ARCHIVE does not check the new catalog and user IDs.

EXCEPT = filename, / (filename,THRU=filename)
This defines files or file ranges to be excluded from the files listed in the NAME operand. An EXCEPT operand refers to the immediately preceding NAME operand.

An EXCEPT operand not preceded by a NAME operand refers to all the files under the user ID and, if the user has the TSOS privilege, to 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.

If systems support want to exclude files from other user IDs, they also need to specify these user IDs.

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

This sequence of statements is not the same as the statement

*FILES EXCEPT=(HUGO1,HUGO2,HUGO7);

it causes all the files under the user ID(s) in question to be saved three times, namely:

• 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



FROM =
The FROM operand specifies the input volumes or save version from which the files are to be read.
If you do not specify FROM, all files from all pubsets and private disks which are specified in the NAME operand and all catalog entries are saved which refer to files on tapes and tape cartridges.

FROM = PUBLIC
Only those files specified in the NAME operand and residing on public volumes are saved.

FROM = PRDISC
Only those files are saved which are specified in NAME and which are on private disks.

FROM = PRTAPE
Only the catalog entries of those files are saved which are specified in the NAME operand and which are on private tapes, regardless of the CATONLY operand.
For entries of file generation groups, however, CATONLY=YES must be specified.
In the case of ERASE=YES (or ALL...), only the catalog entry is deleted.
RENAME is not permitted.

FROM = vsn / (vsn,...)
This determines the volumes on which the files reside.

Disks:
only those files specified in the NAME operand and having at least one extent on the specified VSNs are saved.

Tapes and MT cartridges:
specifying a tape VSN is meaningful only in runs with CATONLY=YES (i.e. only the catalog entries of the files residing on that tape or MT cartridge are saved).

FROM = svid[,(vsn,...),...][,DEVICE = TAPE-C4 / device type]
This form of the FROM operand is used to copy save data from ARCHIVE save runs. vsn,... designates the volumes containing the ARCHIVE save runs.

If the svid to be copied was performed with the directory file specified in the DIRECTORY operand, it is sufficient to specify “svid”. If, however, no directory file is available but the svid's of the volumes are known, the operand svid,(vsn,...)[,DEVICE=type] is used. The DEVICE operand need only be specified when saving was to tape or MT cartridge.

The DEVICE operand may be omitted if a directory file is specified.

FROM = SV,(vsn,...),...[,DEVICE = TAPE-C4 / device type]
This form of the FROM operand is used to copy the ARCHIVE save data in whole or in part when the svid is unknown.
The DEVICE operand need only be specified if saving was to tape or MT cartridge.

Volumes specified in the VSN list must have been defined in the same save version. The VSNs must be specified in the same order as the parallel runs when no directory file is being used.

No directory file should be used when copying save data. When copying with a directory file the copy run would be entered in the directory file as the most recent save version. This might result in an unacceptably old version of a file being restored during a subsequent restoration with FROM=LATEST.

Only those files are copied which have been saved in their entirety to the VSNs specified. Exception:When the beginning of a file is on a volume with a specified VSN, the continuation tape is missing and the run was executed without a directory file.