NCBI C++ ToolKit
Classes | Public Types | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
CQuery Class Reference

Search Toolkit Book for CQuery

Object used to execute queries and stored procedures on the database server and retrieve result sets. More...

#include <dbapi/simple/sdbapi.hpp>

+ Collaboration diagram for CQuery:

Classes

class  CField
 Class representing value in result set or output parameter of stored procedure. More...
 
class  CRow
 A full row of result data. More...
 
class  CRowIterator
 Iterator class doing main navigation through result sets. More...
 

Public Types

enum  EAllowLog { eDisableLog , eEnableLog }
 Allow transaction log (general, to avoid using bools). More...
 
enum  EHowMuch { eThisResultSet , eAllResultSets }
 Whether to consider just the current result set or all result sets, in MultiSet mode. More...
 
typedef CRowIterator iterator
 
typedef CRowIterator const_iterator
 

Public Member Functions

 CQuery (void)
 Empty constructor of query object. More...
 
 ~CQuery (void)
 
 CQuery (const CQuery &q)
 Copying of query object from other one. More...
 
CQueryoperator= (const CQuery &q)
 
CQuerySetParameter (CTempString name, const string &value, ESDB_Type type=eSDB_String, ESP_ParamType param_type=eSP_In)
 Assign string value to the parameter. More...
 
CQuerySetParameter (CTempString name, const char *value, ESDB_Type type=eSDB_String, ESP_ParamType param_type=eSP_In)
 Assign string value to the parameter. More...
 
CQuerySetParameter (CTempString name, Int8 value, ESDB_Type type=eSDB_Int8, ESP_ParamType param_type=eSP_In)
 Assign 8-byte integer value to the parameter. More...
 
CQuerySetParameter (CTempString name, Int4 value, ESDB_Type type=eSDB_Int4, ESP_ParamType param_type=eSP_In)
 Assign 4-byte integer value to the parameter. More...
 
CQuerySetParameter (CTempString name, long value, ESDB_Type type=eSDB_Int4, ESP_ParamType param_type=eSP_In)
 
CQuerySetParameter (CTempString name, short value, ESDB_Type type=eSDB_Short, ESP_ParamType param_type=eSP_In)
 Assign short integer value to the parameter. More...
 
CQuerySetParameter (CTempString name, unsigned char value, ESDB_Type type=eSDB_Byte, ESP_ParamType param_type=eSP_In)
 Assign byte value to the parameter. More...
 
CQuerySetParameter (CTempString name, float value, ESDB_Type type=eSDB_Float, ESP_ParamType param_type=eSP_In)
 Assign float value to the parameter. More...
 
CQuerySetParameter (CTempString name, double value, ESDB_Type type=eSDB_Double, ESP_ParamType param_type=eSP_In)
 Assign double value to the parameter. More...
 
CQuerySetParameter (CTempString name, const CTime &value, ESDB_Type type=eSDB_DateTime, ESP_ParamType param_type=eSP_In)
 Assign CTime value to the parameter. More...
 
CQuerySetParameter (CTempString name, bool value, ESDB_Type type=eSDB_Bit, ESP_ParamType param_type=eSP_In)
 Assign bool value to the parameter. More...
 
CQuerySetNullParameter (CTempString name, ESDB_Type type, ESP_ParamType param_type=eSP_In)
 Assign null value to the parameter. More...
 
CQuerySetOutputParameter (CTempString name, ESDB_Type type)
 Declare an output-only parameter. More...
 
const CFieldGetParameter (CTempString name)
 Get value of the parameter. More...
 
CQueryClearParameter (CTempString name)
 Remove parameter with given name from parameter list. More...
 
CQueryClearParameters (void)
 Remove all parameters from parameter list. More...
 
CQuerySetSql (CTempString sql)
 Set current sql statement. More...
 
CQueryExecute (const CTimeout &timeout=CTimeout(CTimeout::eDefault))
 Explicitly execute sql statement. More...
 
CQueryExecuteSP (CTempString sp, const CTimeout &timeout=CTimeout(CTimeout::eDefault))
 Execute stored procedure with given name. More...
 
void Cancel (void)
 Cancel the current statement or procedure call. More...
 
int GetRowCount (void) const
 Get number of rows read after statement execution. More...
 
int GetStatus (void) const
 Get return status of stored procedure. More...
 
const list< string > & GetPrintOutput (void) const
 Get any PRINT output from the latest procedure call (or statement). More...
 
bool HasMoreResultSets (void)
 Check if any more result sets are available for reading. More...
 
void PurgeResults (void)
 Purge all remaining result sets; fill in all remaining parameter results. More...
 
void RequireRowCount (unsigned int n)
 Indicate precisely how many rows the active query should return. More...
 
void RequireRowCount (unsigned int min_rows, unsigned int max_rows)
 Indicate the minimum and maximum number of rows the active query should return. More...
 
void VerifyDone (EHowMuch how_much=eThisResultSet)
 Ensure that no unread rows or parameter results remain, and that the total number of rows satisfies any constraints specified by RequireRowCount. More...
 
unsigned int GetTotalColumns (void) const
 Get total number of columns in the current result set. More...
 
string GetColumnName (unsigned int col) const
 Get name of the column with given number in the current result set. More...
 
ESDB_Type GetColumnType (unsigned int col) const
 Get type of the column with given number in the current result set All columns are numbered starting with 1. More...
 
unsigned int GetResultSetNo (void) const
 Get number of currently active result set. More...
 
unsigned int GetRowNo (EHowMuch how_much=eAllResultSets) const
 Get row number currently active. More...
 
CQuerySingleSet (void)
 Convert this query to work like only one result set was returned effectively merging all result sets together. More...
 
CQueryMultiSet (void)
 Convert this query to not merge different result sets, i.e. More...
 
CRowIterator begin (void) const
 Start iterating through next result set. More...
 
CRowIterator end (void) const
 Get iterator pointing to the end of the current result set or to the end of all result sets (depending on the setting changed with SingleSet() and MultiSet()). More...
 
CRow GetTheOnlyRow (void)
 Provides the only row for the executed query. More...
 

Private Member Functions

 CQuery (CDatabaseImpl *db_impl)
 Create query object for given database object. More...
 

Private Attributes

CRef< CQueryImplm_Impl
 Query implementation object. More...
 

Friends

class CDatabase
 
CAutoTrans::CSubject DBAPI_MakeTrans (CQuery &query)
 (S)DBAPI_TRANSACTION glue for CQuery. More...
 

Detailed Description

Object used to execute queries and stored procedures on the database server and retrieve result sets.

Definition at line 231 of file sdbapi.hpp.

Member Typedef Documentation

◆ const_iterator

Definition at line 495 of file sdbapi.hpp.

◆ iterator

Definition at line 494 of file sdbapi.hpp.

Member Enumeration Documentation

◆ EAllowLog

Allow transaction log (general, to avoid using bools).

Enumerator
eDisableLog 

Disables log.

eEnableLog 

Enables log.

Definition at line 248 of file sdbapi.hpp.

◆ EHowMuch

Whether to consider just the current result set or all result sets, in MultiSet mode.

(In SingleSet mode, always consider all.)

Enumerator
eThisResultSet 
eAllResultSets 

Definition at line 662 of file sdbapi.hpp.

Constructor & Destructor Documentation

◆ CQuery() [1/3]

CQuery::CQuery ( void  )

Empty constructor of query object.

Object created this way cannot be used for anything except assigning from the other query object.

Definition at line 3881 of file sdbapi.cpp.

◆ ~CQuery()

CQuery::~CQuery ( void  )

Definition at line 3893 of file sdbapi.cpp.

◆ CQuery() [2/3]

CQuery::CQuery ( const CQuery q)

Copying of query object from other one.

The copy of query object behaves with the same internal result set as the original object. So that if you increment iterator created from one object it will move to the next row in another query object too.

Definition at line 3889 of file sdbapi.cpp.

◆ CQuery() [3/3]

CQuery::CQuery ( CDatabaseImpl db_impl)
private

Create query object for given database object.

Definition at line 3884 of file sdbapi.cpp.

References m_Impl, and CRef< C, Locker >::Reset().

Member Function Documentation

◆ begin()

CQuery::CRowIterator CQuery::begin ( void  ) const

Start iterating through next result set.

If a query was supplied but not explicitly executed, automatically execute it before proceeding. If iteration was already in progress, purge the remainder of the current result set and advance to the next, if there is one.

Definition at line 4183 of file sdbapi.cpp.

References CQueryImpl::BeginNewRS(), CRef< C, Locker >::GetNCPointer(), and m_Impl.

Referenced by GetTheOnlyRow().

◆ Cancel()

void CQuery::Cancel ( void  )

Cancel the current statement or procedure call.

May be called asynchronously to force a "timeout" within one second.

Definition at line 4054 of file sdbapi.cpp.

References CQueryImpl::Cancel(), and m_Impl.

◆ ClearParameter()

CQuery & CQuery::ClearParameter ( CTempString  name)

Remove parameter with given name from parameter list.

Definition at line 4019 of file sdbapi.cpp.

References CQueryImpl::ClearParameter(), and m_Impl.

◆ ClearParameters()

CQuery & CQuery::ClearParameters ( void  )

Remove all parameters from parameter list.

Definition at line 4026 of file sdbapi.cpp.

References CQueryImpl::ClearParameters(), and m_Impl.

◆ end()

CQuery::CRowIterator CQuery::end ( void  ) const

Get iterator pointing to the end of the current result set or to the end of all result sets (depending on the setting changed with SingleSet() and MultiSet()).

Method cannot be used to take two different iterators - one for the end of result set and one for the end of all result sets. Which end is pointed to depends on the last call to SingleSet() or MultiSet() even if it was made after call to this method.

Definition at line 4190 of file sdbapi.cpp.

References CRef< C, Locker >::GetNCPointer(), and m_Impl.

Referenced by GetTheOnlyRow().

◆ Execute()

CQuery & CQuery::Execute ( const CTimeout timeout = CTimeout(CTimeout::eDefault))

Explicitly execute sql statement.

All result sets left from previous statement or stored procedure execution are purged. The query reverts to SingleSet mode, with no row count requirements.

Definition at line 4040 of file sdbapi.cpp.

References CQueryImpl::Execute(), and m_Impl.

◆ ExecuteSP()

CQuery & CQuery::ExecuteSP ( CTempString  sp,
const CTimeout timeout = CTimeout(CTimeout::eDefault) 
)

Execute stored procedure with given name.

All result sets left from previous statement or stored procedure execution are purged. The query reverts to SingleSet mode, with no row count requirements.

Definition at line 4047 of file sdbapi.cpp.

References CQueryImpl::ExecuteSP(), and m_Impl.

◆ GetColumnName()

string CQuery::GetColumnName ( unsigned int  col) const

Get name of the column with given number in the current result set.

All columns are numbered starting with 1.

Definition at line 4171 of file sdbapi.cpp.

References CQueryImpl::GetColumnName(), and m_Impl.

◆ GetColumnType()

ESDB_Type CQuery::GetColumnType ( unsigned int  col) const

Get type of the column with given number in the current result set All columns are numbered starting with 1.

Definition at line 4177 of file sdbapi.cpp.

References CQueryImpl::GetColumnType(), and m_Impl.

◆ GetParameter()

const CQuery::CField & CQuery::GetParameter ( CTempString  name)

Get value of the parameter.

For eSP_In parameter value set to it will always be returned. For eSP_InOut parameter value set to it will be returned before stored procedure execution and value returned from procedure after executing it and reading its row results (or confirming that it produced none). Throw an exception if no such parameter exists, or if it's an output parameter but not yet available because the caller hasn't finished processing results.

Definition at line 4013 of file sdbapi.cpp.

References CQueryImpl::GetParameter(), and m_Impl.

◆ GetPrintOutput()

const list< string > & CQuery::GetPrintOutput ( void  ) const

Get any PRINT output from the latest procedure call (or statement).

This output may be incomplete until the caller has explicitly read or purged all result sets.

Note
Many actions can invalidate this output, even working with other CQuery objects associated with the same CDatabase object or a normal (non-clone) copy thereof.

Definition at line 4129 of file sdbapi.cpp.

References CQueryImpl::GetPrintOutput(), and m_Impl.

◆ GetResultSetNo()

unsigned int CQuery::GetResultSetNo ( void  ) const

Get number of currently active result set.

All result sets are numbered starting with 1.

Definition at line 4105 of file sdbapi.cpp.

References CQueryImpl::GetResultSetNo(), and m_Impl.

◆ GetRowCount()

int CQuery::GetRowCount ( void  ) const

Get number of rows read after statement execution.

This number is available only when all result sets are read or purged by call to PurgeResults(). At all other times, the method throws an exception.

Definition at line 4117 of file sdbapi.cpp.

References CQueryImpl::GetRowCount(), and m_Impl.

◆ GetRowNo()

unsigned int CQuery::GetRowNo ( EHowMuch  how_much = eAllResultSets) const

Get row number currently active.

Row numbers are assigned consecutively to each row in all result sets returned starting with 1. With eAllResultSets (default) or in MultiSet mode, row number is not reset after passing result set boundary.

Definition at line 4111 of file sdbapi.cpp.

References CQueryImpl::GetRowNo(), and m_Impl.

◆ GetStatus()

int CQuery::GetStatus ( void  ) const

Get return status of stored procedure.

Status is available only if stored procedure is executed via ExecuteSP() method and all result sets returned from the procedure are read or purged by call to PurgeResults().

Definition at line 4123 of file sdbapi.cpp.

References CQueryImpl::GetStatus(), and m_Impl.

◆ GetTheOnlyRow()

CQuery::CRow CQuery::GetTheOnlyRow ( void  )

Provides the only row for the executed query.

It makes sure that there is exactly one row available and that the required row count range includes 1. VerifyDone() is called in the method so the user does not need to call it. In case of any problems a CSDB_Exception exception is generated.

Definition at line 4074 of file sdbapi.cpp.

References begin(), end(), eRetriable_No, CQueryImpl::GetMaxRowCount(), CQueryImpl::GetMinRowCount(), m_Impl, NCBI_THROW, NStr::NumericToString(), and VerifyDone().

◆ GetTotalColumns()

unsigned int CQuery::GetTotalColumns ( void  ) const

Get total number of columns in the current result set.

Definition at line 4165 of file sdbapi.cpp.

References CQueryImpl::GetTotalColumns(), and m_Impl.

◆ HasMoreResultSets()

bool CQuery::HasMoreResultSets ( void  )

Check if any more result sets are available for reading.

Advances to the next result set purging all remaining rows in current one if reading of it was already started (begin() method was called).

Definition at line 4135 of file sdbapi.cpp.

References CQueryImpl::HasMoreResultSets(), and m_Impl.

◆ MultiSet()

CQuery & CQuery::MultiSet ( void  )

Convert this query to not merge different result sets, i.e.

iterator will be equal to end() at the end of each result set and to switch to the next one you'll have to call begin() again. Method impacts not only this CQuery object and all iterators created from it but all copies of this CQuery object too.

Definition at line 4067 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::SetIgnoreBounds().

◆ operator=()

CQuery & CQuery::operator= ( const CQuery q)

Definition at line 3897 of file sdbapi.cpp.

References m_Impl.

◆ PurgeResults()

void CQuery::PurgeResults ( void  )

Purge all remaining result sets; fill in all remaining parameter results.

Definition at line 4141 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::PurgeResults().

◆ RequireRowCount() [1/2]

void CQuery::RequireRowCount ( unsigned int  min_rows,
unsigned int  max_rows 
)

Indicate the minimum and maximum number of rows the active query should return.

In MultiSet mode, the requirement applies to individual result sets. (Callers may specify the requirement for each set as it comes up, or let it carry over unchanged.) Any call to this method must follow Execute or ExecuteSP, which reset any such requirements.

Parameters
min_rowsMinimum valid row count.
max_rowsMaximum valid row count. (kMax_Auto for no limit.)

Definition at line 4153 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::RequireRowCount().

◆ RequireRowCount() [2/2]

void CQuery::RequireRowCount ( unsigned int  n)

Indicate precisely how many rows the active query should return.

In MultiSet mode, the requirement applies to individual result sets. (Callers may specify the requirement for each set as it comes up, or let it carry over unchanged.) Any call to this method must follow Execute or ExecuteSP, which reset any such requirements.

Definition at line 4147 of file sdbapi.cpp.

References m_Impl, n, and CQueryImpl::RequireRowCount().

◆ SetNullParameter()

CQuery & CQuery::SetNullParameter ( CTempString  name,
ESDB_Type  type,
ESP_ParamType  param_type = eSP_In 
)

Assign null value to the parameter.

Data type should be given explicitly to show which type of data should be sent to server.

Definition at line 4004 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::SetNullParameter().

Referenced by SetOutputParameter().

◆ SetOutputParameter()

CQuery & CQuery::SetOutputParameter ( CTempString  name,
ESDB_Type  type 
)
inline

Declare an output-only parameter.

Equivalent for now to calling SetNullParameter with a param_type value of eSP_InOut because MSSQL and Sybase (and hence FreeTDS) don't support true output-only parameters. However, if SDBAPI ever gains support for database engines with this feature, this method will arrange to make use of it as appropriate.

Definition at line 1446 of file sdbapi.hpp.

References eSP_InOut, and SetNullParameter().

◆ SetParameter() [1/11]

CQuery & CQuery::SetParameter ( CTempString  name,
bool  value,
ESDB_Type  type = eSDB_Bit,
ESP_ParamType  param_type = eSP_In 
)

Assign bool value to the parameter.

If data type requested is not byte then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3994 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [2/11]

CQuery & CQuery::SetParameter ( CTempString  name,
const char *  value,
ESDB_Type  type = eSDB_String,
ESP_ParamType  param_type = eSP_In 
)

Assign string value to the parameter.

If data type requested is not string then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3914 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [3/11]

CQuery & CQuery::SetParameter ( CTempString  name,
const CTime value,
ESDB_Type  type = eSDB_DateTime,
ESP_ParamType  param_type = eSP_In 
)

Assign CTime value to the parameter.

If data type requested is not datetime then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3984 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [4/11]

CQuery & CQuery::SetParameter ( CTempString  name,
const string value,
ESDB_Type  type = eSDB_String,
ESP_ParamType  param_type = eSP_In 
)

Assign string value to the parameter.

If data type requested is not string then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3904 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

Referenced by SetParameter().

◆ SetParameter() [5/11]

CQuery & CQuery::SetParameter ( CTempString  name,
double  value,
ESDB_Type  type = eSDB_Double,
ESP_ParamType  param_type = eSP_In 
)

Assign double value to the parameter.

If data type requested is not double then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3974 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [6/11]

CQuery & CQuery::SetParameter ( CTempString  name,
float  value,
ESDB_Type  type = eSDB_Float,
ESP_ParamType  param_type = eSP_In 
)

Assign float value to the parameter.

If data type requested is not float then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3964 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [7/11]

CQuery & CQuery::SetParameter ( CTempString  name,
Int4  value,
ESDB_Type  type = eSDB_Int4,
ESP_ParamType  param_type = eSP_In 
)

Assign 4-byte integer value to the parameter.

If data type requested is not 4-byte integer then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3934 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [8/11]

CQuery & CQuery::SetParameter ( CTempString  name,
Int8  value,
ESDB_Type  type = eSDB_Int8,
ESP_ParamType  param_type = eSP_In 
)

Assign 8-byte integer value to the parameter.

If data type requested is not 8-byte integer then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3924 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [9/11]

CQuery & CQuery::SetParameter ( CTempString  name,
long  value,
ESDB_Type  type = eSDB_Int4,
ESP_ParamType  param_type = eSP_In 
)
inline

Definition at line 1438 of file sdbapi.hpp.

References SetParameter(), and value.

◆ SetParameter() [10/11]

CQuery & CQuery::SetParameter ( CTempString  name,
short  value,
ESDB_Type  type = eSDB_Short,
ESP_ParamType  param_type = eSP_In 
)

Assign short integer value to the parameter.

If data type requested is not short integer then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3944 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetParameter() [11/11]

CQuery & CQuery::SetParameter ( CTempString  name,
unsigned char  value,
ESDB_Type  type = eSDB_Byte,
ESP_ParamType  param_type = eSP_In 
)

Assign byte value to the parameter.

If data type requested is not byte then attempt to do conversion will be made. If conversion is impossible exception will be thrown.

Definition at line 3954 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetParameter(), and value.

◆ SetSql()

CQuery & CQuery::SetSql ( CTempString  sql)

Set current sql statement.

Method does not clear parameter list and doesn't purge result sets left from previous query execution.

Definition at line 4033 of file sdbapi.cpp.

References m_Impl, CQueryImpl::SetSql(), and sql.

Referenced by CDatabase::NewQuery().

◆ SingleSet()

CQuery & CQuery::SingleSet ( void  )

Convert this query to work like only one result set was returned effectively merging all result sets together.

If some result sets were already read then all the remaining result sets will be merged. Method impacts not only this CQuery object and all iterators created from it but all copies of this CQuery object too. Result sets only from recently executed statement are affected. After re-execution of a statement default behavior is used - to not merge different result sets.

Definition at line 4060 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::SetIgnoreBounds().

◆ VerifyDone()

void CQuery::VerifyDone ( EHowMuch  how_much = eThisResultSet)

Ensure that no unread rows or parameter results remain, and that the total number of rows satisfies any constraints specified by RequireRowCount.

Throw an exception (after purging any unread rows) if not.

Definition at line 4159 of file sdbapi.cpp.

References m_Impl, and CQueryImpl::VerifyDone().

Referenced by GetTheOnlyRow().

Friends And Related Function Documentation

◆ CDatabase

friend class CDatabase
friend

Definition at line 749 of file sdbapi.hpp.

◆ DBAPI_MakeTrans

CAutoTrans::CSubject DBAPI_MakeTrans ( CQuery query)
friend

(S)DBAPI_TRANSACTION glue for CQuery.

Definition at line 3515 of file sdbapi.cpp.

Member Data Documentation

◆ m_Impl

CRef<CQueryImpl> CQuery::m_Impl
private

The documentation for this class was generated from the following files:
Modified on Sat Mar 02 10:55:17 2024 by modify_doxy.py rev. 669887