The RESTORE DELTA function restores a database or file(s) from a full save and zero, one, or more delta save datasets without first merging the save inputs. The input datasets may originate from SAVE database (with DSF=YES), SAVE DELTA, or MERGE functions, and must cover a continuous sequence of full and delta save operations.
For RESTORE DELTA database operations where more input save tapes are present than tape units are available, the excess save tapes may be concatenated to the delta save tape assigned to the last tape unit; however, the logical sequence of delta saves must be retained. If concatenation is not possible or not enough tape units are available, the number of input save datasets must be reduced to eight or fewer by doing consecutive merge operations.
An interrupted RESTORE operation must be executed again from the beginning. For RESTORE DELTA database, the restore operation can be restarted without the full save tape if the full save tape was completely restored and only some of the supplied delta save tapes remain to be restored. Message DSF048 in the restore operation's protocol indicates the input save datasets that have been completely restored. The other delta save datasets must be supplied for the restarted restore operation.
This document covers the following topics:
A full or delta save input dataset may originate from an "online" save operation. In this case, the original or unloaded DSIM dataset that was specified for the online save operation must also be specified as an input dataset. It is possible to specify a single online save input and its corresponding DSIM dataset without specifying any other input save dataset.
The DSIM dataset is automatically built while ADARES PLCOPY copies the dual or multiple PLOGs. Building the DSIM dataset is completed when the PLCOPY function encounters the online save operation's SYN2 checkpoint on the PLOG.
If the RESTORE DELTA function is to be performed directly after the online save operation, the DSIM dataset will normally not be completely built when the RESTORE DELTA function starts. The DSIM dataset will not be ready for merge before the next PLCOPY operation has been performed. The DSIMWAIT parameter tells the RESTORE DELTA function how long to wait for the DSIM dataset to become ready for merge.
When an "unloaded" DSIM dataset is supplied as input for a RESTORE DELTA operation, it must be specified
as one of the DD/DELn input datasets. More than one unloaded DSIM dataset may be supplied for a single RESTORE.
directly after its associated online delta save input; that is, with the next higher DD/DELn index number. For example, if an online delta save input is supplied as DD/DEL2, its associated unloaded DSIM dataset must be given as DD/DEL3. If an unloaded DSIM dataset is associated with an online full save, it must be specified as DD/DEL1.
These rules for specifying unloaded DSIM datasets ensure the correct output: each block is taken from the last input in sequence that contains a block image with the same RABN.
The RESTORE DELTA function checks whether the online save fits the contents of the DSIM dataset. If so, the online save is associated with the DSIM dataset. If not, the next input delta save in logical sequence must be a matching unloaded DSIM dataset.
A RESTORE DELTA function may postpone processing the expected unloaded DSIM dataset until a subsequent phase of the restore. For example, an online full save is first restored on multiple drives and then the associated DSIM dataset is handled, which must be either the original or an unloaded DSIM dataset; or, if the last delta save input in logical sequence contains an online save, the associated unloaded DSIM must be concatenated to that online save. If the expected unloaded DSIM dataset is missing, the restore terminates with an error message, leaving the database intact for a proper RESTORE DELTA from the most recent restart point on, but with all files in restore-status.
During a RESTORE DELTA operation, ADASAV prints the DSF048 partial completion messages providing restart points in case of subsequent failure only when the full and delta saves already restored really form a consistent state of the database. A DSF048 message is suppressed if an online save is restored but the associated DSIM dataset will be processed in a subsequent phase of the restore.
Upon completion of the RESTORE DELTA, the DSIM dataset is not reset; it is still available for a MERGE operation.
Consecutive delta save results can be combined (concatenated) as input to the ADASAV RESTORE DELTA function. The last delta save input (the one with the most recent time stamp) can be a concatenation of several consecutive delta save tapes, as follows:
For BS2000/OSD systems, by using the DDDELn01, DDDELn02, ... link names, where the last delta save input has the serial number "n";
For z/OS, and z/VM systems, by using the available operating systems capabilities;
For VSE/ESA and z/VSE, by using the DELn01, DELn02, ... symbolic names, where the last delta save input has serial number "n".
See the JCL examples for the ADASAV RESTORE DELTA function in section JCL/JCS Requirements and Examples. For more information on dataset concatenation on BS2000/OSD, z/VSE and VSE/ESA systems, see the Adabas Utilities documentation.
For RESTORE DELTA database or RESTORE DELTA GCB, the output database must have the same physical layout (device types, extent sizes) as the original database. The Associator and Data Storage datasets must be present and must have been formatted at least once. The Adabas nucleus must not be active. If the dual or multiple protection log (PLOG) and/or dual or multiple command log (CLOG) datasets are specified in the job control, these datasets are reset to an empty status.
For RESTORE DELTA FILES or RESTORE DELTA FMOVE, an existing database must be present. The files to be restored may come from the same or a different database. The Adabas nucleus may be active. If the nucleus is active when checkpoint or security files are restored, the ADASAV utility requires exclusive database control; that is, no user may be active on the database.
After a RESTORE database or RESTORE DELTA database operation, another RESTORE DELTA database function may be executed without the full save input dataset, provided that
a DSF logging (DLOG) area is defined in the database;
no Adabas nucleus session has been started since the last restore operation;
no utility that makes changes to the database (ADALOD, ADASAV RESTORE FILE) has been run since the last restore operation; and
the delta save tape to be restored is the next in the logical sequence of delta save tapes already restored.
This way of executing the RESTORE DELTA function can be used to keep a shadow database up to date.
The minimum syntax is ADASAV RESTORE DELTA. A database restore is assumed unless the FILES or FMOVE parameter is specified.
Any or all of the parameters DSIMDEV, DSIMWAIT, PATTERN, and TEST may be optionally specified independently. The parameters BUFNO, CLOGDEV, DRIVES, EXCLUDE, NEWDBID, NEWDBNAME, OVERWRITE, and PLOGDEV have special dependencies on other parameters as indicated in the individual parameter discussions.
The FILES, FMOVE, and GCB parameters are optional. However, if FILES or GCB is specified, FMOVE may not be specified and vice versa. FILES may be specified with or without GCB. The parameters available with FILES, FMOVE, and GCB are not depicted in the following syntax diagram; they are depicted instead with their detail descriptions instead.
ALLOCATION, NEWFILES, and PASSWORD are allowed with FILES or FMOVE only.
If FMOVE is specified, any or all of the parameters ACRABN, ALLOCATION, ASSOVOLUME, DATAVOLUME, DRIVES, DSRABN, DSSIZE, MAXISN, NEWFILES, NIRABN, NISIZE, PASSWORD, UIRABN, and UISIZE may be specified.
If GCB is specified, any or all of the parameters CLOGDEV, FILES, NEWDBID, NEWDBNAME, and PLOGDEV may 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.
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 Example.
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 can only be specified if FILES or FMOVE is specified. If specified with FILES, 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:
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 ASSOVOLUME value is to be given for a file, its entry in the list of volumes must be left empty. See the Example.
The BUFNO value, multiplied by the DRIVES parameter value, allocates fixed buffers for the RESTORE DELTA operation. A value of 2 or 3 usually provides optimum performance; a value 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).
CLOGDEV is the device type to be assigned to the dual or multiple command log (CLOG). This parameter is required only if the device type to be used for the CLOG is different from that specified by the ADARUN DEVICE parameter. CLOGDEV is required only for the RESTORE DELTA database and RESTORE DELTA GCB functions if the dual or multiple CLOG is specified in the job control.
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 DATAVOLUME value is to be given for a file, its entry in the list of volumes must be left empty. See the Example.
ADASAV is able to restore files from multiple full SAVE dataset volumes in parallel to RABNs that are different from their original RABNs in the database. DRIVES is the number (1-8 inclusive; default 1) of tape drives to be used for parallel restore processing.
The corresponding number of input datasets must be specified in the job control. These input datasets, combined, must represent a full save dataset.
The default value (DRIVES=1) is required when GCB, FILES, or FMOVE is specified in conjunction with DELTA.
The DSIMDEV parameter specifies the device type of the DSIM dataset. This parameter is required only if the DSIM device type is different from that specified by the ADARUN DEVICE parameter (which is the default).
The DSIMWAIT parameter specifies how long the restore function should wait for the DSIM dataset to become ready for merge. DSIMWAIT can be used if a restore step is to be executed directly after an online save operation but must wait for the ADARES PLCOPY function to copy the nucleus' dual or multiple protection log (PLOG).
The maximum time to wait is specified in seconds. If the DSIM dataset does not become ready for restore operation within this time and one of the input save datasets is an online save dataset, the RESTORE DELTA function fails.
If DSIMWAIT is not specified, the RESTORE DELTA function will not wait for the DSIM dataset to become ready for restore operation, but instead will begin operation immediately or fail if the DSIM dataset is not ready for restore operation (the default).
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 Example.
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. If DSSIZE is omitted, the original Data Storage size is used.
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 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 Example.
The EXCLUDE parameter is provided for use in recovery jobs built by the Adabas Recovery Aid (ADARAI). EXCLUDE lists the file numbers to be excluded from the restore operation; that is, the files that are not to be restored. Files specified in the EXCLUDE parameter will not exist in the restored database.
The parameter is optional: if not specified, no files are excluded. A file number may be listed only once.
For a database restore, all files specified in the EXCLUDE parameter must exist on the save dataset.
For a RESTORE DELTA without a full save input, the EXCLUDE file list must be the same as that specified for the preceding RESTORE DELTA with a full save input; otherwise, the EXCLUDE parameter is rejected.
For a file restore
without the NEWFILES parameter, all files specified in the EXCLUDE parameter must also be specified in the FILES or FMOVE parameter.
with the NEWFILES parameter, 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 the NEWFILES parameter, not the old file numbers in the FILES or FMOVE parameter.
Note:
When FILES is specified, a RESTORE DELTA requires a full save
input dataset.
The file or list of files to be restored. 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 specified files are restored at the same place where they were originally located. The Adabas nucleus may be active during the restore operation unless the GCB parameter is also specified, or the Adabas checkpoint or security file is to be restored.
The FILES parameter cannot be specified if the FMOVE parameter is specified.
The syntax of the FILES parameter is shown next. The subparameters for the FILES parameter are described elsewhere in this section.
Note:
When FMOVE is specified, a RESTORE DELTA requires a full save
input dataset.
The file or list of files to be restored. 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 specified files are restored as designated by the ACRABN, ASSOVOLUME, DATAVOLUME, DSRABN, DSSIZE, MAXISN, NIRABN, NISIZE, UIRABN, and UISIZE parameters. If any of these parameters is not specified, ADASAV chooses values for the locations of the corresponding parts of the file(s), and/or retains the existing sizes. The Adabas nucleus may be active during the restore operation unless the Adabas checkpoint or security file is to be restored.
FMOVE cannot be specified if the GCB or FILE parameter is specified.
The syntax of the FMOVE parameter is shown next. The subparameters for the FMOVE parameter are described elsewhere in this section.
The GCB keyword parameter specifies that the GCB and the other administrative blocks are to be restored from the input save dataset(s), as well as any files specified by the FILES parameter. That is, the entire database is restored except for the files not specified by FILES. The Adabas checkpoint and security files (if present) are always restored.
The Adabas nucleus must not be active when RESTORE DELTA GCB is being executed. The GCB parameter cannot be specified if the FMOVE parameter is specified.
Important:
Any existing database in the target Associator and Data
Storage datasets is completely overwritten, and any files in that database are
lost.
The syntax of the GCB parameter is shown next. The subparameters for the GCB parameter are described elsewhere in this section.
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 used ISN.
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 Example.
If the database consists of several Associator extents with different device types, error-171 may occur if MAXISN is specified. If this happens, remove the MAXISN parameter for the file indicated in the error message and rerun RESTORE DELTA FMOVE.
NEWDBID may be used to assign a different database ID to the restored database. The ID can be in the range 1-65535. NEWDBID can only be specified for ADASAV RESTORE DELTA database and RESTORE DELTA GCB operations.
If NEWDBID is specified, the ADARUN DBID parameter must specify the ID of the database on the save tape.
If NEWDBID is not specified, the restored database keeps its old ID.
NEWDBNAME assigns a new name to the restored database. NEWDBNAME can only be specified for ADASAV RESTORE DELTA database and RESTORE DELTA GCB operations. If NEWDBNAME is not specified, the restored database keeps its old name.
The NEWFILES parameter specifies the new file number to be assigned to each file specified by FILES or 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 FILES or 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 Example.
NIRABN specifies the starting normal index RABN 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 Example.
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 Example.
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.
The OVERWRITE parameter specifies that an existing database or file is to be overwritten by the RESTORE DELTA function.
If the FILES or FMOVE parameter is not specified, OVERWRITE specifies that an existing database is to be overwritten. If OVERWRITE is not specified and a GCB is found in Associator RABN 1, the RESTORE function is rejected.
If the FILES or FMOVE parameter is specified, OVERWRITE specifies that any existing file specified by this parameter is to be overwritten. If OVERWRITE is not specified and an FCB is found for any file to be restored, that file will not be restored.
See also the PASSWORD parameter.
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 also 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. See the Example for more information about the PASSWORD parameter. When overwriting password-protected files, the Adabas nucleus must be active.
PATTERN is an optional parameter that provides a cross-check between the intended save input and the actual datasets specified by the job control. PATTERN specifies the count and type of input datasets to the save operation as single letters "F" (full save tape) or "D" (delta save tape). Only one "F" can be specified in the pattern field, but up to eight "D"s can be entered-one for each existing delta save tape to be included in the restore operation.
The pattern starts with an "F" if a full save input is specified, and continues (or starts) with a "D" for every delta save input. For example, PATTERN=FDD specifies that the input comprises one full save dataset and two delta save datasets. No special indicator is given for a save dataset being online. The pattern string must exactly match the input save datasets specified in the job control.
Concatenated delta save input does not take part in the matching of the PATTERN parameter.
The device type of the dual or multiple protection log (PLOG). This parameter is required only if the device type of the PLOG is different from that specified by the ADARUN DEVICE parameter. PLOGDEV is required only for the RESTORE DELTA database and RESTORE DELTA GCB functions if the dual or multiple protection log is specified in the job control.
The TEST parameter tests the operation syntax without actually performing the restore operation. Only the syntax of the specified parameters can be tested; not the validity of values and variables.
UIRABN specifies the starting upper index RABN 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 Example.
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 Example.
ADASAV RESTORE DELTA,OVERWRITE ADASAV PATTERN=FDD ADASAV DSIMDEV=8381 ADASAV DRIVES=4 ADASAV PLOGDEV=3390,CLOGDEV=3390
An entire database is to be restored, possibly overwriting an already existing database. One full save and two delta save datasets are supplied as input. One of the input save datasets may have been created online; its accompanying DSIM dataset is on a device type 8381.
The full save input is supplied as four datasets and is to be restored from four tape drives in parallel. The dual or multiple protection log and dual or multiple command log datasets are specified in the job control; they both have device type 3390. They are reset to an empty status as part of the restore operation.
ADASAV RESTORE DELTA,EXCLUDE=1000,255
Files 255 and 1000 are excluded from the restore of the database from full and delta save datasets.
ADASAV RESTORE DELTA,OVERWRITE ADASAV FMOVE=10,20,30 ADASAV ACRABN=31415 ADASAV MAXISN=1000000,0,20000 ADASAV DATAVOLUME='ADADS1,,ADADS1' ADASAV DSSIZE=0,0,500B ADASAV NIRABN=0,10001 ADASAV NISIZE=0,50 ADASAV UIRABN=0,9901 ADASAV UISIZE=0,100B ADASAV PASSWORD='PSW10,,PSW30'
Files 10, 20, and 30 are to be restored to new locations in the database, possibly overwriting already existing files. The number and type of input save datasets is not specified and is to be determined from the job control.
File 10's address converter is to be placed beginning at RABN 31,415, with a new highest allocated ISN of 1,000,000. The normal and upper index of file 20 are to be placed beginning at RABNs 10,001 and 9,901, with sizes of 50 cylinders and 100 blocks, respectively. The new highest allocated ISN of file 30 is to be 20,000. The Data Storage of file 10 is to be placed on volume ADADS1, if possible. The Data Storage of file 30 is to be placed on volume ADADS1 as well, if possible, with a size of 500 blocks. No placement instructions are provided for the Data Storage of file 20. File 10 has password "PSW10", file 30 has password "PSW30".
ADASAV RESTORE DELTA ADASAV 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 were specified as zero or omitted. Files 12, 14, 16, and 17 are to be overwritten, if already present in the database.
