Multideck Save/Restore Utility (dbsave)
Purpose
The Multideck Save/Restore utility, executed by entering dbsave at the UNIX shell or the Windows command prompt, increases the speed of a database file-save/restore by providing the capability to group the database into a number of logical groups of accounts, based on the size of accounts and the length of time it takes to save each account. It then saves (and restores) the groups in parallel using multiple tape devices. The grouping attempts to make each set of accounts save in about the same time.
Calculation of equal size groups of accounts is referred to as 'Calibration'. This must be carried out first, using Option 3 on the Multideck Save/Restore Menu, before you can execute a Multideck save. Re-calibration of the groups can be performed as frequently as required. The number of groups must be equal to the number of decks available to carry out the Save or Restore, which is configurable.
Once the groups have been established, a Save is initiated using the pre-configured set of tape decks. This starts a number of Reality Save processes (one Save process per group). Each Save process saves the set of accounts defined in that group. The Save processes run in parallel. As all the sets of accounts are about the same size, the Save of each group should complete in about the same time.
A Reality database saved using this technique can be restored in a similar way by using the Multideck Save/Restore utility to perform parallel ACCOUNT-RESTORE operations. Multideck Restores can only be performed using the same number of decks as the corresponding Save used. However, a single deck could be used to restore tapes sequentially, if required.
The Save tapes do not have to be loaded on exactly the same decks to restore; for example, if the tape is saved on deck 2, it is valid to restore it on deck 4, assuming both decks 2 and 4 are configured for multideck save/restore use. Before the restore starts, all tape labels are read to check that the tapes from a complete save set are loaded. The labels written by the Save processes are of the format:
MULTI-DECK SAVE USING LISTn hh:mm:ss dd mmm yyyy
This technique is not suitable for saving or restoring databases in which the accounts cannot be easily divided up into equal sets; for example, where there is only one application which is wholly contained in one account.
Multideck Save/Restore will operate with File Store Databases or Partition Databases. It uses Reality save/restore techniques and cannot be uses with other back-up schemes (such as cpio and dd on UNIX).
Syntax
dbsave
{-d databasePath} [
-C
| -c ]
dbsave {-d databasePath}
[ -R | -r ]
dbsave {-d databasePath}
[ -S | -s ] { -t
time }
dbsave {-d databasePath}
{ -a account }
dbsave {-d databasePath}
{ -v }
Refer to Conventions for details of syntax conventions.
Options
Options available are as follows:
Note
If you specify no options, other than the database name, a menu is displayed, as described under the topic Main Menu.
-a accountCalibrate named account.
-c Calibrate database. Executes the procedure described under the topic Calibrate System.
-C Calibrate (roughly) database.
-d databasePathThe full path of the database to be saved or restored. If a database is not specified, the default database
is used. If a default database is not defined, you are prompted for the database name.
-r Restore database, suppressing file resizing. Executes the procedure described in the topic Multideck System Restore.
-R Restore database and resize files. Executes the procedure described in the topic Multideck System Restore.
-s Save database and verify save. Executes the procedure described in the topic Multideck System Save.
-S Save database, suppressing verify save. Executes the procedure described in the topic Multideck System Save.
-t timeTime to start save. If a time is not specified, the save is started immediately.
-v Verify save.
Restrictions
dbsave assumes that the specified multiple tape decks each have only one tape. Multiple reels per device are not supported.
If you are using Database Isolation, you must use realroot to select required instance of Reality before running dbsave.
Files
dbsave resides in REALROOT/bin.
Main Menu
Running dbsave without options other than specifying the database name displays a menu similar to the following:
Multideck Save and Restore Menu 1. Multideck System Save 2. Multideck System Restore 3. Multideck Calibration Enter Option (1-3):
Before performing a Multideck System Save you must calibrate the database using Option 3 Multideck Calibration. If you do not do this, the Save will fail with the message:
***FAILED***No account calibration statistics available
Multideck Calibration
On selecting option 3 from the main menu, the following calibration sub-menu is displayed:
Multideck Calibration 1. Calibrate system 2. Calibrate account Enter Option (1-2):
Calibrate System
This procedure generate file statistics for the whole database. It is run by selecting option 1 on the Calibration sub-menu or by running dbsave with the -c or -C option.
Note
On UNIX, if you execute this procedure from the main menu or by using dbsave with the -c option, it will carry out a full calibration. When executed using dbsave with the -C option, it carries out a rough calibration only, calculating the approximate size of accounts by totalling their file modulos. Rough calibration is therefore much quicker than the full calibration of a database. Where a full calibration may take several hours, the rough calibration may only take a few minutes.
On Windows, if you execute this procedure from the main menu, you will be prompted to choose full or rough calibration.
The following procedure is carried out:
- File statistics are generated for each account in turn.
- The statistics generated for each account are processed and the results are written into a data section of STAT-FILE called CALIBRATION, using the account name as the item-id.
Each account item comprises four attributes, as follows:
001 Time taken to save account
002 Total size of account (including in group and indirect)
003 In group size
004 Indirect size
Calibrate Account
You can re-calibrate a single account by selecting option 2 on the Calibration sub-menu or by running dbsave with the -a account option. You might need to do this if an account has been restored, or if an existing account has changed considerably.
If the specified account does not exist, the following messages appear:
FAILED generation of statistics Output from FAILED process... +++++++++++++++++++++++++ ***FAILED*** Accountname 'account' not in SYSTEM file +++++++++++++++++++++++++
Multideck System Save
If you select option 1 on the main menu or run dbsave with the -s or -S options, the utility interrogates the Multideck configuration file to obtain details about which tape devices are to be used. It then displays a pre-test screen similar to the following.
Multideck System Save Using deck selection: TAPE x TAPE y TAPE z Pre-test will attach, rewind, write then rewind decks. Load each deck with write enabled medium Then press 'y' when ready to continue:
When you enter Y, the pre-tests are started, and once successfully completed, the appropriate number of account lists are created. The lists are written to a data section of STAT-FILE called CALIBRATIONLISTS. The lists are called LIST1, LIST2, etc.
All default SYSTEM accounts are automatically put into LIST1, including SYSTEM, SYSMAN, SYSPROG, SYSFILES, DENAT, ENGLISH-TUTORIAL, HOTEL, UPGRADE.ACCOUNT and SQLDEMO.
If you execute the Multideck System Save from the main menu, you are prompted with the option to sleep a specified time before commencing the Saves, as follows:
Enter time to start the Saves (hh:mm) or return to start now :
Entering a time displays the message:
Sleeping until hh:mm hours...
If you run dbsave with the -S or -s option, no prompt is given. You must specify any sleep time with the -t option; if you do not specify a time, the Save is started immediately.
The Multideck System Saves are then started and constantly monitored until all of them have finished. Monitoring is displayed in a format similar to the following:
Multideck System Save Starting Save using list 3 Starting Save using list 4 Starting Save using list 6 Sleeping for 5 seconds Monitoring 3 Save Processes Save Process using deck 4 complete with no errors detected Save Process using deck 6 complete with no errors detected Save Process using deck 3 complete with no errors detected System Save COMPLETE
When all Save processes have completed successfully, a Multideck verify-save is started and monitored, except when the -S option is executed, in which case the verify save is suppressed and the procedure terminated.
Monitoring is displayed in a format similar to the following:
Starting verify using list 3
Starting verify using list 4
Starting verify using list 6
Sleeping for 5 seconds
Monitoring 3 verify processes
Verify process using deck 4 complete with no errors detected.
Verify process using deck 6 complete with no errors detected.
Verify process using deck 3 complete with no errors detected.
system verify COMPLETE
If any errors occurred, they will also be displayed. For example:
Error detected on Save process using deck 4
Errors detected
System Save INCOMPLETE
The error messages displayed should give an indication as to why the process has failed, but for further details of errors encountered, you must look in the file /tmp/db_ERRx (UNIX) or %TEMP%\db_ERRx (Windows), where x is the number of the tape deck which failed.
Multideck System Restore
If you select option 2 from the main menu, or run dbsave with the -r or -R option, the utility interrogates the Multideck configuration file to obtain details about which tape devices are to be used and then displays a pre-test screen similar to the following:
Multideck System Restore Using a deck selection: TAPE x TAPE y TAPE z Pre-test will attach, rewind, read then rewind decks. Load each deck with write protected medium Then press 'Y' when ready to continue:
On entering Y, the pre-tests are started.
If the Restore is executed from the main menu, you are then asked about file sizing with the prompt:
Do you want to resize files during restores (y/n) ? :
Note
If you start the restore by running dbsave with the -r or -R option, this prompt is not displayed. Instead, file sizing will be run automatically if you use the -Roption and will not be carried out if you use the -r option.
Pressing y will cause all the Restore processes to run with resizing of files, if selected, and where specified by attribute 13 of a file definition item. This will result in a slower restore time. Restore processes are started and constantly monitored until all of them have finished.
Monitoring will be displayed in a format similar to the following:
Multideck System Restore Starting Restore using list 3 Starting Restore using list 4 Starting Restore using list 6 Sleeping for 5 seconds Monitoring 3 Restore processes Restore Process using deck 4 complete with no errors detected Restore Process using deck 6 complete with no errors detected Restore Process using deck 3 complete with no errors detected System Restore COMPLETE
If any errors occurred, they will also be displayed. For example:
Error detected on Restore process using deck 4
Errors detected
System Restore INCOMPLETE
If this occurs, retry Option 2. If it still fails, you will need to contact your Support representative.
The error messages displayed should give an indication as to why the process failed, but for further details of any errors encountered you must look in the file /tmp/db_ERRx (UNIX) or %TEMP%\db_ERRx (Windows), where x is the number of the tape deck which failed.
Configuration File
The Multideck Save/Restore utility uses a tape deck configuration file called dbsave_config, located in the database configs directory. The format of this file is simple and consists of one line of entries, where each entry specifies the number of a Reality tape device to be used for the Multideck Save/Restore. Each entry must be configured as a tape device in the normal way in the database config file.
The TapeDevSizen parameter should be defined in the database configfile for each tape device used for the Multideck Save. TapeDevSizen defines the maximum amount of data in Megabytes that can be stored by the tape device and is used by the calibration process when allocating a set of accounts to that device. This prevents the save from exceeding the tape size.
Example
The following example of configuration file format defines that tape devices 3, 4 and 6 are to be used:
3 4 6
This example would generate three groups of accounts to be saved. If the dbsave_config file is missing, the utility will fail, displaying the error message:
Cannot read MultiDeck configuration file, unable to continue