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.
ADABCK is able to process input files that were created on either the same platform or on a platform with a different endian mode. The format in which the file was written is recognized by the restore operation. During the restore, all endian-mode dependent data are converted to the requirements of the target platform.
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.
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 Linux 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 Adabas Basics, Using Utilities for more information.
The following functions are available:
The COPY function copies an Adabas backup copy. A backup data set can only be duplicated on a machine with the same endian mode - attempting to duplicate a backup on a machine with a different endian mode will be rejected;
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 DUMP function writes data in the endian mode of the processor;
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 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.
The functions RESTORE and OVERLAY allow you to create an encrypted database from an Adabas backup copy of a non-encrypted database, and vice versa. The target database is restored with the encryption settings provided by the control parameters ENCRYPTION and KMSTARGET. The new target database is restored or overlayed completely and must not already exist. The ENCRYPTION and KMSTARGET parameters are not permitted for existing databases because the encryption settings of the existing target database are always retained. An encrypted backup copy is restored unencrypted if the existing target database is not encrypted. In contrast, unencrypted backup copies are always restored in encrypted form if the existing target database is encrypted. An encrypted backup copy will be restored using the encryption settings of the existing target database. Different encryption algorithms and keys in the backup copy and database are possible but of course require access to both keys via the configured KMS. To use the encryption functionality, the Adabas Encryption for Linux (AEL) license is required.
Notes:
Caution:
If you do not 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 OPTIONS=AUTO_EXPAND 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. For more information about single- and multi-function utilities. See Adabas Basics, Using Utilities for more information.
| Data Set | Environment Variable/ Logical Name |
Storage Medium |
Additional Information |
|---|---|---|---|
| Associator | ASSOx | Disk | |
| Backup copy | BCK00n | Disk, Tape (see note 1) stdin (see note 2), stdout (see note 3) |
Output of DUMP/EXU_DUMP function, input for other functions |
| BCKOUT | Disk (see note 1) | Output of COPY function | |
| Data storage | DATAx | Disk | |
| DBnnn.INI | Disk | Adabas Extended Operations | |
| Control statements | stdin SYS$INPUT |
Utilities | |
| ADABCK messages | stdout (see note 4), stderr (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 Adabas Basics, 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]
[,REPLICATION]
[PRIMARY_ONLY]
EXU_DUMP = {*|(number[-number][,number[-number]]...)}
[[,BLOCKSIZE = number [K|M]]
D [{,DRIVES = number} |
D {,[NO]DUAL} ]
D [,[NO]NEW_PLOG]
[,REPLICATION]
FILES = { * | (number[-number][,number[-number]]...)}
IOSTAT
OVERLAY = {*|(number[-number][,number[-number]]...)}
[,ENCRYPTION = keyword]
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword])]
[,KEEP_FILE_ALLOC]
[,KMSTARGET = string]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
[,REPLICATION]
PARALLEL = keyword
READ_CHECK
RESTORE = {*|(number[-number][,number[-number]]...)}
[,ENCRYPTION = keyword]
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword])]
[,KMSTARGET = string]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
[,REPLICATION]
SUMMARY
CONTENTS
This parameter displays a list of files in an Adabas backup copy created with the DUMP or EXU_DUMP function.
adabck cont %ADABCK-I-STARTED, 30-OCT-2015 11:42:37, <Version number> Files dumped on 30-OCT-2015 10:51:14 Database 34, GENERAL-DATABASE File 4, Update-log , loaded on 17-SEP-2014 14:44:19 File 9, EMPLOYEES , loaded on 8-OCT-2008 17:59:40 File 14, miscellaneous , loaded on 11-JUN-2015 13:22:19 File 17, Timezone , loaded on 19-SEP-2014 11:44:42 File 19, LARGE , loaded on 2-SEP-2014 15:37:18 File 51, PCA24SYSF1 , loaded on 14-APR-2014 16:55:22 File 91, ADAOS-2544 , loaded on 8-APR-2015 13:19:27 File 95, P299255 , loaded on 20-MAR-2014 11:35:30 File 98, ADAOS-4591 , loaded on 16-JUL-2015 10:03:16 File 1009, LOBFILE of 9 , loaded on 8-OCT-2008 17:59:40 %ADABCK-I-IOCNT, 1 IOs on dataset BCK001 %ADABCK-I-TERMINATED, 30-OCT-2015 11:42:37, elapsed time: 00:00:00
COPY [= number]
This function creates a new file from an existing Adabas backup copy. The input file (BCK0xx) and the output file (BCKOUT) must be on disk, where xx is either the specified number, or 01 if no number is explicitly specified.
You can also use COPY to create an encrypted copy of an existing not encrypted Adabas backup copy. The DBID parameter must be set to the origin encrypted database from which the backup was created to take the encryption settings from.
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 ]
[,REPLICATION]
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 a transaction is already active for the number of seconds (or longer) specified by ET_SYNC_WAIT when the ET synchronization begins, its wait time is 0. Otherwise, the wait time for a transaction, in seconds, is the value specified for the parameter minus the number of seconds that the transaction is already active when the ET synchronization begins. Transactions not yet terminated at the end of their wait times are rolled back.
If this parameter is omitted, the ET synchronization waits until all open transactions are terminated using the normal Adabas timeout logic (ADANUC parameter TT).
The minimum value is 1 and the maximum value is 32767.
Notes:
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.
If NEW_PLOG is specified, it is safe to remove the protection log files after the DUMP function. See Adabas Basics > Locations of Database Containers, Backup Files, and Protection Logs for specific notes on protection logs.
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.
The parameter REPLICATION is relevant only for customers who are using the Adabas Event Replicator with Adabas - Adabas Replication.
This parameter should be specified if you want to use ADABCK for the Adabas - Adabas replication initial state processing. If you specify this parameter, the status of the replications of the files to be dumped is automatically updated.
For further information refer to ADAOPR CHANGE_REPLICATION_STATUS.
The Parameter PRIMARY_ONLY is for customer who are using Adabas Cluster.
This parameter allows only to take dump of primary database, if the secondary database id is provided, ADABCK will terminate with success but no BCKxxx file will be created.
EXU_DUMP = {*|(number[-number][,number[-number]]...)}
[,BLOCKSIZE = number [K|M]]
[ {,DRIVES = number} |
{,[NO]DUAL} ]
[,[NO]NEW_PLOG]
[,REPLICATION]
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=*.
The parameter REPLICATION is relevant only for customers who are using the Adabas Event Replicator with Adabas - Adabas Replication.
This parameter should be specified if you want to use ADABCK for the Adabas - Adabas replication initial state processing. If you specify this parameter, the status of the replications of the files to be dumped is automatically updated.
For further information refer to ADAOPR CHANGE_REPLICATION_STATUS.
The database is dumped to three output devices in parallel.
adabck db=34 parallel=multi_process dump=\* drives=3 %ADABCK-I-STARTED, 30-OCT-2015 11:05:25, <version number> %ADABCK-I-DBOFF, database 34 accessed offline Database dumped on 30-OCT-2015 11:05:25 Database 34, GENERAL-DATABASE File 1, CHECKPOINT-FILE , loaded on 4-SEP-2014 13:52:43 File 2, SECURITY-FILE , loaded on 4-SEP-2014 13:52:43 File 3, USER-DATA-FILE , loaded on 4-SEP-2014 13:52:43 File 4, Update-log , loaded on 17-SEP-2014 14:44:19 File 9, EMPLOYEES , loaded on 8-OCT-2008 17:59:40 File 14, miscellaneous , loaded on 11-JUN-2015 13:22:19 File 17, Timezone , loaded on 19-SEP-2014 11:44:42 File 19, LARGE , loaded on 2-SEP-2014 15:37:18 File 30, FILE-30 , loaded on 31-MAR-2015 13:40:33 File 51, PCA24SYSF1 , loaded on 14-APR-2014 16:55:22 File 80, P295170 , loaded on 4-AUG-2015 12:42:43 File 91, ADAOS-2544 , loaded on 8-APR-2015 13:19:27 File 95, P299255 , loaded on 20-MAR-2014 11:35:30 File 98, ADAOS-4591 , loaded on 16-JUL-2015 10:03:16 File 101, COLLATION-TESTS , loaded on 14-APR-2014 16:47:30 File 111, TESTOPT , loaded on 29-NOV-2011 10:34:23 File 113, lob_LB , loaded on 23-JUN-2015 15:48:48 File 146, XMA-REPOSITORY , loaded on 10-DEC-2014 09:39:52 File 215, ADAOS-4647 , loaded on 27-APR-2012 15:52:49 File 1009, LOBFILE of 9 , loaded on 8-OCT-2008 17:59:40 File 1080, LOBFILE of 80 , loaded on 4-AUG-2015 12:42:43 File 1113, LOBFILE of 113 , loaded on 23-JUN-2015 15:48:48 File 22111, LOBFILE of 111 , loaded on 29-NOV-2011 10:34:23 %ADABCK-I-IOCNT, 2 IOs on dataset WORK %ADABCK-I-IOCNT, 135 IOs on dataset DATA %ADABCK-I-IOCNT, 275 IOs on dataset ASSO %ADABCK-I-IOCNT, 41 IOs on dataset BCK001 %ADABCK-I-IOCNT, 34 IOs on dataset BCK002 %ADABCK-I-IOCNT, 80 IOs on dataset BCK003 %ADABCK-I-TERMINATED, 30-OCT-2015 11:05:26, elapsed time: 00:00:01
File 215 is dumped, and two physical copies of the backup are created. Only ACC users are allowed on file 30 while the dump is in progress.
adabck db=34 exu_dump=215 dual %ADABCK-I-STARTED, 30-OCT-2015 10:45:43, <version number> %ADABCK-I-DBON, database 34 accessed online Files dumped on 30-OCT-2015 10:45:44 Database 34, GENERAL-DATABASE File 215, ADAOS-4647 , loaded on 27-APR-2012 15:52:49 %ADABCK-I-IOCNT, 51 IOs on dataset DATA %ADABCK-I-IOCNT, 29 IOs on dataset ASSO %ADABCK-I-IOCNT, 40 IOs on dataset BCK001 %ADABCK-I-IOCNT, 40 IOs on dataset BCK002 %ADABCK-I-TERMINATED, 30-OCT-2015 10:45:44, elapsed time: 00:00:01
All base files in the database with a file number between 91 and 99 or equal to 51 or between 4 and 19 are dumped (including the corresponding LOB files, even if they are not in the specified file ranges). ADABCK allows a maximum of 10 seconds for ET logic users to come to ET status.
adabck db=34 dump=\(91-99,51,4-19\) et_sync_wait=10 %ADABCK-I-STARTED, 30-OCT-2015 10:51:14, <version number> %ADABCK-I-DBON, database 34 accessed online Files dumped on 30-OCT-2015 10:51:14 Database 34, GENERAL-DATABASE File 4, Update-log , loaded on 17-SEP-2014 14:44:19 File 9, EMPLOYEES , loaded on 8-OCT-2008 17:59:40 File 14, miscellaneous , loaded on 11-JUN-2015 13:22:19 File 17, Timezone , loaded on 19-SEP-2014 11:44:42 File 19, LARGE , loaded on 2-SEP-2014 15:37:18 File 51, PCA24SYSF1 , loaded on 14-APR-2014 16:55:22 File 91, ADAOS-2544 , loaded on 8-APR-2015 13:19:27 File 95, P299255 , loaded on 20-MAR-2014 11:35:30 File 98, ADAOS-4591 , loaded on 16-JUL-2015 10:03:16 File 1009, LOBFILE of 9 , loaded on 8-OCT-2008 17:59:40 %ADABCK-I-IOCNT, 715 IOs on dataset DATA %ADABCK-I-IOCNT, 1145 IOs on dataset ASSO %ADABCK-I-IOCNT, 1195 IOs on dataset BCK001 %ADABCK-I-TERMINATED, 30-OCT-2015 10:51:16, elapsed time: 00:00:02
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:
- Dump Method
Either parallel or non-parallel, depending on the setting of the PARALLEL parameter.
- DB I/O time
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.
- BCK n I/O time
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.
- Wait rates (only for dump method parallel)
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.- BF sync count (only for a backup in online mode)
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.
- ET sync time (only for a backup in online mode)
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.
- Transfer rate
This is the number of kilobytes read from or written to the backup file(s) per second.
Notes:
- For the transfer rate, only the pure backup/restore time is taken into consideration, but not the time required for the preparation of the backup/restore. Therefore, the transfer rate may be higher than the transfer rate you would get if you compute the transfer rate based on the total elapsed time of ADABCK.
- In the case of small backups, rounding errors may occur in the computation. Therefore, for very small backups the transfer rate is not displayed, because the value would be too inaccurate.
- Because usually many database blocks are not filled completely, and because only the net data are copied to the backup file(s), the transfer rate is less than the rate you would get if you consider the processed database space.
OVERLAY = {*|(number[-number][,number[-number]]...)}
[,ENCRYPTION = keyword]
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword] ) ]
[,KEEP_FILE_ALLOC]
[,KMSTARGET = string]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
[,REPLICATION]
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.
This parameter specifies that the created database is encrypted and assigns the encryption algorithm. The keyword can take the values AES_256_XTS, AES_128_XTS and NO. Depending on the keyword specified, the ASSO and DATA container files are encrypted using XTS Advanced Encryption Standard with a key length of 256 bits (AES_256_XTS), a key length of 128 bits (AES_256_XTS), or they are not encrypted (NO).
The default value is NO.
Notes:
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 specifies the key management system that is used if the created database is encrypted. Supported values are FILE and AWS. Depending on the specified value, encryption keys are created, stored, and managed by either the Adabas file-based key management system or the AWS key management service.
The default value is FILE.
Note:
You must specify the KMSTARGET parameter before the ENCRYPTION parameter.
Please see Examples for RESTORE/OVERLAY using ENCRYPTION and KMSTARGET.
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.
Important:
If a backup of e.g. database 100 is restored into an existing database 100,
but a NEW_DBID parameter with a different dbid is used, the database 100 will become
inaccessible. When accessing the database the Adabas utilities will report a DBID
mismatch because of a wrong dbid in the GCB RABN.
In such a case the following steps need to be performed to get access again to the database:
Rename the database directory from db100 to db101, change the container extensions from 100 to 101, and rename the DB100.INI file to DB101.INI.
Update DB101.INI: Edit the content by changing the path and file name of each environment variable value from 100 to 101.
Update assign.bsh: Edit the content by changing the path and file name of each environment variable value from 100 to 101.
Update ADABAS.INI: In the DB_LIST section edit all values from the old dbid value 100 to the new dbid val-ue 101.
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.
The parameter REPLICATION is relevant only for customers who are using the Adabas Event Replicator with Adabas - Adabas Replication.
This parameter should be specified if you want to use ADABCK for the Adabas - Adabas replication initial state processing. If you specify this parameter, the Adabas file is automatically marked as a replication target file.
For further information refer to ADAOPR CHANGE_REPLICATION_STATUS.
PARALLEL = keyword
This parameter can be specified to increase processing speed when creating/restoring from backups on slow devices 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]]...)}
[,ENCRYPTION = keyword]
[,FMOVE [=(number [,number [-number]]...)]]
[,FORMAT = (keyword [,keyword] ) ]
[,KMSTARGET = string]
[,NEW_DBID = number]
[,RENUMBER = (number[-number] [,number [-number]]...)]]
[,REPLICATION]
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.
Notes:
This parameter specifies that the created database is encrypted and assigns the encryption algorithm. The keyword can take the values AES_256_XTS, AES_128_XTS and NO. Depending on the keyword specified, the ASSO and DATA container files are encrypted using XTS Advanced Encryption Standard with a key length of 256 bits (AES_256_XTS), a key length of 128 bits (AES_256_XTS), or they are not encrypted (NO).
The default value is NO.
Notes:
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 specifies the key management system that is used if the created database is encrypted. Supported values are FILE and AWS. Depending on the specified value, encryption keys are created, stored, and managed by either the Adabas file-based key management system or the AWS key management service.
The default value is FILE.
Note:
You must specify the KMSTARGET parameter before the ENCRYPTION parameter.
Please see Examples for RESTORE/OVERLAY using ENCRYPTION and KMSTARGET.
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.
Important:
If a backup of e.g. database 100 is restored into an existing database 100,
but a NEW_DBID parameter with a different dbid is used, the database 100 will become
inaccessible. When accessing the database the Adabas utilities will report a DBID
mismatch because of a wrong dbid in the GCB RABN.
In such a case the following steps need to be performed to get access again to the database:
Rename the database directory from db100 to db101, change the container extensions from 100 to 101, and rename the DB100.INI file to DB101.INI.
Update DB101.INI: Edit the content by changing the path and file name of each environment variable value from 100 to 101.
Update assign.bsh: Edit the content by changing the path and file name of each environment variable value from 100 to 101.
Update ADABAS.INI: In the DB_LIST section edit all values from the old dbid value 100 to the new dbid val-ue 101.
The parameter REPLICATION is relevant only for customers who are using the Adabas Event Replicator with Adabas - Adabas Replication.
This parameter should be specified if you want to use ADABCK for the Adabas - Adabas replication initial state processing. If you specify this parameter, the Adabas file is automatically marked as a replication target file.
For further information refer to ADAOPR CHANGE_REPLICATION_STATUS.
The complete database is restored in parallel from several backup devices. Only database backups can be processed (backups created with DUMP=* or EXU_DUMP=*). The backup of example 1 for DUMP/EXUDUMP is used. The nucleus must be inactive.
adabck db=34 parallel=multi_process restore=\* %ADABCK-I-STARTED, 30-OCT-2015 11:13:24, <version number> %ADABCK-I-DBOFF, database 34 accessed offline Restore database 34 dumped on 30-OCT-2015 11:10:29 Database 34, GENERAL-DATABASE File 1, CHECKPOINT-FILE , loaded on 4-SEP-2014 13:52:43 File 2, SECURITY-FILE , loaded on 4-SEP-2014 13:52:43 File 3, USER-DATA-FILE , loaded on 4-SEP-2014 13:52:43 File 4, Update-log , loaded on 17-SEP-2014 14:44:19 File 9, EMPLOYEES , loaded on 8-OCT-2008 17:59:40 File 14, miscellaneous , loaded on 11-JUN-2015 13:22:19 File 17, Timezone , loaded on 19-SEP-2014 11:44:42 File 19, LARGE , loaded on 2-SEP-2014 15:37:18 File 30, FILE-30 , loaded on 31-MAR-2015 13:40:33 File 51, PCA24SYSF1 , loaded on 14-APR-2014 16:55:22 File 80, P295170 , loaded on 4-AUG-2015 12:42:43 File 91, ADAOS-2544 , loaded on 8-APR-2015 13:19:27 File 95, P299255 , loaded on 20-MAR-2014 11:35:30 File 98, ADAOS-4591 , loaded on 16-JUL-2015 10:03:16 File 101, COLLATION-TESTS , loaded on 14-APR-2014 16:47:30 File 111, TESTOPT , loaded on 29-NOV-2011 10:34:23 File 113, lob_LB , loaded on 23-JUN-2015 15:48:48 File 146, XMA-REPOSITORY , loaded on 10-DEC-2014 09:39:52 File 215, ADAOS-4647 , loaded on 27-APR-2012 15:52:49 File 1009, LOBFILE of 9 , loaded on 8-OCT-2008 17:59:40 File 1080, LOBFILE of 80 , loaded on 4-AUG-2015 12:42:43 File 1113, LOBFILE of 113 , loaded on 23-JUN-2015 15:48:48 File 22111, LOBFILE of 111 , loaded on 29-NOV-2011 10:34:23 %ADABCK-I-IOCNT, 1 IOs on dataset WORK %ADABCK-I-IOCNT, 133 IOs on dataset DATA %ADABCK-I-IOCNT, 244 IOs on dataset ASSO %ADABCK-I-IOCNT, 41 IOs on dataset BCK001 %ADABCK-I-IOCNT, 34 IOs on dataset BCK002 %ADABCK-I-IOCNT, 80 IOs on dataset BCK003 %ADABCK-I-TERMINATED, 30-OCT-2015 11:13:26, elapsed time: 00:00:02
File 215 is restored; the file must not already exist in the database. Database backups and file backups can be processed. If there is more than one backup file, the backup files are not processed in parallel, even if the backup was created with option PARALLEL. The nucleus may be either active or inactive.
adabck db=34 restore=215 %ADABCK-I-STARTED, 30-OCT-2015 11:18:34, <version number> %ADABCK-I-DBOFF, database 34 accessed offline Restore files from database 34 dumped on 30-OCT-2015 11:10:29 Database 34, GENERAL-DATABASE File 215, ADAOS-4647 , loaded on 27-APR-2012 15:52:49 %ADABCK-I-IOCNT, 7 IOs on dataset DATA %ADABCK-I-IOCNT, 28 IOs on dataset ASSO %ADABCK-I-IOCNT, 41 IOs on dataset BCK001 %ADABCK-I-IOCNT, 34 IOs on dataset BCK002 %ADABCK-I-IOCNT, 80 IOs on dataset BCK003 %ADABCK-I-TERMINATED, 30-OCT-2015 11:18:34, elapsed time: 00:00:00
All base files in a backup file with a file number between 91 and 99 or equal to 51 or between 11 and 19 are restored (including the corresponding LOB files, even if they are not in the specified file ranges). If a file already exists in the database, the file is overwritten. Database backups and file backups can be processed. The nucleus may be either active or inactive.
adabck db=34 over=\(91-99,51,11-19\) %ADABCK-I-STARTED, 30-OCT-2015 11:38:12, <version number> %ADABCK-I-DBON, database 34 accessed online Overlay files dumped on 30-OCT-2015 10:51:14 Database 34, GENERAL-DATABASE File 14, miscellaneous , loaded on 11-JUN-2015 13:22:19 File 17, Timezone , loaded on 19-SEP-2014 11:44:42 File 19, LARGE , loaded on 2-SEP-2014 15:37:18 File 51, PCA24SYSF1 , loaded on 14-APR-2014 16:55:22 File 91, ADAOS-2544 , loaded on 8-APR-2015 13:19:27 File 95, P299255 , loaded on 20-MAR-2014 11:35:30 File 98, ADAOS-4591 , loaded on 16-JUL-2015 10:03:16 %ADABCK-I-IOCNT, 619 IOs on dataset DATA %ADABCK-I-IOCNT, 1122 IOs on dataset ASSO %ADABCK-I-IOCNT, 1195 IOs on dataset BCK001 %ADABCK-I-TERMINATED, 30-OCT-2015 11:38:13, elapsed time: 00:00:01
Base file in a backup file with file number 98 will be restored as file 198. If that file already exists in the database, the file is overwritten. Database backups and file backups can be processed. The nucleus may be either active or inactive.
adabck db=34 overlay=98 renumber=198 %ADABCK-I-STARTED, 30-OCT-2015 11:40:12, <version number> %ADABCK-I-DBON, database 34 accessed online Overlay files dumped on 30-OCT-2015 10:51:14 Database 34, GENERAL-DATABASE File 98 renumbered to file 198 File 198 loaded on 16-JUL-2015 10:03:16 %ADABCK-I-IOCNT, 619 IOs on dataset DATA %ADABCK-I-IOCNT, 1122 IOs on dataset ASSO %ADABCK-I-IOCNT, 1195 IOs on dataset BCK001 %ADABCK-I-TERMINATED, 30-OCT-2015 11:40:13, elapsed time: 00:00:01
The complete database is to be restored as an encrypted database from an Adabas backup copy of a non-encrypted database. The ASSO and DATA container files are encrypted with algorithm AES_256_XTS. The encryption keys are created and managed by the Adabas file-based key management system (default: KMSTARGET=FILE).
adabck dbid=1 restore=* encryption=aes_256_xts
The complete database is to be overlayed as an encrypted database from an Adabas backup copy of a non-encrypted database. The ASSO and DATA container files are encrypted with algorithm AES_128_XTS. The encryption keys are created and managed by the Adabas file-based key management system.
adabck dbid=1 overlay=* kmstarget=file encryption=aes_128_xts
The complete database is to be restored as a non-encrypted database from an Adabas backup copy of an encrypted database. The Adabas container files are not encrypted.
adabck dbid=1 restore=* encryption=no
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
%ADABCK-I-STARTED, 30-AUG-2020 12:01:46, <version number>
Database dumped on 30-AUG-2020 11:57:04
Database 34, GENERAL-DATABASE
Summary of Database 34 30-AUG-2020 12:01:46
DATABASE NAME GENERAL-DATABASE
DATABASE ID 34
MAXIMUM FILE NUMBER LOADED 22111
SYSTEM FILES 1 (CHK), 2 (SEC), 3 (USR)
150 (RBAC)
ACTUAL FILES LOADED 23
CURRENT PLOG NUMBER 99
CURRENT CLOG NUMBER 10
SECURITY ACTIVE
ENCRYPTION AES_256_XTS
KMSTARGET FILE
KEKNAME 1598876857F83BB64A01916FFA3ACF9D39DB18537E80E3E48FD8A2333A3D77C8
Container Device Extents in Blocks Number of Block Total Size
File Type from to Blocks Size (Megabytes)
-------------------------------------------------------------------------------
ASSO1 file 1 35,840 35,840 4,096 140.00
ASSO2 file 35,841 166,400 130,560 2,048 255.00
ASSO3 file 166,401 205,120 38,720 32,768 1,210.00
ASSO4 file 205,121 210,240 5,120 16,384 80.00
ASSO5 file 210,241 944,832 734,592 8,192 5,739.00
DATA1 file 1 8,891 8,891 4,096 34.73
DATA2 file 8,892 24,379 15,488 8,192 121.00
DATA3 file 24,380 34,619 10,240 16,384 160.00
DATA4 file 34,620 388,763 354,144 32,768 11,067.00
WORK1 file 1 207,872 207,872 4,096 812.00
-------------------------------------------------------------------------------
19,618.73
=========
%ADABCK-I-IOCNT, 2 IOs on dataset BCK001
%ADABCK-I-TERMINATED, 30-AUG-2020 12:01:46, elapsed time: 00:00:00
The security information is only displayed if database security has been activated. Otherwise, the information is not displayed.
The encryption information about the encryption algorithm, KMS target (Key Management System) and KEK name (Key Encryption Key) is only displayed if the database is encrypted. Otherwise, the information is not displayed.
The RBAC system file is only displayed if it has been defined. Otherwise, the information is not displayed.
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.