Persistent Object Database Manager
Topics
:Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Data Structures
Functions
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.
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
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.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.
void POD::operator=(const POD &ob)
- Private member function used to disallow assignment. - Class destructor responsible for closing all open files when a POD object is destroyed. - 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. - 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. - Public member function used to disable the use of index files. - Public member function used to enable the use of index files after a call to the POD::DisableIndex() function. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - 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. - Public member function that returns true if this database is using an index file.|
End Of Document |