.
Eloquence B.08.10 contact contact

Documentation / Eloquence dbcfix utility

Eloquence dbcfix utility

 
.
 

Contents


Overview

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.


Command line usage

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.


How it works

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.


Limitations

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).


Error Messages

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.

Example screen output

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.


Example log file

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

 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2010-08-20  
  Copyright © 2006-2010 Marxmeier Software AG