The Eloquence dbcfix utility may used to verify and optionally fix
the chain consistency in an Eloquence database.
A chain could be damaged in the Eloquence database if the transaction
integrity was violated. For example due to a system crash (running
in async mode) or fixing an inconsistent database volume with dbfsck.
The dbcfix utility is an off-line tool and requires exclusive access
to the volume files. Before running the dbcfix utility the eloqdb
server must be shut down.
The dbcfix must either be executed by root or the user specified in
the eloqdb.cfg configuration file.
Usage:
dbcfix [options] database [set[.detail_item] ...]
dbcfix [-c cfg] -P database set chain_idx recno {new_chain_values}
options:
-help - show usage (this list)
-u user - set user name
-p pswd - set password
-c cfg - server configuration file
-b size - Buffer cache size (MB)
-v - verbose output
-l file - specify log file (stdout is default)
-w - enable write mode
-R - force chain rebuild (in physical order)
-M - use master key
A list of data sets (and paths) may be specified. If no data set is
given, all paths in the database are verified. If a master set is specified,
all paths to related detail sets are verified. If a detail set is given,
all paths of the detail set are verified. The detail_item option may
be used to specify a single path in the detail set.
The -P and -R options should only be used when instructed by the
product support. Wrong usage may damage the database.
The -c option may be used to specify a database configuration file
other than the default eloqdb.cfg.
The -b option may be used to specify the buffer cache size (in MB).
If not set, it defaults to 64 MB. Older Eloquence versions used the BufferCache setting
from the database server configuration file.
The -l option may be used to specifiy the name of an output file that
provides a report of the processed chains and any problems found.
If the -v option is specified in conjunction with -l, progress messages are displayed.
In case the database requires specific access privileges, the -u
and -p options may be used to specify user and password. Please
note that neither the EQ_DBUSER and EQ_DBPASSWORD environment
variables nor files may be used. By default the dbcfix utility uses
the "public" user.
The -M option is used with encrypted databases. When specified,
the EQ_MKEYID and EQ_MKEYFILE environment variables are used to provide master key(s)
to access encrypted data. The user is prompted to enter the passphrase(s).
The dbcfix utility by default runs in READONLY mode. In readonly
mode, any problems found are reported to the log file but the volume
files are not changed.
If the -w option is specified, chain inconsistencies are corrected.
The -R option is used in WRITE mode to force rebuilding any chains.
Instead of verifying chain consistency and fixing any issues, the
chain information in the master is reset and chains are rebuilt
in detail data set record number order.
This might affect applications that rely on chain order in case the
records in the detail data set were removed and re-added in the past.
Don't use the -R option unless you are aware of the consequences.
The -P option is intended for support usage only. It can be used to
manually overwrite the internal chain linkage information in the data
set with the supplied values. The following arguments must be present:
chain_idx: related_set[.detail_item] or numeric index (0 based)
recno: record number of the affected record
new_chain_values: master set: count first last
detail set: prev next
Don't use the -P option unless you know what you're doing.
The first argument (besides any option) is the database name.
The database name may not include any connection information,
such as a host name or servide/port numer. Also the EQ_DBSERVER
environment variable that is used to specify a default server
envionment is not available.
After the database name, a list of data set names (or numbers)
may be specified. For detail data sets, a path may be specified,
separated by a period.
In case a master set is specified, all chains for this master
are processed (including all related detail sets).
In case a detail set is specified, all chains related to the
detail set are processed.
In case a detail set is specified qualified with an item name,
only the specified path is processed.
For example:
dbcfix -l log -v sample
The database sample is processed. A report is written to the
file log and the progress is printed on the screen.
dbcfix -l log sample orders lineitems
The database sample is processed. A report is written to the
file log. Only chains related to the data sets orders and line
items are processed.
dbcfix -l log -w sample orders.orderid
The database sample is processed in WRITE mode. A report is
written to the file log. Only the chain related to the data
set orders and qualified by the search item orderid is
processed.
The dbcfix utility needs two passes to verify a chain is consistent.
In pass 1 the master set is read sequentially. The chain head in
the master set is validated against the detail records.
In case an inconsistencyis found, the chain head is updated and if
necessary the chain in the detail is truncated.
By the end of pass 1, all chain heads are valid and all chains they
point to are correct.
During pass 1 a map of all valid detail records is created.
Pass 2 reads the related detail set sequentially. In case the record
was not processed in pass 1, it is added to the end of the chain.
The dbcfix utility relies on the consistency of the btree index
of a master set. If the btree that handles the search item of a
master set is defective, consistent chains may be considered broken.
The dbcfix requires that all data sets are created. In case a
data set is not created (or has been purged) it will abort with
an internal error message.
In case of a missing manual master set entry (detail record w/o a
manual master) the detail record is fixed and the manual master
record is added. A message is written to the log file.
The dbcfix utility reads chains in forward order. In case a
link inconsistency is detected, the chain pointers are either
updated or the chain is truncated. Any orphaned detail records
are then re-added to the (end of the) chain in pass 2.
This may cause chain order changes, depending on the type of
inconsistency.
Currently, no attempt is made to use the backwards link information
for recovery. Using the backwards link information may increase
the accuracy (in some cases) to retaining the existing chain order
in case an inconsistency is detected.
Eloquence compares P and Z items based on their numeric value,
even if different binary encoding is used (eg. unsigned and
positive values are considered the same).
dbcfix currently neither correctly verifies nor fixes sorted chains.
All chains are currently considered unsorted, sort items are ignored
(#2575).
The following messages may be written to the log file:
Broken chain (2) at record 13
Circular reference detected
Chain head was: cnt=4, first=6, last=16
Truncating chain at record 16
- Cause:
- The current detail record is already part of a chain.
- Fix:
- Truncate that chain at the previous detail record.
Broken chain (3) at record 6
Search items do not match
Chain head was: cnt=4, first=13, last=31
Truncating chain at record 31
- Cause:
- The master and detail search item values do not match.
- Fix:
- Truncate that chain at the previous detail record.
Updating chain head ...
Chain head was: cnt=4, first=13, last=31
New chain head: cnt=2, first=13, last=26
- Cause:
- The chain in the detail set does not match the chain head.
- Fix:
- Update the chain head.
Broken chain (4) at record 31
Inconsistent backwards link (0, should be 29)
Chain head was: cnt=4, first=13, last=31
- Cause:
- The backwards link is inconsistent.
- Fix:
- Update the backwards link.
Broken chain (1) at record 10000
Unable to read record, status = 13
Chain head was: cnt=4, first=13, last=31
Truncating chain at record 31
- Cause:
- The record specified in the chain head or forward link
does not exist.
- Fix:
- Truncate that chain at the previous detail record.
Reconnecting detail record 13
- Cause:
- A detail record was found that is not connected to a chain.
- Fix:
- The record is added to the chain.
Failed: Missing manual master entry for detail record 23
- Cause:
- A manual master entry was missing for a detail entry.
- Fix:
- Add the manual master entry.
Processing database : sample
Running in READONLY mode
DATA SET CHAIN PASS1 PASS2
----- --------------- --- - ---------------- -------- --------
CUSTOMERS 001 M 1178
[ 1] ORDERS 004 D CUSTNO 1178 47
PARTS 002 M 182
[ 1] LINEITEMS 005 D ITEMNO 182 136
ID 003 A 47
[ 1] ORDERS 004 D ORDERID 47 47
[ 2] LINEITEMS 005 D ORDERID 47 136
Each selected master set is listed with the name, data set number,
data set type and number of entries. For each master set, each
selected chain is printed along with the current progress in
pass 1 and pass 2.
DBCFIX REPORT, Fri Dec 24 00:44:44 2004
Processing database: sample
Running in READONLY mode
--------------------------------------------------------------------
CUSTOMERS 001 M, Entries 1178
--------------------------------------------------------------------
[ 1] ORDERS 004 D CUSTNO
Pass 1: Number of chain heads processed: 1178
Used chain heads: 39, chain entries: 47, problems detected: 0
Avg. chain length: 1, max. chain length: 4
Pass 2: Number of detail records processed: 47
--------------------------------------------------------------------
PARTS 002 M, Entries 182
--------------------------------------------------------------------
[ 1] LINEITEMS 005 D ITEMNO
Pass 1: Number of chain heads processed: 182
Used chain heads: 127, chain entries: 136, problems detected: 0
Avg. chain length: 1, max. chain length: 4
Pass 2: Number of detail records processed: 136
--------------------------------------------------------------------
ID 003 A, Entries 47
--------------------------------------------------------------------
[ 1] ORDERS 004 D ORDERID
Pass 1: Number of chain heads processed: 47
Used chain heads: 47, chain entries: 47, problems detected: 0
Avg. chain length: 1, max. chain length: 1
Pass 2: Number of detail records processed: 47
[ 2] LINEITEMS 005 D ORDERID
Pass 1: Number of chain heads processed: 47
Used chain heads: 40, chain entries: 136, problems detected: 0
Avg. chain length: 3, max. chain length: 16
Pass 2: Number of detail records processed: 136
|
