Class RDbDatabase

class RDbDatabase;

Description

Abstract class providing the functionality of a database.

The source of the database and the implementation characteristics of a particular database are provided by a class derived from RDbDatabase.

DBMS has one such implementation: the store database.

This class is not intended for user derivation.

Note: For functions (i.e. Execute) that take an Sql string, if the string contains a LIKE clause with * (asterisks) wildcard then the characters between them must be no longer than length 255. If only one * exists then the length is taken from the start and to the end of the clause. However, if the clause contains a ? (question mark) wildcard within it then the characters between must be no longer than length 253.

Members

Defined in RDbDatabase:

• AlterTable(const TDesC &,const CDbColSet &)Alters a table synchronously.
• Begin()Begins a transaction.
• Close()Closes a database. Commits any pending transaction. Frees the allocated resource...
• ColSetL(const TDesC &)constReturns the table definition.
• Commit()Commits the current transaction.
• Compact()Synchronous database compaction. Compacts the database and returns when complete...
• CreateIndex(const TDesC &,const TDesC &,const CDbKey &)Creates an index synchronously.
• CreateTable(const TDesC &,const CDbColSet &)Creates a table on the database.
• CreateTable(const TDesC &,const CDbColSet &,const CDbKey &)Creates a table on the database.
• Destroy()Drops the tables and destroys the database. This handle is closed on successful ...
• DropIndex(const TDesC &,const TDesC &)Drops an index synchronously.
• DropTable(const TDesC &)Drops a table synchronously.
• Execute(const TDesC &,TDbTextComparison)Executes a SQL statement on the database, and returns when it is complete. The a...
• InTransaction()const
• IndexNamesL(const TDesC &)constLists the indexes on a table.
• IsDamaged()constReports the damage status of the database. The function checks database indexes ...
• KeyL(const TDesC &,const TDesC &)constReturns the index key.
• Recover()Synchronous database recovery. RDbDatabase::Recover() will try to rebuild databa...
• Rollback()Rollbacks the current transaction.
• Size()constReturns the currently available size information for the database. This comprise...
• TSize
• TableNamesL()constLists the tables on the database.
• UpdateStats()Update any calculated statistics for the database. Note that this can take an ex...
• iDatabase

IMPORT_C void Close();

Description

Closes a database. Commits any pending transaction. Frees the allocated resources.

IMPORT_C TInt Destroy();

Description

Drops the tables and destroys the database. This handle is closed on successful destruction.

Return value

IMPORT_C TBool IsDamaged() const;

Description

Reports the damage status of the database. The function checks database indexes and returs true if some of them are broken.

Return value

IMPORT_C TInt Recover();

Description

Synchronous database recovery. RDbDatabase::Recover() will try to rebuild database indexes if they are broken. If the database data is corrupted, it cannot be recovered.

Return value

IMPORT_C TInt UpdateStats();

Description

Update any calculated statistics for the database. Note that this can take an extended time to complete, so an incremental form is also provided - RDbIncremental::UpdateStats(RDbDatabase &,TInt &).

Return value

See also:

• RDbIncremental::UpdateStats(RDbDatabase &,TInt &)Initiates the operation of calculating and updating database statistics.

IMPORT_C TSize Size() const;

Description

Returns the currently available size information for the database. This comprises a size in bytes for the database objects and a percentage used value which indicates how much of that size is live data-the remainder may be available for compaction. Some types of database may not be able to report this information, e.g. a RDbStoreDatabase, and others may need to have RDbDatabase::UpdateStats() in order to provide valid data. In these cases, the values in the RDbDatabase::TSize structure will contain an error value to indicate this.

Return value

IMPORT_C TInt Compact();

Description

Synchronous database compaction. Compacts the database and returns when complete. Note that this can take an extended time to complete, so an incremental form is also provided. There is a complementary interface to calculate and report database size and usage information, which can be used by the clients to determine when it may be appropriate to compact the database.

Return value

See also:

• RDbIncremental::Compact(RDbDatabase &,TInt &)Initiates the operation of compacting a database. This is the incremental form o...
• RDbDatabase::UpdateStats()Update any calculated statistics for the database. Note that this can take an ex...
• RDbDatabase::Size()constReturns the currently available size information for the database. This comprise...

IMPORT_C TInt Begin();

Description

Begins a transaction.

DBMS server only supports one 'granularity' of transaction lock: the whole database. Beginning a transaction locks the database, and this can fail if another client has already got a lock which excludes this client. If the same client has already locked the database it will be panic'd. The function is guaranteed to return KErrNone for client-side access.

DBMS transactions do not provide any form of isolation between the clients: while one client is updating a table within a transaction, other clients will be able to see the changes as they are made. As a result, if a client retrieves two separate rows from a database there is no automatic guarantee that the data being retrieved has not been changed between the reads - this can lead to an 'inconsistent read'. A client can prevent an update while retrieving related rows by enclosing the individual reads within a transaction. Such a transaction will not modify the database and only operates as a read-lock: releasing such a lock using RDbDatabase::Commit() or RDbDatabase::Rollback() will not affect the database in any way.

How RDbDatabase::Begin() works:

• on a shared database RDbDatabase::Begin() will attempt to get a shared read-lock on the database, and will fail with KErrLocked if anyone has an exclusive write-lock. Other clients with read-locks will not cause this operation to fail.

• any operation which will modify the database attempts to gain an exclusive write-lock on the database, and will fail with KErrLocked if anyone else has any lock on the database. If the current client already has a read-lock as a result of calling RDbDatabase::Begin(), then it will be upgraded to an exclusive write-lock.

• RDbDatabase::Commit() or RDbDatabase::Rollback() after a read-lock has been acquired (but not a write-lock) will release that client's lock. The database will only be considered to be unlocked when all such locks are removed by all clients, when it will report a EUnlock event to any notifiers.

• RDbDatabase::Commit() or RDbDatabase::Rollback() after a write-lock has been acquired will release the lock, and report the ECommit or ERollback event to any notifiers.

• automatic transactions will be used as at present if updates are made outside of explicit transactions, and such updates will also be able to fail with KErrLocked if an exclusive lock cannot be acquired.

Allowing read-locks to be shared enables greater concurrency at the same time as providing some safe guard against inconsistent reads. It does, however, lead to the possibility of deadlock: two clients wanting to update the database can reach deadlock if they both RDbDatabase::Begin() a transaction before either of them starts an update, then one client's read-lock will prevent the other from upgrading to a write lock and vice versa. The only way out of this is to code the clients in such a way as to back out of such a deadlock situation, rather than retry forever without releasing the locks.

A client will be able to change the database schema while other clients are using the database, as long as the other clients have no locks on it. As described above, other clients may find that their rowsets are then invalidated asynchronously as a result of this.

Return value

IMPORT_C TInt Commit();

Description

Commits the current transaction.

Return value

IMPORT_C void Rollback();

Description

Rollbacks the current transaction.

IMPORT_C TBool InTransaction() const;

Description

Return value

inline TInt CreateTable(const TDesC &aName, const CDbColSet &aDef);

Description

Creates a table on the database.

Parameters

Return value

inline TInt CreateTable(const TDesC &aName, const CDbColSet &aDef, const CDbKey &aPrimaryKey);

Description

Creates a table on the database.

Parameters

Return value

IMPORT_C TInt DropTable(const TDesC &aName);

Description

Drops a table synchronously.

Parameters

Return value

IMPORT_C TInt AlterTable(const TDesC &aName, const CDbColSet &aNewDef);

Description

Alters a table synchronously.

Parameters

Return value

IMPORT_C TInt CreateIndex(const TDesC &aName, const TDesC &aTable, const CDbKey &aKey);

Description

Creates an index synchronously.

Parameters

Return value

IMPORT_C TInt DropIndex(const TDesC &aName, const TDesC &aTable);

Description

Drops an index synchronously.

Parameters

Return value

IMPORT_C TInt Execute(const TDesC &aSql, TDbTextComparison aComparison=EDbCompareNormal);

Description

Executes a SQL statement on the database, and returns when it is complete. The aComp parameter is used in the execution of some SQL statements:

• in CREATE INDEX statements it specifies the comparison operation used for text columns in the index key;

• in UPDATE and DELETE statements it specifies the comparison operation used to evaluate the WHERE clause; Other statements ignore the value of aComp. A negative return value indicates an error. A successful DDL operation always returns KErrNone (zero), a successful DML operation returns the number of rows that were inserted, updated or deleted by the operation.

Parameters

Return value

IMPORT_C CDbTableNames* TableNamesL() const;

Description

Lists the tables on the database.

Return value

Leave codes

IMPORT_C CDbColSet* ColSetL(const TDesC &aName) const;

Description

Returns the table definition.

Parameters

Return value

Leave codes

IMPORT_C CDbIndexNames* IndexNamesL(const TDesC &aTable) const;

Description

Lists the indexes on a table.

Parameters

Return value

Leave codes

IMPORT_C CDbKey* KeyL(const TDesC &aName, const TDesC &aTable) const;

Description

Returns the index key.

Parameters

Return value

Leave codes

struct TSize;

Description

Members

Defined in RDbDatabase::TSize:

• iSize
• iUsage

Member data

iSize

TInt iSize;

Description

iUsage

TInt iUsage;

Description

protected: RDbHandle< CDbDatabase > iDatabase;

Description