Page 12 out of 26 total pages


QbDatabaseClass


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:

QbDatabaseClass method

This is the constructor for the class. This method attaches to the database connection specified.

Syntax

QbDatabaseClass( const QbConnectClass &connectArg )

Parameters

Input

connectArg-A reference to a QbConnectClass object that specifies the database connection

Output

None

~QbDatabaseClass method

This is the destructor for the class.

Syntax

virtual ~QbDatabaseClass( void )

Parameters

None

Close method

This method closes an open database table or file.

Syntax

virtual int Close( void )

Parameters

Input

None

Output

An integer value: 0 indicates success; -1 indicates failure

CloseAndRemove method

This method closes an open database table or file, and drops the table or deletes the file.

Syntax

virtual int CloseAndRemove( void )

Parameters

Input

None

Output

An integer value: 0 indicates success; -1 indicates failure

Commit method

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.

Syntax

virtual int Commit( void )

Parameters

Input

None

Output

An integer value: 0 indicates success; -1 indicates failure

CreateIterator method

This method creates an iterator object for the database.

Syntax

virtual QbDatabaseIteratorClass * CreateIterator( void )

Parameters

Input

None

Output

A pointer to a QbDatabaseIteratorClass object; return NULL if the database is not yet open

Delete method

This method deletes a record from the database.

Syntax

virtual int Delete( const QbDatumClass &key )

Parameters

Input

key-A reference to a QbDatumClass object that contains the key

Output

An integer value: 0 indicates success; -1 indicates failure

GetConnection method

This method returns a reference to the database connection specified by protected member connection.

Syntax

const QbConnectClass & GetConnection( void )

Parameters

Input

None

Output

A reference to a QbConnectClass object

GetContainerName method

This method returns the name of the database that is opened.

Syntax

virtual const char * GetContainerName( void )

Parameters

Input

None

Output

A pointer to a string to hold the container name

Insert method

This method inserts a record into the database.

Syntax

virtual int Insert( const QbDatumClass &key, const QbDatumClass &value 
)

Parameters

Input

key-A reference to a QbDatumClass object that contains the key

value-A reference to a QbDatumClass object that contains the record value

Output

An integer value: 0 indicates success; 1 indicates the record already exists; -1 indicates a fatal error

IsEmpty method

This method determines whether the database is empty.

Syntax

virtual int IsEmpty( void )

Parameters

Input

None

Output

An integer value: 0 indicates the database is empty; 1 indicates the database is not empty; -1 indicates a fatal error

Open method

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.

Syntax

virtual int Open( const char *tableOrFileName, const char *mode )

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

Retrieve method

This method reads a record from the database.

Syntax

virtual int Retrieve( const QbDatumClass &key, const QbDatumClass 
&value )

Parameters

Input

Output

An integer value: 0 indicates success; 1 indicates a nonfatal error (such as trying to read a nonexistent record); -1 indicates a fatal error

Update method

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.

Syntax

virtual int Update( const QbDatumClass &key, const QbDatumClass 
&value, const Boolean insert = False )

Parameters

Input

Output

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




Page 12 out of 26 total pages


xzhu@almaden.ibm.com or tedl@almaden.ibm.com
Copyright © 1998, IBM Corporation. All rights reserved.