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:

create a SQL database by calling RSqlDatabase::Create().
open an existing SQL database by calling RSqlDatabase::Open().
close a SQL database by calling RSqlDatabase::Close().
copy a SQL database by calling RSqlDatabase::Copy().
delete a SQL database by calling RSqlDatabase::Delete().
attach a SQL database to current database connection by calling RSqlDatabase::Attach().
detach a SQL database from current database connection by calling RSqlDatabase::Detach().

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

RSqlDatabase::TSize

Public Member Functions
	RSqlDatabase()
IMPORT_C TInt	Attach(const TDesC &, const TDesC &)
IMPORT_C void	Close()
IMPORT_C TInt	Compact(TInt64, const TDesC &)
IMPORT_C void	Compact(TInt64, TRequestStatus &, const TDesC &)
IMPORT_C TInt	Copy(const TDesC &, const TDesC &)
IMPORT_C TInt	Create(const TDesC &, const TDesC8 *)
IMPORT_C TInt	Create(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C void	CreateL(const TDesC &, const TDesC8 *)
IMPORT_C void	CreateL(const TDesC &, const RSqlSecurityPolicy &, const TDesC8 *)
IMPORT_C TInt	Delete(const TDesC &)
IMPORT_C TInt	Detach(const TDesC &)
IMPORT_C TInt	Exec(const TDesC &)
IMPORT_C TInt	Exec(const TDesC8 &)
IMPORT_C void	Exec(const TDesC &, TRequestStatus &)
IMPORT_C void	Exec(const TDesC8 &, TRequestStatus &)
IMPORT_C void	FreeReservedSpace()
IMPORT_C TInt	GetReserveAccess()
IMPORT_C TInt	GetSecurityPolicy(RSqlSecurityPolicy &)
IMPORT_C void	GetSecurityPolicyL(RSqlSecurityPolicy &)
IMPORT_C TBool	InTransaction()
IMPORT_C TPtrC	LastErrorMessage()
IMPORT_C TInt64	LastInsertedRowId()
IMPORT_C TInt	Open(const TDesC &, const TDesC8 *)
IMPORT_C void	OpenL(const TDesC &, const TDesC8 *)
IMPORT_C void	ReleaseReserveAccess()
IMPORT_C TInt	ReserveDriveSpace(TInt)
IMPORT_C TInt	SetIsolationLevel(TIsolationLevel)
IMPORT_C TInt	Size()
IMPORT_C TInt	Size(TSize &, const TDesC &)

Private Member Functions
CSqlDatabaseImpl &	Impl()

Public Member Enumerations
enum	TIsolationLevel { EReadUncommitted, EReadCommitted, ERepeatableRead, ESerializable }

Private Attributes
CSqlDatabaseImpl *	iImpl

Constructor & Destructor Documentation

RSqlDatabase()

IMPORT_C

RSqlDatabase

(

)

Member Functions Documentation

Attach(const TDesC &, const TDesC &)

IMPORT_C TInt	Attach	(	const TDesC &	aDbFileName,
			const TDesC &	aDbName
		)

Parameters

const TDesC & aDbFileName
const TDesC & aDbName

Close()

IMPORT_C void

(

)

Compact(TInt64, const TDesC &)

IMPORT_C TInt	Compact	(	TInt64	aSize,
			const TDesC &	aDbName = KNullDesC
		)

Parameters

TInt64 aSize
const TDesC & aDbName = KNullDesC

Compact(TInt64, TRequestStatus &, const TDesC &)

IMPORT_C void	Compact	(	TInt64	aSize,
			TRequestStatus &	aStatus,
			const TDesC &	aDbName = KNullDesC
		)

Parameters

TInt64 aSize
TRequestStatus & aStatus
const TDesC & aDbName = KNullDesC

Copy(const TDesC &, const TDesC &)

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

Parameters

const TDesC & aSrcDbFileName
const TDesC & aDestDbFileName

Create(const TDesC &, const TDesC8 *)

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

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

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

IMPORT_C TInt	Create	(	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 void	CreateL	(	const TDesC &	aDbFileName,
			const TDesC8 *	aConfig = NULL
		)

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

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

IMPORT_C void	CreateL	(	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 TInt

IMPORT_C void	Exec	(	const TDesC &	aSqlStmt,
			TRequestStatus &	aStatus
		)

Parameters

const TDesC & aSqlStmt
TRequestStatus & aStatus

Exec(const TDesC8 &, TRequestStatus &)

IMPORT_C void	Exec	(	const TDesC8 &	aSqlStmt,
			TRequestStatus &	aStatus
		)

Parameters

const TDesC8 & aSqlStmt
TRequestStatus & aStatus

FreeReservedSpace()

IMPORT_C void

FreeReservedSpace

(

)

GetReserveAccess()

IMPORT_C TInt

GetReserveAccess

(

)

GetSecurityPolicy(RSqlSecurityPolicy &)

IMPORT_C TInt

GetSecurityPolicy

(

RSqlSecurityPolicy &

aSecurityPolicy

)

const

Parameters

RSqlSecurityPolicy & aSecurityPolicy

GetSecurityPolicyL(RSqlSecurityPolicy &)

IMPORT_C void

GetSecurityPolicyL

(

RSqlSecurityPolicy &

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

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

OpenL(const TDesC &, const TDesC8 *)

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

Parameters

const TDesC & aDbFileName
const TDesC8 * aConfig = NULL

Parameters

TIsolationLevel aIsolationLevel

Size()

IMPORT_C TInt

Size

(

)

const

Size(TSize &, const TDesC &)

IMPORT_C TInt	Size	(	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]