fastcgi++
Public Member Functions | Protected Attributes | Private Member Functions | Static Private Member Functions | Private Attributes | Friends
ASql::MySQL::Statement Class Reference

MySQL query statement. More...

#include <mysql.hpp>

Inheritance diagram for ASql::MySQL::Statement:
ASql::Statement

List of all members.

Public Member Functions

 Statement (Connection &connection_, const char *const queryString, const size_t queryLength, const Data::Set *const parameterSet, const Data::Set *const resultSet)
 Complete Constructor.
 Statement (Connection &connection_)
 Simple Constructor.
 ~Statement ()
void init (const char *const &queryString, const size_t &queryLength, const Data::Set *const parameterSet, const Data::Set *const resultSet, bool customPlaceholders=false)
 Initialize statement.
void execute (const Data::Set *const parameters, Data::SetContainer *const results, unsigned long long int *const insertId=0, unsigned long long int *const rows=0, bool docommit=true, const unsigned int thread=0)
 Execute multi-row result MySQL statement.
bool execute (const Data::Set *const parameters, Data::Set &results, bool docommit=true, const unsigned int thread=0)
 Execute single result row MySQL statement.
void execute (const Data::SetContainer &parameters, unsigned long long int *rows=0, bool docommit=true, const unsigned int thread=0)
 Execute result-less multi-row parameter MySQL statement.
void queue (QueryPar &query, int instance=-1)
 Asynchronously execute a MySQL statement.

Protected Attributes

boost::scoped_array
< Data::Conversions
paramsConversions
boost::scoped_array
< Data::Conversions
resultsConversions

Private Member Functions

void executeParameters (const Data::Set *const &parameters, const unsigned int thread)
 Execute parameter part of statement.
bool executeResult (Data::Set &row, const unsigned int thread)
 Fetch a row of the results.

Static Private Member Functions

static void buildBindings (MYSQL_STMT *const &stmt, const Data::Set &set, Data::Conversions &conversions, boost::scoped_array< MYSQL_BIND > &bindings, const std::deque< unsigned char > *order=0)
 Build an array of MySQL C API prepared statement bindings.
static void bindBindings (Data::Set &set, Data::Conversions &conversions, boost::scoped_array< MYSQL_BIND > &bindings, const std::deque< unsigned char > *order=0)
 Bind an array of MySQL bindings to the passed data set.

Private Attributes

Connectionconnection
boost::scoped_array< MYSQL_STMT * > stmt
 Pointer to actual MySQL C API prepared statement object.
std::deque< unsigned char > paramOrder
 Bind data set object to query parameters.
boost::scoped_array
< boost::scoped_array
< MYSQL_BIND > > 
paramsBindings
 Array of parameter bindings for use with the query.
boost::scoped_array
< boost::scoped_array
< MYSQL_BIND > > 
resultsBindings
 Array of result bindings for use with the query.
bool m_initialized
boost::scoped_array< const bool * > m_stop

Friends

class ConnectionPar< Statement >
class Transaction< Statement >

Detailed Description

MySQL query statement.

This class will store up a prepared MySQL statement for both synchronous and asynchronous execution. It should be initialized either by the full constructor or init().

Definition at line 128 of file mysql.hpp.


Constructor & Destructor Documentation

ASql::MySQL::Statement::Statement ( Connection connection_,
const char *const  queryString,
const size_t  queryLength,
const Data::Set *const  parameterSet,
const Data::Set *const  resultSet 
) [inline]

Complete Constructor.

The constructor builds the query and the associated parameters/result data structures based on the template objects provided by resultSet and parameterSet. These should point to data structures derived from ASql::Data::Set. The objects need not have any actual data in them as they are only used to find sizes and types of indexable member objects. A null pointer indicates no parameter/result data.

The SQL query string should be a valid SQL query with '?' as a placeholder for all parameters ex. "SELECT * FROM testTable WHERE id=?". Note the lack of a terminating semicolon and lack of quotations around the question marks. The number of question marks in the query should match up exactly with the value returned by a call of ASql::Data::Set::numberOfSqlElements() on parameterSet. Similarly, the number of returned result columns from the query should match up with the same function called on resultSet.

Parameters:
[in]connection_MySQL connection to run query through.
[in]queryStringSQL query. No null termination.
[in]queryLengthLength of SQL query. No null termination.
[in]parameterSetTemplate object of parameter data set. Null means no parameters.
[in]resultSetTemplate object of result data set. Null means no results.

Definition at line 156 of file mysql.hpp.

References init().

ASql::MySQL::Statement::Statement ( Connection connection_) [inline]

Simple Constructor.

Parameters:
[in]connection_MySQL connection to run query through.

Definition at line 172 of file mysql.hpp.

Definition at line 583 of file mysql.cpp.


Member Function Documentation

void ASql::MySQL::Statement::bindBindings ( Data::Set set,
Data::Conversions conversions,
boost::scoped_array< MYSQL_BIND > &  bindings,
const std::deque< unsigned char > *  order = 0 
) [static, private]

Bind an array of MySQL bindings to the passed data set.

This static function will take an object derived from a Data::Set and bind a corresponding MySQL bind array. If a conversion is required the data set is not binded directly to the bindings array but through the corresponding conversion in the Conversions container.

This function is called before any statement is executed for parameter data, and before a row is fetched for result data.

Parameters:
in/out]set Reference to a data set object.
[in]conversionsReference to an array to pass conversion data through.
[in]bindingsReference to a MySQL bind array to write data to.

Definition at line 415 of file mysql.cpp.

References ASql::Data::Index::data, ASql::Data::Index::type, and ASql::Data::U_TINY_N.

void ASql::MySQL::Statement::buildBindings ( MYSQL_STMT *const &  stmt,
const Data::Set set,
Data::Conversions conversions,
boost::scoped_array< MYSQL_BIND > &  bindings,
const std::deque< unsigned char > *  order = 0 
) [static, private]

Build an array of MySQL C API prepared statement bindings.

This static function will take an object derived from a Data::Set and build a corresponding MySQL bind array. The objects need not have any actual data in them as they are only used to find sizes and types of indexable member objects. A null pointer indicates no parameter/result data.

A Conversions container is also built to accommodate any types that can not be written/read directly to/from the Data::Set passed and will require conversion beforehand.

This function is only called once upon construction of the statement object. The resulting Conversions and MySQL bind arrays can be reused every time the statement is executed with a call to bindBindings().

Parameters:
[in]stmtReference to pointer to MySQL C API statement.
[in]setReference to a template object.
[out]conversionsReference to an array to write conversion data to.
[out]bindingsReference to a MySQL bind array to write data to.

Definition at line 276 of file mysql.cpp.

References ASql::Data::BIGINT, ASql::Data::BINARY, ASql::Data::BLOB, ASql::MySQL::TypedConversion< T >::buffer, ASql::MySQL::TypedConversion< T >::bufferType, ASql::Data::CHAR, ASql::Data::DATE, ASql::Data::DATETIME, ASql::Data::DOUBLE, ASql::Data::FLOAT, ASql::Data::INT, ASql::MySQL::TypedConversion< T >::length, ASql::Data::SHORT, ASql::Data::Index::size, ASql::Data::TEXT, ASql::Data::TIME, ASql::Data::TINY, ASql::Data::Index::type, ASql::Data::U_BIGINT, ASql::Data::U_TINY_N, and ASql::Data::WTEXT.

void ASql::MySQL::Statement::execute ( const Data::Set *const  parameters,
Data::SetContainer *const  results,
unsigned long long int *const  insertId = 0,
unsigned long long int *const  rows = 0,
bool  docommit = true,
const unsigned int  thread = 0 
)

Execute multi-row result MySQL statement.

Executes the built query with the passed parameter data storing the results in the passed results container. The number of rows affected or total matching rows can be retrieved by passing the proper pointer to rows. If SQL_CALC_FOUND_ROWS is included in a select statement then this value will represent the total matching rows regardless of a LIMIT clause. The last insert value on a auto-incremented column can also be retrieved with an appropriate pointer in insertId.

The Data::Set pointed to by parameters must have the same derived type as was passed upon construction of the statement. A null pointer, as in the constructor, indicates no parameter data. The results parameter should be a pointer to a Data::SetContainer templated to the same derived type passed upon construction of the statement for the result set. As well, a null pointer indicates no result data.

Parameters:
[in]parametersData set of MySQL query parameter data.
[out]resultsData set container of MySQL query result data.
[out]insertIdPointer to integer for writing of last auto-increment insert value.
[out]rowsPointer to integer for writing the number of rows affected/matching from last query.
[in]docommitSet to true a transaction commit should be completed at the end of this query.

Definition at line 194 of file mysql.cpp.

References ASql::Data::SetContainer::manufacture(), and ASql::Data::SetContainer::trim().

bool ASql::MySQL::Statement::execute ( const Data::Set *const  parameters,
Data::Set results,
bool  docommit = true,
const unsigned int  thread = 0 
)

Execute single result row MySQL statement.

Executes the built query with the passed parameter data storing the results in the passed results set. This simple alternative exists for cases where the user is certain that only a single result row will be returned and there will be no need for a container of sets.

The Data::Set pointed to by parameters must have the same derived type as was passed upon construction of the statement. A null pointer, as in the constructor, indicates no parameter data. The results parameter should be a Data::Set templated to the same derived type passed upon construction of the statement for the single result result row.

Parameters:
[in]parametersData set of MySQL query parameter data.
[out]resultsSet to store single result row in.
[in]docommitSet to true a transaction commit should be completed at the end of this query.
Returns:
True if result data was recieved, false otherwise.

Definition at line 239 of file mysql.cpp.

void ASql::MySQL::Statement::execute ( const Data::SetContainer parameters,
unsigned long long int *  rows = 0,
bool  docommit = true,
const unsigned int  thread = 0 
)

Execute result-less multi-row parameter MySQL statement.

Executes the built query with the passed parameter data storing no results. This alternative exists to allow users to execute multi-rows parameter queries which obviously will not return any data. (INSERT UPDATE DELETE) and such.

The Data::SetContainer referenced to by parameters must have the same derived type as was passed upon construction of the statement. a Data::SetContainer templated to the same derived type passed upon construction of the statement for the single result result row.

Parameters:
[in]parametersData set of MySQL query parameter data.
[out]rowsPointer to integer for writing the number of rows affected from last query.
[in]docommitSet to true a transaction commit should be completed at the end of this query.

Definition at line 256 of file mysql.cpp.

References ASql::Data::SetContainer::init(), and ASql::Data::SetContainer::pull().

void ASql::MySQL::Statement::executeParameters ( const Data::Set *const &  parameters,
const unsigned int  thread 
) [private]

Execute parameter part of statement.

Parameters:
[in]parametersParameters to use in query

Definition at line 164 of file mysql.cpp.

bool ASql::MySQL::Statement::executeResult ( Data::Set row,
const unsigned int  thread 
) [private]

Fetch a row of the results.

Parameters:
[out]rowSet to store results in
Returns:
true normally, false if no data

Definition at line 177 of file mysql.cpp.

void ASql::MySQL::Statement::init ( const char *const &  queryString,
const size_t &  queryLength,
const Data::Set *const  parameterSet,
const Data::Set *const  resultSet,
bool  customPlaceholders = false 
)

Initialize statement.

The initializer builds the query and the associated parameters/result data structures based on the template objects provided by resultSet and parameterSet. These should point to data structures derived from ASql::Data::Set. The objects need not have any actual data in them as they are only used to find sizes and types of indexable member objects. A null pointer indicates no parameter/result data.

The SQL query string should be a valid SQL query with '?' as a placeholder for all parameters ex. "SELECT * FROM testTable WHERE id=?". Note the lack of a terminating semicolon and lack of quotations around the question marks. The number of question marks in the query should match up exactly with the value returned by a call of ASql::Data::Set::numberOfSqlElements() on parameterSet. Similarly, the number of returned result columns from the query should match up with the same function called on resultSet.

Parameters:
[in]queryStringSQL query. No null termination.
[in]queryLengthLength of SQL query. No null termination.
[in]parameterSetTemplate object of parameter data set. Null means no parameters.
[in]resultSetTemplate object of result data set. Null means no results.

Definition at line 97 of file mysql.cpp.

References Fastcgipp::Http::atoi().

Referenced by Statement().

void ASql::MySQL::Statement::queue ( QueryPar query,
int  instance = -1 
) [inline]

Asynchronously execute a MySQL statement.

This function will queue the statement to be executed in a separate thread and return immediately. The information for execute() applies here with a few minor differences. For one, shared pointers are passed to prevent data being destroyed in one thread before it is finished with in another (segfault). So don't cheat, make sure they are shared pointer controlled on your end as well.

For two, a callback function is supplied to be called when the query is complete. The data passed is a ASql::Error data structure.

Parameters:
in/out]QueryPar object to manage the asynchronous execution of the query.

Definition at line 291 of file mysql.hpp.

References connection, and ASql::ConnectionPar< T >::queue().


Friends And Related Function Documentation

friend class ConnectionPar< Statement > [friend]

Definition at line 369 of file mysql.hpp.

friend class Transaction< Statement > [friend]

Definition at line 370 of file mysql.hpp.


Member Data Documentation

Definition at line 296 of file mysql.hpp.

Referenced by queue().

Definition at line 365 of file mysql.hpp.

boost::scoped_array<const bool*> ASql::MySQL::Statement::m_stop [private]

Definition at line 367 of file mysql.hpp.

std::deque<unsigned char> ASql::MySQL::Statement::paramOrder [private]

Bind data set object to query parameters.

Definition at line 302 of file mysql.hpp.

boost::scoped_array<boost::scoped_array<MYSQL_BIND> > ASql::MySQL::Statement::paramsBindings [private]

Array of parameter bindings for use with the query.

Definition at line 305 of file mysql.hpp.

boost::scoped_array<Data::Conversions> ASql::Statement::paramsConversions [protected, inherited]

Definition at line 204 of file asql.hpp.

boost::scoped_array<boost::scoped_array<MYSQL_BIND> > ASql::MySQL::Statement::resultsBindings [private]

Array of result bindings for use with the query.

Definition at line 308 of file mysql.hpp.

boost::scoped_array<Data::Conversions> ASql::Statement::resultsConversions [protected, inherited]

Definition at line 205 of file asql.hpp.

boost::scoped_array<MYSQL_STMT*> ASql::MySQL::Statement::stmt [private]

Pointer to actual MySQL C API prepared statement object.

Definition at line 299 of file mysql.hpp.


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