ADABCK (Dump And Restore Database Or Files)

This document describes the utility "ADABCK".

The following topics are covered:


Functional Overview

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.

The backup copy can be directly assigned to tape: this option supports consecutive tapes (see 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 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 Using Utilities).

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 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 (Linux 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.

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 should not already exist. To use the encryption functionality, the Adabas Encryption for Linux (AEL) license is required.

Notes:

  1. The RESTORE and OVERLAY functions can process backup files created with earlier Adabas versions, but usually not backup files created with later Adabas versions. However, it is possible to restore with earlier Adabas versions if the structures did not change. For example, version 6.6 backup files can be restored with verions 6.5, unless superdescriptors with character-set encoding are used. If features are not supported by the earlier version, the structure level check will fail.
  2. The RESTORE option PARALLEL=MULTIPROCESS is not supported for backup files created on a platform with a different endian mode. However, a backup that is split into several extents can be loaded.

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.

Procedure Flow

Procedure Flow ADABCK 1

Procedure Flow ADABCK 2

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  
DBnnn.INI   Disk Adabas Extended Operations
Control statements stdin
SYS$INPUT
  Utilities
ADABCK messages stdout/
SYS$OUTPUT (see note 4),
stderr/
SYS$ERR (see note 5)
  Messages and Codes
Work WORK1 Disk  

Notes:

  1. A named pipe can be used for this sequential file (Linux platforms only, see Using Utilities for details).
  2. For functions other than DUMP or EXU_DUMP (BCK001 only).
  3. For DUMP or EXU_DUMP (BCK001 only).
  4. If BCK001 is not stdout/SYS$OUTPUT.
  5. If BCK001 is stdout/SYS$OUTPUT.

The sequential files BCK00n can have multiple extents. For detailed information about sequential files with multiple extents, see Using Utilities.

Checkpoints

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:

  1. Nucleus only required when AUTORESTART is pending at the end of this function.
  2. For restore of database or system files.
  3. For restore of files.

Control Parameters

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]  

     ENCRYPTION = keyword                       

     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

     KMSTARGET = string

     OVERLAY = {*|(number[-number][,number[-number]]...)}
 	       [,FMOVE [=(number [,number [-number]]...)]]
 	       [,FORMAT = (keyword [,keyword])]
 	       [,KEEP_FILE_ALLOC]
 	       [,NEW_DBID = number]
 	       [,RENUMBER = (number[-number] [,number [-number]]...)]]
         [,REPLICATION]

     PARALLEL = keyword

     READ_CHECK

     RESTORE = {*|(number[-number][,number[-number]]...)}
 	       [,FMOVE [=(number [,number [-number]]...)]] 
 	       [,FORMAT = (keyword [,keyword])]
 	       [,NEW_DBID = number]
 	       [,RENUMBER = (number[-number] [,number [-number]]...)]]
         [,REPLICATION]

     SUMMARY

CONTENTS

CONTENTS

This parameter displays a list of files in an Adabas backup copy created with the DUMP or EXU_DUMP function.

Example

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

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.

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

DBID = number

This parameter selects the database to be used.

DUMP

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.

BLOCKSIZE = number[K|M]

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.

DRIVES = number

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.

[NO]DUAL

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.

ET_SYNC_WAIT = number

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:

  1. If you forgot to specify the ET_SYNC_WAIT parameter for ADABCK, and ADABCK is hanging because of open transactions, you can do one of the following to let ADABCK continue: temporarily set TT to a small value -after ADABCK terminates, you can set the value back to its original value; or stop the user(s) that have open transations (with ADAOPR STOP).
  2. If updates were performed in the database during the ET synchronization, all modified blocks must be written to the database containers and to the backup copy when all open transactions have been committed or rolled back. Therefore, the total time for the ET synchronization, which can be displayed via the IOSTAT parameter, may be longer than the time specified with the ET_SYNC_WAIT parameter.

[NO]NEW_PLOG

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.

REPLICATION

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.

ENCRYPTION

ENCRYPTION = keyword

This parameter specifies that the database to be created 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.

Note:
Database encryption cannot be disabled.

Examples for ENCRYPTION and KMSTARGET

Example 1

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 

Example 2

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

Example 3

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

EXU_DUMP

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.

BLOCKSIZE = number[K|M]

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.

DRIVES = number

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.

[NO]DUAL

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.

[NO]NEW_PLOG

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=*.

REPLICATION

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.

Examples for DUMP/EXUDUMP

Example 1

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

Example 2

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

Example 3

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

FILES = { * | (number[-number][,number[-number]]...)}

This parameter displays status information of the specified files in a dump file.

IOSTAT

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.

Example:

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:

  1. 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.
  2. 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.
  3. 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.

KMSTARGET

KMSTARGET = string

This parameter specifies the key management system that is used if the database to be created is encrypted. Supported values are FILE and AWS. Depending on the value specified, either the Adabas file-based key management system or the AWS key management service is used to create, store and manage encryption keys.

The default value is FILE.

Examples for KMSTARGET

Please see the control parameter ENCRYPTION for examples for KMSTARGET.

OVERLAY

OVERLAY = {*|(number[-number][,number[-number]]...)}
          [,FMOVE [=(number [,number [-number]]...)]]
          [,FORMAT = (keyword [,keyword] ) ]
          [,KEEP_FILE_ALLOC]
          [,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.

FMOVE [=(number [,number [-number]]...)]

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.

FORMAT = (keyword [,keyword])

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.

KEEP_FILE_ALLOC

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.

NEW_DBID = number

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 = (number[-number] [,number [-number]]...)

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.

REPLICATION

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

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:

  1. In the case of ADABCK RESTORE or ADABCK OVERLAY, PARALLEL must be specified before the OVERLAY or RESTORE parameter.
  2. The PARALLEL parameter is not supported on Windows platforms.
  3. It is possible to pass the output of ADABCK DUMP or ADABCK EXU_DUMP to named pipes, which can be directly used as input for an ADABCK RESTORE or ADABCK OVERLAY in order to copy a database or some files from one database to another database.
  4. The PARALLEL parameter does not improve the performance of the READ_CHECK function.
  5. The use of PARALLEL=MULTI_PROCESS is not recommended for the DUMP operation if the data is to be restored on a computer with a different endian mode - the RESTORE operation will reject backup files created with PARALLEL=MULTI_PROCESS on a computer with a different endian mode.

READ_CHECK

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

RESTORE = {*|(number[-number][,number[-number]]...)}
          [,FMOVE [=(number [,number [-number]]...)]]
          [,FORMAT = (keyword [,keyword] ) ]
          [,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:

  1. You can only use RESTORE=* if the dump file was created with DUMP=* or EXU_DUMP=*.
  2. A backup created on a platform with different endian mode will not be restored if the backup was created with the option PARALLEL=MULTI_PROCESS.

FMOVE [=(number [,number [-number]]...)]

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.

FORMAT = (keyword [,keyword])

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.

NEW_DBID = number

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.

REPLICATION

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.

Examples for RESTORE/OVERLAY

Example 1

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

Example 2

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

Example 3

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

Example 4

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

SUMMARY

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.

Example

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                    WO-DB-34
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.

Restart Considerations

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.