This document describes the utility "ADABCK".
The following topics are covered:
The backup utility ADABCK provides protection against database corruption by creating Adabas backup copies. ADABCK should be used at regular intervals.
The utility dumps or restores a database or selected files from/to a database.
Making use of the internal structure of the database, this utility provides optimum performance. Unused blocks do not have to be read and can be omitted when dumping. Even though such blocks are not included in the Adabas backup copy, they can be re-created during a restore.
The backup copy can be directly assigned to tape: this option supports consecutive tapes (see Administration, Using Utilities).
Furthermore, a backup copy may be directed to stdout in order to support the piping of the backup data (this feature is only available on UNIX platforms). This feature is enabled by setting the environment variable (BCK001) to '-' (minus). In this case, the output messages are directed to stderr. The RESTORE and OVERLAY functions can also be used in this way, i.e. a backup copy can be read from stdin. In this case, the ADABCK control statements must be given in the command line (see Administration, Using Utilities).
The following functions are available:
The COPY function copies an Adabas backup copy;
The DUMP function dumps a database or selected files from a database to one or more sequential files, which is called an Adabas backup copy. The nucleus may be active and parallel updates are permitted on the files to be dumped while the dump is in progress;
The EXU_DUMP function dumps a database or selected files from a database to one or more sequential files, which is called an Adabas backup copy. Only ACC users are permitted on the files to be dumped while the dump is in progress;
The IOSTAT function prints information about the data transfer rate and the I/O waiting times.
The OVERLAY function restores selected files or a database. The files to be restored may already be loaded in the database: ADABCK performs an implicit delete before restoring such files;
The READ_CHECK function checks the readability (i.e. absence of parity errors) and completeness of the Adabas backup copy. These checks ensure that the dump file can be read by the RESTORE or OVERLAY function;
The RESTORE function restores a database or selected files from an existing Adabas backup copy. If there are no security definitions for the files in the target database, the corresponding entries (as they were defined at the time the files were dumped) are set up in the security table when the file is restored;
The list functions CONTENTS, FILES and SUMMARY display information about an Adabas backup copy. When the list functions are used, the DBID does not have to be entered first; the exception to this is when the backup file is in a raw section. In this case, the DBID is required, but the database itself does not have to be present (UNIX platforms only).
The functions DUMP, EXU_DUMP, OVERLAY and RESTORE are mutually exclusive and only one of them may be executed during a single run of this utility. The list functions can only be used together with the READ_CHECK, RESTORE or OVERLAY function.
If you perform the RESTORE or OVERLAY function and the database is too small or database containers are missing, ADABCK will automatically increase the size of the database or create the missing containers.
Note:
The RESTORE and OVERLAY functions can process backup files created
with earlier Adabas versions, but not backup files created with later Adabas
versions.
Caution:
If you don't use the Adabas INI files, but instead use environment
variables to specify the container file names, and if you forget to assign the
environment variables/logical names before you start ADABCK, a copy of the
database will be created in the database directory. If you perform a file
overlay or restore when the Adabas nucleus is active, and the database has to
be extended, the database is extended by the nucleus, and not by ADABCK. In
this case, the nucleus extends the database even if OPTION=AUTOEXPAND was NOT
specified. If you use environment variables to specify the database containers,
you must consider the following when a new container has to be created for the
restore/overlay: it is important that the nucleus was started with the correct
environment variable settings for the new container - because the new
containers are created by the nucleus, specifying the environment variable for
the ADABCK process has no effect.
This utility is a single-function utility.
| Data Set | Environment Variable/ Logical Name |
Storage Medium |
Additional Information |
|---|---|---|---|
| Associator | ASSOx | Disk | |
| Backup copy | BCK00n | Disk, Tape (see note 1) stdin/ SYS$INPUT (see note 2), stdout/ SYS$OUTPUT (see note 3) |
Output of DUMP/EXU_DUMP function, input for other functions |
| BCKOUT | Disk, Tape (see note 1) | Output of COPY function | |
| Data storage | DATAx | Disk | |
| Control statements | stdin SYS$INPUT |
Utilities Manual | |
| ADABCK messages | stdout/ SYS$OUTPUT (see note 4), stderr/ SYS$ERR (see note 5) |
Messages and Codes | |
| Work | WORK1 | Disk |
Notes:
The sequential files BCK00n can have multiple extents. For detailed information about sequential files with multiple extents, see Administration, Using Utilities.
The following table shows the nucleus requirements for each function and the checkpoint written:
| Function | Nucleus must be active | Nucleus must NOT be active | Nucleus is NOT required | Checkpoint written |
|---|---|---|---|---|
| CONTENTS | X | - | ||
| COPY | X | - | ||
| DUMP | X(see note 1) | X | SYNX | |
| EXU_DUMP | X(see note 1) | X | SYNX | |
| FILES | X | - | ||
| NEW_PLOG | SYNC | |||
| OVERLAY | X(see note 2) | X(see note 3) | SYNP | |
| READ_CHECK | X | - | ||
| RESTORE | X(see note 2) | X(see note 3) | SYNP | |
| SUMMARY | X | - |
Notes:
The following control parameters are available:
CONTENTS
COPY [= number]
M DBID = number
DUMP = {*|(number[-number][,number[-number]]...)}
[,BLOCKSIZE = number [K|M]]
D [{,DRIVES = number} |
D {,[NO]DUAL } ]
[,ET_SYNC_WAIT = number]
D [,[NO]NEW_PLOG]
EXU_DUMP = {*|(number[-number][,number[-number]]...)}
[[,BLOCKSIZE = number [K|M]]
D [{,DRIVES = number} |
D {,[NO]DUAL} ]
D [,[NO]NEW_PLOG]
FILES = { * | (number[-number][,number[-number]]...)}
IOSTAT
OVERLAY = {*|(number[-number][,number[-number]]...)}
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword])]
[,KEEP_FILE_ALLOC]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
PARALLEL = keyword
READ_CHECK
RESTORE = {*|(number[-number][,number[-number]]...)}
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword])]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
SUMMARY
CONTENTS
This parameter displays a list of files in an Adabas backup copy created with the DUMP or EXU_DUMP function.
adabck: contents Database dumped on 14-JUL-2005 14:49:17 Database 76, DOKU-DATABASE File 1, CHECKPOINT-FILE , loaded on 12-JUL-2005 14:57:05 File 2, SECURITY-FILE , loaded on 12-JUL-2005 14:57:05 File 3, USER-DATA-FILE , loaded on 12-JUL-2005 14:57:05 File 9, EMPLOYEES-FILE , loaded on 12-JUL-2005 14:57:08 File 11, EMPLOYEES-NAT , loaded on 12-JUL-2005 14:57:09 File 12, VEHICLES , loaded on 12-JUL-2005 14:57:11 File 13, MISCELLANEOUS , loaded on 12-JUL-2005 14:57:10
COPY [= number]
This function creates a new file from an existing Adabas backup copy. The input file (BCK0xx) and the output file (BCKOUT) may be on either disk or tape, where xx is either the specified number, or 01 if no number is explicitly specified.
DBID = number
This parameter selects the database to be used.
DUMP = { * | (number[-number][,number[-number]]...)}
[,BLOCKSIZE = number [K|M]]
[ {,DRIVES = number} |
{, [NO]DUAL } ]
[,ET_SYNC_WAIT = number ]
[,[NO]NEW_PLOG ]
At the file level, this function dumps the files specified by the numbers in the list. LOB files specified are ignored, but the LOB files assigned to all base files are dumped too. An asterisk '*' specifies that the complete database is to be dumped. Parallel updates are permitted on the files to be dumped while the dump is in progress.
If the nucleus is running in parallel (online backup), ADABCK must ensure that all transactions affecting the dumped files are completed by all users before ADABCK terminates. This is called ET synchronization - please refer to the section ET Synchronization in Administration for further information. If you perform a dump at the file level with the option NONEW_PLOG, the ET synchronization is performed at the file level; otherwise the ET synchronization is performed for the complete database.
If you specify files with referential constraints, all files connected to these files via referential constraints must also be specified in order to maintain referential integrity.
This parameter can be specified to change the I/O transfer blocksize. If PARALLEL is specified, the default blocksize is 512 KB. The following values can be specified: 64KB, 128KB, 256KB, 512KB, 1MB, 2MB, ... 12MB. The blocksize specified will be used in a subsequent RESTORE function.
This parameter limits the maximum number of output devices to be operated in parallel. It can be used to split a backup file into several extents. The output is sent to BCK0xx.
The default value is 1 and the maximum value is 10.
The parameters DRIVES and DUAL are mutually exclusive, and only one of them may be specified in a given call of the DUMP function.
DUAL specifies that two physical copies of the dumped information are to be created. The output is sent to BCK001 and BCK002.
The default is NODUAL.
The parameters DUAL and DRIVES are mutually exclusive, and only one of them may be specified in a given call of the DUMP function.
This parameter defines the time (in seconds) that ADABCK waits for ET-logic users to come to ET status at the end of the DUMP function.
If this parameter is omitted, the value currently in effect for the database nucleus (ADANUC parameter TT) is taken.
The minimum value is 1 and the maximum value is 32767.
This option specifies whether or not to close the protection log file and create a new log file at the end of the DUMP function.
The default for a database dump is NEW_PLOG, and for a file dump it is NONEW_PLOG.
Caution:
Before V6.3 SP1 Fix 13, the default for a file dump was
NEW_PLOG. In most cases, this change is of no consequence, but if you really
need the PLOG switch, you must specify NEW_PLOG explicitly.
EXU_DUMP = {*|(number[-number][,number[-number]]...)}
[,BLOCKSIZE = number [K|M]]
[ {,DRIVES = number} |
{,[NO]DUAL} ]
[,[NO]NEW_PLOG]
At the file level, this function dumps the files specified by the numbers in the list. LOB files specified are ignored, but the LOB files assigned to all base files are dumped too. An asterisk '*' specifies that the complete database is to be dumped. Only ACC users are permitted on the files to be dumped while the dump is in progress. ET-synchronization is not required.
If you specify files with referential constraints, all files connected to these files via referential constraints must also be specified in order to maintain referential integrity.
This parameter can be specified to change the I/O transfer blocksize. If PARALLEL is specified, the default blocksize is 512 KB. The following values can be specified: 64KB, 128KB, 256KB, 512KB, 1MB, 2MB, ... 12MB. The blocksize specified will be used in a subsequent RESTORE function.
This parameter limits the maximum number of output devices to be operated in parallel. It can be used to split a backup file into several extents. The output is sent to BCK0xx.
The default value is 1 and the maximum value is 10.
The parameters DRIVES and DUAL are mutually exclusive, and only one of them may be specified in a given call of the DUMP function.
DUAL specifies that two physical copies of the dumped information are to be created. The output is sent to BCK001 and BCK002.
The default is NODUAL.
The parameters DUAL and DRIVES are mutually exclusive, and only one of them may be specified in a given call of the DUMP function.
This option specifies whether or not to close the protection log file and create a new log file at the end of the EXU_DUMP function.
This option must not be used if dumping single files.
The default is NEW_PLOG for EXU_DUMP=*.
In the examples below, the files 1, 2, 4, 6, 7, 8, 10, 11, 12, and 13 are loaded in the selected database.
adabck: dump = * , drives = 2
The database is dumped with two output devices operating in parallel.
adabck: exu_dump = 8 , dual
File 8 is dumped and two physical copies are created. Only ACC users are allowed on file 8 while the dump is in progress.
adabck: dump = (8-11,13,6,1-4), et_sync_wait = 5
Files 1, 2, 4, 6, 8, 10, 11 and 13 are dumped. ADABCK allows a maximum of 5 seconds for ET-logic users to come to ET status.
FILES = { * | (number[-number][,number[-number]]...)}
This parameter displays status information of the specified files in a dump file.
IOSTAT
If this parameter is specified, the data transfer rate and the I/O (waiting) times on the various devices are printed at the end of ADABCK processing.
adabck db=36 parallel=multi_process dump=\* drives=3 iostat ... ------------------------------------------------------------------ Dump Method : parallel Blocksizes : DB: 512 KB BCK: 512 KB DB I/O time : total: 27.09 sec average: 8084 us BCK 1 I/O time : total: 1.16 sec average: 7606 us BCK 2 I/O time : total: 0.00 sec average: 944 us BCK 3 I/O time : total: 1.24 sec average: 1375 us Wait rates : waits nowaits rate mreq DB : 1439 1898 43% 8 Transfer rate : 15215 KB/sec ------------------------------------------------------------------ %ADABCK-I-IOCNT, 2 IOs on dataset WORK %ADABCK-I-IOCNT, 3147 IOs on dataset DATA %ADABCK-I-IOCNT, 229 IOs on dataset ASSO %ADABCK-I-IOCNT, 153 IOs on dataset BCK001 %ADABCK-I-IOCNT, 2 IOs on dataset BCK002 %ADABCK-I-IOCNT, 906 IOs on dataset BCK003
The IOSTAT statistics display the following information:
Either parallel or non-parallel, depending on the setting of the PARALLEL parameter.
The total I/O time in seconds and the average time per I/O operation in microseconds for the access to the ASSO and DATA containers.
The total I/O time in seconds and the average time per I/O operation in microseconds for the access to the backup files.
Note:
The I/O time measured is the time required for the I/O system
functions. This may be different from the physical I/O times actually required
to accessing the disks because of caches in the operating system or in the
storage system and because of usage of asynchronous I/O.
For a parallel backup/restore, the I/Os for the database containers are performed asynchronously. The wait rate shows for how many ASSO or DATA I/Os a wait operation is required. mreq is the maximum number of parallel I/O requests for database containers.
Note:
Only the I/Os for the real backup or restore are counted. During
the startup phase of ADABCK, some additional I/Os are required; therefore the
sum of wait and nowait I/Os is less than the sum of ASSO and DATA I/Os.
In the case of a backup in online mode during a buffer flush, synchronization with the nucleus is required in order to guarantee that the modified database blocks written to disk by the buffer flush are also written to the backup file(s). The BF sync count is the number of these buffer flush synchronizations.
At the end of a backup in online mode, an ET synchronization is required, i.e. ADABCK must wait until all ET logic users come to ET status. The ET sync time is the time required for this ET synchronization.
This is the number of kilobytes read from or written to the backup file(s) per second.
Notes:
OVERLAY = {*|(number[-number][,number[-number]]...)}
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword] ) ]
[,KEEP_FILE_ALLOC]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
This function restores the files specified by the numbers in the list at file level. LOB files specified are ignored, but the LOB files assigned to all base files are restored too. The files to be restored may already be loaded in the database. ADABCK performs an implicit delete before restoring such files. If only one file of a LOB group is overlaid, the other file of the LOB group is also deleted. An asterisk ('*') specifies that a restore is to be made at the database level. Exclusive control over the database container files is required.
Only the specified files are overlayed, even if there are referential integrity constraints to other files; these referential integrity constraints are removed.
If this keyword is specified, ADABCK reallocates all files to be overlayed or the specified subset rather than attempting to restore them in the same block ranges as in the backup. Using this keyword reduces the number of file extents as much as possible.
The keywords ASSO and/or DATA may be specified. This parameter is used to format Associator and/or Data Storage blocks. When restoring at the file level, only blocks contained in the unused areas of the files' extents are formatted.
If this parameter is specified, ADABCK tries to keep the allocation of the file as it currently is in the database, as opposed to restoring it with the same block ranges as on the backup. This keyword can, for example, be used when a file has been reorganized since the backup was made or also if more space has since been preallocated to the file. If the file on the backup has more blocks allocated than are currently available in the database, the remaining blocks will be allocated in an arbitrary location. This keyword can only be used in conjunction with a file list.
This parameter can be used to change the identifier of the database to be restored. This parameter can only be specified when restoring a complete database.
A new identifier can be used to restore a backup copy of an active database into a different set of container files. The new identifier may not be identical to that of another active database.
If this parameter is omitted, the database identifier remains unchanged.
RENUMBER is used to renumber the files to be overlayed in the target database. The following restrictions and requirements apply:
There must be a 1:1 relationship between the files specified in the OVERLAY file list and the RENUMBER file list.
If you specify a range in the OVERLAY file list, the corresponding range in the RENUMBER file list must be the same size.
Normally it is not necessary to specify LOB files in the OVERLAY file list. However, if the LOB file is also to be renumbered, the LOB file must also be specified.
Files may occur more than once in the OVERLAY file list, for example: (11-55),(44-99). In this case, you are not allowed to specify different target file numbers for the same source file numbers. For the example file list, it is correct to specify RENUMBER=(1011-1055,1044-1099), whereas RENUMBER=(1011-1055,2044-2099) is incorrect.
It is not allowed to renumber more than one file to the same target file number.
PARALLEL = keyword
This parameter can be specified to increase processing speed when creating/restoring from backups on slow devices (e.g. tape drives) by using parallel devices. The keyword MULTI_PROCESS can be used. If PARALLEL=MULTI_PROCESS is specified, the default value of the BLOCKSIZE parameter changes to 512 KB.
The ADABCK operation is only performed in parallel if the number of backup files (ADABCK subparameter DRIVES for DUMP or EXU_DUMP) is greater than 1.
Notes:
READ_CHECK
This function checks the readability (i.e. absence of parity errors) and completeness of the Adabas backup copy. These checks are made to ensure that the dump file can be used to restore the database or files with the RESTORE or OVERLAY function of this utility.
RESTORE = {*|(number[-number][,number[-number]]...)}
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword] ) ]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
This function restores the files specified by the numbers in the list at the file level. LOB files specified are ignored, but the LOB files assigned to all base files are restored too. If a file list is given, the files to be restored must not be loaded in the database. An '*' specifies that a restore is to be made at the database level. In this case, the files may already be loaded in the database and will implicitly be deleted or substituted by files in the dump with identical file numbers. Exclusive control over the database container files is required.
Only the specified files are restored, even if there are referential integrity constraints to other files; these referential integrity constraints are removed.
Note:
You can only use RESTORE=* if the dump file was
created with DUMP=* or EXU_DUMP=*.
If this keyword is specified, ADABCK reallocates all files to be restored or the specified subset rather than attempting to restore them in the same block ranges as in the backup. Using this keyword reduces the number of file extents as much as possible.
The keywords ASSO and/or DATA may be specified. This parameter is used to format Associator and/or Data Storage blocks. When restoring at the file level, only blocks contained in the unused areas of the files' extents are formatted.
This parameter can be used to change the identifier of the database to be restored. This parameter can only be specified when restoring a complete database.
A new identifier can be used to restore a backup copy of an active database into a different set of container files. The new identifier may not be identical to that of another active database.
If this parameter is omitted, the database identifier remains unchanged.
RENUMBER is used to renumber the files to be restored in the target database. The following restrictions and requirements apply:
There must be a 1:1 relationship between the files specified in the RESTORE file list and the RENUMBER file list.
If you specify a range in the RESTORE file list, the corresponding range in the RENUMBER file list must be the same size.
Normally it is not necessary to specify LOB files in the RESTORE file list. However, if the LOB file is also to be renumbered, the LOB file must also be specified.
Files may occur more than once in the RESTORE file list, for example: (11-55),(44-99). In this case, you are not allowed to specify different target file numbers for the same source file numbers. For the example file list, it is correct to specify RENUMBER=(1011-1055,1044-1099), whereas RENUMBER=(1011-1055,2044-2099) is incorrect.
It is not allowed to renumber more than one file to the same target file number.
It is assumed that none of the files specified in the DUMP examples above are loaded in the selected database.
adabck: restore = *
The complete database is restored. The output of DUMP=* or EXU_DUMP=* may be used as input for this example. The nucleus must be inactive.
adabck: restore = 8
File 8 is restored. The output of any of the DUMP/EXU_DUMP examples above can be used as input for this example. The nucleus may be active (assuming that file 8 is neither the checkpoint file nor the security file).
adabck: restore = (11-13, 1, 4-8)
Only the outputs of the first and last DUMP/EXU_DUMP example could be used. The output of the last example would restore files 1, 4, 6, 8, 11 and 13, whereas that of the first example would restore files 7 and 12 as well.
SUMMARY
This parameter displays general information and physical layout of the database in the Adabas backup copy created by a previous run of the DUMP/EXU_DUMP function.
adabck: summary
Database dumped on 14-JUL-2005 14:49:17
Database 76, DOKU-DATABASE
Summary of Database 76 14-JUL-2005 14:49:18
DATABASE NAME DOKU-DATABASE
DATABASE ID 76
MAXIMUM FILE NUMBER LOADED 30
SYSTEM FILES 1 (CHK), 2 (SEC), 3 (USR)
ACTUAL FILES LOADED 6
CURRENT PLOG NUMBER 13
CURRENT CLOG NUMBER 1
Container Device Extents in Blocks Number of Block Total Size
File Type from to Blocks Size (Megabytes)
-------------------------------------------------------------------------------
ASSO1 file 1 1,536 1,536 2KB 3.00 MB
DATA1 file 1 768 768 4KB 3.00 MB
WORK1 file 1 1,365 1,365 3KB 4.00 MB
-------------------------------------------------------------------------------
10.00 MB
========
ADABCK has no restart capability. An abnormally-terminated ADABCK execution must be rerun from the beginning.
An interrupted RESTORE/OVERLAY of one or more files will result in lost RABNs which can be recovered by executing the RECOVER function of the utility ADADBM. An interrupted RESTORE/OVERLAY of a database results in a database that cannot be accessed.