1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtSql module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qsqlquery.h"

    43 

    44 //#define QT_DEBUG_SQL

    45 

    46 #include "qatomic.h"

    47 #include "qsqlrecord.h"

    48 #include "qsqlresult.h"

    49 #include "qsqldriver.h"

    50 #include "qsqldatabase.h"

    51 #include "private/qsqlnulldriver_p.h"

    52 #include "qvector.h"

    53 #include "qmap.h"

    54 

    55 QT_BEGIN_NAMESPACE

    56 

    57 class QSqlQueryPrivate

    58 {

    59 public:

    60     QSqlQueryPrivate(QSqlResult* result);

    61     ~QSqlQueryPrivate();

    62     QAtomicInt ref;

    63     QSqlResult* sqlResult;

    64 

    65     static QSqlQueryPrivate* shared_null();

    66 };

    67 

    68 Q_GLOBAL_STATIC_WITH_ARGS(QSqlQueryPrivate, nullQueryPrivate, (0))

    69 Q_GLOBAL_STATIC(QSqlNullDriver, nullDriver)

    70 Q_GLOBAL_STATIC_WITH_ARGS(QSqlNullResult, nullResult, (nullDriver()))

    71 

    72 QSqlQueryPrivate* QSqlQueryPrivate::shared_null()

    73 {

    74     QSqlQueryPrivate *null = nullQueryPrivate();

    75     null->ref.ref();

    76     return null;

    77 }

    78 

    79 /*!

    80 \internal

    81 */

    82 QSqlQueryPrivate::QSqlQueryPrivate(QSqlResult* result)

    83     : ref(1), sqlResult(result)

    84 {

    85     if (!sqlResult)

    86         sqlResult = nullResult();

    87 }

    88 

    89 QSqlQueryPrivate::~QSqlQueryPrivate()

    90 {

    91     QSqlResult *nr = nullResult();

    92     if (!nr || sqlResult == nr)

    93         return;

    94     delete sqlResult;

    95 }

    96 

    97 /*!

    98     \class QSqlQuery

    99     \brief The QSqlQuery class provides a means of executing and

   100     manipulating SQL statements.

   101 

   102     \ingroup database

   103     \ingroup shared

   104 

   105     \inmodule QtSql

   106 

   107     QSqlQuery encapsulates the functionality involved in creating,

   108     navigating and retrieving data from SQL queries which are

   109     executed on a \l QSqlDatabase. It can be used to execute DML

   110     (data manipulation language) statements, such as \c SELECT, \c

   111     INSERT, \c UPDATE and \c DELETE, as well as DDL (data definition

   112     language) statements, such as \c{CREATE} \c{TABLE}. It can also

   113     be used to execute database-specific commands which are not

   114     standard SQL (e.g. \c{SET DATESTYLE=ISO} for PostgreSQL).

   115 

   116     Successfully executed SQL statements set the query's state to

   117     active so that isActive() returns true. Otherwise the query's

   118     state is set to inactive. In either case, when executing a new SQL

   119     statement, the query is positioned on an invalid record. An active

   120     query must be navigated to a valid record (so that isValid()

   121     returns true) before values can be retrieved.

   122 

   123     For some databases, if an active query that is a \c{SELECT}

   124     statement exists when you call \l{QSqlDatabase::}{commit()} or

   125     \l{QSqlDatabase::}{rollback()}, the commit or rollback will

   126     fail. See isActive() for details.

   127 

   128     \target QSqlQuery examples

   129 

   130     Navigating records is performed with the following functions:

   131 

   132     \list

   133     \o next()

   134     \o previous()

   135     \o first()

   136     \o last()

   137     \o seek()

   138     \endlist

   139 

   140     These functions allow the programmer to move forward, backward

   141     or arbitrarily through the records returned by the query. If you

   142     only need to move forward through the results (e.g., by using

   143     next()), you can use setForwardOnly(), which will save a

   144     significant amount of memory overhead and improve performance on

   145     some databases. Once an active query is positioned on a valid

   146     record, data can be retrieved using value(). All data is

   147     transferred from the SQL backend using QVariants.

   148 

   149     For example:

   150 

   151     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 7

   152 

   153     To access the data returned by a query, use value(int). Each

   154     field in the data returned by a \c SELECT statement is accessed

   155     by passing the field's position in the statement, starting from

   156     0. This makes using \c{SELECT *} queries inadvisable because the

   157     order of the fields returned is indeterminate.

   158 

   159     For the sake of efficiency, there are no functions to access a

   160     field by name (unless you use prepared queries with names, as

   161     explained below). To convert a field name into an index, use

   162     record().\l{QSqlRecord::indexOf()}{indexOf()}, for example:

   163 

   164     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 8

   165 

   166     QSqlQuery supports prepared query execution and the binding of

   167     parameter values to placeholders. Some databases don't support

   168     these features, so for those, Qt emulates the required

   169     functionality. For example, the Oracle and ODBC drivers have

   170     proper prepared query support, and Qt makes use of it; but for

   171     databases that don't have this support, Qt implements the feature

   172     itself, e.g. by replacing placeholders with actual values when a

   173     query is executed. Use numRowsAffected() to find out how many rows

   174     were affected by a non-\c SELECT query, and size() to find how

   175     many were retrieved by a \c SELECT.

   176 

   177     Oracle databases identify placeholders by using a colon-name

   178     syntax, e.g \c{:name}. ODBC simply uses \c ? characters. Qt

   179     supports both syntaxes, with the restriction that you can't mix

   180     them in the same query.

   181 

   182     You can retrieve the values of all the fields in a single variable

   183     (a map) using boundValues().

   184 

   185     \section1 Approaches to Binding Values

   186 

   187     Below we present the same example using each of the four

   188     different binding approaches, as well as one example of binding

   189     values to a stored procedure.

   190 

   191     \bold{Named binding using named placeholders:}

   192 

   193     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9

   194 

   195     \bold{Positional binding using named placeholders:}

   196 

   197     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 10

   198 

   199     \bold{Binding values using positional placeholders (version 1):}

   200 

   201     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 11

   202 

   203     \bold{Binding values using positional placeholders (version 2):}

   204 

   205     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 12

   206 

   207     \bold{Binding values to a stored procedure:}

   208 

   209     This code calls a stored procedure called \c AsciiToInt(), passing

   210     it a character through its in parameter, and taking its result in

   211     the out parameter.

   212 

   213     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 13

   214 

   215     Note that unbound parameters will retain their values.

   216 

   217     Stored procedures that uses the return statement to return values,

   218     or return multiple result sets, are not fully supported. For specific

   219     details see \l{SQL Database Drivers}.

   220 

   221     \warning You must load the SQL driver and open the connection before a

   222     QSqlQuery is created. Also, the connection must remain open while the

   223     query exists; otherwise, the behavior of QSqlQuery is undefined.

   224 

   225     \sa QSqlDatabase, QSqlQueryModel, QSqlTableModel, QVariant

   226 */

   227 

   228 /*!

   229     Constructs a QSqlQuery object which uses the QSqlResult \a result

   230     to communicate with a database.

   231 */

   232 

   233 QSqlQuery::QSqlQuery(QSqlResult *result)

   234 {

   235     d = new QSqlQueryPrivate(result);

   236 }

   237 

   238 /*!

   239     Destroys the object and frees any allocated resources.

   240 */

   241 

   242 QSqlQuery::~QSqlQuery()

   243 {

   244     if (!d->ref.deref())

   245         delete d;

   246 }

   247 

   248 /*!

   249     Constructs a copy of \a other.

   250 */

   251 

   252 QSqlQuery::QSqlQuery(const QSqlQuery& other)

   253 {

   254     d = other.d;

   255     d->ref.ref();

   256 }

   257 

   258 /*!

   259     \internal

   260 */

   261 static void qInit(QSqlQuery *q, const QString& query, QSqlDatabase db)

   262 {

   263     QSqlDatabase database = db;

   264     if (!database.isValid())

   265         database = QSqlDatabase::database(QLatin1String(QSqlDatabase::defaultConnection), false);

   266     if (database.isValid()) {

   267         *q = QSqlQuery(database.driver()->createResult());

   268     }

   269     if (!query.isEmpty())

   270         q->exec(query);

   271 }

   272 

   273 /*!

   274     Constructs a QSqlQuery object using the SQL \a query and the

   275     database \a db. If \a db is not specified, the application's

   276     default database is used. If \a query is not an empty string, it

   277     will be executed.

   278 

   279     \sa QSqlDatabase

   280 */

   281 QSqlQuery::QSqlQuery(const QString& query, QSqlDatabase db)

   282 {

   283     d = QSqlQueryPrivate::shared_null();

   284     qInit(this, query, db);

   285 }

   286 

   287 /*!

   288     Constructs a QSqlQuery object using the database \a db.

   289 

   290     \sa QSqlDatabase

   291 */

   292 

   293 QSqlQuery::QSqlQuery(QSqlDatabase db)

   294 {

   295     d = QSqlQueryPrivate::shared_null();

   296     qInit(this, QString(), db);

   297 }

   298 

   299 

   300 /*!

   301     Assigns \a other to this object.

   302 */

   303 

   304 QSqlQuery& QSqlQuery::operator=(const QSqlQuery& other)

   305 {

   306     qAtomicAssign(d, other.d);

   307     return *this;

   308 }

   309 

   310 /*!

   311   Returns true if the query is \l{isActive()}{active} and positioned

   312   on a valid record and the \a field is NULL; otherwise returns

   313   false. Note that for some drivers, isNull() will not return accurate

   314   information until after an attempt is made to retrieve data.

   315 

   316   \sa isActive(), isValid(), value()

   317 */

   318 

   319 bool QSqlQuery::isNull(int field) const

   320 {

   321     if (d->sqlResult->isActive() && d->sqlResult->isValid())

   322         return d->sqlResult->isNull(field);

   323     return true;

   324 }

   325 

   326 /*!

   327   

   328   Executes the SQL in \a query. Returns true and sets the query state

   329   to \l{isActive()}{active} if the query was successful; otherwise

   330   returns false. The \a query string must use syntax appropriate for

   331   the SQL database being queried (for example, standard SQL).

   332 

   333   After the query is executed, the query is positioned on an \e

   334   invalid record and must be navigated to a valid record before data

   335   values can be retrieved (for example, using next()).

   336 

   337   Note that the last error for this query is reset when exec() is

   338   called.

   339 

   340   Example:

   341 

   342   \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 34

   343 

   344   \sa isActive(), isValid(), next(), previous(), first(), last(),

   345   seek()

   346 */

   347 

   348 bool QSqlQuery::exec(const QString& query)

   349 {

   350     if (d->ref != 1) {

   351         bool fo = isForwardOnly();

   352         *this = QSqlQuery(driver()->createResult());

   353         d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());

   354         setForwardOnly(fo);

   355     } else {

   356         d->sqlResult->clear();

   357         d->sqlResult->setActive(false);

   358         d->sqlResult->setLastError(QSqlError());

   359         d->sqlResult->setAt(QSql::BeforeFirstRow);

   360         d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());

   361     }

   362     d->sqlResult->setQuery(query.trimmed());

   363     if (!driver()->isOpen() || driver()->isOpenError()) {

   364         qWarning("QSqlQuery::exec: database not open");

   365         return false;

   366     }

   367     if (query.isEmpty()) {

   368         qWarning("QSqlQuery::exec: empty query");

   369         return false;

   370     }

   371 #ifdef QT_DEBUG_SQL

   372     qDebug("\n QSqlQuery: %s", query.toLocal8Bit().constData());

   373 #endif

   374     return d->sqlResult->reset(query);

   375 }

   376 

   377 /*!

   378     Returns the value of field \a index in the current record.

   379 

   380     The fields are numbered from left to right using the text of the

   381     \c SELECT statement, e.g. in

   382 

   383     \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 0

   384 

   385     field 0 is \c forename and field 1 is \c

   386     surname. Using \c{SELECT *} is not recommended because the order

   387     of the fields in the query is undefined.

   388 

   389     An invalid QVariant is returned if field \a index does not

   390     exist, if the query is inactive, or if the query is positioned on

   391     an invalid record.

   392 

   393     \sa previous() next() first() last() seek() isActive() isValid()

   394 */

   395 

   396 QVariant QSqlQuery::value(int index) const

   397 {

   398     if (isActive() && isValid() && (index > QSql::BeforeFirstRow))

   399         return d->sqlResult->data(index);

   400     qWarning("QSqlQuery::value: not positioned on a valid record");

   401     return QVariant();

   402 }

   403 

   404 /*!

   405     Returns the current internal position of the query. The first

   406     record is at position zero. If the position is invalid, the

   407     function returns QSql::BeforeFirstRow or

   408     QSql::AfterLastRow, which are special negative values.

   409 

   410     \sa previous() next() first() last() seek() isActive() isValid()

   411 */

   412 

   413 int QSqlQuery::at() const

   414 {

   415     return d->sqlResult->at();

   416 }

   417 

   418 /*!

   419     Returns the text of the current query being used, or an empty

   420     string if there is no current query text.

   421 

   422     \sa executedQuery()

   423 */

   424 

   425 QString QSqlQuery::lastQuery() const

   426 {

   427     return d->sqlResult->lastQuery();

   428 }

   429 

   430 /*!

   431     Returns the database driver associated with the query.

   432 */

   433 

   434 const QSqlDriver *QSqlQuery::driver() const

   435 {

   436     return d->sqlResult->driver();

   437 }

   438 

   439 /*!

   440     Returns the result associated with the query.

   441 */

   442 

   443 const QSqlResult* QSqlQuery::result() const

   444 {

   445     return d->sqlResult;

   446 }

   447 

   448 /*!

   449   Retrieves the record at position \a index, if available, and

   450   positions the query on the retrieved record. The first record is at

   451   position 0. Note that the query must be in an \l{isActive()}

   452   {active} state and isSelect() must return true before calling this

   453   function.

   454 

   455   If \a relative is false (the default), the following rules apply:

   456 

   457   \list

   458 

   459   \o If \a index is negative, the result is positioned before the

   460   first record and false is returned.

   461 

   462   \o Otherwise, an attempt is made to move to the record at position

   463   \a index. If the record at position \a index could not be retrieved,

   464   the result is positioned after the last record and false is

   465   returned. If the record is successfully retrieved, true is returned.

   466 

   467   \endlist

   468 

   469   If \a relative is true, the following rules apply:

   470 

   471   \list

   472 

   473   \o If the result is currently positioned before the first record or

   474   on the first record, and \a index is negative, there is no change,

   475   and false is returned.

   476 

   477   \o If the result is currently located after the last record, and \a

   478   index is positive, there is no change, and false is returned.

   479 

   480   \o If the result is currently located somewhere in the middle, and

   481   the relative offset \a index moves the result below zero, the result

   482   is positioned before the first record and false is returned.

   483 

   484   \o Otherwise, an attempt is made to move to the record \a index

   485   records ahead of the current record (or \a index records behind the

   486   current record if \a index is negative). If the record at offset \a

   487   index could not be retrieved, the result is positioned after the

   488   last record if \a index >= 0, (or before the first record if \a

   489   index is negative), and false is returned. If the record is

   490   successfully retrieved, true is returned.

   491 

   492   \endlist

   493 

   494   \sa next() previous() first() last() at() isActive() isValid()

   495 */

   496 bool QSqlQuery::seek(int index, bool relative)

   497 {

   498     if (!isSelect() || !isActive())

   499         return false;

   500     int actualIdx;

   501     if (!relative) { // arbitrary seek

   502         if (index < 0) {

   503             d->sqlResult->setAt(QSql::BeforeFirstRow);

   504             return false;

   505         }

   506         actualIdx = index;

   507     } else {

   508         switch (at()) { // relative seek

   509         case QSql::BeforeFirstRow:

   510             if (index > 0)

   511                 actualIdx = index;

   512             else {

   513                 return false;

   514             }

   515             break;

   516         case QSql::AfterLastRow:

   517             if (index < 0) {

   518                 d->sqlResult->fetchLast();

   519                 actualIdx = at() + index;

   520             } else {

   521                 return false;

   522             }

   523             break;

   524         default:

   525             if ((at() + index) < 0) {

   526                 d->sqlResult->setAt(QSql::BeforeFirstRow);

   527                 return false;

   528             }

   529             actualIdx = at() + index;

   530             break;

   531         }

   532     }

   533     // let drivers optimize

   534     if (isForwardOnly() && actualIdx < at()) {

   535         qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");

   536         return false;

   537     }

   538     if (actualIdx == (at() + 1) && at() != QSql::BeforeFirstRow) {

   539         if (!d->sqlResult->fetchNext()) {

   540             d->sqlResult->setAt(QSql::AfterLastRow);

   541             return false;

   542         }

   543         return true;

   544     }

   545     if (actualIdx == (at() - 1)) {

   546         if (!d->sqlResult->fetchPrevious()) {

   547             d->sqlResult->setAt(QSql::BeforeFirstRow);

   548             return false;

   549         }

   550         return true;

   551     }

   552     if (!d->sqlResult->fetch(actualIdx)) {

   553         d->sqlResult->setAt(QSql::AfterLastRow);

   554         return false;

   555     }

   556     return true;

   557 }

   558 

   559 /*!

   560   

   561   Retrieves the next record in the result, if available, and positions

   562   the query on the retrieved record. Note that the result must be in

   563   the \l{isActive()}{active} state and isSelect() must return true

   564   before calling this function or it will do nothing and return false.

   565 

   566   The following rules apply:

   567 

   568   \list

   569 

   570   \o If the result is currently located before the first record,

   571   e.g. immediately after a query is executed, an attempt is made to

   572   retrieve the first record.

   573 

   574   \o If the result is currently located after the last record, there

   575   is no change and false is returned.

   576 

   577   \o If the result is located somewhere in the middle, an attempt is

   578   made to retrieve the next record.

   579 

   580   \endlist

   581 

   582   If the record could not be retrieved, the result is positioned after

   583   the last record and false is returned. If the record is successfully

   584   retrieved, true is returned.

   585 

   586   \sa previous() first() last() seek() at() isActive() isValid()

   587 */

   588 bool QSqlQuery::next()

   589 {

   590     if (!isSelect() || !isActive())

   591         return false;

   592     bool b = false;

   593     switch (at()) {

   594     case QSql::BeforeFirstRow:

   595         b = d->sqlResult->fetchFirst();

   596         return b;

   597     case QSql::AfterLastRow:

   598         return false;

   599     default:

   600         if (!d->sqlResult->fetchNext()) {

   601             d->sqlResult->setAt(QSql::AfterLastRow);

   602             return false;

   603         }

   604         return true;

   605     }

   606 }

   607 

   608 /*!

   609 

   610   Retrieves the previous record in the result, if available, and

   611   positions the query on the retrieved record. Note that the result

   612   must be in the \l{isActive()}{active} state and isSelect() must

   613   return true before calling this function or it will do nothing and

   614   return false.

   615 

   616   The following rules apply:

   617 

   618   \list

   619 

   620   \o If the result is currently located before the first record, there

   621   is no change and false is returned.

   622 

   623   \o If the result is currently located after the last record, an

   624   attempt is made to retrieve the last record.

   625 

   626   \o If the result is somewhere in the middle, an attempt is made to

   627   retrieve the previous record.

   628 

   629   \endlist

   630 

   631   If the record could not be retrieved, the result is positioned

   632   before the first record and false is returned. If the record is

   633   successfully retrieved, true is returned.

   634 

   635   \sa next() first() last() seek() at() isActive() isValid()

   636 */

   637 bool QSqlQuery::previous()

   638 {

   639     if (!isSelect() || !isActive())

   640         return false;

   641     if (isForwardOnly()) {

   642         qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");

   643         return false;

   644     }

   645 

   646     bool b = false;

   647     switch (at()) {

   648     case QSql::BeforeFirstRow:

   649         return false;

   650     case QSql::AfterLastRow:

   651         b = d->sqlResult->fetchLast();

   652         return b;

   653     default:

   654         if (!d->sqlResult->fetchPrevious()) {

   655             d->sqlResult->setAt(QSql::BeforeFirstRow);

   656             return false;

   657         }

   658         return true;

   659     }

   660 }

   661 

   662 /*!

   663   Retrieves the first record in the result, if available, and

   664   positions the query on the retrieved record. Note that the result

   665   must be in the \l{isActive()}{active} state and isSelect() must

   666   return true before calling this function or it will do nothing and

   667   return false.  Returns true if successful. If unsuccessful the query

   668   position is set to an invalid position and false is returned.

   669 

   670   \sa next() previous() last() seek() at() isActive() isValid()

   671  */

   672 bool QSqlQuery::first()

   673 {

   674     if (!isSelect() || !isActive())

   675         return false;

   676     if (isForwardOnly() && at() > QSql::BeforeFirstRow) {

   677         qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");

   678         return false;

   679     }

   680     bool b = false;

   681     b = d->sqlResult->fetchFirst();

   682     return b;

   683 }

   684 

   685 /*!

   686 

   687   Retrieves the last record in the result, if available, and positions

   688   the query on the retrieved record. Note that the result must be in

   689   the \l{isActive()}{active} state and isSelect() must return true

   690   before calling this function or it will do nothing and return false.

   691   Returns true if successful. If unsuccessful the query position is

   692   set to an invalid position and false is returned.

   693 

   694   \sa next() previous() first() seek() at() isActive() isValid()

   695 */

   696 

   697 bool QSqlQuery::last()

   698 {

   699     if (!isSelect() || !isActive())

   700         return false;

   701     bool b = false;

   702     b = d->sqlResult->fetchLast();

   703     return b;

   704 }

   705 

   706 /*!

   707   Returns the size of the result (number of rows returned), or -1 if

   708   the size cannot be determined or if the database does not support

   709   reporting information about query sizes. Note that for non-\c SELECT

   710   statements (isSelect() returns false), size() will return -1. If the

   711   query is not active (isActive() returns false), -1 is returned.

   712 

   713   To determine the number of rows affected by a non-\c SELECT

   714   statement, use numRowsAffected().

   715 

   716   \sa isActive() numRowsAffected() QSqlDriver::hasFeature()

   717 */

   718 int QSqlQuery::size() const

   719 {

   720     if (isActive() && d->sqlResult->driver()->hasFeature(QSqlDriver::QuerySize))

   721         return d->sqlResult->size();

   722     return -1;

   723 }

   724 

   725 /*!

   726   Returns the number of rows affected by the result's SQL statement,

   727   or -1 if it cannot be determined. Note that for \c SELECT

   728   statements, the value is undefined; use size() instead. If the query

   729   is not \l{isActive()}{active}, -1 is returned.

   730 

   731   \sa size() QSqlDriver::hasFeature()

   732 */

   733 

   734 int QSqlQuery::numRowsAffected() const

   735 {

   736     if (isActive())

   737         return d->sqlResult->numRowsAffected();

   738     return -1;

   739 }

   740 

   741 /*!

   742   Returns error information about the last error (if any) that

   743   occurred with this query.

   744 

   745   \sa QSqlError, QSqlDatabase::lastError()

   746 */

   747 

   748 QSqlError QSqlQuery::lastError() const

   749 {

   750     return d->sqlResult->lastError();

   751 }

   752 

   753 /*!

   754   Returns true if the query is currently positioned on a valid

   755   record; otherwise returns false.

   756 */

   757 

   758 bool QSqlQuery::isValid() const

   759 {

   760     return d->sqlResult->isValid();

   761 }

   762 

   763 /*!

   764   

   765   Returns true if the query is \e{active}. An active QSqlQuery is one

   766   that has been \l{QSqlQuery::exec()} {exec()'d} successfully but not

   767   yet finished with.  When you are finished with an active query, you

   768   can make make the query inactive by calling finish() or clear(), or

   769   you can delete the QSqlQuery instance.

   770 

   771   \note Of particular interest is an active query that is a \c{SELECT}

   772   statement. For some databases that support transactions, an active

   773   query that is a \c{SELECT} statement can cause a \l{QSqlDatabase::}

   774   {commit()} or a \l{QSqlDatabase::} {rollback()} to fail, so before

   775   committing or rolling back, you should make your active \c{SELECT}

   776   statement query inactive using one of the ways listed above.

   777 

   778   \sa isSelect()

   779  */

   780 bool QSqlQuery::isActive() const

   781 {

   782     return d->sqlResult->isActive();

   783 }

   784 

   785 /*!

   786   Returns true if the current query is a \c SELECT statement;

   787   otherwise returns false.

   788 */

   789 

   790 bool QSqlQuery::isSelect() const

   791 {

   792     return d->sqlResult->isSelect();

   793 }

   794 

   795 /*!

   796   Returns true if you can only scroll forward through a result set;

   797   otherwise returns false.

   798 

   799   \sa setForwardOnly(), next()

   800 */

   801 bool QSqlQuery::isForwardOnly() const

   802 {

   803     return d->sqlResult->isForwardOnly();

   804 }

   805 

   806 /*!

   807   Sets forward only mode to \a forward. If \a forward is true, only

   808   next() and seek() with positive values, are allowed for navigating

   809   the results.

   810 

   811   Forward only mode can be (depending on the driver) more memory

   812   efficient since results do not need to be cached. It will also

   813   improve performance on some databases. For this to be true, you must

   814   call \c setForwardOnly() before the query is prepared or executed.

   815   Note that the constructor that takes a query and a database may

   816   execute the query.

   817 

   818   Forward only mode is off by default.

   819 

   820   Setting forward only to false is a suggestion to the database engine,

   821   which has the final say on whether a result set is forward only or

   822   scrollable. isForwardOnly() will always return the correct status of

   823   the result set.

   824 

   825   \sa isForwardOnly(), next(), seek(), QSqlResult::setForwardOnly()

   826 */

   827 void QSqlQuery::setForwardOnly(bool forward)

   828 {

   829     d->sqlResult->setForwardOnly(forward);

   830 }

   831 

   832 /*!

   833   Returns a QSqlRecord containing the field information for the

   834   current query. If the query points to a valid row (isValid() returns

   835   true), the record is populated with the row's values.  An empty

   836   record is returned when there is no active query (isActive() returns

   837   false).

   838 

   839   To retrieve values from a query, value() should be used since

   840   its index-based lookup is faster.

   841 

   842   In the following example, a \c{SELECT * FROM} query is executed.

   843   Since the order of the columns is not defined, QSqlRecord::indexOf()

   844   is used to obtain the index of a column.

   845 

   846   \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 1

   847 

   848   \sa value()

   849 */

   850 QSqlRecord QSqlQuery::record() const

   851 {

   852     QSqlRecord rec = d->sqlResult->record();

   853 

   854     if (isValid()) {

   855         for (int i = 0; i < rec.count(); ++i)

   856             rec.setValue(i, value(i));

   857     }

   858     return rec;

   859 }

   860 

   861 /*!

   862   Clears the result set and releases any resources held by the

   863   query. Sets the query state to inactive. You should rarely if ever

   864   need to call this function.

   865 */

   866 void QSqlQuery::clear()

   867 {

   868     *this = QSqlQuery(driver()->createResult());

   869 }

   870 

   871 /*!

   872   Prepares the SQL query \a query for execution. Returns true if the

   873   query is prepared successfully; otherwise returns false.

   874 

   875   The query may contain placeholders for binding values. Both Oracle

   876   style colon-name (e.g., \c{:surname}), and ODBC style (\c{?})

   877   placeholders are supported; but they cannot be mixed in the same

   878   query. See the \l{QSqlQuery examples}{Detailed Description} for

   879   examples.

   880 

   881   Portability note: Some databases choose to delay preparing a query

   882   until it is executed the first time. In this case, preparing a

   883   syntactically wrong query succeeds, but every consecutive exec()

   884   will fail.

   885 

   886   Example:

   887 

   888   \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9

   889 

   890   \sa exec(), bindValue(), addBindValue()

   891 */

   892 bool QSqlQuery::prepare(const QString& query)

   893 {

   894     if (d->ref != 1) {

   895         bool fo = isForwardOnly();

   896         *this = QSqlQuery(driver()->createResult());

   897         setForwardOnly(fo);

   898         d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());

   899     } else {

   900         d->sqlResult->setActive(false);

   901         d->sqlResult->setLastError(QSqlError());

   902         d->sqlResult->setAt(QSql::BeforeFirstRow);

   903         d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());

   904     }

   905     if (!driver()) {

   906         qWarning("QSqlQuery::prepare: no driver");

   907         return false;

   908     }

   909     if (!driver()->isOpen() || driver()->isOpenError()) {

   910         qWarning("QSqlQuery::prepare: database not open");

   911         return false;

   912     }

   913     if (query.isEmpty()) {

   914         qWarning("QSqlQuery::prepare: empty query");

   915         return false;

   916     }

   917 #ifdef QT_DEBUG_SQL

   918     qDebug("\n QSqlQuery::prepare: %s", query.toLocal8Bit().constData());

   919 #endif

   920     return d->sqlResult->savePrepare(query);

   921 }

   922 

   923 /*!

   924   Executes a previously prepared SQL query. Returns true if the query

   925   executed successfully; otherwise returns false.

   926 

   927   Note that the last error for this query is reset when exec() is

   928   called.

   929 

   930   \sa prepare() bindValue() addBindValue() boundValue() boundValues()

   931 */

   932 bool QSqlQuery::exec()

   933 {

   934     d->sqlResult->resetBindCount();

   935 

   936     if (d->sqlResult->lastError().isValid())

   937         d->sqlResult->setLastError(QSqlError());

   938 

   939     return d->sqlResult->exec();

   940 }

   941 

   942 /*! \enum QSqlQuery::BatchExecutionMode

   943 

   944     \value ValuesAsRows - Updates multiple rows. Treats every entry in a QVariantList as a value for updating the next row.

   945     \value ValuesAsColumns - Updates a single row. Treats every entry in a QVariantList as a single value of an array type.

   946 */

   947 

   948 /*!

   949     \since 4.2

   950 

   951   Executes a previously prepared SQL query in a batch. All the bound

   952   parameters have to be lists of variants. If the database doesn't

   953   support batch executions, the driver will simulate it using

   954   conventional exec() calls.

   955 

   956   Returns true if the query is executed successfully; otherwise

   957   returns false.

   958 

   959   Example:

   960 

   961   \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 2

   962 

   963   The example above inserts four new rows into \c myTable:

   964 

   965   \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 3

   966 

   967   To bind NULL values, a null QVariant of the relevant type has to be

   968   added to the bound QVariantList; for example, \c

   969   {QVariant(QVariant::String)} should be used if you are using

   970   strings.

   971 

   972   \note Every bound QVariantList must contain the same amount of

   973   variants.

   974 

   975   \note The type of the QVariants in a list must not change. For

   976   example, you cannot mix integer and string variants within a

   977   QVariantList.

   978 

   979   The \a mode parameter indicates how the bound QVariantList will be

   980   interpreted.  If \a mode is \c ValuesAsRows, every variant within

   981   the QVariantList will be interpreted as a value for a new row. \c

   982   ValuesAsColumns is a special case for the Oracle driver. In this

   983   mode, every entry within a QVariantList will be interpreted as

   984   array-value for an IN or OUT value within a stored procedure.  Note

   985   that this will only work if the IN or OUT value is a table-type

   986   consisting of only one column of a basic type, for example \c{TYPE

   987   myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;}

   988 

   989   \sa prepare(), bindValue(), addBindValue()

   990 */

   991 bool QSqlQuery::execBatch(BatchExecutionMode mode)

   992 {

   993     return d->sqlResult->execBatch(mode == ValuesAsColumns);

   994 }

   995 

   996 /*!

   997   Set the placeholder \a placeholder to be bound to value \a val in

   998   the prepared statement. Note that the placeholder mark (e.g \c{:})

   999   must be included when specifying the placeholder name. If \a

  1000   paramType is QSql::Out or QSql::InOut, the placeholder will be

  1001   overwritten with data from the database after the exec() call.

  1002 

  1003   To bind a NULL value, use a null QVariant; for example, use

  1004   \c {QVariant(QVariant::String)} if you are binding a string.

  1005 

  1006   \sa addBindValue(), prepare(), exec(), boundValue() boundValues()

  1007 */

  1008 void QSqlQuery::bindValue(const QString& placeholder, const QVariant& val,

  1009                           QSql::ParamType paramType

  1010 )

  1011 {

  1012     d->sqlResult->bindValue(placeholder, val, paramType);

  1013 }

  1014 

  1015 /*!

  1016   Set the placeholder in position \a pos to be bound to value \a val

  1017   in the prepared statement. Field numbering starts at 0. If \a

  1018   paramType is QSql::Out or QSql::InOut, the placeholder will be

  1019   overwritten with data from the database after the exec() call.

  1020 */

  1021 void QSqlQuery::bindValue(int pos, const QVariant& val, QSql::ParamType paramType)

  1022 {

  1023     d->sqlResult->bindValue(pos, val, paramType);

  1024 }

  1025 

  1026 /*!

  1027   Adds the value \a val to the list of values when using positional

  1028   value binding. The order of the addBindValue() calls determines

  1029   which placeholder a value will be bound to in the prepared query.

  1030   If \a paramType is QSql::Out or QSql::InOut, the placeholder will be

  1031   overwritten with data from the database after the exec() call.

  1032 

  1033   To bind a NULL value, use a null QVariant; for example, use \c

  1034   {QVariant(QVariant::String)} if you are binding a string.

  1035 

  1036   \sa bindValue(), prepare(), exec(), boundValue() boundValues()

  1037 */

  1038 void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType)

  1039 {

  1040     d->sqlResult->addBindValue(val, paramType);

  1041 }

  1042 

  1043 /*!

  1044   Returns the value for the \a placeholder.

  1045 

  1046   \sa boundValues() bindValue() addBindValue()

  1047 */

  1048 QVariant QSqlQuery::boundValue(const QString& placeholder) const

  1049 {

  1050     return d->sqlResult->boundValue(placeholder);

  1051 }

  1052 

  1053 /*!

  1054   Returns the value for the placeholder at position \a pos.

  1055 */

  1056 QVariant QSqlQuery::boundValue(int pos) const

  1057 {

  1058     return d->sqlResult->boundValue(pos);

  1059 }

  1060 

  1061 /*!

  1062   Returns a map of the bound values.

  1063 

  1064   With named binding, the bound values can be examined in the

  1065   following ways:

  1066 

  1067   \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 14

  1068 

  1069   With positional binding, the code becomes:

  1070 

  1071   \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 15

  1072 

  1073   \sa boundValue() bindValue() addBindValue()

  1074 */

  1075 QMap<QString,QVariant> QSqlQuery::boundValues() const

  1076 {

  1077     QMap<QString,QVariant> map;

  1078 

  1079     const QVector<QVariant> values(d->sqlResult->boundValues());

  1080     for (int i = 0; i < values.count(); ++i)

  1081         map[d->sqlResult->boundValueName(i)] = values.at(i);

  1082     return map;

  1083 }

  1084 

  1085 /*!

  1086   Returns the last query that was successfully executed.

  1087 

  1088   In most cases this function returns the same string as lastQuery().

  1089   If a prepared query with placeholders is executed on a DBMS that

  1090   does not support it, the preparation of this query is emulated. The

  1091   placeholders in the original query are replaced with their bound

  1092   values to form a new query. This function returns the modified

  1093   query. It is mostly useful for debugging purposes.

  1094 

  1095   \sa lastQuery()

  1096 */

  1097 QString QSqlQuery::executedQuery() const

  1098 {

  1099     return d->sqlResult->executedQuery();

  1100 }

  1101 

  1102 /*!

  1103   \fn bool QSqlQuery::prev()

  1104 

  1105   Use previous() instead.

  1106 */

  1107 

  1108 /*!

  1109   Returns the object ID of the most recent inserted row if the

  1110   database supports it.  An invalid QVariant will be returned if the

  1111   query did not insert any value or if the database does not report

  1112   the id back.  If more than one row was touched by the insert, the

  1113   behavior is undefined.

  1114 

  1115   For MySQL databases the row's auto-increment field will be returned.

  1116     

  1117   \note For this function to work in PSQL, the table table must

  1118   contain OIDs, which may not have been created by default.  Check the

  1119   \c default_with_oids configuration variable to be sure.

  1120 

  1121   \sa QSqlDriver::hasFeature()

  1122 */

  1123 QVariant QSqlQuery::lastInsertId() const

  1124 {

  1125     return d->sqlResult->lastInsertId();

  1126 }

  1127 

  1128 /*!

  1129 

  1130   Instruct the database driver to return numerical values with a

  1131   precision specified by \a precisionPolicy.

  1132 

  1133   The Oracle driver, for example, can retrieve numerical values as

  1134   strings to prevent the loss of precision. If high precision doesn't