The RESTORE statement restores files, file blocks, job variables or catalog entries that were saved to tape or disk in a SAVE run.
The files and/or job variables to be processed have to be specified in FILES and/or JOBVAR statements before the RESTORE statement is entered.
R[ESTORE] |
DIR[ECTORY] = $TSOS.ARCHIVE.DIR / filename / NONE ,FR[OM] = LATEST[,STATE] / date[.time][,STATE] / svid[,STATE,date[.time]] / [svid,][(vsn,...),...] ,CONSISTENCY-CHECK / CONS-CHK = NO / YES ,REP[LACE] = NO / YES / ALL / ALLP ,NOW = YES / NO[,TIME = sec] |
DIRECTORY =
The user specifies here whether a directory file is to be used for writing back, and if so which one.
DIRECTORY = $TSOS.ARCHIVE.DIR / filename
The name of the directory file that was used in the save run.
DIRECTORY = NONE
No directory file is to be used for this run. The VSNs are to be taken from the FROM operand.
If a directory file is being used, a file with the same name as the directory file will not be restored in the RESTORE run.
A RESTORE run can also be performed with a systems support directory file under the TSOS user ID if the directory file is password-protected and the password has not been entered.
FROM =
This specifies the input volumes or save version from which the files or job variables are to be read.
If no directory file is used, i.e. DIRECTORY=NONE is specified, the VSNs of the volumes must be specified.
If VSNs are specified, the volumes must all be from the same save version and grouped according to the parallel runs. Consequently, the number of parallel runs must not exceed the number of groups of volumes.
FROM = LATEST
Each file or job variable requested is read in from the last save version containing it. A directory file must be specified for this.
FROM = LATEST,STATE
As for LATEST, but only the files and/or job variables which were saved in the last save run performed with this directory file or which are marked CNS (cataloged but not saved) are read in. Files or job variables which at the time of this save run have already been deleted, or which have been excluded by means of the EXCEPT operand, are not read in. Specification of a directory file is mandatory.
FROM = date.time
The requested files or job variables are read in from the last save version created before or at this time which contains these files.
Default value for time: 235959
A directory file must be specified.
FROM = date.time,STATE
As above. Here, however, only those files or job variables are read in which were saved in the very last version of the directory file before or at this time, or which are marked as CNS (Cataloged Not Saved). Files or job variables which have already been deleted or have been excluded by means of the EXCEPT operand are not read in.
A directory file must be specified.
FROM = svid,STATE,date.time
Every file requested in the FILES statement or job variable requested via the JOBVAR statement which is contained in this save version is read in. Files or job variables, however, which were saved again between the specified save version and the time given (both inclusive) are not restored.
date.time is rendered in the format yymmdd.hhmmss. Default value for time: 235959.
A directory file must be specified.
FROM = (vsn,...)
Every required file or job variable on the specified volumes is written back.
The volumes must be listed in the order in which they were recorded during the save run. If a directory file is used, only those files located in their entirety on the specified volumes are read in.
FROM = (vsn,...),(vsn,...)
When files or job variables saved in parallel runs are restored, the volumes must be grouped according to the parallel runs, i.e. the volumes of a parallel run must be specified in each parentheses in the order in which they were recorded.
Data which was saved using
FILES SAVE ...,DRIVES=2,TAPES=(vsn1,vsn2),
and distributed according to the EXPORT listing in two parallel runs over vsn1 and vsn2, must be restored using
FILES RESTORE ...,DRIVES=2,FROM=(vsn1),(vsn2).
A restoration run implemented via
RESTORE ...,DRIVES=2,FROM=(vsn1,vsn2)
causes the run to abort, as ARCHIVE cannot allocate the volumes correctly.
FROM = svid
All the required files or job variables contained in the specified save version are restored. A directory file must be specified.
FROM = svid,(vsn,...),...
As above.
In addition, if a directory file has been specified, a check is made to see whether the specified volumes belong to this save version. If this is not the case, the run is aborted.
DEVICE = TAPE-C4 / device type
The device type is specified via this operand. It must be the same as the one used for the save run. The DEVICE operand defines the device type for all the VSNs, including those specified indirectly, e.g. in FROM=svid.
If a directory file is specified, the device type is taken from the save version of the directory file.
DRIVES = 1 / integer
This specifies the number of parallel runs (up to 16). As many parallel runs should be specified as were defined for the associated SAVE run.
CONSISTENCY-CHECK / CONS-CHK =
This determines whether a consistency check of the save data is carried out.
CONSISTENCY-CHECK = NO
No consistency check is carried out.
CONSISTENCY-CHECK = YES
Before transferring save data, the check bytes are calculated and a comparison is made with the check bytes stored with the save data in EXPORT. If an error occurs, the message ARC0413 is output.
This operand value is ignored if the EXPORT or SAVE operations were carried out with the CONSISTENCY-CHECK=NO operand.
REPLACE =
This specifies whether or not existing files and job variables with the same names are to be replaced.
REPLACE = NO
A file or job variable is not read in if one already exists with the same name; in this case a message is issued.
REPLACE = YES
If a file or job variable with this name exists, it is replaced by the file or job variable from the save run.
However, a file or job variable is not replaced if:
only read access is permitted for it
it has an expiration date (EXPIR DATE) in the catalog which is later than the current date
it is protected by a password which has not been specified.
REPLACE = ALL
If a file or job variable with the same name already exists, it is replaced by the saved file or job variable. The file or job variable is replaced even if only read access is permitted for it or the expiration date has not yet been reached. However, if the existing file is protected by a password, this password must be specified.
REPLACE = ALLP
This operand can only be specified under the ID of the system support. It enables files or job variables protected by passwords to be replaced by the corresponding files from the save run, without the passwords having previously been specified. Otherwise the same applies to the ALLP operand as to ALL.
SPACE =
This specifies whether or not the files which are to be replaced by files with the same names from the save run are to be deleted before restoration.
The operand is not interpreted for migrated files.
SPACE = REORG
Files to be replaced by files with the same names from the save run are deleted before restoration. Usually the file then occupies a different extent after restoration. Thus restoration runs with SPACE=REORG have the effect of reorganizing the disks.
SPACE = KEEP
Files to be replaced by files with the same names from the save run are overwritten in the extents which they occupy at the time of the restoration.
The specification SPACE=KEEP overrides any definitions of the storage area for the file being restored.
Example
The file HUGO is to be written back with SPACE=KEEP. Let us assume that there is already a file of this name on the private disk PRIV01. If TO=PUBLIC is then specified for this run in the FILES statement, ARCHIVE still writes the file back to the private disk PRIV01. In other words the specification SPACE=KEEP overrides the specification TO=PUBLIC.
The specifications in the SPACE operand are ignored if REPLACE=NO has also been specified.
The specifications in the SPACE operand are ignored for file generation groups. FGGs are deleted before writing back takes place.
The following points must be borne in mind for ISAM files with a separate file index section and file data section:
The file in the system must have the same logical structure as the saved file, i.e. the index blocks and data blocks must occupy the same logical blocks.
The access method (ACCESS-METHOD) must be ISAM.
The SPACE operand is irrelevant for catalog entries for tape files. When REPLACE=YES is specified, catalog entries are always deleted.
CONVERSION =
This operand controls whether files which had a PAM key when they were saved must be converted if the output volume is an NK4 disk.
This operand is ignored for job variables.
Entering CONVERSION=STD
/ CONV requires the PAMINT subsystem.
In the case of partially saved files, only CONVERSATION=NO / CONV may be specified.
If a conversion file which is to be imported already exists, it is always reorganized; the SPACE operand is ignored.
CONVERSION = STD
In RESTORE runs to an NK disk, files with PAM keys are converted by means of PAMINT in accordance with the following rules:
K-ISAM files to NK-ISAM files
(BLOCK-CONTROL-INFO=WITHIN-DATA-BLOCK)
K-SAM files to NK-SAM files
(BLOCK-CONTROL-INFO=WITHIN-DATA-BLOCK)
K-UPAM files to NK-UPAM files
(BLOCK-CONTROL-INFO=NO)
PAM files whose structure is known (load modules, libraries) are converted accordingly (e.g. LMR libraries to PLAM libraries). In the case of PAM files whose structure is not known, the PAM key information is lost. If the PAM key contained any information, an appropriate message is displayed.
CONVERSION = NO
Files with a PAM key are not converted in RESTORE runs to an NK disk and are thus not restored.
CONVERSION = CONV
In a RESTORE run to an NK disk, files with PAM keys are converted to “CONV format” by means of PAMINT. The restored file contains all the PAM keys at the end of the file in separate blocks.
If a file has to be converted in a RESTORE run, the SPACE operand has no effect: the file to be replaced is deleted before it is restored.
ENVIRONMENT-ATTRIBUTES =
This specifies how the attributes of files and job variables protected by BACL or GUARDS are to be processed during a RESTORE for a save file (see section "File attribute handling"). This save file was created with SAVE with simultaneous renaming of the catalog ID or user ID.
ENVIRONMENT-ATTRIBUTES = FROM-TARGET
The attributes for access protection are reset to match the status of the target file or job variable.
ENVIRONMENT-ATTRIBUTES = FROM-ORIGIN
The attributes for access protection are taken from the save file. If the user ID has been renamed, this value can only be specified by a user with the TSOS privilege.
NOW =
This operand specifies when the statement is to be executed.
NOW = YES
The RESTORE statement is executed immediately.
NOW = NO
The RESTORE statement is checked for correct syntax and then written to the queue file ARCHIVE.LATER. This process is given the ARCHIVE identifier L.yymmdd.hhmmss. The identifier is only allocated if no LATER job exists in the same task at the time If this is not the case, then the process is stored under the existing identifier.
The LATER job can be started by means of a PROCESS statement or deleted by means of a DELETE statement.
NOW = NO,TIME=sec
The number of CPU seconds that are available to this process when it is started. This entry corresponds to the operand CPU-LIMIT in /START-(EXECUTABLE-)PROGRAM.
PASSWORD = password / (password,...)
If you specify the NOW=NO operand, you must enter here the passwords for
files or job variables to be imported which are protected by read passwords.
the directory file, if it is protected by a write password and is not under TSOS.
the save version, if it has been protected by a password with SVPASS.
magnetic tapes and MT cartridges that are protected by a password (up to 4 characters) under MAREN.
In all other cases, you should specify the passwords with the /ADD-PASSWORD command before you call ARCHIVE. Only in this case are the passwords also valid for the subsequent ARCHIVE runs of the same user job.
The system support can process files and job variables without specifying the passwords. The password for the directory file, however, must be specified if the directory file is assigned under another user ID.
LIST =
This defines the output medium for the report of this ARCHIVE run.
LIST = SYSLST
The report is output to SYSLST.
LIST = SYSOUT
In interactive mode, the report is output to the terminal.
LIST = BOTH
The report is output to both SYSLST and SYSOUT.
LIST = NONE
No report is generated.
LIST = ...,ALL
All the file names on the volumes read in are listed. If a save version (svid) is also specified in the FROM operand, all the file names belonging to this save version are listed (not only those specified in the FILES/JOBVAR statements).
Notes on RESTORE
If a requested file that has only been partially saved (operand CHANGED=YES,LARGE or CHANGED=YES,integer in the save run), ARCHIVE proceeds in the following manner:
If the operand
FROM=LATEST[,STATE]orFROM=date.time[,STATE]is specified, ARCHIVE will automatically first read the whole file from the full save associated with the partial save and then the modified pages from the partial save.Any other entry in the FROM parameter causes ARCHIVE to read only the partial save for such a file, i.e. the pages modified since the associated full save. Consequently, in order to obtain correct results, the user himself must ensure that this file exists prior to the RESTORE run and that it has the status that was current at the time of the associated full save.
The restore of a file is rejected with an error message, if the corresponding user ID is missing.
With an optional rep the missing user ID is created for an administrator restore and the file gets restored.