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(), Begin(), Close(), ColSetL(), Commit(), Compact(), CreateIndex(), CreateTable(), CreateTable(), Destroy(), DropIndex(), DropTable(), Execute(), InTransaction(), IndexNamesL(), IsDamaged(), KeyL(), Recover(), Rollback(), Size(), TSize, TableNamesL(), UpdateStats(), iDatabase

IMPORT_C void Close();

Description

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

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt Destroy();

Description

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

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

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

TBool True if the database is damaged, false otherwise.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the write access policy for the database.

IMPORT_C TInt Recover();

Description

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

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the write access policy for the database.

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().

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

See also:

• RDbIncremental::UpdateStats()

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 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

TSize RDbDatabase::TSize object, containing the database size and the percentage used value.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the write access policy for the database.

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

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

See also:

• RDbIncremental::Compact()
• RDbDatabase::UpdateStats()
• RDbDatabase::Size()

Capability:

Security policy note:

For a secure shared database, the caller must satisfy either the read or the write access policy for the database.

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 Commit() or Rollback() will not affect the database in any way.

How RDbDatabase::Begin() works:

• on a shared database 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 Begin(), then it will be upgraded to an exclusive write-lock.

• Commit() or 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.

• Commit() or 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 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

TInt KErrNone The operation has completed successfully; KErrLocked, the database is locked by another client; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy either the read or the write access policy for the database.

IMPORT_C TInt Commit();

Description

Commits the current transaction.

Return value

TInt KErrNone The operation has completed successfully; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy either the read or the write access policy for the database.

IMPORT_C void Rollback();

Description

Rollbacks the current transaction.

IMPORT_C TBool InTransaction() const;

Description

Return value

TBool True if the database is in a transaction, false otherwise.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

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

Description

Creates a table on the database.

Parameters

const TDesC &aName Table name. const CDbColSet &aDef A set of column definitions which describe the table structure.

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrAlreadyExists, a table with that name already exists; KErrArgument, empty column set, duplicated column name, invalid column length; KErrBadName, invalid table name, invalid column name (containing spaces for example); KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

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

Description

Creates a table on the database.

Parameters

const TDesC &aName Table name. const CDbColSet &aDef A set of column definitions which describe the table structure. const CDbKey &aPrimaryKey Primary key definition.

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrAlreadyExists, a table with that name already exists; KErrArgument, empty column set, duplicated column name, invalid column length; KErrBadName, invalid table name, invalid column name (containing spaces for example); KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt DropTable(const TDesC &aName);

Description

Drops a table synchronously.

Parameters

const TDesC &aName Table name.

Return value

TInt KErrNone The operation has completed successfully; KErrNotFound, there is no table with the supplied name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

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

Description

Alters a table synchronously.

Parameters

const TDesC &aName Table name. const CDbColSet &aNewDef A new set of column definitions which describe the table structure.

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrArgument, empty column set, duplicated column name, invalid column length; KErrNotFound, there is no table with the supplied name; KErrNotSupported, unknown column type, unknown column attributes; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

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

Description

Creates an index synchronously.

Parameters

const TDesC &aName Index name. const TDesC &aTable Table name. const CDbKey &aKey Index definition

Return value

TInt KErrNone The operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrBadName, invalid index name (containing spaces for example); KErrAlreadyExists, an index with that name already exists; KErrNotFound, there is no table with that name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy the schema access policy for the database.

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

Description

Drops an index synchronously.

Parameters

const TDesC &aName Index name. const TDesC &aTable Table name.

Return value

TInt KErrNone The operation has completed successfully; KErrNotFound, there is no table or index with that name; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

Capability:

Security policy note:

For a secure shared database, the caller must satisfy:

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

const TDesC &aSql A string of 16-bit wide characters containing one SQL statement. TDbTextComparison aComparison Tells the DBMS how to compare text and long text columns.

Return value

TInt Zero or positive value, the number of rows that were inserted, updated or deleted by the operation; KErrLocked, the database is locked by another client; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that other system-wide error codes may also be returned.

IMPORT_C CDbTableNames *TableNamesL() const;

Description

Lists the tables on the database.

Return value

CDbTableNames * A pointer to a CDbTableNames container with table names. The caller is responsible for destroying the returned CDbTableNames instance.

Leave codes

KErrNoMemory, an out of memory condition has occurred; Note that the function may leave with other system-wide error codes.

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

Description

Returns the table definition.

Parameters

const TDesC &aName Table name.

Return value

CDbColSet * A pointer to a CDbColSet container with column definitions . The caller is responsible for destroying the returned CDbColSet instance.

Leave codes

KErrNoMemory, an out of memory condition has occurred; KErrNotFound, no table with that name exists; Note that the function may leave with other system-wide error codes.

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

Description

Lists the indexes on a table.

Parameters

const TDesC &aTable Table name.

Return value

CDbIndexNames * A pointer to a CDbIndexNames container with column definitions . The caller is responsible for destroying the returned CDbIndexNames instance.

Leave codes

KErrNoMemory, an out of memory condition has occurred; KErrNotFound, no table with that name exists; Note that the function may leave with other system-wide error codes.

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

Description

Returns the index key.

Parameters

const TDesC &aName Index name. const TDesC &aTable Table name.

Return value

CDbKey * A pointer to a CDbKey object containing the index definition. The caller is responsible for destroying the returned CDbKey instance.

Leave codes

KErrNoMemory, an out of memory condition has occurred; KErrNotFound, no index or table with that name exists; Note that the function may leave with other system-wide error 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