Persistent Object Database Manager

Topics
Overview	Functions
Exceptions

Overview

The Persistent Object Database (POD) manager is used to manage the file pointers to VBD files. When a POD object is instantiated it automatically creates a data file and an index file, or opens an existing set of files. Data files are VBD files used to store an object's data to disk. All data files are created by the VBD file manager and maintained by the Persistent base class. An index file is a VBD file used to store the address where the object's data can be found in the data file. Index files were implemented to increase the speed of search operations. All index files are disk-based balanced multi-way trees created by the VBD file manger and maintained by the B-tree class.

The method by which the objects data are stored to disk is defined by the Persistent base class. In order for objects of a class to become persistent, the class must inherit the Persistent base class and define the procedure used to store its objects to disk. The Persistent base class will use the methods defined in the derived class to maintain the data file and the index file.

The POD manager class is used to manage pointers to the data file and the index file. When a new database is created the POD manager will create a data file with a ". pod" file extension and an index file with a ".btx" file extension. Different file extensions can be specified. NOTE: The POD manager was originally designed to work without using an index file. In order to maintain compatibility with prior releases, the POD manager will not use an index file by default. If the POD manager is not told to use an index file, it will only open or create the data file.

If the POD manager opens an existing data file that is using an index file and no index file exists for that data file, the POD manager will create the index file and inform the application that the index file needs to be rebuilt. The methods for rebuilding the index file must be defined in the class derived from the Persistent base class.

Functions

POD::POD(UString &fname, VBDFile::AccessMode mode = VBDFile::READWRITE, int use_index = 0, int cache_size = 8) - Class constructor used to create or open the persistent object data file and index file. In this version do not use any file extensions when creating or opening a file. Both the data file and the index file will share the same name with different file extensions. The POD manager must be instructed to use an index file by setting use_index to 1. By default the POD manager will not use an index file. The file access mode can be set to either VBDFile::READWRITE or VBDFile::READONLY. The integer constants for the access modes are set in the VBDFile::AccessMode enumeration. The cache size is used to specify the size of the index file cache, in buckets. See the B-tree Cache classes for more details.

Exceptions:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

POD::POD(const char *fname, VBDFile::AccessMode mode = VBDFile::READWRITE, int use_index = 0, int cache_size = 8) - Class constructor used to create or open the persistent object data file and index file. In this version do not use any file extensions when creating or opening file. Both the data file and the index file will share the same name with different file extensions. The POD manager must be instructed to use an index file by setting use_index to 1. By default the POD manager will not use an index file. The file access mode can be set to either VBDFile::READWRITE or VBDFile::READONLY. The integer constants for the access modes are set in the VBDFile::AccessMode enumeration. The cache size is used to specify the size of the index file cache, in buckets. See the B-tree Cache classes for more details.

POD::POD(UString &dfname, UString &ifname, VBDFile::AccessMode mode = VBDFile::READWRITE, int use_index = 0, int cache_size = 8) - Class constructor used to create or open the persistent object data file and index file. In this version you must specify the name and extension of both the data file and the index file. The POD manager must be instructed to use an index file by setting use_index to 1. By default the POD manager will not use an index file. The file access mode can be set to either VBDFile::READWRITE or VBDFile::READONLY. The integer constants for the access modes are set in the VBDFile::AccessMode enumeration. The cache size is used to specify the size of the index file cache, in buckets. See the B-tree Cache classes for more details.

POD::POD(const char *dfname, const char *ifname, VBDFile::AccessMode mode = VBDFile::READWRITE, int use_index = 0, int cache_size = 8) - Class constructor used to create or open the persistent object data file and index file. In this version you must specify the name and extension of both the data file and the index file. The POD manager must be instructed to use an index file by setting use_index to 1. By default the POD manager will not use an index file. The file access mode can be set to either VBDFile::READWRITE or VBDFile::READONLY. The integer constants for the access modes are set in the VBDFile::AccessMode enumeration. The cache size is used to specify the size of the index file cache, in buckets. See the B-tree Cache classes for more details.

POD::~POD() - Class destructor responsible for disconnecting the POD manager from the data file and the index file.

Exceptions:
CDanglingPtr
CFileCloseError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

POD::POD(const POD &ob) - Private class copy constructor implemented to disallow copying.

void POD::operator=(const POD &ob) - Private class assignment operator implemented to disallow assignment.

int POD::Open(const UString &fname, VBDFile::AccessMode mode = VBDFile::READWRITE, int add_ext = 1) - Public member function used to open the data file. By default this function will automatically append the ".pod" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable
CChecksumError

int POD::Open(const char *fname, VBDFile::AccessMode mode = VBDFile::READWRITE, int add_ext = 1) - Public member function used to open the data file. By default this function will automatically append the ".pod" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable

CChecksumError

void POD::Disconnect() - Public member function used to disconnect the POD manager from the data file.

Exceptions:
CDanglingPtr
CFileCloseError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::Create(const UString &fname, int add_ext = 1) - Public member function used to create the data file. By default this function will automatically append the ".pod" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::Create(const char *fname, int add_ext = 1) - Public member function used to create the data file. By default this function will automatically append the ".pod" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

void POD::Flush() - Public member function used to flush any open disk buffers to the data file.

Exceptions:
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

void POD::Close() - Public member function used to disconnect the POD manager from the data file.

Exceptions:
CDanglingPtr
CFileCloseError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::Connect(VBDFilePtr &fp) - Public member function used to connect the POD manager to the data file.

VBDFilePtr POD::OpenDatabase() - Public member function that returns a reference counted pointer to the open data file.

VBDFilePtr POD::OpenDatabase() const - Public member function that returns a reference counted pointer to the open data file.

int POD::Exists() const - Public member function that returns true if the file already exists.

int POD::Exists() - Public member function that returns true if the file already exists.

int POD::OpenIndex(const UString &fname, VBDFile::AccessMode mode=VBDFile::READWRITE, int add_ext = 1) - Public member function used to open the index file. By default this function will automatically append the ".btx" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable

CChecksumError

int POD::OpenIndex(const char *fname, VBDFile::AccessMode mode=VBDFile::READWRITE, int add_ext = 1) - Public member function used to open the index file. By default this function will automatically append the ".btx" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileOpenError
CWrongFileType
CAccessViolation
CFileReadError
CFileNotReady
CDanglingPtr
CFileCloseError
CFileSeekError
CEOFError
CFileWriteError
CFileNotWriteable

CChecksumError

void POD::DisconnectIndex() - Public member function used to disconnect the POD manager from the index file.

Exceptions:
CDanglingPtr
CFileCloseError
CEOFError
CFileWriteError
CFileNotWriteable
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::CreateIndex(const UString &fname, int add_ext = 1) - Public member function used to create the index file. By default this function will automatically append the ".btx" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::CreateIndex(const char *fname, int add_ext = 1) - Public member function used to create the index file. By default this function will automatically append the ".btx" extension to the file name. If add_ext equals zero no file extension will be appended to the file name.

Exceptions:
CFileCreationError
CEOFError
CFileWriteError
CFileNotWriteable
CDanglingPtr
CFileCloseError
CFileSeekError
CAccessViolation
CFileReadError
CFileNotReady
CChecksumError

int POD::ConnectIndex(VBDFilePtr &fp) - Public member function used to connect the POD manager to the index file.

VBDFilePtr POD::OpenIndexFile() - Public member function that returns a reference counted pointer to the open index file.

VBDFilePtr POD::OpenIndexFile() const - Public member function that returns a reference counted pointer to the open index file.

int POD::UsingIndex() - Public member function that returns true if the application is using an index file.

int POD::UsingIndex() const - Public member function that returns true if the application is using an index file.

int POD::RebuildIndex() - Public member function that returns true if the index file needs to be rebuilt due to inconsistencies between the data and index file. Index files are rebuilt by the application in accordance with the methods defined in the class derived from the Persistent base class.

int POD::RebuildIndex() const - Public member function that returns true if the index file needs to be rebuilt due to inconsistencies between the data and index file. Index files are rebuilt by the application in accordance with the methods defined in the class derived from the Persistent base class.

Btree *POD::Index() - Public member function used to return a B-tree pointer to the open balanced multi-way disk based tree.

Btree *POD::Index() const - Public member function used to return a B-tree pointer to the open balanced multi-way disk based tree.

void POD::ResetIndexRebuild() - Public member function used to allow the application to reset the rebuild_index data member, so the POD::RebuildIndex() function will return true.

void POD::BuildNewIndex() - Public member function that allows the application to tell the POD Manager that the index file and the data file do not match.

void POD::DisableIndex() - Public member function that allows the application to disable the index file routines for certain functions.

void POD::EnableIndex() - Public member function that allows the application to enable the index file routines for certain functions after disabling the index file routines with a call to the POD::DisableIndex() function.

Exceptions

POD manager objects can cause any of the following exceptions, generated by calls to the VBD file manager's or B-tree's member functions, if the CPP_EXCEPTIONS macro is defined in the EHandler class at compile time. NOTE: The appropriate try and catch statements within the application must handle these exceptions or the program will terminate. If the CPP_EXCEPTIONS macro is not defined, the global error hander will signal that an exception has occurred and will terminate the program as defined in the EHandler::Terminate() function.

CAccessViolation - this exception is thrown if an "end of file" error occurs during multiple file access. This exception was added to tell the application that the file has grown in size but the EOF marker has not.

CDanglingPtr - this exception is thrown if there are any dangling references to a reference counted pointer, indicating that a copy of this object is still being used by another object.

CEOFError - this exception is thrown if an "end of file" error is encountered.

CFileCloseError - this exception is thrown if the file cannot be closed.

CFileCreationError - this exception is thrown if the file cannot be created.

CFileNotReady - this exception is thrown if the file is not ready for reading.

CFileNotWriteable - this exception is thrown if the file cannot be written to.

CFileOpenError - this exception is thrown if the file cannot be opened because it does not exist or cannot be accessed in the specified file access mode.

CFileReadError - this exception is thrown if an error occurs while reading from the file.

CFileSeekError - this exception is thrown if an error is encountered during a seek operation.

CFileWriteError - this exception is thrown if the number of bytes written do not match the number of bytes requested to write.

CSyncError - this exception is thrown if the VB header's check word cannot be read. This indicates a file synchronization error, meaning the VBD file manager is not reading a valid variable data block or the block is corrupt.

CWrongFileType - this exception is thrown if the file is not a VBD file type or the header is damaged and cannot be identified by the signature string in the VBD file header.

CChecksumError - this exception is thrown if a bit error occurs when writing to disk. A 32-bit CRC checksum based on the Ethernet polynomial of 0x4C11DB7 is calculated when any data is written to the VBD file. The calculated checksum is then compared to data actually stored on disk. If the calculated checksum does not match the actual checksum, a bit error has occurred during data storage.

End Of Document