The RESTORE FMOVE function restores files from a file or database SAVE dataset created while the Adabas nucleus was inactive, or from a file SAVE dataset created with UTYPE=EXU. One or more files can be restored. The files are restored into an existing database to any free space. Their extent sizes may be changed.
Notes:
This document covers the following topics:
To use the RESTORE FMOVE function, the following conditions must be
met:
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 Adabas version 5.1 or above can be used.
An existing database must be present. The files to be restored may have originated from this or from a different database.
The FMOVE file list specifies a file or files to be restored using new RABNs (and sizes). The RABNs must be located on the same device type as used originally for the respective files. Files can be restored into other than the original database as long as device types are identical.
For the file(s) to be restored, sufficient space, either free space (according to the free space table) or space occupied by files to be overwritten, must be available in the database.
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.
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.
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.
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.
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.
New file numbers can be assigned to the files to be restored using the NEWFILES parameter.
The result of this function is the specified files with the same contents they had at the time of the ADASAV SAVE operation but not necessarily in the same database blocks.
The FMOVE file list specifies a file or files to be restored using new RABNs (and sizes).
For an Adabas expanded file, all component files of the expanded file including the anchor file must be specified. If a specified file is coupled to other files, the coupled files must also be specified.
The RABNs must be located on the same device type as used originally for the respective files. Files can be restored into other than the original database as long as device types are identical.
ACRABN specifies the starting address converter RABN for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
If FMOVE is specified and ACRABN omitted, the location of the address converter is chosen by ADASAV from the free areas in the Associator that have the same device type as used originally.
If several files are to be restored, the list of RABNs in the ACRABN parameter must correspond to the list of files in the FMOVE parameter. If no ACRABN value is to be given for a file, its entry in the RABN list must be specified as zero. See the examples .
ALLOCATION specifies the action to be taken if file extent allocations cannot be obtained according to the placement parameters ACRABN, DSRABN, NIRABN, or UIRABN.
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:
The value for ASSOVOLUME must be enclosed in apostrophes.
ASSOVOLUME identifies the volume on which the file's Associator space (that is, the AC, NI, and UI extents) is to be allocated. If the requested number of blocks cannot be found on the specified volume, ADASAV retries the allocation while disregarding the ASSOVOLUME parameter.
If ACRABN, UIRABN, or NIRABN is specified, ADASAV ignores the ASSOVOLUME value when allocating the corresponding extent type. If ASSOVOLUME is not specified, the file's Associator space is allocated according to ADASAV's default allocation rules.
If several files are to be restored, the list of volumes in the ASSOVOLUME parameter must correspond to the list of files in the FMOVE parameter. If no volume is to be given for a file, its entry in the volume list must be left empty. See the examples on page 59.
The BUFNO value allocates fixed buffers for RESTORE 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).
Note:
The value for DATAVOLUME must be enclosed in apostrophes.
DATAVOLUME specifies the volume on which the file's Data Storage space (DS extents) is to be allocated. If the number of blocks requested with DSSIZE cannot be found on the specified volume, ADASAV retries the allocation while disregarding the DATAVOLUME value.
If DSRABN is specified, DATAVOLUME is ignored for the related file. If DATAVOLUME is not specified, the Data Storage space is allocated according to ADASAV's default allocation rules.
If several files are to be restored, the list of volumes in the DATAVOLUME parameter must correspond to the list of files in the FMOVE parameter. If no volume is to be given for a file, its entry in the volume list must be left empty. See the examples.
ADASAV is able to restore files from multiple save dataset volumes in parallel to RABNs that are different from their original RABNs in the database. 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.
DSRABN specifies the starting Data Storage RABN for each file specified by FMOVE. DSRABN can only be used in conjunction with the FMOVE parameter.
If FMOVE is specified and DSRABN omitted, the location of the file's Data Storage is chosen by ADASAV from the free areas in Data Storage that have the same device type as used originally.
If several files are to be restored, the list of RABNs in the DSRABN parameter must correspond to the list of files in the FMOVE parameter. If no DSRABN value is specified for a file, its entry in the RABN list must be specified as zero. See the examples.
DSSIZE is the new size to be allocated for Data Storage for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending "B" to the number). It must be at least as large as the used area of the original Data Storage.
If DSSIZE is omitted, the original Data Storage size is used.
If several files are to be restored, the list of sizes in the DSSIZE parameter must correspond to the list of files in the FMOVE parameter. If no size is to be given for a file, its entry in the size list must be specified as zero. See the examples.
If specified, EXCLUDE lists the numbers of the files to be excluded from the restore operation; that is, the files that are not to be restored. A file number may be listed only once.
If not specified, no files are excluded.
If the NEWFILES parameter
is not specified, all files specified in the EXCLUDE parameter must also be specified in the FMOVE parameter.
is specified, all files specified in the EXCLUDE parameter must also be specified in the NEWFILES parameter. In this case, the file numbers specified in the EXCLUDE parameter refer to the new file numbers in NEWFILES, not to the old file numbers in the FMOVE parameter.
The EXCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI).
MAXISN is the new number of ISNs to be allocated for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter. The value must be at least as large as the original highest allocated ISN (MAXISN).
If MAXISN is omitted, the original ISN count is used.
If several files are to be restored, the list of ISN counts in the MAXISN parameter must correspond to the list of files in the FMOVE parameter. If no ISN count is to be given for a file, its entry in the ISN count list must be specified as zero. See the examples.
The NEWFILES parameter specifies the new file number to be assigned to each file specified by FMOVE.
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 FMOVE 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 .
NIRABN specifies the starting RABN for the normal index for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
If FMOVE is specified and NIRABN omitted, the location of the normal index is chosen by ADASAV from the free areas in the Associator that have the same device type as used originally.
If several files are to be restored, the list of RABNs in the NIRABN parameter must correspond to the list of files in the FMOVE parameter. If no NIRABN value is to be given for a file, its entry in the RABN list must be specified as zero. See the examples .
NISIZE is the new size to be allocated for the normal index for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending "B" to the number). It must be at least as large as the used area of the original normal index.
If NISIZE is omitted, the original normal index size is used.
If several files are to be restored, the list of sizes in the NISIZE parameter must correspond to the list of files in the FMOVE parameter. If no size is to be given for a file, its entry in the size list must be specified as zero. See the examples .
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.
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 FMOVE file list.
PASSWORD specifies one password or a list of passwords if one or more files in the FILES or FMOVE 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 positions of the protected file numbers in the FILES or FMOVE list. Refer to the examples for more information about the PASSWORD parameter. When overwriting password-protected files, the Adabas nucleus must be active.
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.
UIRABN specifies the starting RABN for the upper index for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
If FMOVE is specified and UIRABN omitted, the location of the upper index is chosen by ADASAV from the free areas in the Associator that have the same device type as used originally.
If several files are to be restored, the list of RABNs in the UIRABN parameter must correspond to the list of files in the FMOVE parameter. If no UIRABN value is to be given for a file, its entry in the RABN list must be specified as zero. See the examples.
UISIZE is the new size to be allocated for the upper index for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending "B" to the number). It must be at least as large as the used area of the original upper index.
If UISIZE is omitted, the original upper index size is used.
If several files are to be restored, the list of sizes in the UISIZE parameter must correspond to the list of files in the FMOVE parameter. If no size is to be given for a file, its entry in the size list must be specified as zero. See the examples.
ADASAV RESTORE FMOVE=4,6, ACRABN=0,3820, MAXISN=0,2000000
Three tape drives are available for parallel RESTORE processing. Files 4 and 6 are to be restored with new RABNs. The space allocation for file 4 is to be done using original sizes.
The address converter for file 6 is to begin at Associator RABN 3820, and the value for the file's MAXISN is to be increased to 2,000,000.
ADASAV RESTORE FMOVE=3,4,5, OVERWRITE ADASAV PASSWORD='PWD3,,PWD5'
Files 3, 4 and 5 are to be restored. If they already exist in the database, they are overwritten. Passwords are provided for files 3 and 5 to allow them to be overwritten. All original size values are used. The files might be restored to other than the original RABNs.
ADASAV RESTORE FMOVE=1,2 ADASAV FMOVE=3,4
Restore files 1 through 4.
ADASAV RESTORE FMOVE=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.
