sl@0: // Copyright (c) 2005-2010 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // sl@0: sl@0: #include "SqlStatementImpl.h" //CSqlStatementImpl sl@0: #include "OstTraceDefinitions.h" sl@0: #ifdef OST_TRACE_COMPILER_IN_USE sl@0: #include "SqlStatementTraces.h" sl@0: #endif sl@0: #include "SqlTraceDef.h" sl@0: sl@0: ///////////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Initialises the pointer to the implementation object to NULL. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C RSqlStatement::RSqlStatement() : sl@0: iImpl(NULL) sl@0: { sl@0: } sl@0: sl@0: /** sl@0: Prepares the supplied 16-bit SQL statement for execution. sl@0: sl@0: An RSqlStatement object can prepare and execute a parameterised SQL statement or sl@0: an SQL statement without parameters. sl@0: sl@0: The function can only deal with one SQL statement at a time, i.e. if you sl@0: supply more than one SQL statement, each separated by a ";" character, then sl@0: the function returns an error. sl@0: sl@0: Note that when the statement is to be used to retrieve or write blob or text data sl@0: that is over 2Mb in size then it is recommended that the RSqlBlobReadStream and sl@0: RSqlBlobWriteStream classes or the TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of reading and writing large sl@0: amounts of blob or text data from a database. sl@0: sl@0: @param aDatabase A reference to the RSqlDatabase object that represents sl@0: the database for which the SQL statement is being prepared. sl@0: @param aSqlStmt A string of 16-bit wide characters containing the sl@0: SQL statement to be prepared. sl@0: sl@0: @return KErrNone, the SQL statement has been prepared for execution successfully; sl@0: KErrNoMemory, an out of memory condition has occurred; sl@0: KErrArgument, the SQL statement is invalid, for example, the supplied sl@0: string contains more than one SQL statement, or it sl@0: contains an empty SQL statement. sl@0: Note that database specific errors categorised as ESqlDbError sl@0: can also be returned; sl@0: KSqlErrGeneral, a syntax error has occurred - text describing the problem sl@0: can be obtained by calling RSqlDatabase::LastErrorMessage(). sl@0: KErrPermissionDenied, the calling application does not satisfy the relevant database security policies. sl@0: Note that database specific errors categorised as ESqlDbError, and sl@0: other system-wide error codes may also be returned. sl@0: sl@0: @capability None, if current RSqlStatement object represents a handle which operates on a non-secure database; sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; sl@0: RSqlSecurityPolicy::EReadPolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; sl@0: RSqlSecurityPolicy::EWritePolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database; sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlDatabase sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: @see RSqlSecurityPolicy sl@0: @see RSqlSecurityPolicy::TPolicyType sl@0: @see RSqlBlobReadStream sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::Prepare(RSqlDatabase& aDatabase, const TDesC& aSqlStmt) sl@0: { sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE16_ENTRY, "Entry;0x%X;RSqlStatement::Prepare16;aDatabase=0x%X;aSqlStmt=%S", (TUint)this, (TUint)&aDatabase, __SQLPRNSTR(aSqlStmt))); sl@0: TInt err = CSqlStatementImpl::New(iImpl, aDatabase.Impl(), aSqlStmt); sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE16_EXIT, "Exit;0x%X;RSqlStatement::Prepare16;iImpl=0x%X;err=%d", (TUint)this, (TUint)iImpl, err)); sl@0: return err; sl@0: } sl@0: sl@0: /** sl@0: Prepares the supplied 8-bit SQL statement for execution. sl@0: sl@0: An RSqlStatement object can prepare and execute a parameterised SQL statement or sl@0: an SQL statement without parameters. sl@0: sl@0: The function can only deal with one SQL statement at a time, i.e. if you sl@0: supply more than one SQL statement, each separated by a ";" character, then sl@0: the function returns an error. sl@0: sl@0: Note that when the statement is to be used to retrieve or write blob or text data sl@0: that is over 2Mb in size then it is recommended that the RSqlBlobReadStream and sl@0: RSqlBlobWriteStream classes or the TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of reading and writing large sl@0: amounts of blob or text data from a database. sl@0: sl@0: @param aDatabase A reference to the RSqlDatabase object that represents sl@0: the database for which the SQL statement is being prepared. sl@0: @param aSqlStmt A string of 8-bit wide characters containing the sl@0: SQL statement to be prepared. sl@0: sl@0: sl@0: @return KErrNone, the SQL statement has been prepared for execution successfully; sl@0: KErrNoMemory, an out of memory condition has occurred; sl@0: KErrArgument, the SQL statement is invalid, for example, the supplied sl@0: string contains more than one SQL statement, or it sl@0: contains an empty SQL statement. sl@0: Note that database specific errors categorised as ESqlDbError sl@0: can also be returned; sl@0: KSqlErrGeneral, a syntax error has occurred - text describing the problem sl@0: can be obtained by calling RSqlDatabase::LastErrorMessage(). sl@0: KErrPermissionDenied, the calling application does not satisfy the relevant database security policies. sl@0: Note that database specific errors categorised as ESqlDbError, and sl@0: other system-wide error codes may also be returned. sl@0: sl@0: @capability None, if current RSqlStatement object represents a handle which operates on a non-secure database; sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; sl@0: RSqlSecurityPolicy::EReadPolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; sl@0: RSqlSecurityPolicy::EWritePolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database; sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlDatabase sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: @see RSqlSecurityPolicy sl@0: @see RSqlSecurityPolicy::TPolicyType sl@0: @see RSqlBlobReadStream sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::Prepare(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt) sl@0: { sl@0: __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf); sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE8_ENTRY, "Entry;0x%X;RSqlStatement::Prepare8;aDatabase=0x%X;aSqlStmt=%s", (TUint)this, (TUint)&aDatabase, __SQLPRNSTR8(aSqlStmt, des16prnbuf))); sl@0: TInt err = CSqlStatementImpl::New(iImpl, aDatabase.Impl(), aSqlStmt); sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE8_EXIT, "Exit;0x%X;RSqlStatement::Prepare8;iImpl=0x%X;err=%d", (TUint)this, (TUint)iImpl, err)); sl@0: return err; sl@0: } sl@0: sl@0: /** sl@0: Prepares the supplied 16-bit SQL statement for execution. sl@0: sl@0: An RSqlStatement object can prepare and execute a parameterised SQL statement or sl@0: an SQL statement without parameters. sl@0: sl@0: The function can only deal with one SQL statement at a time, i.e. if you sl@0: supply more than one SQL statement, each separated by a ";" character, then sl@0: the function returns an error. sl@0: sl@0: Note that when the statement is to be used to retrieve or write blob or text data sl@0: that is over 2Mb in size then it is recommended that the RSqlBlobReadStream and sl@0: RSqlBlobWriteStream classes or the TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of reading and writing large sl@0: amounts of blob or text data from a database. sl@0: sl@0: @param aDatabase A reference to the RSqlDatabase object that represents sl@0: the database for which the SQL statement is being prepared. sl@0: @param aSqlStmt A string of 16-bit wide characters containing the sl@0: SQL statement to be prepared. sl@0: sl@0: @leave KErrNoMemory, an out of memory condition has occurred; sl@0: KErrArgument, the SQL statement is invalid, for example, the supplied sl@0: string contains more than one SQL statement, or it sl@0: contains an empty SQL statement. sl@0: Note that database specific errors categorised as ESqlDbError sl@0: can also be returned; sl@0: KSqlErrGeneral, a syntax error has occurred - text describing the problem sl@0: can be obtained by calling RSqlDatabase::LastErrorMessage(). sl@0: KErrPermissionDenied, the calling application does not satisfy the relevant database security policies. sl@0: Note that the function may leave with database specific errors categorised as ESqlDbError and sl@0: other system-wide error codes. sl@0: sl@0: @capability None, if current RSqlStatement object represents a handle which operates on a non-secure database; sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; sl@0: RSqlSecurityPolicy::EReadPolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; sl@0: RSqlSecurityPolicy::EWritePolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database; sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlDatabase sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: @see RSqlSecurityPolicy sl@0: @see RSqlSecurityPolicy::TPolicyType sl@0: @see RSqlBlobReadStream sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: */ sl@0: EXPORT_C void RSqlStatement::PrepareL(RSqlDatabase& aDatabase, const TDesC& aSqlStmt) sl@0: { sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE16L_ENTRY, "Entry;0x%X;RSqlStatement::Prepare16L;aDatabase=0x%X;aSqlStmt=%S", (TUint)this, (TUint)&aDatabase, __SQLPRNSTR(aSqlStmt))); sl@0: __SQLLEAVE_IF_ERROR(Prepare(aDatabase, aSqlStmt)); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_PREPARE16L_EXIT, "Exit;0x%X;RSqlStatement::Prepare16L;iImpl=0x%X", (TUint)this, (TUint)iImpl)); sl@0: } sl@0: sl@0: /** sl@0: Prepares the supplied 8-bit SQL statement for execution. sl@0: sl@0: An RSqlStatement object can prepare and execute a parameterised SQL statement or sl@0: an SQL statement without parameters. sl@0: sl@0: The function can only deal with one SQL statement at a time, i.e. if you sl@0: supply more than one SQL statement, each separated by a ";" character, then sl@0: the function returns an error. sl@0: sl@0: Note that when the statement is to be used to retrieve or write blob or text data sl@0: that is over 2Mb in size then it is recommended that the RSqlBlobReadStream and sl@0: RSqlBlobWriteStream classes or the TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of reading and writing large sl@0: amounts of blob or text data from a database. sl@0: sl@0: @param aDatabase A reference to the RSqlDatabase object that represents sl@0: the database for which the SQL statement is being prepared. sl@0: @param aSqlStmt A string of 8-bit wide characters containing the sl@0: SQL statement to be prepared. sl@0: sl@0: sl@0: @leave KErrNoMemory, an out of memory condition has occurred; sl@0: KErrArgument, the SQL statement is invalid, for example, the supplied sl@0: string contains more than one SQL statement, or it sl@0: contains an empty SQL statement. sl@0: Note that database specific errors categorised as ESqlDbError sl@0: can also be returned; sl@0: KSqlErrGeneral, a syntax error has occurred - text describing the problem sl@0: can be obtained by calling RSqlDatabase::LastErrorMessage(). sl@0: KErrPermissionDenied, the calling application does not satisfy the relevant database security policies. sl@0: Note that the function may leave with database specific errors categorised as ESqlDbError and sl@0: other system-wide error codes. sl@0: sl@0: @capability None, if current RSqlStatement object represents a handle which operates on a non-secure database; sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement modifies a secure database schema; sl@0: RSqlSecurityPolicy::EReadPolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement reads from a secure database; sl@0: RSqlSecurityPolicy::EWritePolicy or sl@0: RSqlSecurityPolicy::ESchemaPolicy database policy type, if the SQL statement writes to a secure database; sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlDatabase sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: @see RSqlSecurityPolicy sl@0: @see RSqlSecurityPolicy::TPolicyType sl@0: @see RSqlBlobReadStream sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: */ sl@0: EXPORT_C void RSqlStatement::PrepareL(RSqlDatabase& aDatabase, const TDesC8& aSqlStmt) sl@0: { sl@0: __SQLTRACE_BORDERVAR(TBuf<100> des16prnbuf); sl@0: SQL_TRACE_BORDER(OstTraceExt3(TRACE_BORDER, RSQLSTATEMENT_PREPARE8L_ENTRY, "Entry;0x%X;RSqlStatement::Prepare8L;aDatabase=0x%X;aSqlStmt=%s", (TUint)this, (TUint)&aDatabase, __SQLPRNSTR8(aSqlStmt, des16prnbuf))); sl@0: __SQLLEAVE_IF_ERROR(Prepare(aDatabase, aSqlStmt)); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_PREPARE8L_EXIT, "Exit;0x%X;RSqlStatement::Prepare8L;iImpl=0x%X", (TUint)this, (TUint)iImpl)); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Closes this SQL statement object. sl@0: sl@0: The function frees memory and any allocated resources. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C void RSqlStatement::Close() sl@0: { sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_CLOSE_ENTRY, "Entry;0x%X;RSqlStatement::Close;iImpl=0x%X", (TUint)this, (TUint)iImpl)); sl@0: delete iImpl; sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_CLOSE_EXIT, "Exit;0x%X;RSqlStatement::Close;iImpl=0x%X", (TUint)this, (TUint)iImpl)); sl@0: iImpl = NULL; sl@0: } sl@0: sl@0: /** sl@0: Tests whether the SQL statement points to a valid record. sl@0: sl@0: @return True, if the SQL statement points to a valid record, false otherwise. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TBool RSqlStatement::AtRow() const sl@0: { sl@0: return Impl().AtRow(); sl@0: } sl@0: sl@0: /** sl@0: Resets the prepared SQL statement to its initial state and makes it ready to be sl@0: executed again. sl@0: sl@0: Any SQL statement parameters that had values bound to them, retain their values. sl@0: sl@0: If this object processes a parameterised SQL statement, then the parameter sl@0: values can be bound after the call to Reset(). sl@0: sl@0: If the call to this function fails because of a database-specific type error sl@0: (i.e. the error is categorised as of type ESqlDbError), then a textual description of sl@0: the error can be obtained calling RSqlDatabase::LastErrorMessage(). sl@0: sl@0: sl@0: Usage pattern 1: sl@0: sl@0: @code sl@0: RSqlStatement stmt; sl@0: TInt err = stmt.Prepare(, ); sl@0: while() sl@0: { sl@0: err = stmt.Bind(, ); sl@0: ... sl@0: err = stmt.Exec(); sl@0: .... sl@0: err = stmt.Reset(); sl@0: } sl@0: stmt.Close(); sl@0: @endcode sl@0: sl@0: Usage pattern 2: sl@0: sl@0: @code sl@0: RSqlStatement stmt; sl@0: TInt err = stmt.Prepare(, ); sl@0: while() sl@0: { sl@0: err = stmt.Bind(, ); sl@0: ... sl@0: while((err = stmt.Next()) == KSqlAtRow) sl@0: { sl@0: .... sl@0: } sl@0: err = stmt.Reset(); sl@0: } sl@0: stmt.Close(); sl@0: @endcode sl@0: sl@0: @return KErrNone, the reset operation has completed successfully; sl@0: KSqlErrStmtExpired, the SQL statement has expired (if new functions or sl@0: collating sequences have been registered or if an sl@0: authorizer function has been added or changed) sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::Reset() sl@0: { sl@0: SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLSTATEMENT_RESET_ENTRY, "Entry;0x%X;RSqlStatement::Reset", (TUint)this)); sl@0: TInt err = Impl().Reset(); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_RESET_EXIT, "Exit;0x%X;RSqlStatement::Reset;err=%d", (TUint)this, err)); sl@0: return err; sl@0: } sl@0: sl@0: /** sl@0: Executes the prepared DDL/DML SQL statement. sl@0: sl@0: The function is very useful when the SQL statement contains parameters, because sl@0: the statement can be prepared once using RSqlStatement::Prepare(), and then sl@0: bound and executed many times. sl@0: sl@0: Note that: sl@0: - parameter values must be bound before calling Exec(). sl@0: - SQL statements that do not have parameters should use RSqlDatabase::Exec() instead. sl@0: sl@0: If the call to this function fails because of a database-specific type error sl@0: (i.e. the error is categorised as of type ESqlDbError), then a textual description of sl@0: the error can be obtained calling RSqlDatabase::LastErrorMessage(). sl@0: sl@0: Usage pattern: sl@0: sl@0: @code sl@0: RSqlStatement stmt; sl@0: TInt err = stmt.Prepare(, ); sl@0: while() sl@0: { sl@0: err = stmt.Bind(, ); sl@0: ... sl@0: err = stmt.Exec(); sl@0: .... sl@0: err = stmt.Reset(); sl@0: } sl@0: stmt.Close(); sl@0: @endcode sl@0: sl@0: @return >=0, The operation has completed successfully. The number of database rows that were sl@0: changed/inserted/deleted by the most recently completed DDL/DML sql statement. sl@0: Exception: If the executed statement is "DELETE FROM ", then the function returns 0 sl@0: if the operation has completed successfully (disregarding the number of the deleted rows); sl@0: KSqlErrStmtExpired, the SQL statement has expired (if new functions or sl@0: collating sequences have been registered or if an sl@0: authorizer function has been added or changed); sl@0: KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE sl@0: statement, try to use the reserved disk space (if there is a reserved disk space) to complete the operation. sl@0: In all other cases the statement and database connection should be closed and some disk space freed sl@0: before reopening the database; sl@0: KErrNoMemory, an out of memory condition has occurred - the statement sl@0: will be reset. sl@0: Note that database specific errors categorised as ESqlDbError sl@0: can also be returned. sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlDatabase::Exec() sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::Exec() sl@0: { sl@0: SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLSTATEMENT_EXEC_ENTRY, "Entry;0x%X;RSqlStatement::Exec", (TUint)this)); sl@0: TInt err = Impl().Exec(); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_EXEC_EXIT, "Exit;0x%X;RSqlStatement::Exec;err=%d", (TUint)this, err)); sl@0: return err; sl@0: } sl@0: sl@0: /** sl@0: Executes the prepared DDL/DML SQL statement asynchronously to allow client to avoid being blocked sl@0: by server activity. sl@0: sl@0: No other operations can be performed on current RSqlStatement object sl@0: until the asynchronous operation completes. sl@0: sl@0: The function is very useful when the SQL statement contains parameters, because sl@0: the statement can be prepared once using RSqlStatement::Prepare(), and then sl@0: bound and executed many times. sl@0: sl@0: Note that: sl@0: - parameter values must be bound before calling Exec(). sl@0: - SQL statements that do not have parameters should use RSqlDatabase::Exec() instead. sl@0: sl@0: If the call to this function fails because of a database-specific type error sl@0: (i.e. the error is categorised as of type ESqlDbError), then a textual description of sl@0: the error can be obtained calling RSqlDatabase::LastErrorMessage(). sl@0: sl@0: @param aStatus Completion status of asynchronous request, one of the following: sl@0: >=0, The operation has completed successfully. The number of database rows that were sl@0: changed/inserted/deleted by the most recently completed DDL/DML sql statement. sl@0: Exception: If the executed statement is "DELETE FROM
", then the function returns 0 sl@0: if the operation has completed successfully (disregarding the number of the deleted rows); sl@0: KSqlErrStmtExpired, the SQL statement has expired (if new functions or sl@0: collating sequences have been registered or if an sl@0: authorizer function has been added or changed); sl@0: KErrDiskFull, There is no available disk space to complete the operation. If the executed statement is a DELETE sl@0: statement, try to use the reserved disk space (if there is a reserved disk space) sl@0: to complete the operation. sl@0: In all other cases the statement and database connection should be closed and some disk space freed sl@0: before reopening the database; sl@0: KErrNoMemory, an out of memory condition has occurred - the statement sl@0: will be reset. sl@0: Note that aStatus may be set with database specific errors categorised as ESqlDbError, sl@0: and other system-wide error codes. sl@0: sl@0: sl@0: @see TSqlRetCodeClass::ESqlDbError sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlDatabase::Exec() sl@0: @see RSqlDatabase::LastErrorMessage() sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C void RSqlStatement::Exec(TRequestStatus& aStatus) sl@0: { sl@0: SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLSTATEMENT_EXECASYNC_ENTRY, "Entry;0x%X;RSqlStatement::ExecAsync", (TUint)this)); sl@0: Impl().Exec(aStatus); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_EXECASYNC_EXIT, "Exit;0x%X;RSqlStatement::ExecAsync;aStatus.Int()=%d", (TUint)this, aStatus.Int())); sl@0: } sl@0: sl@0: /** sl@0: Retrieves a record. sl@0: sl@0: If the prepared SQL statement is a "SELECT" statement, and is expected to sl@0: return a set of records, then this function can be used to retrieve that record data. sl@0: sl@0: If the SQL statement contains parameters, then their values must be bound before sl@0: this function is called. sl@0: sl@0: If the call to this function completes successfully, i.e. it returns sl@0: with KSqlAtRow, then this RSqlStatement object contains the record data, and sl@0: this data will remain valid for access until another call is made to any sl@0: RSqlStatement function. sl@0: sl@0: The record data can be accessed using the following functions: sl@0: - RSqlStatement::ColumnType() sl@0: - RSqlStatement::ColumnSize() sl@0: - RSqlStatement::ColumnInt() sl@0: - RSqlStatement::ColumnInt64() sl@0: - RSqlStatement::ColumnReal() sl@0: - RSqlStatement::ColumnTextL() sl@0: - RSqlStatement::ColumnText() sl@0: - RSqlStatement::ColumnBinary() sl@0: - RSqlStatement::ColumnBinaryL() sl@0: sl@0: Note that if this call to Next() fails, as indicated by a return code value sl@0: other than KSqlAtRow, then calls to these RSqlStatement::Column...() functions sl@0: will raise a panic. sl@0: sl@0: @return KSqlAtRow, the record data is ready for processing by the caller; sl@0: KSqlAtEnd, there is no more record data; sl@0: KSqlErrBusy, the database file is locked; sl@0: KErrNoMemory, an out of memory condition has occurred - the statement sl@0: will be reset; sl@0: KSqlErrGeneral, a run-time error has occured - this function must not sl@0: be called again; sl@0: KSqlErrMisuse, this function has been called after a previous call sl@0: returned KSqlAtEnd or KSqlErrGeneral. sl@0: KSqlErrStmtExpired, the SQL statement has expired (if new functions or sl@0: collating sequences have been registered or if an sl@0: authorizer function has been added or changed); sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::Next() sl@0: { sl@0: SQL_TRACE_BORDER(OstTrace1(TRACE_BORDER, RSQLSTATEMENT_NEXT_ENTRY, "Entry;0x%X;RSqlStatement::Next", (TUint)this)); sl@0: TInt err = Impl().Next(); sl@0: SQL_TRACE_BORDER(OstTraceExt2(TRACE_BORDER, RSQLSTATEMENT_NEXT_EXIT, "Exit;0x%X;RSqlStatement::Next;err=%d", (TUint)this, err)); sl@0: return err; sl@0: } sl@0: sl@0: /** sl@0: Gets the index (starting from 0) of the parameter with the given name. sl@0: sl@0: The function does a case insensitive parameter name search. sl@0: sl@0: For example, if the parameter name is ":Prm", then the ":" prefix cannot sl@0: be omitted when you call ParameterIndex(). sl@0: sl@0: This function can be called at any time after the SQL statement has been prepared. sl@0: sl@0: @param aParameterName The parameter name. sl@0: sl@0: @return the parameter index value, if successful - this is a non-negative integer value; sl@0: KErrNotFound, if no such parameter can be found. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ParameterIndex(const TDesC& aParameterName) const sl@0: { sl@0: return Impl().ParamIndex(aParameterName); sl@0: } sl@0: sl@0: /** sl@0: Gets the number of columns that are to be returned by this SQL statement. sl@0: sl@0: This function can be called at any time after the SQL statement has been prepared, sl@0: but it is useful only for SELECT statements. The column count of any other type of statement is always 0. sl@0: sl@0: @return The number of columns. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnCount() const sl@0: { sl@0: return Impl().ColumnCount(); sl@0: } sl@0: sl@0: /** sl@0: Gets the index (starting from 0) of the column with the given name. sl@0: sl@0: The function does a case insensitive column name search. sl@0: sl@0: This function can be called at any time after the SQL statement has been prepared. sl@0: sl@0: @param aColumnName The column name. sl@0: sl@0: @return the column index value, if successful - this is a non-negative integer value; sl@0: KErrNotFound, if no such parameter can be found. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnIndex(const TDesC& aColumnName) const sl@0: { sl@0: return Impl().ColumnIndex(aColumnName); sl@0: } sl@0: sl@0: /** sl@0: Gets the runtime type of the column identified by the specified column index. sl@0: sl@0: This function returns the actual runtime datatype of the specified column as sl@0: opposed to its declared type. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return The column type. sl@0: sl@0: @see KSqlAtRow sl@0: @see TSqlColumnType sl@0: @see RSqlStatement::DeclaredColumnType() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlStatement::ColumnIndex() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TSqlColumnType RSqlStatement::ColumnType(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnType(aColumnIndex); sl@0: } sl@0: sl@0: /** sl@0: Gets the declared type of the column identified by the specified column index. sl@0: sl@0: Note that the function can only be called when executing a SELECT query, and sl@0: only after a successful call to Prepare(). sl@0: sl@0: This function returns the datatype that the specified column was originally declared to have. sl@0: sl@0: The declared type of a column is determined according to the following rules: sl@0: @code sl@0: - if the column type name contains the string "INT", then the declared column type is ESqlInt; sl@0: - if the column type name contains any of the strings "CHAR, "TEXT" or "CLOB", then the declared column type is ESqlText; sl@0: - if the column type name contains any of the strings "BLOB" or "BINARY", then the declared column type is ESqlBinary; sl@0: - if the column type name contains any of the strings "FLOAT", "REAL" or "DOUBLE", then the declared column type is ESqlReal; sl@0: - in all other cases the declared column type is assumed to be ESqlInt; sl@0: @endcode sl@0: sl@0: @param aColumnIndex The index value identifying the column. This is 0 for the first column. sl@0: @param aColumnType Output parameter. If the call completes successfully, aColumnType contains the type of the column, one of sl@0: TSqlColumnType enum item values. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see TSqlColumnType sl@0: @see RSqlStatement::ColumnType() sl@0: @see RSqlStatement::ColumnIndex() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::DeclaredColumnType(TInt aColumnIndex, TSqlColumnType& aColumnType) const sl@0: { sl@0: return Impl().DeclaredColumnType(aColumnIndex, aColumnType); sl@0: } sl@0: sl@0: sl@0: sl@0: /** sl@0: Gets the length of the data for the column identified by the specified column index. sl@0: sl@0: The length depends on the column type and is normally in bytes, except for sl@0: the case where the column type is ESqlText, in which case the function returns sl@0: the number of characters. sl@0: sl@0: In detail, the following table shows the size associated with a column type. sl@0: Note that column types are identified by TSqlColumnType enum values. sl@0: @code sl@0: -------------------------------------------------------------- sl@0: | Column type | Column Size sl@0: -------------------------------------------------------------- sl@0: | ESqlInt.....|.4 sl@0: | ESqlInt64...|.8 sl@0: | ESqlReal....|.8 sl@0: | ESqlText....|.the number of characters in the unicode string sl@0: | ESqlBinary..|.the byte length of the binary data sl@0: | ESqlNull....|.0 sl@0: -------------------------------------------------------------- sl@0: @endcode sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The column index value; this is 0 for the first column. sl@0: sl@0: @return The size of the column, and depends on the type of column. sl@0: sl@0: @see KSqlAtRow sl@0: @see TSqlColumnType sl@0: @see RSqlStatement::Next() sl@0: @see RSqlStatement::ColumnIndex() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnSize(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnSize(aColumnIndex); sl@0: } sl@0: sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: /////////////////////////// Bind() implemenations ///////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Sets the parameter to a NULL value. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindNull(TInt aParamIndex) sl@0: { sl@0: return Impl().BindNull(aParamIndex); sl@0: } sl@0: sl@0: /** sl@0: Sets the parameter to the specified 32-bit integer value. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aParamValue The 32-bit integer value to be assigned to the parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindInt(TInt aParamIndex, TInt aParamValue) sl@0: { sl@0: return Impl().BindInt(aParamIndex, aParamValue); sl@0: } sl@0: sl@0: /** sl@0: Sets the parameter to the specified 64-bit integer value. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aParamValue The 64-bit integer value to be assigned to the parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindInt64(TInt aParamIndex, TInt64 aParamValue) sl@0: { sl@0: return Impl().BindInt64(aParamIndex, aParamValue); sl@0: } sl@0: sl@0: /** sl@0: Sets the parameter to the specified 64-bit floating point value. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aParamValue The 64-bit floating point value to be assigned to the parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindReal(TInt aParamIndex, TReal aParamValue) sl@0: { sl@0: return Impl().BindReal(aParamIndex, aParamValue); sl@0: } sl@0: sl@0: /** sl@0: Sets the parameter to the specified 16-bit descriptor. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: Note that when the text data to be bound is over 2Mb in size then sl@0: use of the RSqlBlobWriteStream or TSqlBlob class should be considered instead. sl@0: sl@0: These classes provide a more RAM-efficient way of writing large amounts of sl@0: text data to a database, however no conversions are performed on the text data - sl@0: it is simply stored as a stream of bytes. If the text data is part of a record sl@0: to be inserted into a database then BindZeroBlob() should be called on the sl@0: INSERT statement to create a placeholder for the text data, whose content sl@0: can then be written using the above classes. sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aParamText The 16-bit descriptor whose content is to be assigned to the parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlStatement::Exec() sl@0: @see RSqlStatement::BindZeroBlob() sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindText(TInt aParamIndex, const TDesC& aParamText) sl@0: { sl@0: return Impl().BindText(aParamIndex, aParamText); sl@0: } sl@0: sl@0: /** sl@0: Sets the parameter to the specified 8-bit descriptor. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: Note that when the binary data to be bound is over 2Mb in size then it is sl@0: recommended that the RSqlBlobWriteStream or TSqlBlob class is used instead. sl@0: sl@0: These classes provide a more RAM-efficient way of writing large amounts of sl@0: binary data to a database. If the binary data is part of a record to be inserted sl@0: into a database then BindZeroBlob() should be called on the INSERT statement to create sl@0: a placeholder for the binary data, whose content can then be written using the above classes. sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aParamData The 8-bit descriptor whose content is to be assigned to the parameter. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlStatement::Exec() sl@0: @see RSqlStatement::BindZeroBlob() sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindBinary(TInt aParamIndex, const TDesC8& aParamData) sl@0: { sl@0: return Impl().BindBinary(aParamIndex, aParamData); sl@0: } sl@0: sl@0: /** sl@0: Binds a blob of length aBlobSize bytes that is filled with zeroes. sl@0: sl@0: The parameter is identified by the specified index value. sl@0: sl@0: A parameter value can be set: sl@0: - immediately after this SQL statement has been prepared sl@0: - after a call to Reset() sl@0: sl@0: A zeroblob acts as a placeholder for a blob whose binary content is later written sl@0: using the RSqlBlobWriteStream or TSqlBlob class. sl@0: sl@0: Using zeroblobs provides a much more RAM-efficient way of creating large blobs than sl@0: including the blob data in the INSERT statement and it is recommended for blobs that sl@0: are over 2Mb in size. sl@0: sl@0: Note that a zeroblob should be created in a column after which there are no columns sl@0: that contain anything other than zeroblobs or NULLs, otherwise the zeroblob must be sl@0: allocated in full in RAM and its benefit is lost. sl@0: sl@0: When creating a zeroblob it is recommended, where possible, to create the zeroblob sl@0: and then write the blob content (using the RSqlBlobWriteStream or TSqlBlob class) sl@0: within the same transaction. Otherwise the zeroblob will have to be journalled sl@0: before being written to. sl@0: sl@0: @param aParamIndex The index value identifying the parameter; this is 0 for the first parameter. sl@0: @param aBlobSize The size in bytes of the blob. sl@0: sl@0: @return KErrNone, the operation completed successfully; sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: One of the other system-wide error codes may also be returned. sl@0: sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Reset() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlStatement::Exec() sl@0: @see RSqlBlobWriteStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Parameter index out of bounds. sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::BindZeroBlob(TInt aParamIndex, TInt aBlobSize) sl@0: { sl@0: return Impl().BindZeroBlob(aParamIndex, aBlobSize); sl@0: } sl@0: sl@0: sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: /////////////////////////// Column() implemenations /////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Tests whether the value of the specified column is NULL. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return True, if the value of the column is NULL, false otherwise. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TBool RSqlStatement::IsNull(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnType(aColumnIndex) == ESqlNull; sl@0: } sl@0: sl@0: /** sl@0: Gets the value of the column as a 32-bit integer. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return The value of the column as a 32-bit integer. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnInt(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnInt(aColumnIndex); sl@0: } sl@0: sl@0: /** sl@0: Gets the value of the column as a 64-bit integer. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return The value of the column as a 64-bit integer. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt64 RSqlStatement::ColumnInt64(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnInt64(aColumnIndex); sl@0: } sl@0: sl@0: /** sl@0: Gets the value of the column as a 64-bit floating point value. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return The value of the column as a 64-bit floating point value. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TReal RSqlStatement::ColumnReal(TInt aColumnIndex) const sl@0: { sl@0: return Impl().ColumnReal(aColumnIndex); sl@0: } sl@0: sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: /////////////////////////// ColumnText () /////////////////////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Gets the value of the column as a 16-bit descriptor (leaves on failure). sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the text to be retrieved is over 2Mb in size then it is sl@0: recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of text data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return A non-modifiable pointer descriptor representing the 16-bit column text. sl@0: sl@0: @leave KErrNoMemory if the operation for retrieving the column value from the server sl@0: fails with an out of memory condition. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::ColumnText() sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TPtrC RSqlStatement::ColumnTextL(TInt aColumnIndex) const sl@0: { sl@0: TPtrC res; sl@0: __SQLLEAVE_IF_ERROR(Impl().ColumnText(aColumnIndex, res)); sl@0: return res; sl@0: } sl@0: sl@0: /** sl@0: Gets the value of the column as a 16-bit descriptor. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the text to be retrieved is over 2Mb in size then it is sl@0: recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of text data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: @param aPtr A non-modifiable pointer descriptor. On successful completion of this sl@0: function, the pointer descriptor represents the 16-bit column text. sl@0: The descriptor does not change if the function fails. sl@0: sl@0: @return KErrNone, if the function completes successfully, sl@0: otherwise one of the other system-wide error codes. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::ColumnTextL() sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnText(TInt aColumnIndex, TPtrC& aPtr) const sl@0: { sl@0: return Impl().ColumnText(aColumnIndex, aPtr); sl@0: } sl@0: sl@0: /** sl@0: Interprets the value of the column as a 16-bit descriptor, and copies the data sl@0: into a 16-bit modifiable descriptor supplied by the caller. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the text to be retrieved is over 2Mb in size then it is sl@0: recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of text data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: @param aDest A 16-bit modifiable descriptor into which the column data is to be copied. sl@0: sl@0: @return KErrNone, the operation has completed successfully; sl@0: KErrOverflow, the maximum length of the target descriptor supplied by sl@0: the caller (aDest) is less than the length of sl@0: the column text - the column data sl@0: is truncated to fit into the target descriptor. sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnText(TInt aColumnIndex, TDes& aDest) const sl@0: { sl@0: return Impl().ColumnText(aColumnIndex, aDest); sl@0: } sl@0: sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: /////////////////////////// ColumnBinary () ///////////////////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Gets the value of the column as an 8-bit descriptor (leaves on failure). sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the binary data to be retrieved is over 2Mb in size then it sl@0: is recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of binary data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: sl@0: @return A non-modifiable pointer descriptor representing the 8-bit column data. sl@0: sl@0: @leave KErrNoMemory if the operation for retrieving the column value from the server sl@0: fails with an out of memory condition. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::ColumnBinary() sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TPtrC8 RSqlStatement::ColumnBinaryL(TInt aColumnIndex) const sl@0: { sl@0: TPtrC8 res; sl@0: __SQLLEAVE_IF_ERROR(Impl().ColumnBinary(aColumnIndex, res)); sl@0: return res; sl@0: } sl@0: sl@0: /** sl@0: Gets the value of the column as an 8-bit descriptor. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the binary data to be retrieved is over 2Mb in size then it sl@0: is recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of binary data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: @param aPtr A non-modifiable pointer descriptor. On successful completion of this sl@0: function, the pointer descriptor represents the 8-bit column data. sl@0: The descriptor does not change if the function fails. sl@0: sl@0: @return KErrNone, if the function completes successfully, sl@0: otherwise one of the other system-wide error codes. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::ColumnBinaryL() sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnBinary(TInt aColumnIndex, TPtrC8& aPtr) const sl@0: { sl@0: return Impl().ColumnBinary(aColumnIndex, aPtr); sl@0: } sl@0: sl@0: /** sl@0: Interprets the value of the column as an 8-bit descriptor, and copies the data sl@0: into an 8-bit modifiable descriptor supplied by the caller. sl@0: sl@0: The column is identified by the specified index value. sl@0: sl@0: Note that the function can only be called after a successful call to Next(), sl@0: i.e. after a call to Next() that has completed with a KSqlAtRow return code. sl@0: Calling this function after an unsuccessful call to Next() raises a panic. sl@0: sl@0: Note that when the binary data to be retrieved is over 2Mb in size then it sl@0: is recommended that the RSqlBlobReadStream or TSqlBlob class is used instead. sl@0: These classes provide a more RAM-efficient way of retrieving large amounts sl@0: of binary data from a database. sl@0: sl@0: @param aColumnIndex The index value identifying the column; this is 0 for the first column. sl@0: @param aDest An 8-bit modifiable descriptor into which the column data is to be copied. sl@0: sl@0: @return KErrNone, the operation has completed successfully; sl@0: KErrOverflow, the maximum length of the target descriptor supplied by sl@0: the caller (aDest) is less than the length of sl@0: the column data - the column data sl@0: is truncated to fit into the target descriptor. sl@0: KErrNoMemory, an out of memory condition has occurred. sl@0: sl@0: @see KSqlAtRow sl@0: @see RSqlStatement::Prepare() sl@0: @see RSqlStatement::Next() sl@0: @see RSqlBlobReadStream sl@0: @see TSqlBlob sl@0: sl@0: @panic SqlDb 5 Column index out of bounds. sl@0: @panic SqlDb 11 Statement cursor not positioned on a row sl@0: sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnBinary(TInt aColumnIndex, TDes8& aDest) const sl@0: { sl@0: return Impl().ColumnBinary(aColumnIndex, aDest); sl@0: } sl@0: sl@0: /** sl@0: Obtain the name of a column after preparing a query. sl@0: sl@0: @param aColumnIndex Column index sl@0: @param aNameDest Descriptor which will be set to column name sl@0: @return KErrNone if successfull or one of the system-wide error codes on error sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ColumnName(TInt aColumnIndex, TPtrC& aNameDest) sl@0: { sl@0: return Impl().ColumnName(aColumnIndex, aNameDest); sl@0: } sl@0: sl@0: /** sl@0: Obtain the name of a parameter after preparing a DML query. sl@0: The parameter names are returned in exactly the same form as sl@0: supplied in SQL statement. For example, if the parameter name is ":Prm", sl@0: then the ":" prefix will not be omitted. sl@0: sl@0: This function can be called at any time after the DML SQL statement has been prepared. sl@0: sl@0: @param aParameterIndex Parameter index sl@0: @param aNameDest Descriptor which will be set to column name sl@0: @return KErrNone if successfull or one of the system-wide error codes on error sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ParameterName(TInt aParameterIndex, TPtrC& aNameDest) sl@0: { sl@0: return Impl().ParameterName(aParameterIndex, aNameDest); sl@0: } sl@0: sl@0: /** sl@0: Obtain the name of a parameter after preparing a DML query. sl@0: The parameter names are returned in exactly the same form as sl@0: supplied in SQL statement. For example, if the parameter name is ":Prm", sl@0: then the ":" prefix will not be omitted. sl@0: sl@0: ParamName has the same behaviour as ParameterName. It is provided to maintain sl@0: source compatibility with previous Symbian releases. sl@0: sl@0: This function can be called at any time after the DML SQL statement has sl@0: been prepared. sl@0: sl@0: @param aParameterIndex Parameter index sl@0: @param aNameDest Descriptor which will be set to parameter name sl@0: @return KErrNone if successful or one of the system-wide error codes on error sl@0: @capability None sl@0: */ sl@0: EXPORT_C TInt RSqlStatement::ParamName(TInt aParameterIndex, TPtrC& aNameDest) sl@0: { sl@0: return ParameterName(aParameterIndex, aNameDest); sl@0: } sl@0: sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: //////////////////////////////////////////////////////////////////////////////////////////////////////// sl@0: sl@0: /** sl@0: Returns a reference to the implementation object of RSqlStatement - CSqlStatementImpl. sl@0: sl@0: @panic SqlDb 2 The SQL statement has not been prepared, sl@0: i.e. Prepare() has not yet been called on this RSqlStatement object. sl@0: sl@0: @internalComponent sl@0: */ sl@0: CSqlStatementImpl& RSqlStatement::Impl() const sl@0: { sl@0: __ASSERT_ALWAYS(iImpl != NULL, __SQLPANIC(ESqlPanicInvalidObj)); sl@0: return *iImpl; sl@0: }