NCBI C++ ToolKit
|
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>
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... | |
CQuery & | operator= (const CQuery &q) |
CQuery & | SetParameter (CTempString name, const string &value, ESDB_Type type=eSDB_String, ESP_ParamType param_type=eSP_In) |
Assign string value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, const char *value, ESDB_Type type=eSDB_String, ESP_ParamType param_type=eSP_In) |
Assign string value to the parameter. More... | |
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. More... | |
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. More... | |
CQuery & | SetParameter (CTempString name, long value, ESDB_Type type=eSDB_Int4, ESP_ParamType param_type=eSP_In) |
CQuery & | SetParameter (CTempString name, short value, ESDB_Type type=eSDB_Short, ESP_ParamType param_type=eSP_In) |
Assign short integer value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, unsigned char value, ESDB_Type type=eSDB_Byte, ESP_ParamType param_type=eSP_In) |
Assign byte value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, float value, ESDB_Type type=eSDB_Float, ESP_ParamType param_type=eSP_In) |
Assign float value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, double value, ESDB_Type type=eSDB_Double, ESP_ParamType param_type=eSP_In) |
Assign double value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, const CTime &value, ESDB_Type type=eSDB_DateTime, ESP_ParamType param_type=eSP_In) |
Assign CTime value to the parameter. More... | |
CQuery & | SetParameter (CTempString name, bool value, ESDB_Type type=eSDB_Bit, ESP_ParamType param_type=eSP_In) |
Assign bool value to the parameter. More... | |
CQuery & | SetNullParameter (CTempString name, ESDB_Type type, ESP_ParamType param_type=eSP_In) |
Assign null value to the parameter. More... | |
CQuery & | SetOutputParameter (CTempString name, ESDB_Type type) |
Declare an output-only parameter. More... | |
const CField & | GetParameter (CTempString name) |
Get value of the parameter. More... | |
CQuery & | ClearParameter (CTempString name) |
Remove parameter with given name from parameter list. More... | |
CQuery & | ClearParameters (void) |
Remove all parameters from parameter list. More... | |
CQuery & | SetSql (CTempString sql) |
Set current sql statement. More... | |
CQuery & | Execute (const CTimeout &timeout=CTimeout(CTimeout::eDefault)) |
Explicitly execute sql statement. More... | |
CQuery & | ExecuteSP (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... | |
CQuery & | SingleSet (void) |
Convert this query to work like only one result set was returned effectively merging all result sets together. More... | |
CQuery & | MultiSet (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< CQueryImpl > | m_Impl |
Query implementation object. More... | |
Friends | |
class | CDatabase |
CAutoTrans::CSubject | DBAPI_MakeTrans (CQuery &query) |
(S)DBAPI_TRANSACTION glue for CQuery. More... | |
Object used to execute queries and stored procedures on the database server and retrieve result sets.
Definition at line 231 of file sdbapi.hpp.
typedef CRowIterator CQuery::const_iterator |
Definition at line 495 of file sdbapi.hpp.
typedef CRowIterator CQuery::iterator |
Definition at line 494 of file sdbapi.hpp.
enum CQuery::EAllowLog |
Allow transaction log (general, to avoid using bools).
Enumerator | |
---|---|
eDisableLog | Disables log. |
eEnableLog | Enables log. |
Definition at line 248 of file sdbapi.hpp.
enum CQuery::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.
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 3908 of file sdbapi.cpp.
CQuery::~CQuery | ( | void | ) |
Definition at line 3920 of file sdbapi.cpp.
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 3916 of file sdbapi.cpp.
|
private |
Create query object for given database object.
Definition at line 3911 of file sdbapi.cpp.
References m_Impl, and CRef< C, Locker >::Reset().
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 4210 of file sdbapi.cpp.
References CQueryImpl::BeginNewRS(), CRef< C, Locker >::GetNCPointer(), and m_Impl.
Referenced by GetTheOnlyRow().
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 4081 of file sdbapi.cpp.
References CQueryImpl::Cancel(), and m_Impl.
CQuery & CQuery::ClearParameter | ( | CTempString | name | ) |
Remove parameter with given name from parameter list.
Definition at line 4046 of file sdbapi.cpp.
References CQueryImpl::ClearParameter(), and m_Impl.
CQuery & CQuery::ClearParameters | ( | void | ) |
Remove all parameters from parameter list.
Definition at line 4053 of file sdbapi.cpp.
References CQueryImpl::ClearParameters(), and m_Impl.
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 4217 of file sdbapi.cpp.
References CRef< C, Locker >::GetNCPointer(), and m_Impl.
Referenced by GetTheOnlyRow().
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 4067 of file sdbapi.cpp.
References CQueryImpl::Execute(), and m_Impl.
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 4074 of file sdbapi.cpp.
References CQueryImpl::ExecuteSP(), and m_Impl.
Get name of the column with given number in the current result set.
All columns are numbered starting with 1.
Definition at line 4198 of file sdbapi.cpp.
References CQueryImpl::GetColumnName(), and m_Impl.
Get type of the column with given number in the current result set All columns are numbered starting with 1.
Definition at line 4204 of file sdbapi.cpp.
References CQueryImpl::GetColumnType(), and m_Impl.
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 4040 of file sdbapi.cpp.
References CQueryImpl::GetParameter(), and m_Impl.
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.
Definition at line 4156 of file sdbapi.cpp.
References CQueryImpl::GetPrintOutput(), and m_Impl.
unsigned int CQuery::GetResultSetNo | ( | void | ) | const |
Get number of currently active result set.
All result sets are numbered starting with 1.
Definition at line 4132 of file sdbapi.cpp.
References CQueryImpl::GetResultSetNo(), and m_Impl.
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 4144 of file sdbapi.cpp.
References CQueryImpl::GetRowCount(), and m_Impl.
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 4138 of file sdbapi.cpp.
References CQueryImpl::GetRowNo(), and m_Impl.
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 4150 of file sdbapi.cpp.
References CQueryImpl::GetStatus(), and m_Impl.
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 4101 of file sdbapi.cpp.
References begin(), end(), eRetriable_No, CQueryImpl::GetMaxRowCount(), CQueryImpl::GetMinRowCount(), m_Impl, NCBI_THROW, NStr::NumericToString(), row, and VerifyDone().
unsigned int CQuery::GetTotalColumns | ( | void | ) | const |
Get total number of columns in the current result set.
Definition at line 4192 of file sdbapi.cpp.
References CQueryImpl::GetTotalColumns(), and m_Impl.
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 4162 of file sdbapi.cpp.
References CQueryImpl::HasMoreResultSets(), and m_Impl.
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 4094 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::SetIgnoreBounds().
Definition at line 3924 of file sdbapi.cpp.
References m_Impl.
void CQuery::PurgeResults | ( | void | ) |
Purge all remaining result sets; fill in all remaining parameter results.
Definition at line 4168 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::PurgeResults().
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.
min_rows | Minimum valid row count. |
max_rows | Maximum valid row count. (kMax_Auto for no limit.) |
Definition at line 4180 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::RequireRowCount().
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 4174 of file sdbapi.cpp.
References m_Impl, n, and CQueryImpl::RequireRowCount().
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 4031 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::SetNullParameter().
Referenced by SetOutputParameter().
|
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 1450 of file sdbapi.hpp.
References eSP_InOut, and SetNullParameter().
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 4021 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3941 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 4011 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3931 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
Referenced by SetParameter().
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 4001 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3991 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3961 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3951 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
|
inline |
Definition at line 1442 of file sdbapi.hpp.
References SetParameter(), and rapidjson::value.
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 3971 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 3981 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetParameter(), and rapidjson::value.
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 4060 of file sdbapi.cpp.
References m_Impl, CQueryImpl::SetSql(), and sql.
Referenced by CDatabase::NewQuery().
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 4087 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::SetIgnoreBounds().
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 4186 of file sdbapi.cpp.
References m_Impl, and CQueryImpl::VerifyDone().
Referenced by GetTheOnlyRow().
|
friend |
Definition at line 749 of file sdbapi.hpp.
|
friend |
(S)DBAPI_TRANSACTION glue for CQuery.
Definition at line 3542 of file sdbapi.cpp.
|
private |
Query implementation object.
Definition at line 758 of file sdbapi.hpp.
Referenced by CQuery::CField::AsBool(), CQuery::CField::AsByte(), CQuery::CField::AsDateTime(), CQuery::CField::AsDouble(), CQuery::CField::AsFloat(), CQuery::CField::AsInt4(), CQuery::CField::AsInt8(), CQuery::CField::AsIStream(), CQuery::CField::AsShort(), CQuery::CField::AsString(), CQuery::CField::AsVector(), begin(), Cancel(), CQuery::CField::CField(), ClearParameter(), ClearParameters(), CQuery(), end(), Execute(), ExecuteSP(), CQuery::CField::GetBookmark(), GetColumnName(), GetColumnType(), CQuery::CField::GetOStream(), GetParameter(), GetPrintOutput(), GetResultSetNo(), GetRowCount(), GetRowNo(), GetStatus(), GetTheOnlyRow(), GetTotalColumns(), HasMoreResultSets(), CQuery::CField::IsNull(), MultiSet(), operator=(), PurgeResults(), RequireRowCount(), SetNullParameter(), SetParameter(), SetSql(), SingleSet(), VerifyDone(), and CQuery::CField::x_Detach().