VBD Embedded Database Engine


Topics:

Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Data Members
Functions


Overview

The vbDatabase class defines low-level methods used to build embedded database engines based on variable block technology.

Platform Independence:

Database file created with the 32-bit vbDatabase class gain their platform independence by using the vbINT32 class objects to represent file addresses. The vbINT32 class can produce platform independent 32-bit signed integers by manipulating long integer values in memory. It works by separating a 32-bit value into four separate byte values and reordering the bytes lowest-order to highest-order.

Exception Handling:

Two forms of error handling are implemented in the file manager class. An integer value within the vbDatabase class is used to record the last error reported by any of the file functions. When a fatal error condition is reached the vbDatabase class will set its error variable and conditionally return a non-zero value to the caller or throw an exception if C++ exception handling is enabled at compile time. NOTE: If C++ exception handling is enabled the appropriate try and catch statements within the application must handle the exceptions or the program will terminate abnormally.


Conditional Directives

__CPP_EXCEPTIONS__ - Directive used to enable C++ exception handling.


Public Data Members

Static data members used by the vbDatabase class in place of global variables. NOTE: An application or a derived should only change these values if VBD version 1 compatibility is required.

static __SBYTE__ vbDatabase::VBDSignature[8] - Eight byte string used to identify 32-bit VBD files and the revision level.

static FAU vbDatabase::VBDVersion - 32-bit value used to represent the VBD library version number.

static vbUINT32 vbDatabase::VBDInternalCheckWord - 32-bit check word used to mark variable blocks and maintain synchronization between the database engine and the application.


Functions

vbDatabase::vbDatabase()
vbDatabase::~vbDatabase()
vbDatabase::Alloc()
vbDatabase::CalcChecksum()
vbDatabase::Close()
vbDatabase::Create()
vbDatabase::DatabaseExceptionMessage()
vbDatabase::vbDatabaseName()
vbDatabase::Delete()
vbDatabase::Exists()
vbDatabase::FileHeaderSize()
vbDatabase::FilePosition()
vbDatabase::FileSize()
vbDatabase::FindFirstObject()
vbDatabase::FindFirstVB()
vbDatabase::FindNextObject()
vbDatabase::FindNextVB()
vbDatabase::FindPrevObject()
vbDatabase::FindPrevVB()
vbDatabase::Flush()
vbDatabase::GetDatabaseError()
vbDatabase::GetEOF()
vbDatabase::GetHeapStart()
vbDatabase::GetHighestVB()
vbDatabase::GetRevLetter()
vbDatabase::GetSignature()
vbDatabase::GetVBDFreeSpace()
vbDatabase::GetVersion()
vbDatabase::InitFileHdr()
vbDatabase::InitFileLockHdr()
vbDatabase::InitRecordLockHdr()
vbDatabase::IsOK()
vbDatabase::IsOpen()
vbDatabase::LockFile()
vbDatabase::LockRecord()
vbDatabase::ObjectLength()
vbDatabase::Open()
vbDatabase::Read()
vbDatabase::ReadBlockHdr()
vbDatabase::ReadFileHdr()
vbDatabase::ReadFileLockHdr()
vbDatabase::ReadForReading()
vbDatabase::ReadObjectChecksum()
vbDatabase::ReadRecordLockHdr()
vbDatabase::ReadyForWriting()
vbDatabase::ReclaimFirstFit()
vbDatabase::ReclaimBestFit()
vbDatabase::Remove()
vbDatabase::ResetDatabaseError()
vbDatabase::ResetFileLock()
vbDatabase::ResetRecordLock()
vbDatabase::Seek()
vbDatabase::SeekTo()
vbDatabase::SetDatabaseError()
vbDatabase::SetRevisionLetter()
vbDatabase::StaticArea()
vbDatabase::TestVBDHeader()
vbDatabase::UnDelete()
vbDatabase::UnlockFile()
vbDatabase::UnlockRecord()
vbDatabase::VBDeleted()
vbDatabase::VBHeaderSize()
vbDatabase::VBLength()
vbDatabase::VBTotal()
vbDatabase::Write()
vbDatabase::WriteBlockHdr()
vbDatabase::WriteFileHdr()
vbDatabase::WriteFileLockHdr()
vbDatabase::WriteObjectChecksum()
vbDatabase::WriteRecordLockHdr()

vbDatabase::vbDatabase() - Default class constructor.

virtual vbDatabase::~vbDatabase() - Virtual class destructor responsible for closing the open file and flushing any disk buffers.

virtual FAU vbDatabase::Alloc(__ULWORD__ bytes, vbDatabaseReclaimMethod method = vbDBASE_RECLAIM_FIRSTFIT) - Public member function used to allocate a specified number of bytes for a database object. The number of bytes allocated is adjusted to hold a block header plus any block overhead plus the object. Only the block header is written to the allocated space. The application is responsible for writing the object to the block at the file address returned by this function. This function will return a zero if an allocation error occurs. NOTE: The database engine will position the file pointer to the file address where the next write operation should take place after allocating space for the object. The block reclamation method should be set to vbDBASE_RECLAIM_NONE (to extend the file and do not reclaim deleted blocks), vbDBASE_RECLAIM_BESTFIT (to reclaim deleted blocks using the best fit reclamation method), or vbDBASE_RECLAIM_FIRSTFIT (to reclaim deleted blocks using the first fit reclamation method).

Exceptions:
vbCDatabaseException

__ULWORD__ vbDatabase::CalcChecksum(__ULWORD__ bytes, FAU file_address, int mem_alloc = 1) - Public member function used to calculate a 32-bit CRC checksum base on the Ethernet polynomial of 0x4C11DB7 for a given number of bytes starting at the specified address. Returns a 32-bit CRC value. If the "mem_alloc" variable is true, a buffer equal to the specified number of bytes will be created in memory. If the "mem_alloc" variable is false or memory allocation fails the CRC will be calculated byte by byte starting at the specified address.

Exceptions:
vbCDatabaseException

virtual vbDatabaseError vbDatabase::Close() -Virtual public member function used to close an open database file. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions, if not overridden in a derived class:
vbCDatabaseException

virtual vbDatabaseError vbDatabase::Create(const char *fname, FAU static_size = (FAU)0, __SBYTE__ RevisionLetter = vbDatabaseRevisionLetter) Virtual public member function used to create a new file and truncate the file if it already exists. The "static_size" variable is used to reserve a specified number of bytes that will not be affected by the dynamic allocation routines. The "RevisionLetter" variable is used to select a specific revision letter when the file is created. The revision letter is used to enable or disable specific features that will determine the amount of overhead per block. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions, if not overridden in a derived class:
vbCDatabaseException

const char *vbDatabase::DatabaseExceptionMessage() - Public member function that returns a null terminated string, which can be used to log or print the last reported database exception.

const char *vbDatabase::vbDatabaseName() - Public member function that returns the file name of currently opened database file.

int vbDatabase::Delete(FAU object_address, int remove = 0) - Public member function used to mark a block at object address deleted and leaves the object unchanged, allowing it to be undeleted. If the "remove" variable is true the block is marked removed, indicating that the object cannot be undeleted. Returns true if the block was deleted/removed or false if the block was not deleted/removed.

Exceptions:
vbCDatabaseException

static int vbDatabase::Exists(const char *fname) - Static public member function that returns true if the "fname" file exists.

size_t vbDatabase::FileHeaderSize() - Public member function that returns the correct size of the file header plus any overhead according to the VBD revision level. This function should only be used when calculating file offsets and not for determining the actual size of the vbFileHeader data structure.

vbStreamPos vbDatabase::FilePosition() - Public member function that returns the current file position. Returns the current file position or -1 to indicate an error condition.

Exceptions:
vbCDatabaseException

static FAU vbDatabase::FileSize(const char *fname) - Static public member function used to obtain the size of file "fname". Returns the file size or -1 to indicate an error condition.

FAU vbDatabase::FindFirstObject(FAU offset = (FAU)0) - Public member function used to search through the file until a valid block is found and then return the object's address. If the block is marked deleted or removed, this function will continue searching until the first normal block is found. The search begins starts at specified offset. This function will return zero if no valid blocks are found or the end of file is reached.

Exceptions:
vbCDatabaseException

FAU vbDatabase::FindFirstVB(FAU offset = (FAU)0) - Public member function used to search through the file until a valid block is found. The search begins starts at specified offset. This function will return zero if no valid blocks are found or the end of file is reached.

Exceptions:
vbCDatabaseException

FAU vbDatabase::FindNextObject(FAU offset = (FAU)0) - Public member function used to search through the file until the next valid block after the first valid block is found and then return the object's address. If the block is marked deleted or removed, this function will continue searching until the next normal block is found. The search begins starts at specified offset. This function will return zero if no valid blocks are found or the end of file is reached.

Exceptions:
vbCDatabaseException

FAU vbDatabase::FindNextVB(FAU offset = (FAU)0) - Public member function used to search through the file until the next valid block after the first valid block is found. The search begins starts at specified offset. This function will return zero if no valid blocks are found or the end of file is reached.

Exceptions:
vbCDatabaseException

FAU vbDatabase::FindPrevObject(FAU offset) - Public member function used to search backwards through the database until a valid block is found and then return the object's address. If the block is marked deleted this function will continue searching until the first normal block is found. The search starts at the specified offset. Returns 0 if no valid block is found in the file or the start of file is reached.

Exceptions:
vbCDatabaseException

FAU vbDatabase::FindPrevVB(FAU offset) - Public member function used to search backwards through the database until a valid block is found and then return the block's address. If the block is marked deleted this function continue searching until the first normal block is found. The search starts at the specified offset. Returns 0 if no valid block is found in the file or the start of file is reached.

Exceptions:
vbCDatabaseException

virtual vbDatabaseError vbDatabase::Flush() - Public member function used flush the file header and any open disk buffers. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions, if not overridden in a derived class:
vbCDatabaseException

vbDatabaseError vbDatabase::GetDatabaseError() - Public member function the returns an error code representing the last reported database error.

FAU vbDatabase::GetEOF() - Public member function that returns the "end of file" marker stored in the file header.

Exceptions:
vbCDatabaseException

FAU vbDatabase::GetHeapStart() - Public member function that returns the file address where the dynamic data area starts.

Exceptions:
vbCDatabaseException

FAU vbDatabase::GetHighestVB() - Public member function that returns the file address of the highest allocated block.

Exceptions:
vbCDatabaseException

char vbDatabase::GetRevLetter() - Returns the current VBD file revision letter which will be used to perform compatibility checks to ensure compatibility with all VBD file revisions.

const char *vbDatabase::GetSignature() - Public member function that returns the file signature stored in the file header.

FAU vbDatabase::GetVBDFreeSpace() - Public member function that returns the file address to the starting address of the free space list. This function returns zero if no blocks have been deleted or removed.

Exceptions:
vbCDatabaseException

vbINT32 vbDatabase::GetVersion() - Public member function that returns the VBD library version number stored in the file header.

vbDatabaseError vbDatabase::InitFileHdr() - Protected member function used initialize the file header with default values and write it to disk. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

void vbDatabase::InitFileLockHdr(vbFileLockHeader &hdr) - Public member function used to initialize a the lock header for a newly constructed file lock header.

void vbDatabase::InitRecordLockHdr(vbRecordLockHeader &hdr) - Public member function used to initialize a the lock header for a newly constructed record lock header.

int vbDatabase::IsOK() - Public member function that returns false if a fatal error condition has been reached.

int vbDatabase::IsOpen() - Public member function that returns true if a database file is open.

int vbDatabase::LockFile(vbDatabaseLockType l_type = vbDBASE_WRITELOCK) - Public member function used to lock the entire database file during a multi-threaded read or write operation. The "l_type" variable should be set to vbDBASE_WRITELOCK for exclusive file locks owned by a single thread or to vbDBASE_READLOCK for shared file locks owned by multiple threads. Returns a non-zero value if the file cannot be locked or the lock variable cannot be changed because it is exclusive or another thread is currently updating it.

Exceptions:
vbCDatabaseException

int vbDatabase::LockRecord(vbDatabaseLockType l_type = vbDBASE_WRITELOCK,FAU block_address = vbCurrAddress) - Public member function used to a single node at the specified block address during a multi-threaded read or write operation. The "l_type" variable should be set to vbDBASE_WRITELOCK for exclusive record locks owned by a single thread or to vbDBASE_READLOCK for shared record locks owned by multiple threads. Returns a non-zero value if the node cannot be locked or the lock variable cannot be changed because it is exclusive or another thread is currently updating it.

Exceptions:
vbCDatabaseException

__ULWORD__ vbDatabase::ObjectLength(FAU object_address = vbCurrAddress) - Public member function that returns the object's length, in bytes, at a specified object address.

Exceptions:
vbCDatabaseException

virtual vbDatabaseError vbDatabase::Open(const char *fname, vbDatabaseAccessMode mode = vbDBASE_READWRITE) - Virtual public member function used to open an existing file. The "mode" variable determines if the file is opened for read only or read/write access. This function will check and record the VBD file revision letter each time an existing file is opened. Returns a non-zero value to indicate an error condition or zero if successful. This version of the open functions will only accept: vbDBASE_READONLY or vbDBASE_READWRITE access modes.

Exceptions, if not overridden in a derived class:
vbCDatabaseException

vbDatabaseError vbDatabase::Read(void *buf, __ULWORD__ bytes, FAU file_address = vbCurrAddress) - Public member function used to read a specified number of bytes from the specified file offset or the current file position into a memory buffer. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::ReadBlockHdr(vbBlockHeader &hdr, FAU block_address = vbCurrAddress) - Public member function used to read a block header and tests the block's check word to ensure that this is a valid block. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::ReadFileHdr() - Public member function used to read the database file header. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::ReadFileLockHdr(vbFileLockHeader &hdr) - Public member function used to read the lock header from the file. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

int vbDatabase::ReadForReading() - Public member function that returns true if the file is ready for reading.

int vbDatabase::ReadObjectChecksum(FAU object_address, __ULWORD__ *object_crc = 0,__ULWORD__ *calc_crc = 0) - Used by an application to test the object's CRC value stored on disk against the actual CRC of the bytes stored on disk. The Address variable must be set to the file address of the block data, not the block header. This function assumes that the data has already been written to the block. Returns true if the object's CRC test good or false if the CRC tests bad. Passes back the object's CRC stored on disk in the "object_crc" variable and the calculated CRC value in the "calc_crc" variable.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::ReadRecordLockHdr(vbRecordLockHeader &hdr, FAU block_address = vbCurrAddress) - Public member function used to read the block's record lock header. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

int vbDatabase::ReadyForWriting() - Public member function that returns true if the file is ready for writing or false if this is a read only file.

FAU vbDatabase::ReclaimBestFit(__ULWORD__ bytes) - Public member function used by the dynamic allocation routines to search for a block that can be reused. This function will search the free space list for an "exact-fit" first and then try to find the "best-fit" for the number of bytes requested. NOTE: The byte size should always be adjusted by the dynamic allocation routine to allocate space for the block header plus any block overhead. An exact-fit is a block that matches the exact number of bytes requested. If an exact-fit cannot be found, the next block big enough to hold number of bytes requested plus a block header with overhead and at least one byte left over becomes a "best-fit" block. A "best-fit" search continues until a block with the least number of unused bytes is found. The used bytes in a "best-fit" block are used to create a new block that will be put back on the free space list. This "best-fit" method is specifically designed to keep the gaps between blocks as small as possible, with the smallest gap being as large as a single block header plus one byte. The "best-fit" method will prevent fragmentation as much as possible but is very costly in terms of speed. Returns address of the reclaimed space, or zero if a deleted or removed block of the appropriate size is not found

Exceptions:
vbCDatabaseException

FAU vbDatabase::ReclaimFirstFit(__ULWORD__ bytes) - Public member function used by the dynamic allocation routines to search a for block that can be reused. This function will search the free space list for the first deleted block large enough to hold the number of bytes requested. A "first-fit" search continues until the first block big enough to hold the number of bytes requested plus the size a block header with overhead and at least one byte left over is returned. The used bytes in a "first-fit" block are used to create a new block that will be put back on the free space list. The "first-fit" method will not prevent fragmentation as well as the "best-fit" method but offers a tremendous speed advantage. Returns address of the reclaimed space, or zero if a deleted or removed block of the appropriate size is not found

Exceptions:
vbCDatabaseException

int vbDatabase::Remove(FAU object_address) - Public member function used to mark a variable block removed indicating that the object cannot be undeleted. Returns true if the block was or removed or false if the block was not removed.

Exceptions:
vbCDatabaseException

void vbDatabase::ResetDatabaseError() - Public member function used to reset the last reported database error.

vbDatabaseError vbDatabase::ResetFileLock() - Public member function used to reset the database file lock header. NOTE: This function will clear all the file lock fields without testing the lock or the lock protect. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::ResetRecordLock(FAU block_address = vbCurrAddress) - Public member function used to reset the block's record lock. NOTE: This function will clear all the record lock fields without testing the lock or the lock protect. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::Seek(FAU offset, vbDatabaseSeekMode mode = vbDBASE_SEEK_BEG) - Public member function used to seek to the specified offset starting at the beginning of the file (vbDBASE_SEEK_BEG), the end of the file (vbDBASE_SEEK_END) or current offset (vbDBASE_SEEK_CUR). Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

FAU vbDatabase::SeekTo(FAU file_address) - Public member function used to seek to the specified address, optimizing the seek operation by moving the file position indicator based on the current stream position. Returns the current file position after performing the seek operation.

Exceptions:
vbCDatabaseException

void vbDatabase::SetDatabaseError(vbDatabaseError err) - Public member function used to set the last reported database error. This function is used to inform the database engine of fatal error condition.

void vbDatabase::SetRevisionLetter(__SBYTE__ RevisionLetter) - Public member function used to set the database revision letter to a specified value. If a valid revision is not specified the current revision letter will be used. The function is used to detect revision letter errors when new database files are created.

FAU vbDatabase::StaticArea() - Public member that returns the size of the pre-allocated static data area.

Exceptions:
vbCDatabaseException

int vbDatabase::TestVBDHeader() - Public member function used to ensure that the in-memory copy of the file header and the disk copy stay in sync during multiple file access. This function will return zero if no errors are found, or return the number of errors encountered during the test. If any errors are encountered the file header will be re-read from disk.

Exceptions:
vbCDatabaseException

int vbDatabase::UnDelete(FAU object_address) - Public member function used to undelete a secified object if the block has not been removed or reclaimed.

Exceptions:
vbCDatabaseException

int vbDatabase::UnlockFile(vbDatabaseLockType l_type = vbDBASE_WRITELOCK) - Public member function used to unlock the file following a multi-threaded read or write operation. The "l_type" variable should be set to vbDBASE_WRITELOCK for exclusive file locks owned by a single thread or to vbDBASE_READLOCK for shared file locks owned by multiple threads. Returns a non-zero value if the file cannot be unlocked or the lock variable cannot be changed because it is exclusive or another thread is currently updating it.

Exceptions:
vbCDatabaseException

int vbDatabase::UnlockRecord(vbDatabaseLockType l_type = vbDBASE_WRITELOCK,FAU block_address = vbCurrAddress) - Public member function used to unlock a specific node following a multi-threaded read or write operation. The "l_type" variable should be set to vbDBASE_WRITELOCK for exclusive record locks owned by a single thread or to vbDBASE_READLOCK for shared record locks owned by multiple threads. Returns a non-zero value if the record cannot be unlocked or the lock variable cannot be changed because it is exclusive or another thread is currently updating it.

Exceptions:
vbCDatabaseException

__ULWORD__ vbDatabase::VBDeleted(__ULWORD__ *d = 0, __ULWORD__ *r = 0) -Public member function that returns the total number of removed and deleted blocks and passes back the number of delete and removed blocks in the "d" and "r" variables.

Exceptions:
vbCDatabaseException

size_t vbDatabase::VBHeaderSize() - Public member function that returns the correct size of the block header plus any overhead according to the VBD revision level. This function should only be used when calculating file offsets and not for determining the actual size of the vbBlockHeader data structure.

__ULWORD__ vbDatabase::VBLength(FAU object_address = vbCurrAddress) - Public member function that returns the total length of a block, in bytes, at a specified address. The total length refers to the size of the block header including any block overhead plus the block data.

Exceptions:
vbCDatabaseException

__ULWORD__ vbDatabase::VBTotal() - Public member function that returns the total number of normal, deleted, and removed blocks.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::Write(const void *buf, __ULWORD__ bytes, FAU file_address = vbCurrAddress,int flush = 1, int bit_test = 1) - Public member function used to write a specific number of bytes from a memory buffer to a specified file offset. If the "flush" variable is true, the file buffers will be flushed to disk with each write operation. If the "bit_test" variable if true, the CRC of the buffer will be compared to the CRC of the actual bytes written to disk. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::WriteBlockHdr(const vbBlockHeader &hdr, FAU block_address = vbCurrAddress) - Public member function to write a block header to the specified block address. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::WriteFileHdr() - Public member function used to write the database file header. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::WriteFileLockHdr(const vbFileLockHeader &hdr) -Public member function used to write the lock header to the file. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException

vbUINT32 vbDatabase::WriteObjectChecksum(FAU object_address) - Used to by an application to write a 32-bit checksum for the object at the end of a block. The Address variable must be set to the file address of the block data, not the block header. This function assumes that the data has already been written to the block. Returns the 32-bit CRC checksum value for the object stored in the block.

Exceptions:
vbCDatabaseException

vbDatabaseError vbDatabase::WriteRecordLockHdr(const vbRecordLockHeader &hdr, FAU block_address = vbCurrAddress) - Public member function used to write the block's record lock header. Returns a non-zero value to indicate an error condition or zero if successful.

Exceptions:
vbCDatabaseException


End Of Document