# VBD File Debug Utility

Topics
Usage | Compiling

Usage

The VBD file utility is a console-based program used to analyze VBD files, and rebuild corrupt VBD files. File corruption occurs when either the VBD File Header is damaged or any of the block headers are damaged. To use this utility enter the name of the program followed by the name of the VBD file:

    vb_debug mtank.pod

To open a file, perform a single operation, and exit the program enter the name of the program followed by the name of the file followed by the letter of the command you wish to perform:

    vb_debug mtank.pod d

If no command is giving after the file name the utility program will display a menu and give you a ">" prompt. At the prompt enter the single letter of the command you wish to perform.

    Analyzing file: mtank.pod
    Enter the letter of your selection at the prompt.

    (A) - Analyze the VBD file header
    (D) - Dump every variable block
    (F) - Find every variable block in the file
    (H) - Displays this menu
    (Q) - Quit this program
    (R) - Rebuild a damaged VBD file
    (S) - Display VBD file statistics
    (W) - Walk through every variable block

Enter "A" to analyze the VBD file header. If this function reports any errors, rebuild this file by selecting the "R" option.

Enter "D" to dump the blocks to the stdout.

Enter "F" to report how many variable blocks were found in this file, including blocks marked deleted or removed.

Enter "H" to display this menu again, after the program processes your selection.

Enter "Q" to exit this program.

Enter "R" to rebuild this file. This function will create a new file and attempt to recover every variable block that is not marked deleted or remove. NOTE: The rebuild function will not allow you to overwrite existing files. Each time this function is executed you need to name a new file to be created. To abort a rebuild, press the enter key without typing a file name.

Enter "S" to display detailed file information about this file. This information is used to analyze and troubleshoot VBD files.

    ----- Static information -----
    File Name: mtank.pod (VBD file currently open)
    Signature: VBDFILE (VBD file signature)
    Revision Letter: A (VBD file manager version letter)
    Version Number: 1031 (VBD file manager version number)
    File Header Size: 28 (size of the VBD file header in bytes)
    Block Header Size: 16 (size of the Variable Block headers in bytes)
    Static area size: 0 (size of VBD static storage area in bytes)
    Static file size: 39830 (size of the file in bytes)

    ----- Dynamic Information -----
    File Status: Good Open Read/Write (status of this file)
    Free Space: 24068 (file address of the next free block)
    End of File: 39830 (end of file marker)
    Heap Start: 28 (file address where all block allocation starts)
    Highest Block: 39695 (file address of the last block)
    Total Blocks: 385 (total number of blocks, including deleted ones)
    Deleted/Removed: 179/17 (196) (total number of deleted blocks)

VBD Signature

:
The signature is used to determine if the file is of the correct type when an existing file is opened. When a new file is created the VBD file manager writes the "VBDFILE" string to this field. The eighth byte is used for all revision changes. Version 1027 sets the revision letter to 'A' and performs a compatibility checks to ensure backward compatibility with previous releases. Revision 'A' adds a 32-bit CRC checksum routine and reserves space at the end of each block for an application to write 32-bit check-word.

VBD Version

:
A version number is used to indicate that changes have been made to the VBD file manager class itself. Version numbers are used to conditionally perform certain operations based on a numerical value. This will ensure backward compatibility with previous versions of the file manager class.

File Header Size

:
The "file header size" represents the size of the VBD file header in bytes.

VB Header Size

:
The "VB header size" represents the size of the variable block header in bytes.

Static Area Size

:
The "static area size" represents the size of the file's static data area in bytes. The static data area is used to store fixed data that cannot be altered by any of the dynamic allocation routines. The size of the static data must by specified by the application that creates the VBD file. If no static area is specified then the dynamic data area will start directly after the VBD file header.

Static File Size

:
The "static file size" represents the size of the file in bytes. This value is used after the file has been closed and reopened to ensure that all the memory buffers were flushed to disk.

VBD Free Space

:
The "free space" pointer is used by the allocation function to reclaim deleted blocks. The number of deleted blocks is maintained in a non-contiguous list. Each block in the list points to the next block in the list starting at a specified address. The "free space" pointer is used to store the file address of the block where the list starts. In order to prevent VBD files from becoming extremely fragmented due to numerous deletions, blocks marked deleted or removed will be reused by the allocation function. The allocation function checks the "free space" field before allocating any blocks. If the "free space" field is not empty, the allocation function will walk through the free space list looking for a deleted or removed variable block of the size to be allocated. This includes the size of the block data plus the block header and CRC. One of two methods can be used to reclaim deleted or removed blocks, the best-fit method or the first-fit method. The best-fit method works by scanning the entire free space list until the best location to reuse a block is found. The first-fit method works by searching the free space list until the first block of the appropriate size is found. Both methods will reuse any unused portion of a reclaimed block. The unused portion is assigned a new block header (marked removed) and placed back on the free space list. NOTE: If the free space list becomes corrupt, the "free space" field will be marked corrupt by the FSListCorrupt integer constant (-1) and no longer be used.

VBD End of file

:
The "end of file" pointer is used to mark the end of the file and locate where the file can be extended during block allocation. When an existing file is opened the file manager will compare this field to the true end of file. If the values do not match, this pointer will be adjusted if possible.

VBD Heap Start

:
The "heap start" pointer is used to store the address where the static storage area ends and the dynamic data area begins. The allocation of new blocks will always start at this address. The size of the static storage area is determined when the file is created. Any data stored in the static area will not be affected by any of the allocation routines.

VBD Highest VB

:
The "highest VB" pointer is used to store the address of the highest allocated variable block. This ensures that the file manager will always know where the first and last blocks are located in the file.

Enter "W" to find every block in the file and display its statistics.

    ----- Block statistics -----
    Check Word = 0x0000FEFE

(Check word used to mark each block) Length = 32 (Block Length: Header + Object + CRC) Status = N (Normal, Removed, or Deleted block) Next Deleted = 0 (Pointer to the next deleted or removed block) ----- Object statistics ----- Object Length = 12 (Length of this object) Stored CRC = 0xA3C26B50 Calculated CRC = 0xA3C26B50

VB Check Words

:
A "check word" is used to test for file corruption. If the next block in sequence does not have a valid check word it means that the block is damaged. The VBD file manager sets the check word field to 0x00000FEFE using an UINT32 constant named CheckWord. Revision 'A' uses all 32 bits of the block check-word. In previous releases the upper 16 bits of the block check-word was reserved for a 16-bit CRC. Revision 'A' implements a 32-bit CRC routine and reserves four bytes at the end of each block for a 32-bit checksum. NOTE: If the check word value is changed, the file will no longer be compatible with previous releases.

VB Length

:
The "length" field stores the length of the object plus the size of the block header and the size of the block's CRC checksum value. The file manager uses this field to index the file block by block. The "check-word" field is used to ensure that the next block in sequence is a valid variable block. The length of the object can be calculated by subtracting the size of the block header and the size of the CRC checksum from the "length" field.

VB Status

:
The "status" field is a 32-bit value used to store the status of the dynamic data in a block. Only one byte of the status field is used. The remaining three bytes of the status field is reserved for future use. The status of a variable data block can be determined by one of three byte values: 'N' for normal (ASCII 78), 'D' for deleted (ASCII 68), or 'R' for removed (ASCII 82.) A block marked 'N' for normal indicates that the block is in use and cannot be reclaimed by the allocation function. A block marked 'D' for deleted means that the data in the block is still valid, but the block can be overwritten if needed. A block marked 'R' for removed means that the data in the block has been removed and the block can be overwritten. Once a block is removed it can never be restored.

Next Deleted Block Pointers

:
The "next deleted block" pointer stores a pointer to the next deleted or removed variable block, only if this block has been deleted or removed. The total number of deleted blocks is maintained in a non-contiguous list. Each deleted or removed block in the list points to the next deleted or removed block in the list starting at the head of the list. The "free space" pointer in the VBD file header is used to store the file address where the head of the free space list is located. When a variable block is deleted or removed the next deleted block field is set to the VBD header's "free space" value to become the head of the free space list and the VBD header's "free space" pointer is set to the address of this deleted or remove block.

Compiling

Console Base Utility Program

:
Four makefiles are provided in the "utils" directory to compile the source code on one of four different compilers.

    "msvc40.mak"  - Makefile for Microsoft visual C/C++ 4.2
    "djgpp.mak"   - Makefile for DJGPP gcc 2.7.2.1
    "gnu_gcc.mak" - Makefile for GNU g++ 2.7.2.1
    "hpux10.mak"  - Makefile for HPUX C++ A.10.24

Building the Executable:

To compile use the "make -f" option followed by the makefile name. To compile using MSVC use the "nmake -f" option. The resulting executable will be named after the name set by the PROJECT macro in the makefile. By default the program will be named "vb_debug" under UNIX or "vb_debug.exe" under Windows 95/DOS.

Installing:

Execute a "make -f (makefile name) install" to move the executable to the "bin" directory.

Removing the Object Files and the Executable:

To remove the object files and the executable use the "make -f" option followed by the makefile name, followed by "clean": make -f hpux10.mak clean

Under MSVC use the "nmake -f" option followed by the makefile name, followed by "clean": nmake -f msvc40.mak clean

End Of Document