RSqlDatabase Class Reference

class RSqlDatabase

A handle to a SQL database.

A RSqlDatabase object is, in effect, a handle to the SQL database. A client can:

The RSqlDatabase handles are not thread-safe.

A client can create either a non-secure database or a secure database, depending on the variant of RSqlDatabase::Create() that is used.
  • a non-secure database is created if the RSqlDatabase::Create(const TDesC&) variant is used.

  • a secure database is created if the RSqlDatabase::Create(const TDesC&, const RSqlSecurityPolicy&) variant is used. In this case, a container containing a collection of security policies needs to be set up first and passed to this Create() function. See references to RSqlSecurityPolicy for more information on security policies.

A client can also specify how it wants a transaction to interact with other transactions that may be running concurrently. The various ways in which transactions can interact (i.e. how one transaction can affect another) are referred to as "transaction isolation levels", and are defined by the values of the TIsolationLevel enum. A client specifies this by calling RSqlDatabase::SetIsolationLevel().

Each of the various flavours of Open and Create allows the optional provision of a configuration string. It is acceptable for this string to be missing. In the case where the string is missing, the config in the SqlServer.sql file will be used. If that does not exist then the MMH macro definitions will be used.

The config string is in the format PARAM=VALUE; PARAM=VALUE;...

Allowed parameters are: cache_size=nnnn page_size=nnnn encoding=UTF8|UTF16

Badly formed config strings are reported as KErrArgument

The string may not exceed 255 characters.

Please note that a database can only be accessed within the thread where it has been created. It is then not possible to create a database from thread1 and access it from thread2.

A client calls RSqlDatabase::Exec() to execute SQL statements. RSqlDatabase::Create()

RSqlDatabase::Open()

RSqlDatabase::Close()

RSqlDatabase::Copy()

RSqlDatabase::Delete()

RSqlDatabase::Attach()

RSqlDatabase::Detach()

RSqlDatabase::SetIsolationLevel()

RSqlDatabase::Exec()

TIsolationLevel

RSqlSecurityPolicy

Nested Classes and Structures

Public Member Functions
RSqlDatabase()
IMPORT_C TIntAttach(const TDesC &, const TDesC &)
IMPORT_C voidClose()
IMPORT_C TIntCompact(TInt64, const TDesC &)
IMPORT_C voidCompact(TInt64, TRequestStatus &, const TDesC &)
IMPORT_C TIntCopy(const TDesC &, const TDesC &)
IMPORT_C TIntCreate(const TDesC &, const TDesC8 *)
IMPORT_C TIntCreate(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C voidCreateL(const TDesC &, const TDesC8 *)
IMPORT_C voidCreateL(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C TIntDelete(const TDesC &)
IMPORT_C TIntDetach(const TDesC &)
IMPORT_C TIntExec(const TDesC &)
IMPORT_C TIntExec(const TDesC8 &)
IMPORT_C voidExec(const TDesC &, TRequestStatus &)
IMPORT_C voidExec(const TDesC8 &, TRequestStatus &)
IMPORT_C voidFreeReservedSpace()
IMPORT_C TIntGetReserveAccess()
IMPORT_C TIntGetSecurityPolicy(RSqlSecurityPolicy &)
IMPORT_C voidGetSecurityPolicyL(RSqlSecurityPolicy &)
IMPORT_C TBoolInTransaction()
IMPORT_C TPtrCLastErrorMessage()
IMPORT_C TInt64LastInsertedRowId()
IMPORT_C TIntOpen(const TDesC &, const TDesC8 *)
IMPORT_C voidOpenL(const TDesC &, const TDesC8 *)
IMPORT_C voidReleaseReserveAccess()
IMPORT_C TIntReserveDriveSpace(TInt)
IMPORT_C TIntSetIsolationLevel(TIsolationLevel)
IMPORT_C TIntSize()
IMPORT_C TIntSize(TSize &, const TDesC &)
Private Member Functions
CSqlDatabaseImpl &Impl()
Public Member Enumerations
enumTIsolationLevel { EReadUncommitted, EReadCommitted, ERepeatableRead, ESerializable }
Private Attributes
CSqlDatabaseImpl *iImpl

Constructor & Destructor Documentation

RSqlDatabase()

IMPORT_CRSqlDatabase()

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

IMPORT_C TIntAttach(const TDesC &aDbFileName,
const TDesC &aDbName
)

Parameters

const TDesC & aDbFileName
const TDesC & aDbName

Close()

IMPORT_C voidClose()

Compact(TInt64, const TDesC &)

IMPORT_C TIntCompact(TInt64aSize,
const TDesC &aDbName =  KNullDesC
)

Parameters

TInt64 aSize
const TDesC & aDbName =  KNullDesC

Compact(TInt64, TRequestStatus &, const TDesC &)

IMPORT_C voidCompact(TInt64aSize,
TRequestStatus &aStatus,
const TDesC &aDbName =  KNullDesC
)

Parameters

TInt64 aSize
TRequestStatus & aStatus
const TDesC & aDbName =  KNullDesC

Copy(const TDesC &, const TDesC &)

IMPORT_C TIntCopy(const TDesC &aSrcDbFileName,
const TDesC &aDestDbFileName
)[static]

Parameters

const TDesC & aSrcDbFileName
const TDesC & aDestDbFileName

Create(const TDesC &, const TDesC8 *)

IMPORT_C TIntCreate(const TDesC &aDbFileName,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

Create(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)

IMPORT_C TIntCreate(const TDesC &aDbFileName,
const RSqlSecurityPolicy &aSecurityPolicy,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const RSqlSecurityPolicy & aSecurityPolicy
const TDesC8 * aConfig = NULL

CreateL(const TDesC &, const TDesC8 *)

IMPORT_C voidCreateL(const TDesC &aDbFileName,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

CreateL(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)

IMPORT_C voidCreateL(const TDesC &aDbFileName,
const RSqlSecurityPolicy &aSecurityPolicy,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const RSqlSecurityPolicy & aSecurityPolicy
const TDesC8 * aConfig = NULL

Delete(const TDesC &)

IMPORT_C TIntDelete(const TDesC &aDbFileName)[static]

Parameters

const TDesC & aDbFileName

Detach(const TDesC &)

IMPORT_C TIntDetach(const TDesC &aDbName)

Parameters

const TDesC & aDbName

Exec(const TDesC &)

IMPORT_C TIntExec(const TDesC &aSqlStmt)

Parameters

const TDesC & aSqlStmt

Exec(const TDesC8 &)

IMPORT_C TIntExec(const TDesC8 &aSqlStmt)

Parameters

const TDesC8 & aSqlStmt

Exec(const TDesC &, TRequestStatus &)

IMPORT_C voidExec(const TDesC &aSqlStmt,
TRequestStatus &aStatus
)

Parameters

const TDesC & aSqlStmt
TRequestStatus & aStatus

Exec(const TDesC8 &, TRequestStatus &)

IMPORT_C voidExec(const TDesC8 &aSqlStmt,
TRequestStatus &aStatus
)

Parameters

const TDesC8 & aSqlStmt
TRequestStatus & aStatus

FreeReservedSpace()

IMPORT_C voidFreeReservedSpace()

GetReserveAccess()

IMPORT_C TIntGetReserveAccess()

GetSecurityPolicy(RSqlSecurityPolicy &)

IMPORT_C TIntGetSecurityPolicy(RSqlSecurityPolicy &aSecurityPolicy)const

Parameters

RSqlSecurityPolicy & aSecurityPolicy

GetSecurityPolicyL(RSqlSecurityPolicy &)

IMPORT_C voidGetSecurityPolicyL(RSqlSecurityPolicy &aSecurityPolicy)const

Parameters

RSqlSecurityPolicy & aSecurityPolicy

Impl()

CSqlDatabaseImpl &Impl()const [private]

InTransaction()

IMPORT_C TBoolInTransaction()const

LastErrorMessage()

IMPORT_C TPtrCLastErrorMessage()const

LastInsertedRowId()

IMPORT_C TInt64LastInsertedRowId()const

Open(const TDesC &, const TDesC8 *)

IMPORT_C TIntOpen(const TDesC &aDbFileName,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

OpenL(const TDesC &, const TDesC8 *)

IMPORT_C voidOpenL(const TDesC &aDbFileName,
const TDesC8 *aConfig = NULL
)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

ReleaseReserveAccess()

IMPORT_C voidReleaseReserveAccess()

ReserveDriveSpace(TInt)

IMPORT_C TIntReserveDriveSpace(TIntaSize)

Parameters

TInt aSize

SetIsolationLevel(TIsolationLevel)

IMPORT_C TIntSetIsolationLevel(TIsolationLevelaIsolationLevel)

Parameters

TIsolationLevel aIsolationLevel

Size()

IMPORT_C TIntSize()const

Size(TSize &, const TDesC &)

IMPORT_C TIntSize(TSize &aSize,
const TDesC &aDbName =  KNullDesC
)const

Parameters

TSize & aSize
const TDesC & aDbName =  KNullDesC

Member Enumerations Documentation

Enum TIsolationLevel

Defines a set of values that represents the transaction isolation level.

A transaction isolation level defines the way in which a transaction interacts with other transactions that may be in progress concurrently.

A client sets the transaction isolation level by calling SetIsolationLevel()

RSqlDatabase::SetIsolationLevel()

Enumerators

EReadUncommitted

A transaction can read uncommitted data, i.e. data that is being changed by another transaction, which is still in progress.

This means that
  • a 'database read' transaction will not block 'database write' transactions being performed by different database connections on the same shared database.

  • a 'database read' transaction will not be blocked by 'database write' transactions performed by the same database connection.

  • concurrent 'database write' transactions are prevented.

This transaction isolation level can be set at any time during the lifetime of the database.

TIsolationLevel

RSqlDatabase::SetIsolationLevel()

EReadCommitted

Not currently supported.

A transaction cannot read uncommitted data. "Dirty reads" are prevented.

"Dirty read" is a data inconsistency type which can be described with the following example:
  • Transaction A updates TableA.Column1 value from 1 to 2;

  • Transaction B reads TableA.Column1 value;

  • Transaction A rolls back and restores the original value of TableA.Column1 (1);

  • Transaction B ends showing that TableA.Column1 value is 2, even though, logically and transactionally, this data never really even existed in the database because Transaction A never committed that change to the database;

TIsolationLevel

RSqlDatabase::SetIsolationLevel()

ERepeatableRead

Not currently supported.

A transaction cannot change data that is being read by a different transaction. "Dirty reads" and "non-repeatable reads" are prevented.

"Non-repeatable reads" is a data inconsistency type which can be described with the following example:
  • Transaction A reads TableA.Column1 value which is 1;

  • Transaction B updates TableA.Column1 value from 1 to 2;

  • Transaction B commits the chages;

  • Transaction A reads TableA.Column1 value again. Transaction A has inconsistent data because TableA.Column1 value now is 2 instead of 1, all within the scope of the same Transaction A;

TIsolationLevel

RSqlDatabase::SetIsolationLevel()

ESerializable

Any number of 'database read' transactions can be performed concurrently by different database connections on the same shared database.

Only one 'database write' transaction can be performed at any one time. If a 'database write' transaction is in progress, then any attempt to start another 'database read' or 'database write' transaction will be blocked until the first 'database write' transaction has completed.

This is the default isolation level, if no isolation level is explicitly set.

"Dirty reads", "non-repeatable" reads and "phantom reads" are prevented.

"Phantom reads" is a data inconsistency type which can be described with the following example:
  • Transaction A reads all rows that have Column1 = 1;

  • Transaction B inserts a new row which has Column1 = 1;

  • Transaction B commits;

  • Transaction A updates all rows that have Column1 = 1. This will also update the row that Transaction B inserted, because Transaction A must read the data again in order to update it.

  • Transaction A commits;

TIsolationLevel

RSqlDatabase::SetIsolationLevel()

Member Data Documentation

CSqlDatabaseImpl * iImpl

CSqlDatabaseImpl *iImpl[private]