kdbfchk - Check and repair a database file

SYNOPSIS

kdbfchk [options] inputfile [inputfile ...]

DESCRIPTION
The kdbfchk utility checks and optionally repairs the given KDBF input files. Nearly all files in a database are KDBF format, including tables, regular indexes, and most files of Metamorph indexes. Each inputfile is a full filename, including extension. For example, to check the patent table in the database /usr/local/morph3/texis/testdb, use the command kdbfchk /usr/local/morph3/texis/testdb/patent.tbl.

kdbfchk is a low-level repair utility and as such does not use Texis locks to guarantee database integrity. It is imperative that no modifications be made to a file while it is being repaired. This means no inserts, deletes or updates on the file, or on any table/index that affects it (e.g. if repairing an index, don't touch the table either). Failure to do so may further corrupt the file, or cause spurious corruption messages during a scan. Care must also be taken while replacing a corrupt file with a newly-repaired copy.

Given just an inputfile, kdbfchk will conduct a full scan for KDBF-level errors. As it can take a while to thoroughly scan a large table, kdbfchk prints a progress meter (#-signs) during each of its 3 passes over the file, showing the relative percentage completed so far. The meter may not reach 100% if not applicable to the current pass. If all appears well when finished, the message "File checks ok" will be printed.

If corruption or other errors are detected, a summary of the errors will be printed, and a non-zero exit code is returned: 26 if the file is not KDBF format, 29 if corruption was detected, or 27 if an internal error was encountered. When multiple inputfiles are being scanned, the exit code is the "worst case" found among the files. Therefore a bad file will always cause the final exit code to be nonzero, even if other good files were scanned after it in the list. The exit code can be checked by automated scripts that use kdbfchk, e.g. as an integrity check on machine boot.

If an outputfile is specified with -o, a repaired copy of the inputfile is written to it. (Only one inputfile may be given if an outputfile is set.) As far as possible, data blocks in the inputfile will have the same offset in the outputfile. This means that if a table is repaired, pre-existing indexes will generally not be invalidated because of the repair. Since the indexes may be out of sync due to the original corruption, however, it is a good idea to re-create them as soon as possible. It is up to the user to safely replace the input file with the repaired output file, taking to prevent database writes while doing so.

Instead of an in-depth scan and repair, kdbfchk has several other actions it can perform:

-q Quick scan. Only check the free tree and the end of the file. This is much faster than the in-depth scan, but only checks that the file can be inserted into, not other errors.

-d offset [size] Just delete (free) the KDBF block at offset, which is given in decimal, or hexadecimal with a 0x prefix. The -d action requires the -O overwrite option (see below), as the file is written in place. If size is also given, the total block size is forced to be that size - use with caution, as other blocks may then be overwritten. Giving the size may be needed if the offset is corrupt, or otherwise doesn't look like a valid block.

Note: With -d it is assumed that you really know what you're doing. The above caveats about modifying an in-use file apply here as well. Deleting blocks from a table will not update associated indexes, as normally happens with a high-level SQL delete. While not always a problem, indexes should be remade nonetheless.

-p offset [size] Print the raw block data at offset, in hexadecimal and ASCII. As with -d, size forces the size. Since kdbfchk is a low-level utility, the data may not be humanly decipherable.

-l List data blocks' offsets and sizes. Added in versions after 3.0.940300000 (Oct. 18 1999).

Additional options may be given:

-o outputfile Output the repaired KDBF file to outputfile. Only one inputfile may be specified if this option is used.

-O Overwrite the inputfile. This option is required for the -q and -d actions, though it is not yet supported for the default in-depth scan.

-s Save truncated data blocks instead of deleting them. Normally kdbfchk completely frees any data blocks that appear truncated. With -s truncated blocks are repaired but left truncated. This can cause problems for higher-level programs when reading the repaired block, as the missing data may be an error.

-k Assume inputfile is in KDBF format even if it doesn't appear to be. If a file was badly corrupted, it may no longer appear to be KDBF, and kdbfchk will not scan it. The -k option forces the scan or repair when the user knows the file to be KDBF.

-i Ignore orphaned free blocks in scan. This tells kdbfchk to assume that any free blocks found during the scan are bad if they're not part of the free tree or list (i.e. they're orphans). They will be merged into the next free pad block created.

-t dir Use temporary directory dir. If not specified, the environment variables TMPDIR, TMP and TEMP are checked.

-M none|simple|pct Type of progress meter to print while working. Added in version 4.01.1031238533 Sep 5 2002.

-f file List free blocks. A list of free blocks found during the scan will be printed to file. This includes normal free-tree/free-list blocks, as well as any orphaned blocks found.

-b file List bad blocks. A list of bad blocks found during the scan will be printed to file.

-n Don't list orphaned free blocks/pages. This applies only when the -b option is used.

m N Limit information to N messages. By default no more than 1000 messages are written to the bad blocks (-b) file. With -m a different limit can be set; if 0 is specified there will be no limit.

-version Print version information.

--identify Print release, features and other information.

-h Print help on options.

CAVEATS
It is normal (and benign) to have orphaned free blocks left over after a file has been successfully repaired (i.e. reported if the file is re-scanned by kdbfchk), as these cannot currently be re-attached. Some loss of free space will result - which can be regained by copying the table at the SQL level - but no data will be lost from these blocks, nor will corruption result from normal operations.