Main Page | Class List | File List | Class Members

RMimerCommand Class Reference

Use objects of this class to create and executes statements and queries. More...


Public Types
enum	TQueryOptions { EForwardOnly = 0x0, EScrollable = 0x1, ECloseAtCommit = 0x0, EHoldOverCommit = 0x2, EReadOnly = 0x0, EUpdatable = 0x4 }
	Result set options. These values are used to build a combined set of options for specifying the behavior of a RMimerResultSet object. More...
enum	TStatementType { EQuery = 1, ENonQuery = 2, EProcedure = 3 }
	An enumeration to help the application in determining the type the prepared statement. More...
Public Member Functions
IMPORT_C void	Cancel ()
	Cancels an ongoing server request.
IMPORT_C void	Close ()
	Closes this execution environment and releases any resources held by it.
IMPORT_C void	CreateL (RMimerDatabase &aMimerDb, const TDesC &aSQL, const enum TQueryOptions aQueryOptions=EForwardOnly)
	Creates a command object to be used for executing SQL statements.
IMPORT_C void	CreateL (RMimerDatabase &aMimerDb, const enum TQueryOptions aQueryOptions=EForwardOnly)
	Create a command object in a Mimer SQL database server.
IMPORT_C TBool	ExecuteL ()
	Executes a prepared statement.
IMPORT_C TInt	ExecuteNonQueryL ()
	Executes an SQL statement that does not returns a result set.
IMPORT_C RMimerParameterData	ExecuteProcedureL ()
	Executes a procedure call on the server.
IMPORT_C RMimerResultSet	ExecuteQueryL ()
	Executes an SQL statement that returns a result set.
IMPORT_C TInt	GetLastError ()
	Obtain error information about the last database operation.
IMPORT_C TInt	GetLastError (TDes &aErrorText)
	Obtain error information about the last database operation.
IMPORT_C RMimerMetaData	GetMetaDataL ()
	Obtains a meta data object describing a prepared statement.
IMPORT_C RMimerResultSet	GetResultSet ()
	Gets the result set returned by the last statement.
IMPORT_C TInt	GetUpdateCount ()
	Gets the update count of the last statement.
IMPORT_C int	PrepareL ()
	Prepares a statement for later execution.
IMPORT_C void	SetCommandTextL (const TDesC &aSQL)
	Sets the SQL command text to execute in future calls.
IMPORT_C void	SetParameterL (TInt aParNo, TDesC &aValue)
	Setting a parameter using a string descriptor value.
IMPORT_C void	SetParameterL (TInt aParNo, TUint aValue)
	Setting a parameter using a TUInt value.
IMPORT_C void	SetParameterL (TInt aParNo, TReal32 aValue)
	Setting a parameter using a TReal32 value.
IMPORT_C void	SetParameterL (TInt aParNo, TReal aValue)
	Setting a parameter using a TReal value.
IMPORT_C void	SetParameterL (TInt aParNo, TTime aValue)
	Setting a parameter using a TTime value.
IMPORT_C void	SetParameterL (TInt aParNo, TInt64 aValue)
	Setting a parameter using a TInt64 value.
IMPORT_C void	SetParameterL (TInt aParNo, TInt aValue)
	Setting a parameter using a TInt value.
Friends
class	RMimerMetaData
class	RMimerParameterData
class	RMimerResultSet

Detailed Description

Use objects of this class to create and executes statements and queries.

Each instance may be used to execute one or more SQL statements.

The life of a RMimerCommand handle is to be attached to a database connection using the #Create call. Once the handle is associated with a connection, statements may be defined and executed using SetCommandTextL. Applications may then execute statements by calling either #ExecuteQueryLC, ExecuteNonQueryL, or ExecuteL. Long running queries may be cancelled by calling the Cancel() method.

When an application does not need this object anymore, it is highly recommended to explicitly call the Close method as soon as possible. However, Close is automatically called by the object destructor.

Member Enumeration Documentation

enum RMimerCommand::TQueryOptions

Result set options. These values are used to build a combined set of options for specifying the behavior of a RMimerResultSet object.

Enumeration values:

EForwardOnly	A forward only result set.
EScrollable	A scrollable result set.
ECloseAtCommit	Cursors are closed at commit or rollback.
EHoldOverCommit	Cursors are held over commits and rollbacks.
EReadOnly	Result set is read only.
EUpdatable	Cursor is updatable.

enum RMimerCommand::TStatementType

An enumeration to help the application in determining the type the prepared statement.

Enumeration values:

EQuery	Represents a statement that returns a result set, including result set procedures.
ENonQuery	Represents a statement that does not return a result set and is not a procedure call.
EProcedure	Represents a call to procedure that does not return a result set.

Member Function Documentation

IMPORT_C void RMimerCommand::Cancel

(

)

Cancels an ongoing server request.

Although the cancel request returns immediately, the server is not guaranteed to have been cancelled. This method returns as soon as possible, and the database request may be cancelled at a later time.

IMPORT_C void RMimerCommand::Close

(

)

Closes this execution environment and releases any resources held by it.

This method is automatically called by the destructor.

IMPORT_C void RMimerCommand::CreateL	(	RMimerDatabase &	aMimerDb,
		const TDesC &	aSQL,
		const enum TQueryOptions	aQueryOptions = `EForwardOnly`
	)

Creates a command object to be used for executing SQL statements.

All RMimerCommand objects returned belongs to the database connection represented by this object, they will all participate in the same transaction.

Creating a command object using this method is shorthand for using #Create, SetCommandTextL, and the PrepareL. The below two code fragments brings the resulting command object to the same state:

 RMimerCommand command;
 _LIT(select_M_from_MIMER_ONEROW,"select M from MIMER.ONEROW");
 if (i_want_to_use_short_hand) {
   command.Create(database,select_M_from_MIMER_ONEROW);
 } else {
   command.Create();
   command.SetCommandText(select_M_from_MIMER_ONEROW);
   command.PrepareL();
 }
 // The <command> object is now in the same state no matter the value of <i_want_to_use_short_hand>.

Parameters:

aMimerDb

The Mimer database server in which to create the command object.

aSQL

The CommandText attribute of RMimerCommand will be preset to this SQL statement.

aQueryOptions

A bitmap specifying the characteristics of the query. The following may be combined using an logical OR to form a complete query option.

Cursor Scrollability:	0x0 - Forward only (EForwardOnly) 0x1 - Scrollable (EScrollable)
Cursor Holdability:	0x0 - Close at commit (ECloseAtCommit) 0x2 - Hold over commit (EHoldOverCommit)
Cursor Updatability:	0x0 - Read only (EReadOnly) 0x4 - Updatable (EUpdatable)

The default query option is a forward only, read only cursor that is closed at commit or rollback.

Returns:: An RMimerCommand object that may be used to execute queries and statements.

Note:: The return type of this method is under evaluation.

IMPORT_C void RMimerCommand::CreateL	(	RMimerDatabase &	aMimerDb,
		const enum TQueryOptions	aQueryOptions = `EForwardOnly`
	)

Create a command object in a Mimer SQL database server.

Command objects created

Parameters:

aMimerDb

The Mimer database server in which to create the command object.

aQueryOptions

A bitmap specifying the characteristics of the query. The following may be combined using an logical OR to form a complete query option.

Cursor Scrollability:	0x0 - Forward only (EForwardOnly) 0x1 - Scrollable (EScrollable)
Cursor Holdability:	0x0 - Close at commit (ECloseAtCommit) 0x2 - Hold over commit (EHoldOverCommit)
Cursor Updatability:	0x0 - Read only (EReadOnly) 0x4 - Updatable (EUpdatable)

The default query option is a forward only, read only cursor that is closed at commit or rollback.

IMPORT_C TBool RMimerCommand::ExecuteL

(

)

Executes a prepared statement.

Returns:: ETrue if the executed statement returned a result set, EFalse otherwise.

IMPORT_C TInt RMimerCommand::ExecuteNonQueryL

(

)

Executes an SQL statement that does not returns a result set.

This includes UPDATE, INSERT and DELETE statements, as well procedure calls and DDL statements. Stored statements of these types may also be executed using the EXECUTE STATEMENT call.

The object returned by this method is invalidated whenever PrepareL, #ExecuteQueryLC, #ExecuteProcedureLC or #ExecuteNoNQuery is called.

Returns:: Number of rows affected by the statement. An UPDATE returns the number of rows updated, a DELETE the number of rows deleted, and an INSERT returns the number of rows inserted. DDL statements always return 0.

Exceptions:

KErrMimerNoCommandText

if no command text has been supplied by calling SetCommandText.

IMPORT_C RMimerParameterData RMimerCommand::ExecuteProcedureL

(

)

Executes a procedure call on the server.

This call executes a procedure stored on the server. Upon return, a RMimerParameterData object is returned. Use this object to obtain values of output parameters.

The object returned by this method is invalidated whenever PrepareL, #ExecuteQueryLC, #ExecuteProcedureLC or #ExecuteNoNQuery is called.

Returns:: An object holding parameter output data.

IMPORT_C RMimerResultSet RMimerCommand::ExecuteQueryL

(

)

Executes an SQL statement that returns a result set.

This includes regular SELECT queries as well as procedure calls returning result sets.

Returns:: An RMimerResultSet object to be used to access the created result set.

Please keep in mind that a scrollable resultset may be expensive both in terms of processing time as well all memory consumption. Scrollable cursors are less expensive when the ordering of the result set is known in advance, such as through primary keys or indexes, and expensive when the ordering has to be established at execution time.

The object returned by this method is invalidated whenever PrepareL, #ExecuteQueryLC, #ExecuteProcedureLC or #ExecuteNoNQuery is called.

Note:: Cursor holdability and Cursor updatability are currently not implemented. All cursors are closed at commit and cursor may not be updated using

IMPORT_C TInt RMimerCommand::GetLastError

(

)

Obtain error information about the last database operation.

The error information is lost once another operation is performed on the database.

Returns:: The Mimer SQL error code. This error code is a negative number.

IMPORT_C TInt RMimerCommand::GetLastError

(

TDes &

aErrorText

)

Obtain error information about the last database operation.

The error information is lost once another operation is performed on the database.

Parameters:

aErrorText

A reference to a descriptor to hold a descriptive error message about the error. If this reference is a NULL pointer, no error text is obtained.

Returns:: The Mimer SQL error code. This error code is a negative number.

IMPORT_C RMimerMetaData RMimerCommand::GetMetaDataL

(

)

Obtains a meta data object describing a prepared statement.

Note:: Although this method returns a reference to an object

Returns:: A meta data object.

IMPORT_C RMimerResultSet RMimerCommand::GetResultSet

(

)

Gets the result set returned by the last statement.

Obtains the result set of the last executed statement. If the statement did not return a result set, a NULL pointer is returned.

Returns:: A handle to a result set object.

IMPORT_C TInt RMimerCommand::GetUpdateCount

(

)

Gets the update count of the last statement.

Obtains the update count of the last executed statement. This is the number of rows affected by INSERT, UPDATE or DELETE statements. If the statement was a query, 0 is returned.

Returns:: The update count.

IMPORT_C int RMimerCommand::PrepareL

(

)

Prepares a statement for later execution.

Preparing a statement in advance will offer the possibility both to supply parameters to the statement as well as reusing often used statements.

The below code snippet demonstrates how to supply parameters to a statement.

 RMimerCommand command;
 _LIT(insert_into_OUR_TABLE,"insert into OUR_TABLE values (?,?,?)");
 _LIT(a_string,"a sample string");
 command.Create(database);
 command.SetCommandTextL(insert_into_OUR_TABLE);
 command.PrepareL();
 command.SetParameterL(1,12);
 command.SetParameterL(2,a_string);
 command.SetParameterL(3,-7);
 RMimerResultSet resultset = command.ExecuteQueryL();

Returns:: A value of the enumeration according to the type of the statement.

IMPORT_C void RMimerCommand::SetCommandTextL

(

const TDesC &

aSQL

)

Sets the SQL command text to execute in future calls.

The command text may be set any number of times.

Parameters:

aSQL

The SQL command text.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TDesC &	aValue
	)

Setting a parameter using a string descriptor value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TUint	aValue
	)

Setting a parameter using a TUInt value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TReal32	aValue
	)

Setting a parameter using a TReal32 value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TReal	aValue
	)

Setting a parameter using a TReal value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TTime	aValue
	)

Setting a parameter using a TTime value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TInt64	aValue
	)

Setting a parameter using a TInt64 value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

IMPORT_C void RMimerCommand::SetParameterL	(	TInt	aParNo,
		TInt	aValue
	)

Setting a parameter using a TInt value.

Parameters:

	aParNo	The parameter number. First parameter is parameter number 1.
	aValue	The value to set.

RMimerCommand Class Reference

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation