Version 7.4.4
 —  Utilities  —

RESTONL FILES: Restore Files to Original RABNs from Online Source

The RESTONL FILES function restores files from a file or database SAVE dataset created while the Adabas nucleus was active . One or more files can be restored. The files are restored into an existing database to their original RABNs.

Notes:

  1. An interrupted RESTONL FILES operation must be reexecuted from the beginning. If the interruption occurred while RESTONL FILES was restoring the PLOG, the restore operation can be completed using the RESTPLOG function. Until successful completion or reexecution of the restore operation, the files to be restored are inaccessible.
  2. Checkpoint and security files from Adabas version 5 cannot be restored.

This document covers the following topics:


Conditions

Start of instruction setTo use the RESTONL FILES function, the following conditions must be met:

  1. The correct SAVE dataset must be supplied. It can be a database or file SAVE dataset and must contain the files to be restored. SAVE datasets from version 5.1 or above can be used.

  2. A file may be restored using a SAVE tape created from a different database; however, the device types must be identical.

  3. An existing database must be present. The files to be restored may have originated from this or from a different database.

  4. All RABNs originally used by the file(s) to be restored must either be free (available according to the free space table) or be occupied by files to be overwritten.

  5. The Adabas nucleus may be active or inactive on the output database.

    If the Adabas nucleus is active for restoring the checkpoint or security files, the ADASAV utility requires exclusive database control; that is, no user may be active on the database.

  6. The protection log (PLOG) dataset containing information written by the nucleus session at the time of the SAVE operation (see output of SAVE run) must be supplied. PLOG datasets from other sessions may also be included. If none of the files to be restored were modified during the online SAVE operation, the protection log dataset(s) can be omitted.

  7. If the SAVE tape was created with Adabas version 5.1, the location of the SYN1/SYN4 checkpoint written by the Adabas nucleus at the beginning of the online SAVE operation must be specified.

  8. If the SAVE operation was performed with the DRIVES parameter, the SAVE datasets created can also be restored with the DRIVES parameter. In that case, the restore operation is performed from the different SAVE datasets in parallel. Alternatively, the SAVE datasets can be concatenated to a single SAVE dataset for a restore operation without the DRIVES parameter.

  9. For restoring just a few files from a multivolume database SAVE dataset, only those tape volumes that actually contain data of the files to be restored need to be supplied in the ADASAV job control. The job protocol of the SAVE operation as well as the corresponding SYNV checkpoints indicate the files or parts of files contained on each volume.

  10. Expanded files and coupled files can only be restored or overwritten as a whole. That is, if one file in an expanded file is specified, all other files in the expanded file must be specified. If one file in a coupled relationship is specified, all other files in that relationship must be specified.

  11. A checkpoint, security, trigger, or user-defined system file can be overwritten only by another checkpoint, security, trigger, or user-defined system file, respectively. A checkpoint, security, or trigger file cannot be restored if such a file already exists in the database with a different file number.

  12. New file numbers can be assigned to the files to be restored using the NEWFILES parameter.

Top of page

Result

The result of this function is the specified files with the same physical status they had at the end of the ADASAV SAVE operation.

Top of page

Syntax

graphics/util_adasav_restonl_files.png

The FILES file list specifies the file or files to be restored. If the specified file is a component file of an Adabas expanded file, all other component files of the expanded file must also be specified here. If a specified file is coupled to other files, the coupled files must also be specified.

The file list specified need not correspond to a file list used in the corresponding SAVE function. A file list may be specified even if no file list was used for the corresponding SAVE function.

A file may also be restored using a SAVE tape created from a different database; however, the device types must be identical.

Top of page

Optional Parameters and Subparameters

ALLOCATION: Action to Follow File Extent Allocation Failure

ALLOCATION specifies the action to be taken if file extent allocations cannot be obtained according to the placement parameters ACRABN, DSRABN, NIRABN, or UIRABN.

ALLOCATION pertains to the implicit RABN specifications derived from the files on the save dataset.

By default (that is, ALLOCATION=FORCE), the utility terminates with error if any file extent allocation cannot be met according to RABN placement parameters.

If ALLOCATION=NOFORCE is specified and any allocation with placement parameters fails, the utility retries the allocation without the placement parameter.

Note:
An ADASAV RESTONL FILES operation with ALLOCATION=NOFORCE specified cannot be completed with RESTPLOG if the function fails after completing the restore from the save dataset but before completing the restore from the protection log.

BUFNO: Count of Buffers Per Drive

The BUFNO value, multiplied by the DRIVES parameter value, allocates fixed buffers for RESTONL operation. A value of 2 or 3 usually provides optimum performance; up to 255 is possible. A value greater than 5, however, provides little advantage and allocates a lot of space. The default is 1 (one buffer per drive).

DRIVES: Tape Drives for Parallel Restore

DRIVES is the number of tape drives to be used for parallel restore processing. The number can range 1 to 8, inclusively; the default is 1.

EXCLUDE: Exclude Specified Files from Restore

EXCLUDE lists the numbers of the files to be excluded from the restore operation; that is, the files that are not to be restored.

The parameter is optional: if not specified, no files are excluded. A file number may be listed only once.

If the NEWFILES parameter

The EXCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).

NEWFILES: New File Numbers

The NEWFILES parameter specifies the new file number to be assigned to each file specified by FILES.

The parameter is optional: if no new file number is assigned to a file, the file retains its original number.

NEWFILES may not be specified for expanded files, physically coupled files, or replicated files.

If a file with a number specified by NEWFILES already exists in the database, the corresponding file will not be restored unless the OVERWRITE parameter is also specified. If the file to be overwritten is password-protected, the corresponding PASSWORD parameter must also be specified.

If several files are to be restored, the list of file numbers in the NEWFILES parameter must correspond to the list of files in the FILES parameter. If no new file number is to be assigned to a file, its entry in the file number list of NEWFILES must be specified as zero. See the Examples.

NOUSERABEND: Termination without Abend

When an error is encountered while the function is running, the utility prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump).

If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

OVERWRITE: Overwrite Existing File

This parameter causes an existing file to be deleted and then restored. If a file which is to be restored is already present in the database, ADASAV will skip this file unless the OVERWRITE parameter is supplied.

Note:
To avoid unintentionally overwriting the database, Software AG recommends that you always specify the OVERWRITE parameter after, and not before, the FILES file list.

PASSWORD: File Password/Passwords

PASSWORD specifies one password or a list of passwords if one or more files in the FILES file list are password protected. This only applies to files already in the database that are to be overwritten. If the NEWFILES parameter is specified, the PASSWORD parameter must specify the passwords related to the new file numbers.

When restoring more than one password-protected file, the correct passwords must be specified as positional values corresponding to the protected file numbers' positions in the FILES list. Refer to the Examples for more information about the PASSWORD parameter. The Adabas nucleus must be active if password-protected files are being overwritten.

PLOGNUM: Protection Log Number

PLOGNUM specifies the number of the nucleus protection log (PLOG) used while the ADASAV SAVE operation was active (see output listing of the online SAVE function). This parameter is optional when restoring a SAVE tape created by ADASAV version 5.2 or above, or when none of the files to be restored were changed during the SAVE operation. Sequential protection (SIBA) logs from more than one nucleus session can be concatenated. ADASAV skips PLOGs with a number lower than the PLOGNUM value.

If PLOGNUM is not specified, ADASAV automatically determines the correct value from information stored in the SAVE dataset.

Note:
This is not possible when restoring from a version 5.1 SAVE dataset.

SYN1|SYN4: Starting Block Number

The block number containing the SYN1/SYN4 checkpoint at which the restore operation is to begin (refer to the output listing of the online SAVE function for the block number). When restoring a SAVE tape created by ADASAV version 5.2 or above, this parameter is optional.

If SYN1/SYN4 is not specified, ADASAV automatically determines the correct value from information stored in the SAVE dataset.

Note:
This is not possible when restoring from a version 5.1 SAVE dataset.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the operation. Only the syntax of the specified parameters can be tested; not the validity of values and variables.

Top of page

Examples

Example 1:

ADASAV RESTONL FILES=3,4,5, OVERWRITE
ADASAV      PASSWORD='PWDFIL3,,PWDFIL5'
ADASAV      PLOGNUM=15,SYN1=20

Files 3, 4, and 5 are to be restored. Files 3 and 5 are password-protected and their passwords are PWDFIL3 and PWDFIL5. The PLOG number is 15 and the block containing the SYN1 checkpoint is 20. The old files are to be overwritten.

Example 2:

ADASAV RESTONL FILES=11,12,13,14,OVERWRITE
ADASAV      NEWFILES=16,0,17

Files 11, 12, 13, and 14 are to be restored. Files 11 and 13 are to be restored as files 16 and 17, respectively. The file numbers of files 12 and 14 will not be changed because the corresponding NEWFILES parameter values are specified as zero or omitted. Files 12, 14, 16, and 17 are to be overwritten, if already present in the database.

Top of page