Ebase

Ebase class declares an interface for embedded database engine. It is embedded because no separate server is around; the function is executed through the caller thread. It is a database engine because it is a library; it does not provided command line interface. Ebase provides basic functions for creating database, adding/ deleting/modifying records, building/deleting indices, and searching.

Back to the top of Ebase

Ebase();

Constructor.

    Ebase();

Back to the top of Ebase

~Ebase();

Destructor.

    ~Ebase();

Back to the top of Ebase

void CreateDatabase(EbaseDef * def, const char * dbFileName);

Create a database with the specified name, fileds, etc.

Note that the caller retains the ownership of 'def' after the call.

Parameters :

in def: Database definition.
in dbFileName: The file used to hold the database

    static void CreateDatabase(EbaseDef * def,
                               const char * dbFileName);

Back to the top of Ebase

void OpenDatabase(const char * dbFileName);

Open a database. Almost all functions need an open database associated with this object.

Parameters :

in dbFileName: Database file name.

Exceptions:

EBE_OPEN_FILE
EBE_OUT_OF_MEMORY

    void OpenDatabase(const char * dbFileName);

Back to the top of Ebase

void CloseDatabase();

Close database. After closing the current open database, this object can open another database.

    void CloseDatabase();

Back to the top of Ebase

EbBoolean IsOpen();

Query if database is open.

    EbBoolean IsOpen();

Back to the top of Ebase

EbIndexDef * NewIndexDef();

Create a new index template for later index creation. Ebase owns the new data. The caller should never try to free the data.

Limit : Currently there can only be one new index def structure at any time. The new index def is converted to a regular index def whne BuildIndex() is called. The curr new index def is deleted if a second NewIndexDef() is called before any BuildIndex() is called. The new index def, if there is one, is deleted when database is closed.

Exceptions : EBE_OUT_OF_MEMORY

    EbIndexDef * NewIndexDef();

Back to the top of Ebase

void BuildIndex(EbIndexDef *& def);

Build a new index. If an index already exists with the same definition, this function has no effect other than setting the def pointer to the existing index def.

If def was a new index def, the caller will not be able to modify the index def strcuture after this function is successfully called.

Parameters :

in/out def: Pointer to the index definition.

Exceptions :

EBE_INVALID_INDEX: The def is not created by this ebase. Or ebase cannot find the index driver.
EBE_OUT_OF_MEMORY
EBE_OUT_OF_FILE_SPACE

    void BuildIndex(EbIndexDef *& def);

Back to the top of Ebase

void DeleteIndex(EbIndexDef * pIndex);

Delete an index. The argument can be obtained either through NewIndexDef() or through GetIndexDef().

Applications cannot delete the record id index.

Parameters :

in pIndex: Pointer to the index def to be deleted.

Exceptions :

EBE_INVALID_INDEX: The def does not belong to the ebase. Or the index is record id index.

    void DeleteIndex(EbIndexDef * pIndex);

Back to the top of Ebase

EbUint32 NumberOfIndices();

Return the number of indices.

    EbUint32 NumberOfIndices();

Back to the top of Ebase

EbIndexDef * GetIndexDef(EbUint32 iid);

Return a pointer to the existing index def. The ebase owns the data.

Exceptions :

EBE_INVALID_INDEX

    EbIndexDef * GetIndexDef(EbUint32 iid);

Back to the top of Ebase

EbInt32 GetIndexId(EbIndexDef * pIndex);

Get index id. Return -1 if not found.

    EbInt32 GetIndexId(EbIndexDef * pIndex);

Back to the top of Ebase

EbRecord * NewRecord();

Return a new empty record for further manipulation. The new will normally be added to database through CommitRecord().

The new record will have -1 record id until it is committed.

The ebase owns the new record. In other words, the caller should not try to free the data.

There can be more than one new records at a time.

Exception :

EBE_OUT_OF_MEMORY

    EbRecord * NewRecord();

Back to the top of Ebase

EbRecord * GetRecord(EbUint32 offset, EbIndexId iid );

Retrieve an existing record by its offset according to the specified index sorting order.

The ebase owns the record. In other words, the caller should not try to free the data.

Get the same record multiple times will result in multipe copies of the same record.

Parameters :

in offset: The record offset, [0, numRecords -1 ].

Return value : Pointer to a newly created record.

Exceptions :

EBE_OUT_OF_MEMORY
EBE_INVALID_INDEX
EBE_INVALID_RECORD_OFFSET

    EbRecord * GetRecord(EbUint32 offset, EbIndexId iid=0);

Back to the top of Ebase

void CommitRecord(EbRecord *rec);

Add a new record or modify an existing record, depending on whether the record was obtained through NewRecord() or GetRecord().

Parameters :

in rec: Pointer to the modified or new record.

Exception :

EBE_OUT_OF_MEMORY
EBE_OUT_OF_FILE_SPACE

    void CommitRecord(EbRecord *rec);

Back to the top of Ebase

void DeleteRecord(EbRecord *pRecord);

Delete a record. Both memory resource and file resource are freed. For a new, uncommited record, this function frees the memory space occupied by the record.

Parameters :

in pRecord: The record to be deleted.

Exception :

EBE_INVALID_RECORD: Possibly record is created by another db.

    void DeleteRecord(EbRecord *pRecord);

Back to the top of Ebase

void FreeRecord(EbRecord * pRecord);

Free the memory occupied by the record. This function is called when the caller does not want to use the record anymore. If this function is not called on a record, the record will be freed when the database is closed.

Exception :

EBE_INVALID_RECORD: The record is not a valid record of ebase.

    void FreeRecord(EbRecord * pRecord);

Back to the top of Ebase

void FreeAllRecords();

Free the memory occupied by all active records.

    void FreeAllRecords();

Back to the top of Ebase

EbUint32 NumberOfRecords();

Return the number of records.

    EbUint32 NumberOfRecords();

Back to the top of Ebase

void BinarySearch(EbIndexDef * index, EbRecord *pRecord, EbUint32 & pos, EbBoolean & found, EbInt32 option );

Binary search a record. The index must have already been built. The record can be a new record, an existing record or a modified existing record.

HINT : This search is faster. You only need to supply the field data that are relavent to the current index in the record. For example, if current index is a dictionary order on "LastName" field, you can create a new record and put "Smith" in to the "LastName" field to search for a record with last name "Smith".

BinarySearch only searches for exact match with built indices.

Parameters :

in index

The index according to which binary search is performed

in pRecord

The record

out pos

The position of the found, matching record.

out found

whether a match is found.

in option

Search option in case there is multiple matches :

< 0 : return the first hit
= 0 : return random hit
> 0 : return the last hit

Exceptions :

EBE_OUT_OF_MEMORY
EBE_INVALID_INDEX
EBE_INVALID_RECORD

    void BinarySearch(EbIndexDef * index,
                      EbRecord *pRecord,
                      EbUint32 & pos,
                      EbBoolean & found,
                      EbInt32 option = 0);

Back to the top of Ebase

EbaseDef * GetEbaseDef();

Get a pointer to the database definition. The caller must not modify the definition.

The caller does not own the ebase def data.

Return value : a pointer to the copy of the database definition. Or NULL on errors.

    EbaseDef * GetEbaseDef();

Back to the top of Ebase

All Members

public:: static void CreateDatabase(EbaseDef * def, const char * dbFileName);; void OpenDatabase(const char * dbFileName);; void CloseDatabase();; EbBoolean IsOpen();; EbIndexDef * NewIndexDef();; void BuildIndex(EbIndexDef *& def);; void DeleteIndex(EbIndexDef * pIndex);; EbUint32 NumberOfIndices();; EbIndexDef * GetIndexDef(EbUint32 iid);; EbInt32 GetIndexId(EbIndexDef * pIndex);; EbRecord * NewRecord();; EbRecord * GetRecord(EbUint32 offset, EbIndexId iid );; void CommitRecord(EbRecord *rec);; void DeleteRecord(EbRecord *pRecord);; void FreeRecord(EbRecord * pRecord);; void FreeAllRecords();; EbUint32 NumberOfRecords();; void BinarySearch(EbIndexDef * index, EbRecord *pRecord, EbUint32 & pos, EbBoolean & found, EbInt32 option );; EbaseDef * GetEbaseDef();
protected:

Back to the top of Ebase

Ancestors

Class does not inherit from any other class.

Back to the top of Ebase

Descendants

Class is not inherited by any others.

Back to the top of Ebase

Generated from source by the Cocoon utilities on Tue Aug 14 12:00:07 2001 .

Report problems to jkotula@vitalimages.com