EPOC   SDK Home Glossary Indexes Previous Next Up

RDbDatabase class


Contents


RDbDatabase class — Database

Section Contents

These members of the class are new in EPOC Release 5. They offer new functionality for:

See RDbDatabase for the pre-ER5 documentation for this class.


Transactions


Begin() — Begin a transaction

TInt Begin();

Description

Use this function to begin a transaction on the database. Transactions cannot be nested, so this must not be called if a transaction is outstanding — including automatic transactions.

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 and this ensures binary compatibility with the pre-ER5 version.

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 system error codes; see system error codes.

Notes

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


Size information and statistics updating


Size() — Fetch size information

TSize Size() const;

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Use this function to return the currently available size information for the database.

Specifically, the information returned is:

Return value

TSize

Size information for the database.


UpdateStats() — Update database statistics

TInt UpdateStats();

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Use this function to update any calculated statistics for the database and return 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 or one of the system error codes; see system error codes.


Database compaction


Compact() — Compact the database

TInt Compact();

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Use this function to compact the database and return when the compact 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 or one of the system error codes; see system error codes.


Enhanced SQL


Execute() — Execute DDL and DML statements

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

Compatibility

Applications that call this member function will not work correctly on a version of EPOC earlier than ER5.

Description

Use this function to execute a DDL (SQL schema update) statement or a DML (SQL data update) statement on the database and return when complete.

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

Arguments

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


Size information


TSize struct — Database size information

Description

The struct is a data type that is returned by the Size() member function of this class.

Member data

iSize

The total size of database objects, in bytes.

iUsage

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

EPOC       SDK Home Glossary Indexes Previous Next Up