Topics
:Overview
Constants
Type Definitions
Enumerations
VBD File Header
VBD Block Header
VBD File Lock Header
VBD Record Lock Header
Type definitions, constants, and data structures needed to create variable block headers.
// Constants for dynamic data attributes used by the first byte of the // block header Status member. const __SBYTE__ vbBadBlock = 'B'; // Bad Variable Block const __SBYTE__ vbDeletedBlock = 'D'; // Deleted Variable Block const __SBYTE__ vbNormalBlock = 'N'; // Normal Read/Write attribute const __SBYTE__ vbRemovedBlock = 'R'; // Removed Variable Block // This block was received from a remote device. Added in VBD revision C const __SBYTE__ vbRemoteDeviceBlock = 'V'; // Constants for block control characters used by the second byte of the // block header Status member. Added in VBD revision C to handle device // control commands. const __SBYTE__ vbAddRemoteBlock = 'A'; // Add a remote block const __SBYTE__ vbChangeRemoteBlock = 'C'; // Change a remote block const __SBYTE__ vbDeleteRemoteBlock = 'D'; // Delete a remote block const __SBYTE__ vbRequestFailed = 'F'; // The client request failed const __SBYTE__ vbCloseConnection = 'L'; // Close Client/Server connection const __SBYTE__ vbKillServer = 'K'; // Shutdown Client/Server const __SBYTE__ vbRequestBlock = 'R'; // Requesting a block const __SBYTE__ vbSendBlock = 'S'; // Sending raw data block const __SBYTE__ vbAcknowledgeBlock = 'W'; // Acknowledge a data block // Constants for file operations and stream position const int vbMaxNameLength = 255; // Max length of file names const FAU vbStartOfFile = (FAU)0; // First byte in the file const FAU vbCurrAddress = -1; // Indicates current location const vbUINT32 vbCheckWord = 0xfefefefe; // Default synchronization word const vbINT32 vbFSListCorrupt = -1; // Free space list is corrupt
VBD type definitions common to all platforms:
__SBYTE__ - Type definition for 8-bit signed values.
__UBYTE__ - Type definition for 8-bit unsigned values.
__WORD__ - Type definition for native integer types.
__UWORD__ - Type definition for native unsigned integer types.
__LWORD__ - Type definition for native 32-bit signed integer types.
__ULWORD__ - Type definition for native 32-bit unsigned integer types.
__SWORD__ - Type definition for native 16-bit signed integer types.
__USWORD__ - Type definition for native 16-bit unsigned integer types.
__DPFLOAT__ - Type definition for native 64-bit double precision floating points types.
Type definitions used for file operations and stream position:
FAU - File address unit physical file address type.
vbStreamPos - Stream position indicator.
Type definition used to represent CRC-32 checksum values:
vbChecksum - CRC-32 checksum type.
Enumerated integer constants used by the database engine to control file access, I/O operations, and identify file lock types.
enum vbDatabaseAccessMode { // vbDatabase access/open mode enumeration vbDBASE_READONLY, // Open file with read access only vbDABSE_WRITEONLY, // Open file with write access only vbDBASE_READWRITE, // Open file with read and write access vbDBASE_CREATE, // Create the file if it does not exist vbDBASE_NO_CREATE, // Do not create the file if it does not exist vbDBASE_TRUNCATE, // Truncate the file vbDBASE_APPEND, // Append to the file vbDBASE_SHARE, // Enable file sharing (Platform specific) vbDBASE_EXCLUSIVE // Disable file sharing (Platform specifiec) }; enum vbDatabaseOperation { // vbDatabase I/O operation codes vbDBASE_READ, // A read was performed vbDBASE_WRITE, // A write operation was performed vbDBASE_REWIND, // A rewind operation was performed vbDBASE_NO_OPERATION, // No operation was performed vbDBASE_SEEK // A seek operation was preformed }; enum vbDatabaseSeekMode { // vbDatabase seek mode enumeration vbDBASE_SEEK_BEG, // Seek starting from the beginning of the file vbDBASE_SEEK_CUR, // Seek starting from the current location vbDBASE_SEEK_END // Seek starting from the end of the file }; enum vbDatabaseLockType { // vbDatabase file/record lock enumeration vbDBASE_READLOCK, vbDBASE_WRITELOCK }; enum vbDatabaseReclaimMethod { // vbDatabase Block reclamation methods vbDBASE_RECLAIM_NONE = 0, // Do not reclaim deleted blocks vbDBASE_RECLAIM_BESTFIT, // Use the best fit reclamation method vbDBASE_RECLAIM_FIRSTFIT // Use the first fit reclamation method };
VBD File Header
The vbFileHeader data structure is used to represent the VBD file header in accordance with the VBD file format.
struct vbFileHeader // VBD file header information { FAU vbd_fs_fptr; // Address to first block of free heap space FAU vbd_eof; // Address of byte after end of file FAU vbd_hs_fptr; // Address of the start of the heap space FAU vbd_hb_fptr; // Highest allocated variable block __SBYTE__ vbd_sig[8]; // Signature used to ID a VBD file FAU vbd_ver; // VBD version number };
Free space field:
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 database engine's 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. 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 s pace 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 vbFSListCorrupt integer constant and no longer be used.
End of file field:
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 database engine will compare this field to the true end of file. If the values do not match, this pointer will be adjusted if possible.
Start of heap field:
The "start of heap" 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.
Highest block field:
The "highest block" pointer is used to store the address of the highest allocated variable block. This ensures that the database engine will always know where the first and last blocks are located in the file.
Signature field:
The signature field 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 32-bit database engine writes the "VBDBASE" string to this field. The eighth byte is used for all revision changes. VBD version 2 sets the revision letter to 'C' and performs a compatibility check 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 a 32-bit block checksum. Revision 'B' adds a persistent file lock header used to lock the entire file during a multi-threaded read or write operation. Revision 'C' adds a persistent record lock header used to lock a specific node during a multi-threaded read or write operation.
Version field:
A version number is used to indicate that changes have been made to the database engine without affecting the file format. Version numbers are used to conditionally perform certain operations based on its numerical value. This will ensure backward compatibility with previous versions of the database engine.
The vbBlockHeader data structure is used to represent variable block headers in accordance with the VBD File Format and is additionally used for block transfers between local and remote devices. Block headers can be broken down into two specific categories: database blocks and device blocks.
Database Blocks:
A database block header is stored with each variable block allocated by an application and is used by the VBD file manger to keep track of variable blocks stored in the database. Applications can also use database block header information to obtain file locations and status information of its file data. When new blocks are allocated the database engine writes the block header and then reserves enough space to store the number of bytes requested. The application is responsible for writing the actual data in the block starting at the address following the block header.
Device Blocks:
Device block headers contain synchronization and control information. They are used to transfer blocks and to signal events between devices. When an application sends a block the header precedes the block and informs the receiver of the block size and the block status. After reception of a device header the receiver then waits for the block data and processes the data or signals an event according to the status of the block
// Variable Block Header struct vbBlockHeader // Marks each variable data block (16 bytes total) { vbUINT32 block_check_word; // Block synchronization marker vbUINT32 block_length; // Block length (object length + overhead) vbUINT32 block_status; // First byte = status of the block's data // Second byte = block control commands // Third byte = reserved for future use // Fourth byte = reserved for future use FAU block_nd_fptr; // Pointer to next deleted block };
Check word field:
The "check word" field represents a 32-bit check word. Database blocks use this field for integrity checks and to maintain synchronization between the database engine and the application. Device blocks use this field to maintain synchronization between local and remote devices. The check word field to should always be set to 0xFEFEFEFE using a vbUINT32 integer type. NOTE: If the check word value is changed, database files and device drivers will no longer be compatible with previous releases.
Length field:
The "length" field stores the total length of the variable block. Block lengths include the size of the object plus the total size of the block overhead determined by the by the VBD revision letter and whether the block is a database block or a device block.
Database Block Lengths:
Revision 0 database blocks account for the length of the object plus the size of the block header. Revision 'A' database blocks account for the length of the object plus the size of the block header and the size of the block's CRC checksum value. Revision 'C' database blocks account for the length of the object plus the size of the block header, record lock header, and the size of the block's CRC checksum value. The VBD database engine 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 total size of the block overhead from the "length" field.
Device Block Lengths:
VBD device blocks are used to send and receive variable blocks to and from various I/O devices. NOTE: All device blocks will only account for the length of the object. Device blocks used to send and receive control signals will only account for the length of the block header as no additional data will be sent or received other then the block header itself.
Status field:
The "status" field stores the status of the dynamic data contained in the block. Only two bytes of the status field are used. The remaining two bytes of the status field are reserved for future use.
Database Block Status Information:
The status of a database block can be determined by one of three primary byte values stored in the first block of the status field: 'N' for normal (ASCII 78), 'D' for deleted (ASCII 68), or 'R' for removed (ASCII 82). The VBD database engine uses a signed byte constant named vbNormalVB to mark normal database blocks, vbDeletedVB to mark deleted database blocks, and vbRemovedVB to mark database removed blocks. A block marked 'N' for normal indicates that the database 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. Marking deleted blocks 'N' for normal can restore deleted database blocks. 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.
Device Block Status Information:
The status of a device block can be determined by one of several byte values stored in the second block of the status field. Block control characters were added in VBD revision 'C' to handle device control commands. Device control commands allow blocks to be added, changed, removed, and requested by local and remote devices. Device control commands are also used to signal events between local and remote devices.
Next deleted block field:
Database blocks use the "next deleted block" field to store a pointer to the next deleted or removed variable block, only if this block has been deleted or removed. Device block headers ignore this field by default. The total number of deleted database blocks is maintained in a non-contiguous list. Each deleted or removed database block in the list points to the next deleted or removed database block in the list starting at the head of the list.
The file lock header is used in revision 'B' and higher to allow applications to lock the entire file during a multi-threaded/multi-machine read or write operations. The VBD advisory file locking scheme includes lock protect member required to protect the lock values during multiple file access. NOTE: The lock protect member is required in the VBD platform independent file locking system because file lock headers operate independently of the I/O subsystem and are manipulated by the database engine in the same manner as variable blocks.
struct vbFileLockHeader { // The lock protect is used to serialize access to the file lock // values. The VBD locking scheme will allow a total of 2^32 or // 4,294,967,295 threads to read lock a file and single thread to // write lock a file. vbUINT32 file_lock_protect; // Serialize access to the file lock members vbUINT32 file_read_lock; // Shared (or read-only) file lock vbUINT32 file_write_lock; // Exclusive (or write-only) file lock };
Record lock headers are used by an application in revision 'C' to lock a specific block during a multi-threaded/multi-machine read or write operation. The VBD advisory record locking scheme includes a lock protect member required to protect the lock values during multiple file access. NOTE: The lock protect member is required in the VBD platform independent node locking system because record lock headers operate independently of the I/O subsystem and are manipulated by the database engine in the same manner as variable blocks.
struct vbRecordLockHeader // Lock a contiguous set of bytes { // The lock protect is used to serialize access to each record // lock. The VBD locking scheme will allow a total of 2^32 or // 4,294,967,295 threads to read lock a record and single thread to // write lock a record. vbUINT32 record_lock_protect; // Serialize access to the record lock vbUINT32 record_read_lock; // Shared (or read-only) file lock vbUINT32 record_write_lock; // Exclusive (or write-only) file lock };
End Of Document |