sptk::CQuery Class Reference
[Database Support]

Database query. More...

#include <CQuery.h>

Inheritance diagram for sptk::CQuery:

List of all members.

Public Member Functions
	CQuery (CDatabaseDriver *db=0L, std::string sql="", const char *createdFile=0, unsigned createdLine=0)
	Constructor.
	CQuery (const CQuery &)
	Copy constructor.
	~CQuery ()
	Destructor.
CField *	fieldByName (const char *fname) const
	Finds a field by the field name.
virtual const CField &	operator[] (uint32_t fieldIndex) const
	Field access by number, const version.
virtual CField &	operator[] (uint32_t fieldIndex)
	Field access by number, const version.
virtual const CField &	operator[] (const char *fieldName) const
	Field access by field name, const version.
virtual CField &	operator[] (const char *fieldName)
	Field access by field name.
virtual const CField &	operator[] (const std::string &fieldName) const
	Field access by field name, const version.
virtual CField &	operator[] (const std::string &fieldName)
	Field access by field name.
virtual uint32_t	fieldCount () const
	Reports a number of columns in the recordset for the active query.
virtual uint32_t	recordCount () const
	Reports the record count for the recordset, returned by the open() method.
std::string	sql ()
	Returns the text of current SQL query as std::string.
CFieldList &	fields ()
	Returns the query fields list.
CParamList &	params ()
	Returns the query parameters list.
virtual bool	readField (const char *fname, CVariant &value)
	Field read access by the field name, for the universal data connection.
virtual bool	writeField (const char *fname, const CVariant &fvalue)
	Field write access by the field name, for the universal data connection.
virtual bool	open ()
	Opens the query and fetches the first row.
virtual bool	close ()
	Closes the query.
virtual bool	next ()
	Fetches the next row from the recordset, same as fetch().
virtual bool	eof () const
	Returns true if there is no more rows in the recordset.
void	exec ()
	Executes the query and closes the statement.
void	exec (std::string newSQL)
	Executes the query and closes the statement.
void	fetch ()
	Fetches the next row from the recordset, same as next().
void	connect (CDatabaseDriver *db)
	Connects a query to a database.
void	disconnect ()
	Disconnects query from the database and releases all the allocated resourses.
uint32_t	paramCount () const
	Reports the number of unique parameters in the query.
CParam &	param (const char *paramName) const
	Returns the parameter by the name.
CParam &	param (const std::string &paramName) const
	Returns the parameter by the name.
CParam &	param (uint32_t paramIndex) const
	Returns the parameter by the index.
void *	statement () const
	Returns query statement handle.
std::string	sql () const
	Returns SQL Query text.
void	sql (std::string _sql)
	Sets SQL Query text. If the Query text is not the same and the db statement was prepared earlier then the db statement is released and new one is created.
CDatabaseDriver *	database () const
	Returns the database the query is connected to.
void	database (CDatabaseDriver *db)
	Connects the query to the database different database.
bool	active () const
	Reports if the query is opened.
bool	prepared () const
	True if the statement is prepared.
bool	autoPrepare () const
	Returns the value for auto-prepare flag.
void	autoPrepare (bool ap)
	Sets the value for auto-prepare flag.
void	prepare ()
	Prepares query for the fast execution.
void	unprepare ()
	Unprepares query releasing previously prepared statement.
void	logText (std::string text, const CLogPriority &logPriority=CLP_DEBUG)
	Adds the text to log file.
void	logAndThrow (std::string method, std::string error) throw (CException)
	Throws an exception.
CStrings &	messages ()
	Access to diag messages.
Protected Member Functions
int	countCols ()
	Counts columns of the dataset (if any) returned by query.
void	allocStmt ()
	Allocates a statement.
void	freeStmt ()
	Deallocates a statement. All the resources allocated by statement are released.
void	closeStmt ()
	Closes a statement. Prepared statement stay prepared but closed.
void	execute ()
	Executes a statement.
void	colAttributes (int16_t column, int16_t descType, int32_t &value)
	In a dataset returned by a query, retrieves the column attributes.
void	colAttributes (int16_t column, int16_t descType, char *buff, int len)
	In a dataset returned by a query, retrieves the column attributes.
std::string	getError () const
	Retrieves an error (if any) after executing an ODBC statement.
void	notImplemented (std::string functionName) const
	Internal function to throw 'Not implemented' exception.
void	closeQuery (bool releaseStatement=false)
	Closes query by closing the statement.
virtual bool	loadData ()
	In CDataset it should load data into the dataset.
virtual bool	saveData ()
	In CDataset it should save data into the dataset.
void	storeStatistics ()
	Stores calls statistics to the database.
Protected Attributes
bool	m_autoPrepare
	Prepare the query automatically, on the first call.
void *	m_statement
	ODBC statement handle.
void *	m_connection
	Database server connection.
bool	m_prepared
	True if the statement is prepared.
bool	m_active
	True if query is active (opened).
bool	m_eof
	True if there is no more records to fetch.
CParamList	m_params
	List of query parameters.
CFieldList	m_fields
	List of query fields - makes sense after fetch.
double	m_duration
	The duration of last execution, in seconds.
double	m_totalDuration
	The total duration of executions, in seconds.
unsigned	m_totalCalls
	The total number of query executions.
CDatabaseDriver *	m_db
	Database connection.
std::string	m_sql
	SQL statement string.
const char *	m_createdFile
	The source file the query was created in.
unsigned	m_createdLine
	The source file line the query was created at.
CStrings	m_messages
	Optional diag messages populated after exec() or open().
int	m_objectIndex
	Unique index for query object.
Static Protected Attributes
static int	nextObjectIndex
	Internal number to implement unique query index. That is pretty useful for logs.
Friends
class	CDatabaseDriver

---

Detailed Description

Database query.

A CDataset connected to the database to execute a database queries. The type of the database depends on the CDatabaseDriver object query is connected to.

---

Constructor & Destructor Documentation

sptk::CQuery::CQuery	(	CDatabaseDriver *	db = 0L,
		std::string	sql = "",
		const char *	createdFile = 0,
		unsigned	createdLine = 0
	)

Constructor.

You can optionally provide the name of the file and line number where this query is created. This is used to collect statistical information for the query calls. If file and line information is provided, then calls statistics is stored to the database object during the query dtor.

Parameters:

	db	CDatabaseDriver, the database to connect to, optional
	sql	std::string, the SQL query text to use, optional
	createdFile	const char*, the name of the file this query was created in (optional)
	createdLine	unsigned, the line of the file this query was created at (optional)

---

Member Function Documentation

void sptk::CQuery::autoPrepare

(

bool

ap

)

[inline]

Sets the value for auto-prepare flag.

If the flag is set the query would automatically call prepare() when needed.

bool sptk::CQuery::autoPrepare

(

)

const [inline]

Returns the value for auto-prepare flag.

If the flag is set the query would automatically call prepare() when needed.

virtual bool sptk::CQuery::close

(

)

[inline, virtual]

Closes the query.

Doesn't release the db statement, so the query may be called again, and faster than for the first time.

Reimplemented from sptk::CDataSource.

Referenced by sptk::CQueryGuard::~CQueryGuard().

void sptk::CQuery::closeQuery

(

bool

releaseStatement = false

)

[protected]

Closes query by closing the statement.

If the statement isn't released it may be re-used later.

Parameters:

releaseStatement

bool, true if we need to release the query's ODBC statement

void sptk::CQuery::connect

(

CDatabaseDriver *

db

)

Connects a query to a database.

If the query was connected to another database, releases all the allocated resources in it.

void sptk::CQuery::exec

(

std::string

newSQL

)

[inline]

Executes the query and closes the statement.

Query SQL would be set to the new SQL statement

Parameters:

newSQL

std::string, an SQL statement to execute

CField* sptk::CQuery::fieldByName

(

const char *

fname

)

const [inline]

Finds a field by the field name.

Parameters:

fname

const char *, field name

Returns:

CField pointer, or 0L if not found

virtual uint32_t sptk::CQuery::fieldCount

(

)

const [inline, virtual]

Reports a number of columns in the recordset for the active query.

Typically is used after the open() method is called, but before query is closed.

Implements sptk::CDataSource.

virtual bool sptk::CQuery::loadData

(

)

[inline, protected, virtual]

In CDataset it should load data into the dataset.

Since the query loads all the data by open() or fetch(), in CQuery this method does exactly nothing

Reimplemented from sptk::CDataSource.

void sptk::CQuery::logAndThrow	(	std::string	method,
		std::string	error
	)			throw (CException)

Throws an exception.

Before exception is thrown, it is logged into the logfile (if the logfile is defined)

Parameters:

	method	std::string, method name where error has occured
	error	std::string, error text

void sptk::CQuery::logText	(	std::string	text,
		const CLogPriority &	logPriority = CLP_DEBUG
	)

Adds the text to log file.

The log file should be set to active, otherwise no text is added to the log file. Every successful call of this method adds a new line to the log file.

Parameters:

	text	std::string, log text
	logPriority	const CLogPriority&, log message priority

CStrings& sptk::CQuery::messages

(

)

[inline]

Access to diag messages.

Some of the database drivers (ODBC, for example) may return diag messages after the execution of the query. Usually, such messages may be generated by a stored procedure call.

virtual bool sptk::CQuery::open

(

)

[virtual]

Opens the query and fetches the first row.

It is necessary for the select queries and some stored procedures that may return the dataset. First-time call for open() also prepares the query.

Reimplemented from sptk::CDataSource.

Referenced by sptk::CQueryGuard::open().

virtual CField& sptk::CQuery::operator[]

(

uint32_t

fieldIndex

)

[inline, virtual]

Field access by number, const version.

Field index should be inside 0..fieldCount()-1

Parameters:

fieldIndex

int, field index

Implements sptk::CDataSource.

virtual const CField& sptk::CQuery::operator[]

(

uint32_t

fieldIndex

)

const [inline, virtual]

Field access by number, const version.

Field index should be inside 0..fieldCount()-1

Parameters:

fieldIndex

int, field index

Implements sptk::CDataSource.

CParam& sptk::CQuery::param

(

uint32_t

paramIndex

)

const [inline]

Returns the parameter by the index.

Returns:

parameter

See also:

CParamList

CParam& sptk::CQuery::param

(

const std::string &

paramName

)

const [inline]

Returns the parameter by the name.

If the parameter name isn't found, throws an exception

Parameters:

paramName

std::string, parameter name

Returns:

parameter

See also:

CParamList

CParam& sptk::CQuery::param

(

const char *

paramName

)

const [inline]

Returns the parameter by the name.

If the parameter name isn't found, throws an exception

Parameters:

paramName

const char *, parameter name

Returns:

parameter

See also:

CParamList

Referenced by sptk::CQueryGuard::param().

uint32_t sptk::CQuery::paramCount

(

)

const [inline]

Reports the number of unique parameters in the query.

Makes sense after the SQL query text is set.

virtual uint32_t sptk::CQuery::recordCount

(

)

const [inline, virtual]

Reports the record count for the recordset, returned by the open() method.

Currently is NOT implemented.

Implements sptk::CDataSource.

virtual bool sptk::CQuery::saveData

(

)

[inline, protected, virtual]

In CDataset it should save data into the dataset.

Since the query saves all the data by execute, in CQuery this method does exactly nothing

Reimplemented from sptk::CDataSource.

---

The documentation for this class was generated from the following file:

• CQuery.h