From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/qsqlquery.html | 595 ------------------------------------------------ 1 file changed, 595 deletions(-) delete mode 100644 doc/html/qsqlquery.html (limited to 'doc/html/qsqlquery.html') diff --git a/doc/html/qsqlquery.html b/doc/html/qsqlquery.html deleted file mode 100644 index 373f0ad1e..000000000 --- a/doc/html/qsqlquery.html +++ /dev/null @@ -1,595 +0,0 @@ - - - - - -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 required -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 requires 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.1