The RESTONL FMOVE function restores files from a file or database SAVE data set created while the Adabas nucleus was active. 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 RESTONL FMOVE function, the following conditions must be
met:
The correct SAVE data set must be supplied. It can be a database or file SAVE data set and must contain the files to be restored. SAVE data sets 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 the file or files to be restored using new RABNs. The RABNs must be located on the same device type as used originally.
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.
The protection log (PLOG) data set containing information written by the nucleus session at the time of the SAVE operation (see output of SAVE run) must be supplied. PLOG data sets 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 data set(s) can be omitted.
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.
If the SAVE operation was performed with the DRIVES parameter, the SAVE data sets created can also be restored with the DRIVES parameter. In that case, the restore operation is performed from the different SAVE data sets in parallel. Alternatively, the SAVE data sets can be concatenated to a single SAVE data set for a restore operation without the DRIVES parameter.
For restoring just a few files from a multivolume database SAVE data set, 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 end of the ADASAV SAVE operation but not necessarily in the same database blocks.
The FMOVE file list specifies one or more Adabas file numbers or a range
of file numbers to be restored using new RABNs. The RABNs must be located on
the same device type as used originally. Ranges of file numbers should be
specified using a dash (-) in the format:
fnfirst-fnlast.
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. If a specified file is coupled to other files, the coupled files must also be specified.
ACRABN specifies the starting address converter RABN for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
Note:
The ACRABN parameter is not allowed if a range of files is
specified in 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.
AC2RABN specifies the starting secondary address converter RABN for each file specified by FMOVE. It can only be used in conjunction with the FMOVE parameter.
Note:
The AC2RABN parameter is not allowed if a range of files is
specified in the FMOVE parameter.
If FMOVE is specified and AC2RABN omitted, the location of the secondary address converter is chosen by ADASAV from the free areas in the Associator that have the same device type as used originally. If the file contains no secondary address converter extents, this parameter is ignored.
If several files are to be restored, the list of RABNs in the AC2RABN parameter must correspond to the list of files in the FMOVE parameter. If no AC2RABN value is to be given for a file, its entry in the RABN list must be specified as zero.
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.
Note:
The ASSOVOLUME parameter is not allowed if a range of files is
specified in the FMOVE 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 .
The BUFNO 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).
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.
Note:
The DATAVOLUME parameter is not allowed if a range of files is
specified in the FMOVE parameter.
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 data set 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.
Note:
The DSRABN parameter is not allowed if a range of files is
specified in 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.
Note:
The DSSIZE parameter is not allowed if a range of files is
specified in the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending a "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.
EXCLUDE lists the numbers of the files to be excluded from the
restore operation; that is, the files that are not to be restored. This list
can include a list of more than one Adabas file number or a range of file
numbers. Ranges of file numbers should be specified using a dash (-) in the
format:
fnfirst-fnlast.
The parameter is optional: if not specified, no files are excluded. A file number may be listed only once individually or in a range.
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.
Note:
The MAXISN parameter is not allowed if a range of files is
specified in 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.
If the database consists of several Associator extents with different device types, ERROR-171 may occur if MAXISN is specified and the nucleus allocated an additional address converter extent during the online save operation. If this happens, remove the MAXISN parameter for the file indicated in the error message and rerun RESTONL FMOVE.
MAXISN specifies the desired size of the secondary address converter (AC2) in ISNs. It can only be used in conjunction with the FMOVE parameter. The secondary address converter is used to map secondary ISNs of secondary spanned records to the RABNs of the Data Storage blocks where the secondary records are stored.
Note:
The MAXISN2 parameter is not allowed if a range of files is
specified in the FMOVE parameter.
The value must be at least as large as the original highest allocated ISN (MAXISN2).
If MAXISN2 is omitted, the original ISN count is used. If the file contains no secondary address converter extents, this parameter is ignored.
If several files are to be restored, the list of ISN counts in the MAXISN2 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.
If the database consists of several Associator extents with different device types, ERROR-171 may occur if MAXISN2 is specified and the nucleus allocated an additional address converter extent during the online save operation. If this happens, remove the MAXISN2 parameter for the file indicated in the error message and rerun RESTONL FMOVE.
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.
Note:
The NEWFILES parameter is not allowed if a range of files is
specified in the FMOVE parameter.
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.
You can use NEWFILES to renumber a base file or LOB file only if both files of the LOB file group are restored. In this case, ADASAV assigns both files the new file numbers specified by the NEWFILES parameter and adjusts the links between the two files accordingly. However, if only one file of a LOB file group is restored, it cannot be assigned a new file number using the NEWFILES parameter; use the ADADBS or AOS RENUMBER function instead.
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.
Note:
The NIRABN parameter is not allowed if a range of files is
specified in 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.
Note:
The NISIZE parameter is not allowed if a range of files is
specified in the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending a "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 a parameter error or a functional error occurs while this utility function is running, the utility ordinarily 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.
Note:
When NOUSERABEND is specified, we recommend that it be specified
as the first parameter of the utility function (before all other parameters).
This is necessary to ensure that its parameter error processing occurs
properly.
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 protected file numbers' positions 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.
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 data set.
Note:
This is not possible when restoring from a version 5.1 SAVE data
set.
READONLY indicates whether the read-only status is on or off for a file or a list of files. Valid values for this parameter are "YES" (read-only status is on) and "NO" (read-only status is off).
When restoring more than one file, the read-only status must be specified as positional values corresponding to the file number positions in the FILES list.
If READONLY is not specified, the read-only status of the file will be the same as it was on the SAVE data set.
Note:
The READONLY parameter is not allowed if a range of files is
specified in the FMOVE parameter.
RPLACTIVE is an optional parameter that specifies the inactive flag setting for a file during restore processing. Valid inactive flag settings are "YES", "NO", or no setting at all. A setting of "YES" turns off the replication inactive flag (YFSTQRPI) for a file. A setting of "NO" turns on the replication inactive flag.
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
If no setting is specified, the default value is used. The default depends on the target database ID of the restore processing and its replication state. If any of the following conditions are met, the default is "YES"; otherwise the default is "NO":
The original replication is turned off.
The restore DBID is not the same as the original saved DBID.
The original replication target ID has been changed.
The original replication-before-image has been changed.
The replication primary key has changed.
The original replication is turned off.
When restoring more than one file, the correct RPLACTIVE settings must be specified as positional values corresponding to the file numbers' positions in the FILES list. For example, if four files are listed in the FILES file list, the following might be the setting for the RPLACTIVE parameter:
RPLACTIVE='YES,NO,,YES'
In this example, the inactive flag is turned off (YES) for the first and fourth files and turned on (NO) for the second file. No value is provided for the third file, so an default appropriate for the file is used.
RPLDATA is an optional parameter that indicates whether the data in a file should be replicated to the replication target ID (RPLTARGETID parameter).
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
Valid replication settings are "YES", "NO", "CREATE", or no setting at all. A setting of "YES" causes the restore function to replicate the file data to the replication target during restore processing. A setting of "NO" will not replicate the data to the replication target during restore processing. A setting of CREATE causes the restore function to replicate the file data to the replication target during restore processing, but also sends a "create file" transaction to the replication target. If no setting is specified, the default "NO" is used.
Note:
Values of "YES" or
"CREATE" can only be specified if replication is
turned on for the corresponding file.
When restoring more than one file in the FILE file list, the RPLDATA settings must be specified as positional values corresponding to the file numbers' positions in the FILES list. For example, if four files are listed in the FILES file list, the following might be the setting for the RPLACTIVE parameter:
RPLDATA='YES,NO,,YES'
In this example, the data in the first and fourth files (YES) will be replicated to the replication target, but it will not be replicated for the second and third files (NO and no setting for the third file).
RPLDSBI is an optional parameter that indicates whether the collection of before images of data storage should occur for an update command to a file.
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
Valid RPLDSBI settings are "YES", "NO", or no setting at all. A setting of "YES" indicates that the collection of before images of data storage will occur for the file during restore processing. A setting of "NO" indicates that the collection of before images of data storage will not occur for the file during restore processing.
If no setting is specified, the default value is used. The default depends on the target database ID of the restore processing and its replication state. If the restore DBID is the same as the originally saved DBID and REPLICATION=YES in the target DBID, the default is "YES"; otherwise the default is "NO".
Note:
A values of "YES" can only be specified
if replication is turned on for the corresponding file.
When restoring more than one file in the FILE file list, the RPLDSBI settings must be specified as positional values corresponding to the file numbers' positions in the FILES list. For example, if four files are listed in the FILES file list, the following might be the setting for the RPLDSBI parameter:
RPLDSBI='YES,NO,,YES'
In this example, the before images are collected for the first and fourth files (YES), but are not collected for the second file (NO). No value is provided for the third file, so an default appropriate for the file is used..
RPLKEY is an optional parameter that specifies the primary key for replication. Valid RPLKEY settings are a two-character field name, "OFF", or no setting at all. Specifying a field name identifies that field as the primary key for replication. A setting of "OFF" indicates that no primary key should be used for replication.
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
If no setting is specified, the default value is used. The default depends on the target database ID of the restore processing and its replication state. If the restore DBID is the same as the originally saved DBID and REPLICATION=YES in the target DBID, the original RPLKEY value for the file is used; otherwise the default is "OFF".
Note:
A primary key can only be set if replication is turned on for the
file and if the field name is a valid Adabas field according to the field
definition table (FDT) for the file. When a new RPLKEY is specified it will not
be confirmed as a valid Adabas field until the end of the ADASAV run. At that
time, if any RPLKEY is found to be invalid, a warning message is issued, the
RPLKEY is set to "OFF", and condition code 8 is
returned.
When restoring more than one file in the FILE file list, the RPLKEY settings must be specified as positional values corresponding to the file numbers' positions in the FILES list. For example, if four files are listed in the FILES file list, the following might be the setting for the RPLKEY parameter:
RPLKEY='AA,BB,,OFF'
In this example, field AA is used as the replication primary key for the first file, BB is used as the replication primary key for the second file, and no replication primary key is used for the fourth file (OFF). No value is provided for the third file, so an default appropriate for the file is used..
RPLTARGETID is an optional parameter that specifies the target ID of the Event Replicator Server to which the restored transactions should be sent.
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
Valid RPLTARGETID settings are a valid target ID, "OFF", or no setting at all. Specifying a target ID identifies that as the target for replication. A setting of "OFF" or "0" indicates that no replication target should be used for replication.
If no setting is specified, the default value is used. The default depends on the target database ID of the restore processing and its replication state. If the restore DBID is the same as the originally saved DBID and REPLICATION=YES in the target DBID, the original RPLTARGETID value for the file is used; otherwise the default is "OFF".
Note:
A replication target ID can only be specified if replication is
turned on for the file.
When restoring more than one file in the FILE file list, the RPLTARGETID settings must be specified as positional values corresponding to the file numbers' positions in the FILES list. For example, if four files are listed in the FILES file list, the following might be the setting for the RPLTARGETID parameter:
RPLTARGETID='23,24,,OFF'
In this example, target ID 23 is used as the replication target for the first file, 24 is used as the replication target for the second file, and no replication target is used for the fourth file (OFF). No value is provided for the third file, so an default appropriate for the file is used..
The RPLUPDATEONLY parameter can be used in the ADASAV RESTONL function to indicate whether an Adabas database file may be updated only by the Event Replicator Server as part of Adabas-to-Adabas replication or by other means as well. This parameter is optional.
Note:
This parameter can only be specified if you also have Adabas 8.2
SP2 or later installed.
Valid values are "YES" or "NO". A value of "YES" indicates that the file can only be updated via Event Replicator processing; a value of NO indicates that the file can be updated by any normal means, including Event Replicator processing.
If no value is specified, the default RPLUPDATEONLY setting of the file at the time of the corresponding SAVE operation is used.
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 data set.
Note:
This is not possible when restoring from a version 5.1 SAVE data
set.
The TEST parameter tests the operation syntax without actually performing the operation. Note that the validity of values and variables cannot be tested; only the syntax of the specified parameters can be tested.
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.
Note:
The UIRABN parameter is not allowed if a range of files is
specified in 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.
Note:
The UISIZE parameter is not allowed if a range of files is
specified in the FMOVE parameter.
The size can be specified in cylinders, or in blocks (by appending a "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 RESTONL PLOGNUM=25,SYN1=160,OVERWRITE ADASAV FMOVE=1,2 ADASAV ACRABN=2100,2300 ADASAV DSRABN=1500,2000 ADASAV NIRABN=0,2380 ADASAV UIRABN=2190
Protection log 25 is to be used. The block containing the SYN1 checkpoint is 160. Files 1 and 2 are to be deleted and restored. File 1 is to be restored using starting RABNs:
| Address Converter | 2100 |
| Data Storage | 1500 |
| Normal Index | (chosen by ADASAV) |
| Upper Index | 2190 |
File 2 is to be restored using starting RABNs:
| Address Converter | 2300 |
| Data Storage | 2000 |
| Normal Index | 2380 |
| Upper Index | (chosen by ADASAV) |
ADASAV RESTONL PLOGNUM=4711,SYN4=99,FMOVE=3,4,5,OVERWRITE ADASAV PASSWORD='PWD3,,PWD5'
The files specified by the FMOVE file list may possibly be restored to different RABNs than they had before. Files 3 and 5 are password-protected and their passwords are PWD3 and PWD5.
ADASAV RESTONL 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.
