realdbck

Checks the consistency of a partition database and attempts to fix errors that are found.

Caution

Although realdbck reports GFEs, and validates and attempts to repair the physical structure of a database, it does not restore data loss, nor it is guaranteed that all GFEs will be reported. To ensure complete database integrity, it is recommended that you remake the database (see mkdbase), restore the last FILE-SAVE and roll forward clean logs. To check for GFEs execute the ALL-FILE-STATS command.

By default, realdbck logs all users off the database.

Syntax

realdbck {options} {database}

Options

-a Allows realdbck to be run on an active database without logging users off. It is recommended that you use the -a option in conjunction with the -n option.

-c Checks only that the database is marked as having been shutdown cleanly. Does not do a full check.

-f Checks free space only. This option is only available if the database has been configured to mark every block as free or in use (the default is to mark only the first block of each contiguous set of blocks). For more information, refer to the description of the ForceFreeSpaceUpd configuration option.

-l num Sets limits on the number of errors. Abandons the check/repair if the limit is reached.

-m size Specifies the amount of memory (in megabytes) used for the database map (see Checking). Must not exceed 1Gb. Default, 256Mb.

-n Assumes the answer is "no" to any question. This ensures no modifications are made to the database.

-s Marks the database as having been shutdown cleanly (for database daemon and server use only).

-S Marks the database as dirty and does not carry out the check sequence (for database daemon and server use only).

-v Verbose mode. If not selected, messages to the terminal will refer only to errors.

-V Semi-verbose mode. Prints account names only.

-y Assumes the answer is "yes" to any "Are you sure?" type question.

-z Discards the existing free space table before starting the check.

The -S and -s options are used by the database daemon only at start and end of a session. Both fail silently if the database is not a partition type (possible on UNIX only).

Parameters

database is the database to be checked, specified as an absolute path name or the system name of the database, as defined in the ROUTE-FILE (UNIX) or registry (Windows). If you do not specify database, realdbck checks the default database.

Comments

realdbck logs off all database users before starting its check, unless you use the -a option.

realdbck with the -c option is run by the database daemon (UNIX) or server (Windows) each time a database is started up. If the check fails then the utility must be run again to clean up the database. The degree of checking and salvaging is user selectable using the options described above.

If you are using Database Isolation, you must use realroot to select required instance of Reality before running realdbck.

Checking

When you run realdbck, it builds a map of the database, containing the status of each block. This map requires 8 bytes for each block in the database; the map of a 256Gb database will therefore occupy 2Gb of disk space. The -m option allows you to set the amount of memory used when building the map. The greater the amount of memory, the faster realdbck will run.

realdbck walks through all database files, beginning with the first group of the SYSTEM file. For each group it checks off each block used for in-group space. Assuming there are no group format errors (GFEs), it checks the:

D-pointer, recursing down that section.
Out-of-group items with less than 127 contiguous blocks, checking off referenced blocks without reading them.
Fragmented out-of-group items, checking off referenced blocks by reading only the tails of each fragment.
In-group items.

Repair

realdbck cleans up inconsistent data blocks and transfers them to the free block list. Its main purpose is the quick recovery of the free space table, black-holed files and out-of-group items.

Note: Black holes are unreferenced blocks or groups of blocks.

realdbck will not normally prompt you for input. However, if your database is badly damaged, you may see one or more prompts. realdbck is not equipped to repair a badly damaged database, so if this occurs it is recommended that you exit realdbck. Then rebuild the database (using mkdbase -r) and restore the last back-up tape. If in doubt, contact your Northgate support representative for assistance.

Types of Error

The following types of error are found by realdbck:

Group Format Errors (GFEs). These can be caused if a multi-block operation is interrupted. Repairing a GFE black-holes any branches from that group.

Note: It is not guaranteed that realdbck will report all GFEs. To check for GFEs execute the ALL-FILE-STATS command.
Black holes. These are unreferenced blocks, or groups of blocks. If the blocks are marked as being type free or unknown, the hole can be cleaned up and added to the free list.
Duplicate References. These may arise from an aspect of delayed-write in which the blocks are not synchronised to disk in correct order. For example, when an out-of-group item is deleted and its space assigned to a new item, if the older in-group reference was not synchronised, but the new one was, the item body would be double-referenced. Similarly a block might be on the free list as well as in a file.
Incorrect Linkage of blocks. These occur in the same way as Duplicate References.

Checking the Database Automatically at Startup

The RealDbCk database configuration parameter allows you to choose what action to take at startup if the database was not shut down properly. The parameter accepts the following values:

0 If the database was not shut down cleanly, the connection is rejected and the database is not opened. You will need to run realdbck to check and, optionally, clean the database, or the database will need to be rebuilt.

1 If the database was not shut down cleanly, realdbck is run automatically to check the database and recover unreferenced blocks. If no errors are found the connection is allowed; otherwise, the connection is rejected and the database is not opened.

2 If the database was not shut down cleanly, realdbck is run automatically to check the database and recover unreferenced blocks. When realdbck completes, the connection is allowed, whether or not any errors were found.

3 If the database was not shut down cleanly, a message is logged to that effect in the daemon log, but realdbck is not run. The connection is allowed.

Connection is always allowed if the database was shut down cleanly.

Daemon Log Messages

The messages listed in the following table are logged in the daemon log, to record the checks made and their success or otherwise in cleaning a dirty database. The messages are also logged in the file DatabasePath/configs/dbproblems.log to ensure that they are not lost when the daemon log is rotated.

Message	Reason
`Database was not shutdown cleanly`	The start-up test found that the database was not shut down cleanly.
`Initiating auto check`	The database daemon is about to run realdbck to check the database. Logons will be inhibited until the check is complete.
`Database check succeeded`	Checking the database succeeded and logons are enabled.
`Database check failed`	Checking the database failed and the database has been left locked.
`Database check failed - continuing anyway`	Checking the database failed, but logons have been enabled anyway.
`Ignoring dirty status`	The start-up test found that the database was not shut down cleanly but logons have been enabled anyway.