Name

btr — B Tree index recovery

Synopsis

btr [-a] [-d] [-f] [-k] [-n cnt] [-r] [-v] [--] old_file new_file

Description

btr will attempt to recover key (and optionally data) information from the B Tree index file identified by old_file. The recovered contents are written to the B Tree index file identified by new_file. btr recovery is controlled by a number of arguments:

Command Arguments

 

[ -k | -d ]

Specifies recovery mode; -k for keys, -d for keys and data. Default if omitted is -k.

 

[-n cnt]

Sets maximum number of io errors to ignore before terminating the recovery. Default is 0.

 

[-v]

Causes btr to display information on the recovery process. This flag may be repeated up to three times to increase the level of information. For a large B Tree index this could lead to a significant amount of output.

 

[-a]

If specified, the B Tree index in new_file will allow duplicate keys. The default is not to allow duplicates.

 

[-f]

If specified, the B Tree index represented by new_file will be overwritten. Default is to preserve new_file, should it exist.

 

[-r]

Requests btr to attempt full recovery mode even if the version of the old_file does not support it.

 

[--]

Causes btr to stop processing command arguments. Should be used if old_file begins with a '-'.

Recovery Processing

btr will attempt to open the input btree file using the btree library version of btopn. If this fails, the btr version of btopn is used instead, which bypasses the consistency checks.

An attempt to read the superroot is made. If successful, the root names and root blocks are recorded. Only the roots present in the superroot are retained. Root names in any child blocks are ignored; the index structure may be damaged and therefore no attempt to traverse it is made.

Each block, starting from 1, is read. If marked as ZROOT, ZINUSE or ZDUP the keys and values are extracted directly from the in-memory array. If -k specified, the key and value are written to the new_btree index file. If -d specified, and the value is a valid disk record address, an attempt is made to read the data record. Data record addresses are stored in a supporting bt index file (.bt_da.db), to enable detection of circular references. If the data record is read OK, the key and data record is written to the new_file btree file. If the data record cannot be read, only the key is written.

In version 4 (and later) of the BTree index, each ZINUSE block contains the root block it belongs to. This data allows btr to partition keys by their roots. Only those roots recovered from the superroot will be named as in the old_file. Keys from other roots will be copied to new roots, named after their root block number (e.g. root_19834).

btr will display summary statistics about the recovery on stdout when complete.

Exit Status

0 if OK.

Notes

btr can be used to recover (or indeed migrate) data from earlier (i.e. pre-version 4) versions of a Btree index file. Since the root block numbers are not held in the ZINUSE blocks, keys can not be partitioned by root. Therefore, this facility is only really applicable to single-rooted B Tree index files.