KEYCHECK: Btrieve File Key Consistency Checker

This application was created to provide a simple method of validating key
structures within a Btrieve/Pervasive.SQL file.  It reads the file, first in
physical order, then in order by each key.  When an error is detected, the
error is displayed, along with the total number of records read on that path.
If a different number of records is detected on a specific keypath, an error
will also be displayed.  This can indicate a corrupted key.  Note that an
active file (records being inserted & deleted) will flag this as an error,
as will NULL keys. This is normal.

The syntax can be displayed by simply running KeyCheck:

KEYCHECK Version 2.6: 07/28 (C)2005 Goldstar Software Inc.
*** Registered 32-Bit Version ***

Usage:  KEYCHECK Filename [/K##] [/C] [/R] [/S] [/E] [/Q] [/W] [/O=Owner] [/D]

    This command scans the Btrieve file for corrupted keys.
    Use the /K option to specify a single Key to traverse (or -1).
    Use the /C option to check for unique value mismatches while scanning.
    Use the /R option to traverse records in Reverse order.
    Use the /S option to disable Status reporting.
    Use the /E option to exit on the first error encountered.
    Use the /Q option to enable QuickRead (4-Byte Record Reads).
    Use the /B option to identify missing (Status 2) records on each key path.
    Use the /W option to output statistics in CGI format.
    Use the /O= option to provide an owner name.
    Use the /D option to enable DEBUG mode.


KEYCHECK is functionally equivilent to the following:
        BUTIL -RECOVER filename NUL
        BUTIL -SAVE filename NUL n 1
        BUTIL -SAVE filename NUL n 2
        BUTIL -SAVE filename NUL n 3
        ...
        BUTIL -SAVE filename NUL n lastkey

KEYCHECK /R is functionally equivilent to the following:
        BUTIL -RECOVER filename NUL /J
        BUTIL -SAVE filename NUL n 1 /J
        BUTIL -SAVE filename NUL n 2 /J
        BUTIL -SAVE filename NUL n 3 /J
        ...
        BUTIL -SAVE filename NUL n lastkey /J


The options available are:

/B: Identify Bad Records On Key Path
When data files get corrupted due to a server crash that damages data pages, 
it is then impossible to extract those records.  This option attempts to 
determine the key value along each key path that corresponds to the missing 
records.  If successful, it reports the key value information to the screen 
of the missing record.  If two records fail in a row, the system is not able 
to continue and it stops processing that key path.  Specify the /K switch to 
scan one key only.

/C: Check for Unique Values Mismatches in the KAT
The Key Allocation Table count of unique values for each key in the file is 
shown when you perform a BUTIL STAT on the file.  If the KAT data gets 
mangled somehow, this can impact SQL queries that depend on this information.  
This switch adds extra processing that determines the number of unique values 
that are found down each key path and compares that number with the value in 
the KAT.  If a mismatch is found, a Status 21 will be reported on that key. 

/E: Exit on first Error.
By default, KeyCheck scans all keys looking for errors.  If you are scripting 
this via a batch file, it is often helpful to know what error occurred, if 
any.  However, this error may not be returned from KeyCheck if it is not 
the LAST error encountered.  Use this switch to exit immediately with the 
appropriate status code when an error is found.

/K: Specify a key to traverse.
Normally, KeyCheck will process ALL keys in a given file, in order from -1 
(physical order) to the last keyt available.  Use the /K switch if you wish
to scan only ONE specific key.  Provide the key number immediately after the
"K" on the command line, as in "/K3".

/O: Provide an Owner Name.
Some database files are protected via an owner name and cannot be opened without
this name.  If you encounter a file which is protected in this manner, you can
use the "/O" switch to provide the owner name.  For example, if the owner name
is "FRED", the proper parameter is "/O=FRED".  Please note that the owner name,
like most passwords, is case sensitive.

/Q: Enable QuickRead scanning.
By default, KeyCheck will read EVERY byte of every record (up to 63K).  While
this is the most effective way to check an entire file, it is possible to 
increase performance (at the expense of less stringent checking) by adding the
"/Q" switch.  When this is enabled, KeyCheck will only read 4 bytes from each
record instead of the whole record.  The performance difference, especially
across a networked connection, can be dramatic.

/R: Scan in reverse order.
By default, Keycheck will scan all indices in forward order.  It is possible 
that a key structure could have become corrupted on a reverse pointer only.
Use the "/R" option (after a successful forward run) to scan backwards as well.

/S: Disable status reporting.
KeyCheck reports periodically on its progress.  First, it displays a "twirly"
after every 50 records it processes.  This allows you to see that it is working.
Second, it displays a percentage complete number.  It will do this every 10%
of the way through small files (under 100,000 records) or every 1% for large
files (over 100,000 records).  To improve performance this status reporting 
should be disabled with the "/S" flag. (Automatically done with CGI output.)

/W: Enable Web (CGI) output.
Normally, KeyCheck will dump its scanning data to the screen (stdout).  However,
it may be advantageous to be able to run KeyCheck on a web server to check 
files from a remote location.  To use this, simply create a link:
     <A REF="http://www.webserver.com/scripts/keycheck.exe?c:\pvsw\demodata\billing.mkd%20/w"
	target="_blank">BILLING.MKD</A>
This link will call the KEYCHECK.EXE file (in the server's SCRIPTS directory)
and pass it the name of the BILLING.MKD file, as well as the "/W" switch.


KeyCheck 2.3 and above return the following ErrorLevel values:
-4	Out of Memory
-3	Invalid Specified Key Number Value
-2	Unable to Parse Owner Name from Command Line
-1	No Parameters Specified (Help Screen Printed)
###	Btrieve Status Code Returned
Batch files can check ERRORLEVEL and handle issues.  Status 9 will indicate a 
proper EndOfFile condition, while Status codes 2, 30, and 54 indicate problems.
You may need to use the /E flag to ensure that a valid error is returned, since
some errors may exist on some keys, but not on all.

Status 21 will be returned only if the /C option is selected.


For more information on these utilities, for custom changes to this utility, 
or for onsite consulting, contact:
	Goldstar Software Inc.
        www.goldstarsoftware.com
