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

     2 **

     3 ** Copyright (C) 2010 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   \note Calling setForwardOnly after execution of the query will result

   826   in unexpected results at best, and crashes at worst.

   827 

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

   829 */

   830 void QSqlQuery::setForwardOnly(bool forward)

   831 {

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

   833 }

   834 

   835 /*!

   836   Returns a QSqlRecord containing the field information for the

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

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

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

   840   false).

   841 

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

   843   its index-based lookup is faster.

   844 

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

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

   847   is used to obtain the index of a column.

   848 

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

   850 

   851   \sa value()

   852 */

   853 QSqlRecord QSqlQuery::record() const

   854 {

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

   856 

   857     if (isValid()) {

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

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

   860     }

   861     return rec;

   862 }

   863 

   864 /*!

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

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

   867   need to call this function.

   868 */

   869 void QSqlQuery::clear()

   870 {

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

   872 }

   873 

   874 /*!

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

   876   query is prepared successfully; otherwise returns false.

   877 

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

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

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

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

   882   examples.

   883 

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

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

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

   887   will fail.

   888 

   889   Example:

   890 

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

   892 

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

   894 */

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

   896 {

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

   898         bool fo = isForwardOnly();

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

   900         setForwardOnly(fo);

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

   902     } else {

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

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

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

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

   907     }

   908     if (!driver()) {

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

   910         return false;

   911     }

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

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

   914         return false;

   915     }

   916     if (query.isEmpty()) {

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

   918         return false;

   919     }

   920 #ifdef QT_DEBUG_SQL

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

   922 #endif

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

   924 }

   925 

   926 /*!

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

   928   executed successfully; otherwise returns false.

   929 

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

   931   called.

   932 

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

   934 */

   935 bool QSqlQuery::exec()

   936 {

   937     d->sqlResult->resetBindCount();

   938 

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

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

   941 

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

   943 }

   944 

   945 /*! \enum QSqlQuery::BatchExecutionMode

   946 

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

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

   949 */

   950 

   951 /*!

   952     \since 4.2

   953 

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

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

   956   support batch executions, the driver will simulate it using

   957   conventional exec() calls.

   958 

   959   Returns true if the query is executed successfully; otherwise

   960   returns false.

   961 

   962   Example:

   963 

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

   965 

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

   967 

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

   969 

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

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

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

   973   strings.

   974 

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

   976   variants.

   977 

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

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

   980   QVariantList.

   981 

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

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

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

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

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

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

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

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

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

   991 

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

   993 */

   994 bool QSqlQuery::execBatch(BatchExecutionMode mode)

   995 {

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

   997 }

   998 

   999 /*!

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

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

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

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

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

  1005   In this case, sufficient space must be pre-allocated to store

  1006   the result into.

  1007 

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

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

  1010 

  1011   Values cannot be bound to multiple locations in the query, eg:

  1012   \code

  1013   INSERT INTO testtable (id, name, samename) VALUES (:id, :name, :name)

  1014   \endcode

  1015   Binding to name will bind to the first :name, but not the second.

  1016 

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

  1018 */

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

  1020                           QSql::ParamType paramType

  1021 )

  1022 {

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

  1024 }

  1025 

  1026 /*!

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

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

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

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

  1031 */

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

  1033 {

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

  1035 }

  1036 

  1037 /*!

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

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

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

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

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

  1043 

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

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

  1046 

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

  1048 */

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

  1050 {

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

  1052 }

  1053 

  1054 /*!

  1055   Returns the value for the \a placeholder.

  1056 

  1057   \sa boundValues() bindValue() addBindValue()

  1058 */

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

  1060 {

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

  1062 }

  1063 

  1064 /*!

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

  1066 */

  1067 QVariant QSqlQuery::boundValue(int pos) const

  1068 {

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

  1070 }

  1071 

  1072 /*!

  1073   Returns a map of the bound values.

  1074 

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

  1076   following ways:

  1077 

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

  1079 

  1080   With positional binding, the code becomes:

  1081 

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

  1083 

  1084   \sa boundValue() bindValue() addBindValue()

  1085 */

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

  1087 {

  1088     QMap<QString,QVariant> map;

  1089 

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

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

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

  1093     return map;

  1094 }

  1095 

  1096 /*!

  1097   Returns the last query that was successfully executed.

  1098 

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

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

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

  1102   placeholders in the original query are replaced with their bound

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

  1104   query. It is mostly useful for debugging purposes.

  1105 

  1106   \sa lastQuery()

  1107 */

  1108 QString QSqlQuery::executedQuery() const

  1109 {

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

  1111 }

  1112 

  1113 /*!

  1114   \fn bool QSqlQuery::prev()

  1115 

  1116   Use previous() instead.

  1117 */

  1118 

  1119 /*!

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

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

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

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

  1124   behavior is undefined.

  1125 

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

  1127     

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

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

  1130   \c default_with_oids configuration variable to be sure.

  1131 

  1132   \sa QSqlDriver::hasFeature()

  1133 */

  1134 QVariant QSqlQuery::lastInsertId() const

  1135 {