QbDatabaseClass is derived from the QbBaseClass and defines the abstract interface to a database to store feature data. You need to make a specific implementation for the virtual abstract functions (Open, Close, Insert, Update, Retrieve, Delete, Commit and CreateIterator) in order to use your database manager (IBM's UDB, Oracle, Sybase, dbm, and so on). In the current QBIC implementation, the Berkeley dbm system is used to implement the virtual functions.
Open and Close opens and closes a name space for subsequent operations. If the name space does not exist, Open creates it. Open also takes an optional second argument that specifies the mode, either "w" for write access or "r" for read access. The default is to open using the same mode supported by the connection to the database. However, a call to Open with the "w" (write) mode when the connection uses the read mode will fail.
To remove the namespace use the CloseAndRemove member function. The Insert member function inserts the key/value pair into the database and fails if the key already exists. To update an existing record, use the Update function. Update fails if the key does not exist. Given a key, Retrieve returns the value and Delete deletes the record. Because the database object often keeps state, copying of QbDatabaseClass is not allowed. If multiple objects are needed, the program is free to create them. CreateIterator is an abstract virtual function that creates an instance of a database iterator.
This chapter describes the following methods:
Create a QbDatabaseClass object by calling the CreateDatabaseClass method of the QbConnectClass.
You can see coding examples in Appendix C, "Sample Code" on page 185. Other programs are located in the qbic/QbicApi
directory.
This is the constructor for the class. This method attaches to the database connection specified.
QbDatabaseClass( const QbConnectClass &connectArg )
connectArg-A reference to a QbConnectClass object that specifies the database connection
This is the destructor for the class.
virtual ~QbDatabaseClass( void )
This method closes an open database table or file.
virtual int Close( void )
An integer value: 0 indicates success; -1 indicates failure
This method closes an open database table or file, and drops the table or deletes the file.
virtual int CloseAndRemove( void )
An integer value: 0 indicates success; -1 indicates failure
This method allows a database that has transaction support to keep a record of all the updates, additions, and deletions that have been made. In other words, this method tells the database to commit the changes to the database.
virtual int Commit( void )
An integer value: 0 indicates success; -1 indicates failure
This method creates an iterator object for the database.
virtual QbDatabaseIteratorClass * CreateIterator( void )
A pointer to a QbDatabaseIteratorClass object; return NULL if the database is not yet open
This method deletes a record from the database.
virtual int Delete( const QbDatumClass &key )
key-A reference to a QbDatumClass object that contains the key
An integer value: 0 indicates success; -1 indicates failure
This method returns a reference to the database connection specified by protected member connection.
const QbConnectClass & GetConnection( void )
A reference to a QbConnectClass object
This method returns the name of the database that is opened.
virtual const char * GetContainerName( void )
A pointer to a string to hold the container name
This method inserts a record into the database.
virtual int Insert( const QbDatumClass &key, const QbDatumClass &value )
key-A reference to a QbDatumClass object that contains the key
value-A reference to a QbDatumClass object that contains the record value
An integer value: 0 indicates success; 1 indicates the record already exists; -1 indicates a fatal error
This method determines whether the database is empty.
virtual int IsEmpty( void )
An integer value: 0 indicates the database is empty; 1 indicates the database is not empty; -1 indicates a fatal error
This method opens a database table or file. It creates one if the named one does not exist. The argument mode specifies whether to open the database in read or write mode.
The Open method fails if the mode specified is write while the mode of the database connection is read.
virtual int Open( const char *tableOrFileName, const char *mode )
An integer value: 0 indicates success; -1 indicates failure
This method reads a record from the database.
virtual int Retrieve( const QbDatumClass &key, const QbDatumClass &value )
An integer value: 0 indicates success; 1 indicates a nonfatal error (such as trying to read a nonexistent record); -1 indicates a fatal error
This method updates a record in the database.
Set the insert flag to True to insert the record if it does not exist. Set the insert flag to False to return an error if the record does not exist (rather than inserting it.
virtual int Update( const QbDatumClass &key, const QbDatumClass &value, const Boolean insert = False )
An integer value: 0 indicates success; 1 indicates a nonfatal error (such as trying to update a nonexistent record with the insert flag set to False); -1 indicates a fatal error