RDbDatabase

RDbDatabase

Support

Supported from 5.0

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.

Defined in RDbDatabase:
AlterTable(), Begin(), ChangeSecurity(), Close(), ColSetL(), Commit(), Compact(), CreateIndex(), CreateTable(), Destroy(), DropIndex(), DropTable(), Execute(), InTransaction(), IndexNamesL(), IsDamaged(), KeyL(), Recover(), Rollback(), Size(), TSize, TableNamesL(), UpdateStats()

void Close();

Description

Closes the database object. It is safe to close a database object which is not open.

An attempt is made to commit any outstanding transaction on the database. If this fails, then when the database is finally closed it is effectively rolled back.

If a rowset is open or an incremental operation is in progress on this database, the database itself remains open until these have also been closed, though the database can no longer be accessed through this object.

For the Store database in this situation, the store must remain open and usable until all rowsets and incremental operations have been closed on this database.

TInt Destroy();

Description

Deletes an entire database. This involves first removing all tables in the database, before deleting and releasing any other resources required by the database.

If successful, the database object will be closed.

Notes:

The process of removing the tables may be a long-running operation. No incremental operation has been provided to do this. However, each table can be dropped incrementally by the client prior to calling this function to achieve the same result.
The Store database implementation deletes all of its streams from the store as part of this function.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes.

Description

Tests whether recovery is required for the database to be fully functional.

Note that the Store database implementation continues to allow operation on any objects in the database which are not damaged, even when it reports that recovery is necessary.

Return value

TBool

True if the database requires recovery; false, otherwise.

TInt Recover();

Description

Recovers a damaged database. The database must not have any tables or views open on it, or any pending transactions when recovering.

Database recovery can be performed incrementally, see the RDbIncremental class.

The Store database implementation does not require recovery to be performed in order to use the database — only the damaged indexes are unavailable until recovery has been completed.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. If recovery fails with either KErrNoMemory or KErrDiskFull, then recovery may be attempted again when more memory or disk space is available.

Description

Begins a transaction on the database. Transactions cannot be nested, so this must not be called if a transaction, including automatic transactions, is outstanding.

If transactions are not begun explicitly using Begin(), any modifications to the database will be made within an automatic transaction.

Beginning a transaction locks the database; the lock is a shared read-lock. In ER5, this can fail if another client already has a lock which excludes this client; the function returns an error code to indicate this.

The function always returns KErrNone for client side access to the database.

Not that if the client has already locked the database, then another attempt to lock it causes the client to be panicked.

Return value

TInt

KErrNone for client side access to the database or, if this is a shared database and the client has successfully locked it.KErrLocked if this is a shared database and another client already has an exclusive write-lock on it. Otherwise, one of the other system error codes.

TInt Commit();

Description

Commits the current transaction on the database. This must match a call to Begin(), as automatic transactions cannot be committed using this function.

On failure, the database becomes unusable until it is rolled back.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes.

Description

Rolls back the current transaction on the database, restoring the database to its previous state. It should be used if an error occurs while making the updates or committing the transaction.

This must match a call to Begin(), as automatic transactions cannot be rolled back using this function.

The Store database implementation may not be able to fully restore indexes to their previous state upon roll back. They will remain unusable until the database has been recovered: the database will report damage if this is the case.

Description

Tests if there is an outstanding transaction on the database. This only reports on transactions started explicitly using the Begin() function.

Return value

TBool

True, if a transaction is in progress; false, otherwise.

Description

Schema modifications cannot be done while any tables or views are open, it also cannot be done within the same transaction as row updates.

Most operations to modify the database schema can potentially take a while to execute, the RDbIncremental class provides a way to do these incrementally.

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

Description

Creates a new table in the database with the supplied column set.

Parameters

`const TDesC& aName`	The name of the table to create.
`const CDbColSet& aDef`	The definition of the new table. It is validated to ensure that all the columns have valid and unique names, and that the types can support the requested attributes.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. Specifically, the function returns:KErrBadName if a table or column name is invalid.KErrAlreadyExists if a table of the same name already exists in the database.KErrArgument if the column set is empty, there are duplicate column names, a column's maximum length is non-positive but not KDbUndefinedLength, or a non-numeric column has the auto-increment attribute.KErrNotSupported if a column type is out of the recognised range, an unknown attribute bit is set, or the maximum length for a Text8, Text16 or Binary column is more than 255.KErrTooBig if the resulting record size can be larger than 8200 bytes.

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

Description

Creates a new table in the database with the supplied column set, using a primary key.

The Store database implementation does not support primary keys.

Parameters

`const TDesC& aName`	The name of the table to create.
`const CDbColSet& aDef`	The definition of the new table. It is validated to ensure that all the columns have valid and unique names, and that the types can support the requested attributes.
`const CDbKey& aPrimaryKey`	The primary key for the new table.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. The Store database always returns KErrNotSupported for this function.

Description

Removes a specified table from the database. This also removes all indexes on the table.

Tables can be dropped incrementally, see the RDbIncremental class.

Parameters

const TDesC& aName

The name of the table to remove from the database.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. The Store database always returns KErrNotSupported for this function.

Description

Changes the structure of a specified table in the database to the new column set.

Compared to the table's current column set, the new set may add new columns and remove columns which are not indexed. Columns cannot have their type, name or attributes changed.

The table data may need to be reorganised as a result of changing the definition, so this function may take a while to complete.

Tables can be altered incrementally, see the RDbIncremental class.

For the Store database, adding new columns to a table can be done easily, dropping columns requires that the entire table is rebuilt.

Parameters

`const TDesC& aName`	The name of the table to alter.
`const CDbColSet& aNewDef`	The new definition for the table.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. Specifically, the function returns:KErrNotFound if the table does not exist in the database.KErrBadName if a column name is invalid.KErrArgument if the new column set is empty, or there are duplicate column names, or if a column's maximum length is non-positive but not KDbUndefinedLength, or a non-numeric column has the auto-increment attribute, or an indexed column has been dropped, or a column has changed its type or attributes, or a not-null or auto-increment column has been added to a table which is not empty.KErrNotSupported if a column type is out of the recognised range, or an unknown attribute bit is set, or the maximum length for a Text8, Text16 or Binary column is more than 255.KErrTooBig if the resulting record size can be larger than 8200 bytes.

Description

Creates a new index with the provided key on the specified table in the database.

The index is automatically built from the table data in the database, so this function may take a while to complete.

Indexes can be built incrementally, see the RDbIncremental class.

Parameters

`const TDesC& aName`	The name of the index to create.
`const TDesC& aTable`	The table on which to create the index.
`const CDbKey& aKey`	The key for the new index. It is validated by this function to ensure that it matches the table structure.

Return value

TInt

KErrNone if successful, otherwise one of the other system wide error codes including the DBMS database error codes. Specifically, the function returns:KErrNotFound if the table does not exist in the database or a key column is not found in the table.KErrAlreadyExists if an index of the same name already exists on table or a duplicate key is present when building an index. Note that it is not possible to tell the difference between the possible causes of this error if index creation is not carried out incrementally.KErrBadName if an index or column name is invalid.KErrArgument if the key has no key columns or a fixed width column has a truncation length specified, or an invalid truncation length has been specified for a key column, or a LongText8 or LongText16 key column has no truncation length specified, or the key contains a Binary or LongBinary column.KErrNotSupported if a truncated key column is not the last one.KErrTooBig if the resulting key size is too big.

Description

Removes an index from the database.

Indexes can be dropped incrementally, see the RDbIncremental class.

Parameters

`const TDesC& aName`	The name of the index to remove from the database.
`const TDesC& aTable`	The table to which the index belongs.

Return value

TInt

Description

Returns a list all of the tables in the database.

The function leaves if it encounters any error conditions.

Return value

CDbTableNames*

A pointer to a table names list object. The caller should delete it when it is no longer required.

CDbColSet* ColSetL(const TDesC& aName) const;

Description

Returns the row structure of a table from the database.

Parameters

const TDesC& aName

The name of the table whose structure is required.

Return value

CDbColSet*

A pointer to a column set object which describes the table's row structure. The caller should delete it when it is no longer required.

Leave codes

The Store database can leave with one of the one of the DBMS database error codes or one of the system-wide error codes. Specifically, it leaves with KErrNotFound if the table does not exist.

CDbIndexNames* IndexNamesL(const TDesC& aTable) const;

Description

Returns a list all of the indexes belonging to a table on the database.

Parameters

const TDesC& aTable

The name of the table whose index list is required.

Return value

CDbIndexNames*

A pointer to a index names list object. The caller should delete it when it is no longer required.

Leave codes

The Store database can leave one of the DBMS database error codes or one of the system-wide error codes. Specifically it leaves with KErrNotFound if the table or index does not exist.

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

Description

Returns the definition of an index from the database.

Parameters

`const TDesC& aName`	The name of the index whose definition is required.
`const TDesC& aTable`	The table to which the index belongs.

Return value

CDbKey*

A pointer to a key object which describes the index. The caller should delete it when it is no longer required.

TSize Size() const;

Description

Returns the currently available size information for the database.

Specifically, the information returned is:

the size, in bytes, of the database objects.
the proportion, as a percentage, of the size of the database which is current data. This indicates how much space may be available for compaction.

Return value

TSize

Size information for the database.

TInt UpdateStats();

Description

Updates any calculated statistics for the database and returns when the update operation is complete.

This function can take an extended time to complete; an incremental form is provided by the RDbIncremental class.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Compacts the database and returns when the operation is complete.

This function can take an extended time to complete; an incremental form is provided by the RDbIncremental class.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Executes a DDL (SQL schema update) statement or a DML (SQL data update) statement on the database and returns when complete.

This function can take an extended time to complete; an incremental form is provided by the RDbIncremental class.

Parameters

const TDesC& aSql

A reference to a descriptor containing the SQL statement to be executed on the database.

TDbTextComparison aComparison

This argument is used in the execution of some SQL statements; specifically: 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. All other SQL statements ignore this argument. If not explicitly specified, this argument defaults to EDbCompareNormal.

Return value

TInt

Either:KErrNone, if a DDL statement was successfully executed. or the number of rows inserted, updated or deleted, if a DML statement was successfully executed. or another of the system error codes.

Description

Changes the access key for the database.

The function deletes both key objects.

Parameters

`CSecurityDecryptBase* aKey`	A pointer to the current decryption key which is authenticated in the same way as for opening a database.
`CSecurityEncryptBase* aNewKey`	A pointer to the new encryption key used to re-encrypt the authentication data

Return value

TInt

KErrArgument, if the database is not encrypted.KErrGeneral, if the decrypt key fails to access the database.

TSize

Description

Data type that is returned by RDbDatabase::Size().

Defined in RDbDatabase::TSize:
iSize, iUsage

`iSize`

TInt iSize

Description

The total size of database objects, in bytes.

`iUsage`

TInt iUsage

Description

The proportion, as a percentage, of the total size of database objects which is live data.

Class RDbDatabase

Support

Description

Closing the database

Close()

Description

Destroy()

Description

Return value

See also:

Recovery

IsDamaged()

Description

Return value

Recover()

Description

Return value

See also:

Transactions

Begin()

Description

Return value

Commit()

Description

Return value

See also:

Rollback()

Description

See also:

InTransaction()

Description

Return value

See also:

Changing the schema

Description

CreateTable()

Description

Parameters

Return value

CreateTable()

Description

Parameters

Return value

See also:

DropTable()

Description

Parameters

Return value

See also:

AlterTable()

Description

Parameters

Return value

See also:

CreateIndex()

Description

Parameters

Return value

See also:

DropIndex()

Description

Parameters

Return value

See also:

Schema enquiry

TableNamesL()

Description

Return value

ColSetL()

Description

Parameters

Return value

Leave codes

IndexNamesL()

Description

Parameters

Return value

Leave codes

KeyL()

Description

Class `RDbDatabase`

`Close()`

`Destroy()`

`IsDamaged()`

`Recover()`

`Begin()`

`Commit()`

`Rollback()`

`InTransaction()`

`CreateTable()`

`CreateTable()`

`DropTable()`

`AlterTable()`

`CreateIndex()`

`DropIndex()`

`TableNamesL()`

`ColSetL()`

`IndexNamesL()`

`KeyL()`

`Size()`

`UpdateStats()`

`Compact()`

`Execute()`

`ChangeSecurity()`

Struct `TSize`

`iSize`

`iUsage`