# Persistent Object Database Manager

Topics

:

Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Data Structures
Functions

Overview

The POD manager and Persistent base class comprise a persistent object framework used to create and maintain persistent objects. The POD (Persistent Object Database) manager is used to manage file pointers to data files and multiple index files. When a POD object is instantiated it automatically creates a data file and index file(s), or opens an existing set of files. Data files are files used to store an object's data to disk. All data files are created by the 32/64-bit database engine and maintained by the Persistent base class. Index files are used to navigate the data file by associating a data key with the address where the object's data can be found in the data file. All index files are created by the 32/64-bit database engine and maintained by the B-tree class. Index files were implemented primarily to increase the speed of search operations and can be omitted if indexed navigation is not required by the application. The POD manager allows you to use multiple indexes in a single index file or multiple indexes using multiple files.

Constants

    const unsigned POD_MAX_INDEX = 255; // Max number of index files per database

    // NOTE: The values are only used if no value is specified
    const BtreeNodeOrder_t POD_DEFAULT_ORDER = 29; // Default index file order
    const BtreeSize_t POD_DEFAULT_KEY_SIZE = 64;   // Default key size

Database engine constants

Data Structures

The POD index file type is used to store index file variables specific to each open index file managed by the PODIndexFile class.

    struct PODIndexFile_t
    {
      gxBtree *btree;         // Pointer to the open index file
      BtreeSize_t dbkey_size; // Size of the entry key used by this index
      BtreeNodeOrder_t order; // Order of the B-tree index
      gxClassID cid;          // Optional class ID
      int use_index;          // True if this index file is being used
      int rebuild_index;      // True if this index needs to be rebuilt
    };

The POD index file sub-system class is used by the POD manager to open and close multiple index files.

    class PODIndexFile
    {
    public:
      PODIndexFile(unsigned num_indexes);
      ~PODIndexFile();

    public:
      gxDatabaseError Open(const char *ifname, unsigned index_number,
    		       DatabaseKeyB &key_type,
    		       BtreeNodeOrder_t order = POD_DEFAULT_ORDER,
    		       gxDatabaseAccessMode mode = gxDBASE_READWRITE,
    		       gxClassID cid = (gxClassID_t)-1);
      gxDatabaseError Close(unsigned index_number);

    public:
      PODIndexFile_t *index_file[POD_MAX_INDEX]; // Array of POD index files
      unsigned n_indexes;  // Total number of index files in use by this database
      unsigned curr_index; // Current index file in use
    };

PODIndexFile::PODIndexFile(unsigned num_indexes)

- Constructor used to allocate an array large enough the specified number of index files.

PODIndexFile::~PODIndexFile()

- Class destructor responsible for de-allocating memory for the index file array when a PODIndexFile object is destroyed.

gxDatabaseError PODIndexFile::Close(unsigned index_number)

- Public member function used to close an open index file. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError PODIndexFile::Open(const char *ifname, unsigned index_number, DatabaseKeyB &key_type, BtreeNodeOrder_t order = POD_DEFAULT_ORDER, gxDatabaseAccessMode mode = gxDBASE_READWRITE,gxClassID cid = (gxClassID_t)-1);

- Public member function used to open an existing index file or create a new one if the specified file name does not exist. Returns a non-zero value to indicate an error condition or zero if successful.

Functions

POD::POD()
POD::~POD()
POD::Close()
POD::CloseDataFile()
POD::CloseIndex()
POD::CreateDataFile()
POD::CreateIndex()
POD::DataFileExceptionMessage()
POD::DisableIndex()
POD::EnableIndex()
POD::Exists()
POD::GetDataFileError()
POD::GetIndexFileError()
POD::Index()
POD::IndexFileExceptionMessage()
POD::Open()
POD::OpenDataFile()
POD::OpenIndex()
POD::OpenIndexFile()
POD::RebuildIndex()
POD::Release()
POD::ReleaseDataFile()
POD::ReleaseIndexFile()
POD::SetDataFileError()
POD::SetIndexFileError()
POD::UsingIndex()

POD::POD() - Default class constructor.

POD::POD(const POD &ob)

- Private class constructor used to disallow copying.

void POD::operator=(const POD &ob)

- Private member function used to disallow assignment.

POD::~POD()

- Class destructor responsible for closing all open files when a POD object is destroyed.

gxDatabaseError POD::Close()

- Public member function used to close the database, disconnecting both the data and index files. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::CloseDataFile()

- Public member function used to disconnect the database from the file. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::CloseIndex(unsigned index_number)

- Public member function used to disconnects the database from the index file. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::CreateDataFile(const char *fname, FAU static_size = (FAU_t)0)

- Public member function used to create a new data file. The "static_size" variable is used to reserve a specified number of bytes that will not be affected by the dynamic allocation routines. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::CreateIndex(const char *fname, unsigned index_number, DatabaseKeyB &key_type, BtreeNodeOrder_t order, int num_trees = 1)

- Public member function to create a new index file. The "num_trees" variable is used to specify how many trees this index file will contain.

const char *POD::DataFileExceptionMessage()

- Public member function that returns a null terminated string, which can be used to log or print the last reported data file exception.

void POD::DisableIndex()

- Public member function used to disable the use of index files.

void POD::EnableIndex()

- Public member function used to enable the use of index files after a call to the POD::DisableIndex() function.

int POD::Exists()

- Public member function the returns true is the data file exists or false is the data file had to be created during a database open call.

gxDatabaseError POD::GetDataFileError()

- Public member function the returns an error code representing the last reported data file error.

gxDatabaseError POD::GetIndexFileError(unsigned index_number = 0)

- Public member function the returns an error code representing the last reported index file error.

gxBtree *POD::Index(unsigned index_number = 0)

- Public member function that returns a pointer to the Btree index file for the specified index number or a null pointer if the index number is out of range.

const char *POD::IndexFileExceptionMessage(unsigned index_number = 0)

- Public member function that returns a null terminated string, which can be used to log or print the last reported index file exception.

gxDatabaseError POD::Open(const char *dfname, const char *ifname, DatabaseKeyB &key_type, BtreeNodeOrder_t order = POD_DEFAULT_ORDER, gxDatabaseAccessMode mode = gxDBASE_READWRITE, int use_index = 1, FAU static_size = (FAU_t)0, int num_trees = 1)

- Public member function used to open an existing database or create a new one using a single index file. Returns a non-zero value to indicate an error condition or zero if successful. If the "use_index" variable is false this database will not use an index file. The "num_trees" variable is used to specify how many trees the index file will contain.

gxDatabaseError POD::Open(const char *dfname, PODIndexFile *ix_ptr, gxDatabaseAccessMode mode = gxDBASE_READWRITE,FAU static_size = (FAU_t)0)

- Public member function used to open an existing database or create a new one using multiple index files with different key types. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::Open(const char *dfname, char *ifname[POD_MAX_INDEX], unsigned num_indexes, DatabaseKeyB &key_type, BtreeNodeOrder_t order = POD_DEFAULT_ORDER, gxDatabaseAccessMode mode = gxDBASE_READWRITE, FAU static_size = (FAU_t)0)

- Public member function used to open an existing database or create a new one using multiple index files that use the same key type. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError POD::OpenDataFile(const char *fname, gxDatabaseAccessMode mode = gxDBASE_READWRITE)

- Public member function used to open a data file. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabase *POD::OpenDataFile()

- Public member function that returns a pointer to the open data file or a null pointer if no data file is currently open.

gxDatabaseError POD::OpenIndex(const char *fname, unsigned index_number, DatabaseKeyB &key_type, BtreeNodeOrder_t order,gxDatabaseAccessMode mode = gxDBASE_READWRITE)

- Public member function used to open an index file. Returns a non-zero value to indicate an error condition or zero if successful.

PODIndexFile *POD::OpenIndexFile()

- Public member function that returns a pointer to the open index file array or a null pointer if no index files are currently open.

int POD::RebuildIndex(unsigned index_number = 0)

- Public member function that returns true if the current index file needs to be rebuilt.

void POD::Release()

- Public member function used to reset the data file and index file pointers to zero without closing the files or performing any other action. NOTE: This is function used to reset the file pointers when more the one object is referencing this POD database and the database has been closed or the file pointers have been deleted. You can also use the a Release() class to signal that this object is finished with the file pointers and can be deleted without affecting other objects currently using these files.

void POD::ReleaseDataFile()

- Public member function used to reset the data file pointer to zero without closing the file or performing any other action. NOTE: This function is used to reset the data file pointer when more the one object is referencing this data file pointer and the file has been closed or the pointer has been deleted.

void POD::ReleaseIndexFile()

- Public member function used to reset the index file pointer to zero without closing the file or performing any other action. NOTE: This function is used to reset the index file pointer when more the one object is referencing this index file pointer and the file has been closed or the pointer has been deleted.

gxDatabaseError POD::SetDataFileError(gxDatabaseError err)

- Public member function used to set the last reported data file error. This function is used to inform the database engine of a fatal error condition. Redundantly returns the "err" value to allow this function to be used as a return value.

gxDatabaseError POD::SetIndexFileError(gxDatabaseError err, unsigned index_number = 0)

- Public member function used to set the last reported index file error. This function is used to inform the database engine of a fatal error condition. Redundantly returns the "err" value to allow this function to be used as a return value.

int POD::UsingIndex()

- Public member function that returns true if this database is using an index file.

End Of Document