Overview
Usage
Command Line Switches
B-tree Header Report
Messages and Exit Codes
Building
Overview
The index file debug utility is a console-based program used to inspect gxBtree index files. It opens the index file in read-only mode with the gxDatabaseDebugManager class, checks the static storage area where B-tree headers are kept, and displays every B-tree header stored in the file. The program never writes to the index file.
Both a 32-bit and 64-bit version can be built. The 64-bit version is compiled with the __64_BIT_DATABASE_ENGINE__ directive and reports its name as ix_debug64. The 32-bit version reports its name as ix_debug.
Usage
To use the index file debug utility enter the name of the program followed by the name of the index file. The example programs in examples_database/btree and examples_database/pod create index files named with the .btx extension:
ix_debug testfile.btx ix_debug64 testfile.btx
The program takes exactly one argument. If no argument or more than one argument is given, the program displays its version information and a usage message, then exits with a status of 1:
ix_debug gxBtree index file debug program. Default Database Library Version: ... Default Database Library Revision: ... Usage: ix_debug infile Usage: ix_debug version
NOTE: 10/14/2026: Fixed the usage message. It showed an optional command after the file name that the program never read. Extra arguments are now reported as a usage error.
Command Line Switches
The program accepts one switch:
ix_debug version
If the argument is exactly "version" and no file with that name exists, the program prints its name and the default database library version and revision, then exits with a status of 0.
NOTE: 10/14/2026: Fixed opening a file named "version". If a file with that name exists, it is opened as the index file.
Any other argument is taken as the name of the index file to open.
B-tree Header Report
The program performs these steps:
1. Checks that the file exists.
2. Opens the file in read-only mode without checking the file type, using gxDatabaseDebugManager::BlindOpen().
3. Checks that the static storage area is at least as large as one B-tree header and is an exact multiple of the B-tree header size.
4. Reads each B-tree header in the static storage area. The first header is stored directly after the database file header and the others follow it.
5. Displays each header and waits for the enter key after each one.
The report has this format. The values are read from the file:
Found room for 1 B-tree header(s) in the static storage area Connecting to the first B-tree header... B-tree header stats for tree number 1 B-Tree node order = ... B-Tree key size = ... Number of keys = ... Number of nodes = ... B-Tree height = ... Root node address = ... Number of trees = ... Press enter to continue...
The number of headers is the static storage area size divided by the B-tree header size. The fields come from the gxBtreeHeader structure:
B-Tree node order - The node order of the tree.
B-Tree key size - The size of each entry key in bytes.
Number of keys - The total number of entry keys in the tree.
Number of nodes - The total number of nodes in the tree.
B-Tree height - The height of the tree.
Root node address - The file address of the root node.
Number of trees - The number of B-trees recorded in this index file.
NOTE: 10/14/2026: Fixed the report to display every B-tree header in the file. Only the first header was displayed before.
The program does not walk the tree, check the nodes, or analyze the database file header.
Messages and Exit Codes
The program exits with a status of 1 in these cases:
No argument or more than one argument was given. The usage message is displayed.
The file does not exist. The program prints "The specified file does not exist!" and "Exiting...".
The file cannot be opened, for example because it is smaller than a database file header. The database error message is printed.
A B-tree header cannot be read. The database error message is printed.
The debug manager object cannot be allocated. The program prints "Memory allocation error!".
The static storage area cannot hold valid B-tree headers. One of the messages below is printed.
Cannot connect to B-tree header This gxDatabase file has no static storage area allocated
The file has no static storage area, so it holds no B-tree header.
Cannot connect to B-tree header The static storage area is not large enough to store a B-tree header
The static storage area is smaller than one B-tree header.
Detected a storage area error The static storage area does not contain valid B-tree header information
The static storage area size is not an exact multiple of the B-tree header size.
NOTE: 10/14/2026: Fixed the exit status for these static storage area errors. It was 0, so scripts could not detect them. Also corrected the spelling of "information" and the word order of the "Connecting to the first B-tree header" message.
The program exits with a status of 0 after a successful report or after the "version" switch.
Building
The source code and build files are in the utils/ix_debug directory. The program is built from the single source file ix_debug.cpp and links to the DataReel library. On Linux, build the library first, then run make in the utils/ix_debug directory:
cd utils/ix_debug make
The makefile uses the shared env/linux.mak template and links to the static library lib/libdatareel.a. The executable is named ix_debug. The 64-bit database engine is compiled in when the LARGEFILES setting in env/linux.env is set to 1. The msvc.mak file is provided for Microsoft Visual C++ command line builds.