From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qsqlquery.html | 595 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 595 insertions(+) create mode 100644 doc/html/qsqlquery.html (limited to 'doc/html/qsqlquery.html') diff --git a/doc/html/qsqlquery.html b/doc/html/qsqlquery.html new file mode 100644 index 000000000..e54001124 --- /dev/null +++ b/doc/html/qsqlquery.html @@ -0,0 +1,595 @@ + + + + + +TQSqlQuery Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQSqlQuery Class Reference
[sql module]

+ +

The TQSqlQuery class provides a means of executing and +manipulating SQL statements. +More... +

#include <qsqlquery.h> +

Inherited by TQSqlCursor. +

List of all member functions. +

Public Members

+ +

Protected Members

+ +

Detailed Description

+ + +The TQSqlQuery class provides a means of executing and +manipulating SQL statements. +

+ + +

TQSqlQuery encapsulates the functionality involved in creating, +navigating and retrieving data from SQL queries which are executed +on a TQSqlDatabase. It can be used to execute DML (data +manipulation language) statements, e.g. SELECT, INSERT, UPDATE and DELETE, and also DDL (data definition language) +statements, e.g. CREATE TABLE. It can also be used to +execute database-specific commands which are not standard SQL +(e.g. SET DATESTYLE=ISO for PostgreSQL). +

Successfully executed SQL statements set the query's state to +active (isActive() returns TRUE); otherwise the query's state is +set to inactive. In either case, when executing a new SQL +statement, the query is positioned on an invalid record; an active +query must be navigated to a valid record (so that isValid() +returns TRUE) before values can be retrieved. +

Navigating records is performed with the following functions: +

+

These functions allow the programmer to move forward, backward or +arbitrarily through the records returned by the query. If you only +need to move forward through the results, e.g. using next() or +using seek() with a positive offset, you can use setForwardOnly() +and save a significant amount of memory overhead. Once an active +query is positioned on a valid record, data can be retrieved using +value(). All data is transferred from the SQL backend using +TQVariants. +

For example: +

+    TQSqlQuery query( "SELECT name FROM customer" );
+    while ( query.next() ) {
+        TQString name = query.value(0).toString();
+        doSomething( name );
+    }
+
+ +

To access the data returned by a query, use the value() method. +Each field in the data returned by a SELECT statement is accessed +by passing the field's position in the statement, starting from 0. +Information about the fields can be obtained via TQSqlDatabase::record(). +For the sake of efficiency there are no functions to access a field +by name. (The TQSqlCursor class provides a higher-level interface +with field access by name and automatic SQL generation.) +

TQSqlQuery supports prepared query execution and the binding of +parameter values to placeholders. Some databases don't support +these features, so for them TQt emulates the retquired +functionality. For example, the Oracle and ODBC drivers have +proper prepared query support, and TQt makes use of it; but for +databases that don't have this support, TQt implements the feature +itself, e.g. by replacing placeholders with actual values when a +query is executed. The exception is positional binding using named +placeholders, which retquires that the database supports prepared +queries. +

Oracle databases identify placeholders by using a colon-name +syntax, e.g :name. ODBC simply uses ? characters. TQt +supports both syntaxes (although you can't mix them in the same +query). +

Below we present the same example using each of the four different +binding approaches. +

Named binding using named placeholders +

+    TQSqlQuery query;
+    query.prepare( "INSERT INTO atable (id, forename, surname) "
+                   "VALUES (:id, :forename, :surname)" );
+    query.bindValue( ":id", 1001 );
+    query.bindValue( ":forename", "Bart" );
+    query.bindValue( ":surname", "Simpson" );
+    query.exec();
+
+ +

Positional binding using named placeholders +

+    TQSqlQuery query;
+    query.prepare( "INSERT INTO atable (id, forename, surname) "
+                   "VALUES (:id, :forename, :surname)" );
+    query.bindValue( 0, 1001 );
+    query.bindValue( 1, "Bart" );
+    query.bindValue( 2, "Simpson" );
+    query.exec();
+
+ +Note: Using positional binding with named placeholders will +only work if the database supports prepared queries. This can be +checked with TQSqlDriver::hasFeature() using TQSqlDriver::PreparedQueries +as argument for driver feature. +

Binding values using positional placeholders #1 +

+    TQSqlQuery query;
+    query.prepare( "INSERT INTO atable (id, forename, surname) "
+                   "VALUES (?, ?, ?)" );
+    query.bindValue( 0, 1001 );
+    query.bindValue( 1, "Bart" );
+    query.bindValue( 2, "Simpson" );
+    query.exec();
+
+ +

Binding values using positional placeholders #2 +

+    query.prepare( "INSERT INTO atable (id, forename, surname) "
+                   "VALUES (?, ?, ?)" );
+    query.addBindValue( 1001 );
+    query.addBindValue( "Bart" );
+    query.addBindValue( "Simpson" );
+    query.exec();
+
+ +

Binding values to a stored procedure +This code calls a stored procedure called AsciiToInt(), passing +it a character through its in parameter, and taking its result in +the out parameter. +

+    TQSqlQuery query;
+    query.prepare( "call AsciiToInt(?, ?)" );
+    query.bindValue( 0, "A" );
+    query.bindValue( 1, 0, TQSql::Out );
+    query.exec();
+    int i = query.boundValue( 1 ).toInt(); // i is 65.
+
+ +

See also TQSqlDatabase, TQSqlCursor, TQVariant, and Database Classes. + +

Member Function Documentation

+

TQSqlQuery::TQSqlQuery ( TQSqlResult * r ) +

+Creates a TQSqlQuery object which uses the TQSqlResult r to +communicate with a database. + +

TQSqlQuery::TQSqlQuery ( const TQString & query = TQString::null, TQSqlDatabase * db = 0 ) +

+Creates a TQSqlQuery object using the SQL query and the database +db. If db is 0, (the default), the application's default +database is used. If query is not a null string, it will be +executed. +

See also TQSqlDatabase. + +

explicit TQSqlQuery::TQSqlQuery ( TQSqlDatabase * db ) +

+Creates a TQSqlQuery object using the database db. If db is +0, the application's default database is used. +

See also TQSqlDatabase. + +

TQSqlQuery::TQSqlQuery ( const TQSqlQuery & other ) +

+Constructs a copy of other. + +

TQSqlQuery::~TQSqlQuery () [virtual] +

+Destroys the object and frees any allocated resources. + +

void TQSqlQuery::addBindValue ( const TQVariant & val, TQSql::ParameterType type ) +

+Adds the value val to the list of values when using positional +value binding. The order of the addBindValue() calls determines +which placeholder a value will be bound to in the prepared query. +If type is TQSql::Out or TQSql::InOut, the placeholder will +be overwritten with data from the database after the exec() call. +

See also bindValue(), prepare(), and exec(). + +

void TQSqlQuery::addBindValue ( const TQVariant & val ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Binds the placeholder with type TQSql::In. + +

void TQSqlQuery::afterSeek () [virtual protected] +

+Protected virtual function called after the internal record +pointer is moved to a new record. The default implementation does +nothing. + +

int TQSqlQuery::at () const +

+Returns the current internal position of the query. The first +record is at position zero. If the position is invalid, a +TQSql::Location will be returned indicating the invalid position. +

See also prev(), next(), first(), last(), seek(), isActive(), and isValid(). + +

Example: sql/overview/navigating/main.cpp. +

void TQSqlQuery::beforeSeek () [virtual protected] +

+Protected virtual function called before the internal record +pointer is moved to a new record. The default implementation does +nothing. + +

void TQSqlQuery::bindValue ( const TQString & placeholder, const TQVariant & val, TQSql::ParameterType type ) +

+Set the placeholder placeholder to be bound to value val in +the prepared statement. Note that the placeholder mark (e.g :) +must be included when specifying the placeholder name. If type +is TQSql::Out or TQSql::InOut, the placeholder will be +overwritten with data from the database after the exec() call. +

See also addBindValue(), prepare(), and exec(). + +

void TQSqlQuery::bindValue ( const TQString & placeholder, const TQVariant & val ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Binds the placeholder with type TQSql::In. + +

void TQSqlQuery::bindValue ( int pos, const TQVariant & val ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Binds the placeholder at position pos with type TQSql::In. + +

void TQSqlQuery::bindValue ( int pos, const TQVariant & val, TQSql::ParameterType type ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Set the placeholder in position pos to be bound to value val +in the prepared statement. Field numbering starts at 0. If type +is TQSql::Out or TQSql::InOut, the placeholder will be +overwritten with data from the database after the exec() call. +

See also addBindValue(), prepare(), and exec(). + +

TQVariant TQSqlQuery::boundValue ( const TQString & placeholder ) const +

+Returns the value for the placeholder. + +

TQVariant TQSqlQuery::boundValue ( int pos ) const +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns the value for the placeholder at position pos. + +

TQMap<TQString, TQVariant> TQSqlQuery::boundValues () const +

+Returns a map of the bound values. +

The bound values can be examined in the following way: +

+    TQSqlQuery query;
+    ...
+    // Examine the bound values - bound using named binding
+    TQMap<TQString, TQVariant>::ConstIterator it;
+    TQMap<TQString, TQVariant> vals = query.boundValues();
+    for ( it = vals.begin(); it != vals.end(); ++it )
+        qWarning( "Placeholder: " + it.key() + ", Value: " + (*it).toString() );
+    ...
+
+    // Examine the bound values - bound using positional binding
+    TQValueList<TQVariant>::ConstIterator it;
+    TQValueList<TQVariant> list = query.boundValues().values();
+    int i = 0;
+    for ( it = list.begin(); it != list.end(); ++it )
+        qWarning( "Placeholder pos: %d, Value: " + (*it).toString(), i++ );
+    ...
+
+
+ + +

const TQSqlDriver * TQSqlQuery::driver () const +

+Returns the database driver associated with the query. + +

bool TQSqlQuery::exec ( const TQString & query ) [virtual] +

+Executes the SQL in query. Returns TRUE and sets the query +state to active if the query was successful; otherwise returns +FALSE and sets the query state to inactive. The query string +must use syntax appropriate for the SQL database being queried, +for example, standard SQL. +

After the query is executed, the query is positioned on an invalid record, and must be navigated to a valid record before +data values can be retrieved, e.g. using next(). +

Note that the last error for this query is reset when exec() is +called. +

See also isActive(), isValid(), next(), prev(), first(), last(), and seek(). + +

Examples: sql/overview/basicbrowsing/main.cpp, sql/overview/basicbrowsing2/main.cpp, sql/overview/basicdatamanip/main.cpp, and sql/overview/connection.cpp. +

bool TQSqlQuery::exec () +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Executes a previously prepared SQL query. Returns TRUE if the +query executed successfully; otherwise returns FALSE. +

See also prepare(), bindValue(), and addBindValue(). + +

TQString TQSqlQuery::executedQuery () const +

+Returns the last query that was executed. +

In most cases this function returns the same as lastQuery(). If a +prepared query with placeholders is executed on a DBMS that does +not support it, the preparation of this query is emulated. The +placeholders in the original query are replaced with their bound +values to form a new query. This function returns the modified +query. Useful for debugging purposes. +

See also lastQuery(). + +

bool TQSqlQuery::first () [virtual] +

+Retrieves the first record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and isSelect() must return TRUE before +calling this function or it will do nothing and return FALSE. +Returns TRUE if successful. If unsuccessful the query position is +set to an invalid position and FALSE is returned. +

See also next(), prev(), last(), seek(), at(), isActive(), and isValid(). + +

Example: sql/overview/navigating/main.cpp. +

bool TQSqlQuery::isActive () const +

+Returns TRUE if the query is currently active; otherwise returns +FALSE. + +

Examples: sql/overview/basicbrowsing/main.cpp, sql/overview/basicbrowsing2/main.cpp, sql/overview/basicdatamanip/main.cpp, sql/overview/navigating/main.cpp, and sql/overview/retrieve1/main.cpp. +

bool TQSqlQuery::isForwardOnly () const +

+Returns TRUE if you can only scroll forward through a result +set; otherwise returns FALSE. +

See also setForwardOnly(). + +

bool TQSqlQuery::isNull ( int field ) const +

+Returns TRUE if the query is active and positioned on a valid +record and the field is NULL; otherwise returns FALSE. Note +that for some drivers isNull() will not return accurate +information until after an attempt is made to retrieve data. +

See also isActive(), isValid(), and value(). + +

bool TQSqlQuery::isSelect () const +

+Returns TRUE if the current query is a SELECT statement; +otherwise returns FALSE. + +

bool TQSqlQuery::isValid () const +

+Returns TRUE if the query is currently positioned on a valid +record; otherwise returns FALSE. + +

bool TQSqlQuery::last () [virtual] +

+Retrieves the last record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and isSelect() must return TRUE before +calling this function or it will do nothing and return FALSE. +Returns TRUE if successful. If unsuccessful the query position is +set to an invalid position and FALSE is returned. +

See also next(), prev(), first(), seek(), at(), isActive(), and isValid(). + +

Example: sql/overview/navigating/main.cpp. +

TQSqlError TQSqlQuery::lastError () const +

+Returns error information about the last error (if any) that +occurred. +

See also TQSqlError. + +

TQString TQSqlQuery::lastQuery () const +

+Returns the text of the current query being used, or TQString::null +if there is no current query text. +

See also executedQuery(). + +

bool TQSqlQuery::next () [virtual] +

+Retrieves the next record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and isSelect() must return TRUE before +calling this function or it will do nothing and return FALSE. +

The following rules apply: +

+

If the record could not be retrieved, the result is positioned after +the last record and FALSE is returned. If the record is successfully +retrieved, TRUE is returned. +

See also prev(), first(), last(), seek(), at(), isActive(), and isValid(). + +

Examples: sql/overview/basicbrowsing/main.cpp, sql/overview/basicbrowsing2/main.cpp, sql/overview/delete/main.cpp, sql/overview/order1/main.cpp, sql/overview/retrieve1/main.cpp, sql/overview/subclass4/main.cpp, and sql/overview/subclass5/main.cpp. +

int TQSqlQuery::numRowsAffected () const +

+Returns the number of rows affected by the result's SQL statement, +or -1 if it cannot be determined. Note that for SELECT +statements, the value is undefined; see size() instead. If the +query is not active (isActive() returns FALSE), -1 is returned. +

See also size() and TQSqlDriver::hasFeature(). + +

Examples: sql/overview/basicbrowsing2/main.cpp and sql/overview/basicdatamanip/main.cpp. +

TQSqlQuery & TQSqlQuery::operator= ( const TQSqlQuery & other ) +

+Assigns other to the query. + +

bool TQSqlQuery::prepare ( const TQString & query ) +

+Prepares the SQL query query for execution. The query may +contain placeholders for binding values. Both Oracle style +colon-name (e.g. :surname), and ODBC style (e.g. ?) +placeholders are supported; but they cannot be mixed in the same +query. See the Description for examples. +

See also exec(), bindValue(), and addBindValue(). + +

bool TQSqlQuery::prev () [virtual] +

+Retrieves the previous record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and isSelect() must return TRUE before +calling this function or it will do nothing and return FALSE. +

The following rules apply: +

+

If the record could not be retrieved, the result is positioned +before the first record and FALSE is returned. If the record is +successfully retrieved, TRUE is returned. +

See also next(), first(), last(), seek(), at(), isActive(), and isValid(). + +

const TQSqlResult * TQSqlQuery::result () const +

+Returns the result associated with the query. + +

bool TQSqlQuery::seek ( int i, bool relative = FALSE ) [virtual] +

+Retrieves the record at position (offset) i, if available, and +positions the query on the retrieved record. The first record is +at position 0. Note that the query must be in an active state and +isSelect() must return TRUE before calling this function. +

If relative is FALSE (the default), the following rules apply: +

+

If relative is TRUE, the following rules apply: +

+

See also next(), prev(), first(), last(), at(), isActive(), and isValid(). + +

Example: sql/overview/navigating/main.cpp. +

void TQSqlQuery::setForwardOnly ( bool forward ) +

+Sets forward only mode to forward. If forward is TRUE only +next(), and seek() with positive values, are allowed for +navigating the results. Forward only mode needs far less memory +since results do not need to be cached. +

Forward only mode is off by default. +

Forward only mode cannot be used with data aware widgets like +TQDataTable, since they must to be able to scroll backward as well +as forward. +

See also isForwardOnly(), next(), and seek(). + +

int TQSqlQuery::size () const +

+Returns the size of the result, (number of rows returned), or -1 +if the size cannot be determined or if the database does not +support reporting information about query sizes. Note that for +non-SELECT statements (isSelect() returns FALSE), size() will +return -1. If the query is not active (isActive() returns FALSE), +-1 is returned. +

To determine the number of rows affected by a non-SELECT +statement, use numRowsAffected(). +

See also isActive(), numRowsAffected(), and TQSqlDriver::hasFeature(). + +

Example: sql/overview/navigating/main.cpp. +

TQVariant TQSqlQuery::value ( int i ) const [virtual] +

+Returns the value of the i-th field in the query (zero based). +

The fields are numbered from left to right using the text of the +SELECT statement, e.g. in SELECT forename, surname FROM people, +field 0 is forename and field 1 is surname. Using SELECT * +is not recommended because the order of the fields in the query is +undefined. +

An invalid TQVariant is returned if field i does not exist, if +the query is inactive, or if the query is positioned on an invalid +record. +

See also prev(), next(), first(), last(), seek(), isActive(), and isValid(). + +

Examples: sql/overview/basicbrowsing/main.cpp, sql/overview/basicbrowsing2/main.cpp, sql/overview/retrieve1/main.cpp, sql/overview/subclass3/main.cpp, sql/overview/subclass4/main.cpp, sql/overview/subclass5/main.cpp, and sql/overview/table4/main.cpp. + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.3