Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

mysqlpp::Query Class Reference

A class for building and executing SQL queries. More...

#include <query.h>

Inheritance diagram for mysqlpp::Query:

Inheritance graph
[legend]
Collaboration diagram for mysqlpp::Query:

Collaboration graph
[legend]
List of all members.

Public Methods

 Query (Connection *c, bool te=false)
 Create a new query object attached to a connection.

 Query (const Query &q)
 Create a new query object as a copy of another.

std::string error ()
 Get the last error message that happened on the connection we're bound to.

bool success ()
 Returns true if the query executed successfully.

std::string preview ()
 Return the query string currently in the buffer.

bool exec (const std::string &str)
 Execute an SQL query.

ResNSel execute ()
 Execute a query and returns status information about the results of the query.

ResUse use ()
 Execute a query returning data, when you wish to deal with the data one row at a time.

Result store ()
 Execute a query, and store the entire result set immediately in memory.

template<class T1> void storein_sequence (T1 &con, query_reset r=RESET_QUERY)
 Execute a query, and store the entire result set in the given STL sequence container.

template<class T1> void storein_set (T1 &con, query_reset r=RESET_QUERY)
 Execute a query, and store the entire result set in the given associative STL container.

template<class T1> void storein (T1 &con, query_reset r=RESET_QUERY)
 Execute a query, and store the entire result set in an STL container.

template<class T> Query & update (const T &o, const T &n)
 Replace an existing row's data with new data.

template<class T> Query & insert (const T &v)
 Insert a new row.

template<class T> Query & replace (const T &v)
 Insert new row unless there is an existing row that matches on a unique index, in which case we replace it.


Detailed Description

A class for building and executing SQL queries.

This class is derived from SQLQuery. It adds to that a tie between the query object and a MySQL++ Connection object, so that the query can be sent to the MySQL server we're connected to.


Constructor & Destructor Documentation

mysqlpp::Query::Query Connection   c,
bool    te = false
[inline]
 

Create a new query object attached to a connection.

This is the constructor used by mysqlpp::Connection::query().

Parameters:
c  connection the finished query should be sent out on
te  if true, throw exceptions on errors


Member Function Documentation

bool mysqlpp::Query::exec const std::string &    str
 

Execute an SQL query.

Use this method for queries that do not return data, and for which you only require a success or failure indication. See execute() if you need more information about the status of a query. See store(), storein(), and use() for alternative query execution methods.

This method is basically a thin wrapper around the MySQL C API function mysql_query().

Parameters:
str  the query to execute
Returns:
true if query was executed successfully

ResNSel mysqlpp::Query::execute   [inline]
 

Execute a query and returns status information about the results of the query.

Use this method for queries that do not return data as such. (For example, CREATE INDEX, or OPTIMIZE TABLE.) See exec(), store(), storein(), and use() for alternative query execution methods.

There are a number of overloaded versions of this function. The one without parameters simply executes a query that you have built up in the object in some way. (For instance, via the insert() method, or by using the object's stream interface.) You can also pass the function an std::string containing a SQL query, a SQLQueryParms object, or as many as 12 SQLStrings. The latter two (or is it 13?) overloads are for filling out template queries.

See exec(), store(), storein_sequence(), storein_set() and use() for alternate query execution mechanisms.

Returns:
mysqlpp::ResNSel object containing the state information resulting from the query

template<class T>
Query& mysqlpp::Query::insert const T &    v [inline]
 

Insert a new row.

This function builds an INSERT SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
v  new row
See also:
replace(), update()

Reimplemented from mysqlpp::SQLQuery.

template<class T>
Query& mysqlpp::Query::replace const T &    v [inline]
 

Insert new row unless there is an existing row that matches on a unique index, in which case we replace it.

This function builds a REPLACE SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
v  new row
See also:
insert(), update()

Reimplemented from mysqlpp::SQLQuery.

ResUse mysqlpp::Query::store   [inline]
 

Execute a query, and store the entire result set immediately in memory.

"Store" queries tell the server to send you the result set as a single block of data. (The name comes from the MySQL C API function that initiates this process, mysql_store_result() .) Compared to "use" queries, this mechanism keeps your code simpler, and minimizes the amount of resources that the database server has to keep tied up for you. The downside is, it can cause memory problems if the result set is sufficiently large.

See the documentation for execute() regarding the various overloads. This function has the same set of overloads.

See exec(), execute(), storein(), and use() for alternative query execution mechanisms.

template<class T1>
void mysqlpp::Query::storein T1 &    con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, and store the entire result set in an STL container.

This is a set of specialized template functions that call either storein_sequence() or storein_set(), depending on the type of container you pass it. It understands std::vector, deque, list, slist (a common C++ library extension), set, and multiset.

Like the functions it wraps, this is actually an overloaded set of functions. See the other functions' documentation for details.

Use this function if you think you might someday switch your program from using a set-associative container to a sequence container for storing result sets, or vice versa.

See exec(), execute(), store(), and use() for alternative query execution mechanisms.

template<class T1>
void mysqlpp::Query::storein_sequence T1 &    con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, and store the entire result set in the given STL sequence container.

This is a sort of marriage between "use" queries and "store" queries. It is implemented with a "use" query, but it immediately consumes the results in a loop to populate the given sequence container. (For example, an std::vector.)

There are many overloads for this function, pretty much the same as for execute(), except that there is a Container parameter at the front of the list. So, you can pass a container and a query string, or a container and template query parameters.

See exec(), execute(), store(), and use() for alternative query execution mechanisms.

Parameters:
con  any STL sequence container, such as std::vector
r  whether the query automatically resets after being used

template<class T1>
void mysqlpp::Query::storein_set T1 &    con,
query_reset    r = RESET_QUERY
[inline]
 

Execute a query, and store the entire result set in the given associative STL container.

The same thing as storein_sequence(), except that it's used with associative STL containers, such as std::set.

template<class T>
Query& mysqlpp::Query::update const T &    o,
const T &    n
[inline]
 

Replace an existing row's data with new data.

This function builds an UPDATE SQL query using the new row data for the SET clause, and the old row data for the WHERE clause. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters:
o  old row
n  new row
See also:
insert(), replace()

Reimplemented from mysqlpp::SQLQuery.

ResUse mysqlpp::Query::use   [inline]
 

Execute a query returning data, when you wish to deal with the data one row at a time.

"Use" queries tell the server to send you the results one row at a time. (The name comes from the MySQL C API function that initiates this process, mysql_use_result() .) This saves memory in the client program, but it potentially allows the client to tie up a connection with the database server until the result set is consumed.

See the documentation for execute() regarding the various overloads. This function has the same set of overloads.

See exec(), execute(), store() and storein() for alternative query execution mechanisms.


The documentation for this class was generated from the following files:
Generated on Thu May 5 05:31:30 2005 for MySQL++ by doxygen1.2.18