RSqlDatabase Class Reference

#include <sqldb.h>

Link against: sqldb.lib

class RSqlDatabase

Nested Classes and Structures

RSqlDatabase::TSize

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

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

Detailed Description

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.

Member Enumeration Documentation

Enum anonymous

If this value is used as an argument of RSqlDatabase::Compact() (aSize argument), then all free space will be removed

Enumerator	Value	Description
EMaxCompaction	-1

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

Enumerator	Value	Description
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. See also: 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; See also: 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; See also: 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; See also: TIsolationLevel RSqlDatabase::SetIsolationLevel()

Constructor & Destructor Documentation

RSqlDatabase ( )

IMPORT_C

RSqlDatabase

(

)

Initialises the pointer to the implementation object to NULL.

capability: None

Member Function Documentation

Attach ( const TDesC &, const TDesC & )

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

Attaches an existing database to the current database connection.

The attached database can be read, written or modified. One database can be attched multiple times to the same connection, using different logical database names. Tables in an attached database can be referred to using "database-name.table-name" syntax. If an attached table doesn't have a duplicate table name in the main database, it doesn't require a database name prefix.

Transactions involving multiple attached databases are atomic.

capability: None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

Parameter	Description
aDbFileName	The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the attached database.
aDbName	Logical database name. It must be unique (per database connection). This is the name which can be used for accessing tables in the attached database. The syntax is "database-name.table-name".

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrPermissionDenied, the caller does not satisfy the relevant database security policies; KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Close ( )

IMPORT_C void

(

)

Closes this handle to the database.

The function frees memory and any allocated resources.

You can reuse this object, but you must reinitialise it by calling RSqlDatabase::Create() or RSqlDatabase::Open().

capability: None

Compact ( TInt64, const TDesC & )

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

Compacts the database. This function should be used for databases that have been configured for a manual compaction during the database creation. The function has no effect if the database has been configured for an auto compaction. The function has no effect if the aSize argument value is zero. The function has no effect also if there aren't any free pages in the database file. If the database has been configured for a background compaction, then the function works as if the database has been configured for a manual compaction.

capability: None

Parameter	Description
aSize	Can be one of: RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages (if any exists) will be removed; Positive 32-bit signed integer value - the server will attempt to compact the database removing at most aSize bytes from the database file, rounded up to the nearest page count, e.g. request for removing 1 byte will remove one free page from the database;
aDbName	The attached database name or KNullDesC for the main database

Returns: Zero or positive integer - the operation has completed succesfully, the return value is the size of the removed free space in bytes, KErrArgument, Invalid aSize value; KErrBadName, Invalid (too long) attached database name; KSqlErrReadOnly, Read-only database; KSqlErrGeneral, There is no an attached database with aDbName name; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Compact ( TInt64, TRequestStatus &, const TDesC & )

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

Compacts the database asynchronously. This function should be used for databases that have been configured for a manual compaction during the database creation. The function has no effect if the database has been configured for an auto compaction. The function has no effect if the aSize argument value is zero. The function has no effect also if there aren't any free pages in the database file. If the database has been configured for a background compaction, then the function works as if the database has been configured for a manual compaction.

capability: None

Parameter	Description
aSize	Can be one of: RSqlDatabase::EMaxCompaction - requests a full database compaction. All free pages (if any exists) will be removed; Positive 32-bit signed integer value - the server will attempt to compact the database removing at most aSize bytes from the database file, rounded up to the nearest page count, e.g. request for removing 1 byte will remove one free page from the database;
aStatus	Completion status of asynchronous request, one of the following: Zero or positive integer - the operation has completed succesfully, the return value is the size of the removed free space in bytes, KErrArgument, Invalid aSize value; KErrBadName, Invalid (too long) attached database name; KSqlErrReadOnly, Read-only database; KSqlErrGeneral, There is no an attached database with aDbName name; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.
aDbName	The attached database name or KNullDesC for the main database

Copy ( const TDesC &, const TDesC & )

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

Copies a database file to the specified location.

Note that this is a static function, and its use is not restricted to any specific RSqlDatabase instance.

The allowed copying operations are:

secure to secure database. Only the application created the database is allowed to copy it.
non-secure to non-secure database. No restrictions apply to this operation.

capability: None

Note that if the source database is a secure database, only the application, which created the database, can copy it.

Parameter	Description
aSrcDbFileName	Source database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
aDestDbFileName	Destination database file name. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which performs the copying operation.

Returns: KErrNone, the operation completed has successfully; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrPermissionDenied, the SID of the calling application does not match the SID of source or destination database. Note that other system-wide error codes may also be returned.

Create ( const TDesC &, const TDesC8 * )

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

Creates a new shared non-secure or private secure database.

capability: None

Parameter	Description
aDbFileName	The full path name of the file that is to host the database.
aConfig	the configuration string "PARAM=VALUE;....". The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

Parameter

Description

aDbFileName

The full path name of the file that is to host the database.

aConfig

the configuration string "PARAM=VALUE;....". The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrArgument, the file name refers to a secure database, invalid configuration string, invalid parameter values in the configuration string. Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

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

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

Creates a new shared secure database.

capability: The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;

Parameter	Description
aDbFileName	The name of the file that is to host the database. The format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID.
aSecurityPolicy	The container for the security policies.
aConfig	the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrArgument, the file name does not refer to a secure database; KErrArgument, system table name found in the security policies (aSecurityPolicy), invalid configuration string, invalid parameter values in the configuration string; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

CreateL ( const TDesC &, const TDesC8 * )

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

Creates a new shared non-secure or private secure database.

leave: KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrArgument, the file name refers to a secure database, invalid configuration string, invalid parameter values in the configuration string. Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.

capability: None

Parameter	Description
aDbFileName	The full path name of the file that is to host the database.
aConfig	the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

Parameter

Description

aDbFileName

The full path name of the file that is to host the database.

aConfig

the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16"; compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

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

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

Creates a new shared secure database. compaction=value - where "value" is the desired compaction mode. "value" could be either "background", "synchronous" or "manual".

leave: KErrNoMemory, an out of memory condition has occurred; KErrArgument, the file name does not refer to a secure database; KErrArgument, system table name found in the security policies (aSecurityPolicy), invalid configuration string, invalid parameter values in the configuration string; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrAlreadyExists, the file already exists; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.

capability: The calling application must satisfy the database policy of RSqlSecurityPolicy::ESchemaPolicy type;

Parameter	Description
aDbFileName	The name of the file that is to host the database. The format of the name is <drive>:<[SID]database file name excluding the path>. "[SID]" refers to the application SID.
aSecurityPolicy	The container for the security policies.
aConfig	the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number; page_size=value - where "value" is the page size in bytes. The "page_size" parameter can accept the following values: 512, 1024, 2048, 4096, 8192, 16384, 32768; encoding=value - where "value" is the desired database encoding. "value" could be either "UTF-8" or "UTF-16";

Delete ( const TDesC & )

IMPORT_C TInt

Delete

(

const TDesC &

aDbFileName

)

[static]

Deletes the specified database file.

Note that this is a static function, and its use is not restricted to any specific RSqlDatabase instance.

capability: None

Note that if the database to be deleted is a secure database, only the application, which created the database, can delete it.

Parameter	Description
aDbFileName	The name of the database file. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a private or shared non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.

Returns: KErrNone, the operation has completed successfully; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the database file is in use; KErrNotFound, the database file cannot be found; KErrAccessDenied, access to the database file is denied (e.g. it might be a read-only file); KErrPermissionDenied, the SID of the calling application does not match the SID of the database; Note that other system-wide error codes may also be returned.

Detach ( const TDesC & )

IMPORT_C TInt

Detach

(

const TDesC &

aDbName

)

Detaches previously attached database.

capability: None

Parameter	Description
aDbName	Logical database name. The logical name of the database to be detached.

Returns: KErrNone, the operation completed has successfully; KErrNotFound, no attached database with aDbName name; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Exec ( const TDesC & )

IMPORT_C TInt

Exec

(

const TDesC &

aSqlStmt

)

Executes one or more 16-bit SQL statements.

This method should be used for executing DDL/DML statements, but note the following point:

if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class (RSqlDatabase) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

If the call to this function fails because of a database-specific type error (i.e. the error is categorised as of type ESqlDbError), then a textual description of the error can be obtained calling RSqlDatabase::LastErrorMessage().

capability: None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

Parameter	Description
aSqlStmt	A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

Returns: >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); KErrNoMemory, an out of memory condition has occured; KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation. In all other cases the database connection should be closed and some disk space freed before reopening the database; KErrPermissionDenied, the caller does not satisfy the relevant database security policies. Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Exec ( const TDesC8 & )

IMPORT_C TInt

Exec

(

const TDesC8 &

aSqlStmt

)

Executes one or more 8-bit SQL statements.

This method should be used for executing DDL/DML statements, but note the following point:

if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class (RSqlDatabase) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

If the call to this function fails because of a database-specific type error (i.e. the error is categorised as ESqlDbError), then a textual description of the error can be obtained calling RSqlDatabase::LastErrorMessage().

capability: None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

Parameter	Description
aSqlStmt	A string of 8-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

Returns: >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); KErrNoMemory, an out of memory condition has occured; KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation. In all other cases the database connection should be closed and some disk space freed before reopening the database; KErrPermissionDenied, the caller does not satisfy the relevant database security policies; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Exec ( const TDesC &, TRequestStatus & )

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

Executes one or more 16-bit SQL statements asynchronously to allow client to avoid being blocked by server activity.

No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it until the asynchronous operation completes.

This method should be used for executing DDL/DML statements, but note the following point:

if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class (RSqlDatabase) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

capability: None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

Parameter

Description

aSqlStmt

A string of 16-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

aStatus

Completion status of asynchronous request, one of the following: >=0, The operation has completed successfully. The number of database rows that were changed/inserted/deleted by the most recently completed DDL/DML sql statement. Exception: If the executed statement is "DELETE FROM <table>", then the function returns 0 if the operation has completed successfully (disregarding the number of the deleted rows); KErrNoMemory, an out of memory condition has occured; KSqlErrGeneral, a syntax error has occurred - text describing the problem can be obtained by calling RSqlDatabase::LastErrorMessage(); KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation. In all other cases the database connection should be closed and some disk space freed before reopening the database; KErrPermissionDenied, the caller does not satisfy the relevant database security policies; Note that aStatus may be set with database specific errors categorised as ESqlDbError, and other system-wide error codes.

Exec ( const TDesC8 &, TRequestStatus & )

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

Executes one or more 8-bit SQL statements asynchronously to allow client to avoid being blocked by server activity.

No other operations can be performed on current RSqlDatabase object and RSqlStatement objects using it until the asynchronous operation completes.

This method should be used for executing DDL/DML statements, but note the following point:

if an SQL statement contains one or more parameters, then the function will execute it, giving the parameters default NULL values.

This class (RSqlDatabase) does not offer functions for setting the parameter values. Use the RSqlStatement class instead.

capability: None, if current RSqlDatabase object represents a handle to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database;

Parameter

Description

aSqlStmt

A string of 8-bit wide characters containing one or more DDL/DML SQL statements; each statement is separated by a ';' character.

aStatus

FreeReservedSpace ( )

IMPORT_C void

FreeReservedSpace

(

)

Frees the reserved disk space.

GetReserveAccess ( )

IMPORT_C TInt

GetReserveAccess

(

)

Gives the client an access to the already reserved disk space.

Returns: KErrNone, The operation has completed succesfully; KErrNotFound, An attempt is made to get an access to a disk space, which is not reserved yet; KErrInUse, An access to the reserved space has already been given; Note that other system-wide error codes may also be returned.

GetSecurityPolicy ( RSqlSecurityPolicy & )

IMPORT_C TInt

GetSecurityPolicy

(

RSqlSecurityPolicy &

aSecurityPolicy

)

const

Initializes aSecurityPolicy output parameter with a copy of the database security policies. The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

Note that there may be no security policies in force for this database.

capability: None

Parameter	Description
aSecurityPolicy	Input/Output parameter, which will be initialized with the database security policies.

Returns: KErrNone, the operation has completed successfully; KErrNotSupported, the current database is not a secure database; KErrNoMemory, an out of memory condition has occurred;

GetSecurityPolicyL ( RSqlSecurityPolicy & )

IMPORT_C void

GetSecurityPolicyL

(

RSqlSecurityPolicy &

aSecurityPolicy

)

const

Initializes aSecurityPolicy output parameter with a copy of the database security policies. The caller is responsible for destroying the initialized aSecurityPolicy paramemter.

Note that there may be no security policies in force for this database.

leave: KErrNotSupported, the current database is not a secure database; KErrNoMemory, an out of memory condition has occurred;

capability: None

Parameter	Description
aSecurityPolicy	Input/Output parameter, which will be initialized with the database security policies.

InTransaction ( )

IMPORT_C TBool

InTransaction

(

)

const

Checks the database transaction state.

capability: None

Returns: True, if the database is in transaction, false otherwise.

LastErrorMessage ( )

IMPORT_C TPtrC

LastErrorMessage

(

)

const

Retrieves a reference to the textual description of the error returned by the most recent call to any of the functions:

Note that the function can only return a reference to text for database-specific type errors, i.e. those errors that are categorised as of type ESqlDbError.

capability: None

Returns: A non-modifiable pointer descriptor representing the most recent error message. Note that message may be NULL, i.e. the descriptor may have zero length.

LastInsertedRowId ( )

IMPORT_C TInt64

LastInsertedRowId

(

)

const

Returns the ROWID of the most recent successful INSERT into the database from this database connection.

capability: None

Returns: >0, the ROWID of the most recent successful INSERT into the database from this database connection; 0, if no successful INSERTs have ever occurred from this database connection <0, if one of the system-wide error codes is returned

Open ( const TDesC &, const TDesC8 * )

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

Opens an existing database, which can be:

 - shared non-secure;
 - shared secure;
 - private secure;

capability: None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

Parameter	Description
aDbFileName	The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
aConfig	the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number;

Returns: KErrNone, the operation has completed successfully; KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrArgument, invalid configuration string, invalid parameter values in the configuration string; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrPermissionDenied, the caller does not satisfy the relevant database security policies; KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

OpenL ( const TDesC &, const TDesC8 * )

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

Opens an existing database, which can be:

 - shared non-secure;
 - shared secure;
 - private secure;

leave: KErrNoMemory, an out of memory condition has occurred; KErrBadName, the file name is invalid - it has either a zero length or it is the name of a directory; KErrNotReady, the drive does not exist or is not ready; KErrInUse, the file is already open; KErrNotFound, database file not found; KErrArgument, invalid configuration string, invalid parameter values in the configuration string; KErrGeneral, missing or invalid security policies (if the database to be opened is a secure database); KErrPermissionDenied, the caller does not satisfy the relevant database security policies; KErrNotSupported, incompatible SQL security version (if the database to be opened is a secure database). Note that the function may leave with database specific errors categorised as ESqlDbError and other system-wide error codes.

capability: None, if aDbFileName refers to a non-secure database; RSqlSecurityPolicy::ESchemaPolicy or RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::EWritePolicy database policy type, if aDbFileName refers to a secure database;

Parameter	Description
aDbFileName	The name of the file that hosts the database. If this is a secure database, then the format of the name must be: <drive>:<[SID]database file name excluding the path>. If this is a non-secure database, then aDbFileName has to be the full database file name. "[SID]" refers to SID of the application which created the database.
aConfig	the configuration string "PARAM=VALUE;...." The following parameters can be set using the configuration string: cache_size=value - where "value" is the cache size in pages. "value" must be a positive integer number;

ReleaseReserveAccess ( )

IMPORT_C void

ReleaseReserveAccess

(

)

Releases the access to the reserved disk space.

ReserveDriveSpace ( TInt )

IMPORT_C TInt

ReserveDriveSpace

(

TInt

aSize

)

Reserves a predefined amount of disk space on the drive where the database file is.

At the moment the max possible amount, allowed by the file server, is reserved on the database file drive. Use this call to ensure that if your "delete records" transaction fails because of "out of disk space" circumstances, you can get an access to the already reserved disk space and complete your transaction successfully the second time.

There is no strong, 100% guarantee, that the reserved disk space will always help the client in "low memory" situations.

Returns: KErrNone, The operation has completed succesfully; KErrNoMemory, Out of memory condition has occured; KErrAlreadyExists, The space has already been reserved; Note that other system-wide error codes may also be returned.

SetIsolationLevel ( TIsolationLevel )

IMPORT_C TInt

SetIsolationLevel

(

TIsolationLevel

aIsolationLevel

)

Sets the transaction isolation level for the database.

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

Transaction isolation levels are defined by the values of the RSqlDatabase::TIsolationLevel enum.

The default isolation level is RSqlDatabase::ESerializable

Note that the isolation level is not a persistent property of the database. It is set to the default value, i.e. RSqlDatabase::ESerializable, whenever the database is created or opened.

Size ( )

IMPORT_C TInt

Size

(

)

const

Returns the database file size, in bytes.

capability: None

Returns: >= 0, the operation has completed successfully. The number is the size of the main database file; KErrNoMemory, an out of memory condition has occurred; KErrTooBig, the database is too big and the size cannot fit into 32-bit signed integer; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.

Size ( TSize &, const TDesC & )

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

Returns the database file size and free space, in bytes.

capability: None

Parameter	Description
aSize	An output parameter. If the call was successfull the aSize object will contain information about the database size and database free space.
aDbName	The attached database name or KNullDesC for the main database

Returns: KErrNone, The operation has completed succesfully; KErrBadName, Invalid (too long) attached database name; KSqlErrGeneral, There is no an attached database with aDbName name; Note that database specific errors categorised as ESqlDbError, and other system-wide error codes may also be returned.