/****************************************************************************+
−
**+
−
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** Contact: Nokia Corporation (qt-info@nokia.com)+
−
**+
−
** This file is part of the QtSql module of the Qt Toolkit.+
−
**+
−
** $QT_BEGIN_LICENSE:LGPL$+
−
** No Commercial Usage+
−
** This file contains pre-release code and may not be distributed.+
−
** You may use this file in accordance with the terms and conditions+
−
** contained in the Technology Preview License Agreement accompanying+
−
** this package.+
−
**+
−
** GNU Lesser General Public License Usage+
−
** Alternatively, this file may be used under the terms of the GNU Lesser+
−
** General Public License version 2.1 as published by the Free Software+
−
** Foundation and appearing in the file LICENSE.LGPL included in the+
−
** packaging of this file.  Please review the following information to+
−
** ensure the GNU Lesser General Public License version 2.1 requirements+
−
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.+
−
**+
−
** In addition, as a special exception, Nokia gives you certain additional+
−
** rights.  These rights are described in the Nokia Qt LGPL Exception+
−
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at qt-info@nokia.com.+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
** $QT_END_LICENSE$+
−
**+
−
****************************************************************************/+
−
+
−
#include "qsqlquery.h"+
−
+
−
//#define QT_DEBUG_SQL+
−
+
−
#include "qatomic.h"+
−
#include "qsqlrecord.h"+
−
#include "qsqlresult.h"+
−
#include "qsqldriver.h"+
−
#include "qsqldatabase.h"+
−
#include "private/qsqlnulldriver_p.h"+
−
#include "qvector.h"+
−
#include "qmap.h"+
−
+
−
QT_BEGIN_NAMESPACE+
−
+
−
class QSqlQueryPrivate+
−
{+
−
public:+
−
    QSqlQueryPrivate(QSqlResult* result);+
−
    ~QSqlQueryPrivate();+
−
    QAtomicInt ref;+
−
    QSqlResult* sqlResult;+
−
+
−
    static QSqlQueryPrivate* shared_null();+
−
};+
−
+
−
Q_GLOBAL_STATIC_WITH_ARGS(QSqlQueryPrivate, nullQueryPrivate, (0))+
−
Q_GLOBAL_STATIC(QSqlNullDriver, nullDriver)+
−
Q_GLOBAL_STATIC_WITH_ARGS(QSqlNullResult, nullResult, (nullDriver()))+
−
+
−
QSqlQueryPrivate* QSqlQueryPrivate::shared_null()+
−
{+
−
    QSqlQueryPrivate *null = nullQueryPrivate();+
−
    null->ref.ref();+
−
    return null;+
−
}+
−
+
−
/*!+
−
\internal+
−
*/+
−
QSqlQueryPrivate::QSqlQueryPrivate(QSqlResult* result)+
−
    : ref(1), sqlResult(result)+
−
{+
−
    if (!sqlResult)+
−
        sqlResult = nullResult();+
−
}+
−
+
−
QSqlQueryPrivate::~QSqlQueryPrivate()+
−
{+
−
    QSqlResult *nr = nullResult();+
−
    if (!nr || sqlResult == nr)+
−
        return;+
−
    delete sqlResult;+
−
}+
−
+
−
/*!+
−
    \class QSqlQuery+
−
    \brief The QSqlQuery class provides a means of executing and+
−
    manipulating SQL statements.+
−
+
−
    \ingroup database+
−
    \ingroup shared+
−
+
−
    \inmodule QtSql+
−
+
−
    QSqlQuery encapsulates the functionality involved in creating,+
−
    navigating and retrieving data from SQL queries which are+
−
    executed on a \l QSqlDatabase. It can be used to execute DML+
−
    (data manipulation language) statements, such as \c SELECT, \c+
−
    INSERT, \c UPDATE and \c DELETE, as well as DDL (data definition+
−
    language) statements, such as \c{CREATE} \c{TABLE}. It can also+
−
    be used to execute database-specific commands which are not+
−
    standard SQL (e.g. \c{SET DATESTYLE=ISO} for PostgreSQL).+
−
+
−
    Successfully executed SQL statements set the query's state to+
−
    active so that 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.+
−
+
−
    For some databases, if an active query that is a \c{SELECT}+
−
    statement exists when you call \l{QSqlDatabase::}{commit()} or+
−
    \l{QSqlDatabase::}{rollback()}, the commit or rollback will+
−
    fail. See isActive() for details.+
−
+
−
    \target QSqlQuery examples+
−
+
−
    Navigating records is performed with the following functions:+
−
+
−
    \list+
−
    \o next()+
−
    \o previous()+
−
    \o first()+
−
    \o last()+
−
    \o seek()+
−
    \endlist+
−
+
−
    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., by using+
−
    next()), you can use setForwardOnly(), which will save a+
−
    significant amount of memory overhead and improve performance on+
−
    some databases. 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 QVariants.+
−
+
−
    For example:+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 7+
−
+
−
    To access the data returned by a query, use value(int). Each+
−
    field in the data returned by a \c SELECT statement is accessed+
−
    by passing the field's position in the statement, starting from+
−
    0. This makes using \c{SELECT *} queries inadvisable because the+
−
    order of the fields returned is indeterminate.+
−
+
−
    For the sake of efficiency, there are no functions to access a+
−
    field by name (unless you use prepared queries with names, as+
−
    explained below). To convert a field name into an index, use+
−
    record().\l{QSqlRecord::indexOf()}{indexOf()}, for example:+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 8+
−
+
−
    QSqlQuery supports prepared query execution and the binding of+
−
    parameter values to placeholders. Some databases don't support+
−
    these features, so for those, Qt emulates the required+
−
    functionality. For example, the Oracle and ODBC drivers have+
−
    proper prepared query support, and Qt makes use of it; but for+
−
    databases that don't have this support, Qt implements the feature+
−
    itself, e.g. by replacing placeholders with actual values when a+
−
    query is executed. Use numRowsAffected() to find out how many rows+
−
    were affected by a non-\c SELECT query, and size() to find how+
−
    many were retrieved by a \c SELECT.+
−
+
−
    Oracle databases identify placeholders by using a colon-name+
−
    syntax, e.g \c{:name}. ODBC simply uses \c ? characters. Qt+
−
    supports both syntaxes, with the restriction that you can't mix+
−
    them in the same query.+
−
+
−
    You can retrieve the values of all the fields in a single variable+
−
    (a map) using boundValues().+
−
+
−
    \section1 Approaches to Binding Values+
−
+
−
    Below we present the same example using each of the four+
−
    different binding approaches, as well as one example of binding+
−
    values to a stored procedure.+
−
+
−
    \bold{Named binding using named placeholders:}+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9+
−
+
−
    \bold{Positional binding using named placeholders:}+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 10+
−
+
−
    \bold{Binding values using positional placeholders (version 1):}+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 11+
−
+
−
    \bold{Binding values using positional placeholders (version 2):}+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 12+
−
+
−
    \bold{Binding values to a stored procedure:}+
−
+
−
    This code calls a stored procedure called \c AsciiToInt(), passing+
−
    it a character through its in parameter, and taking its result in+
−
    the out parameter.+
−
+
−
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 13+
−
+
−
    Note that unbound parameters will retain their values.+
−
+
−
    Stored procedures that uses the return statement to return values,+
−
    or return multiple result sets, are not fully supported. For specific+
−
    details see \l{SQL Database Drivers}.+
−
+
−
    \warning You must load the SQL driver and open the connection before a+
−
    QSqlQuery is created. Also, the connection must remain open while the+
−
    query exists; otherwise, the behavior of QSqlQuery is undefined.+
−
+
−
    \sa QSqlDatabase, QSqlQueryModel, QSqlTableModel, QVariant+
−
*/+
−
+
−
/*!+
−
    Constructs a QSqlQuery object which uses the QSqlResult \a result+
−
    to communicate with a database.+
−
*/+
−
+
−
QSqlQuery::QSqlQuery(QSqlResult *result)+
−
{+
−
    d = new QSqlQueryPrivate(result);+
−
}+
−
+
−
/*!+
−
    Destroys the object and frees any allocated resources.+
−
*/+
−
+
−
QSqlQuery::~QSqlQuery()+
−
{+
−
    if (!d->ref.deref())+
−
        delete d;+
−
}+
−
+
−
/*!+
−
    Constructs a copy of \a other.+
−
*/+
−
+
−
QSqlQuery::QSqlQuery(const QSqlQuery& other)+
−
{+
−
    d = other.d;+
−
    d->ref.ref();+
−
}+
−
+
−
/*!+
−
    \internal+
−
*/+
−
static void qInit(QSqlQuery *q, const QString& query, QSqlDatabase db)+
−
{+
−
    QSqlDatabase database = db;+
−
    if (!database.isValid())+
−
        database = QSqlDatabase::database(QLatin1String(QSqlDatabase::defaultConnection), false);+
−
    if (database.isValid()) {+
−
        *q = QSqlQuery(database.driver()->createResult());+
−
    }+
−
    if (!query.isEmpty())+
−
        q->exec(query);+
−
}+
−
+
−
/*!+
−
    Constructs a QSqlQuery object using the SQL \a query and the+
−
    database \a db. If \a db is not specified, the application's+
−
    default database is used. If \a query is not an empty string, it+
−
    will be executed.+
−
+
−
    \sa QSqlDatabase+
−
*/+
−
QSqlQuery::QSqlQuery(const QString& query, QSqlDatabase db)+
−
{+
−
    d = QSqlQueryPrivate::shared_null();+
−
    qInit(this, query, db);+
−
}+
−
+
−
/*!+
−
    Constructs a QSqlQuery object using the database \a db.+
−
+
−
    \sa QSqlDatabase+
−
*/+
−
+
−
QSqlQuery::QSqlQuery(QSqlDatabase db)+
−
{+
−
    d = QSqlQueryPrivate::shared_null();+
−
    qInit(this, QString(), db);+
−
}+
−
+
−
+
−
/*!+
−
    Assigns \a other to this object.+
−
*/+
−
+
−
QSqlQuery& QSqlQuery::operator=(const QSqlQuery& other)+
−
{+
−
    qAtomicAssign(d, other.d);+
−
    return *this;+
−
}+
−
+
−
/*!+
−
  Returns true if the query is \l{isActive()}{active} and positioned+
−
  on a valid record and the \a 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.+
−
+
−
  \sa isActive(), isValid(), value()+
−
*/+
−
+
−
bool QSqlQuery::isNull(int field) const+
−
{+
−
    if (d->sqlResult->isActive() && d->sqlResult->isValid())+
−
        return d->sqlResult->isNull(field);+
−
    return true;+
−
}+
−
+
−
/*!+
−
  +
−
  Executes the SQL in \a query. Returns true and sets the query state+
−
  to \l{isActive()}{active} if the query was successful; otherwise+
−
  returns false. The \a 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 \e+
−
  invalid record and must be navigated to a valid record before data+
−
  values can be retrieved (for example, using next()).+
−
+
−
  Note that the last error for this query is reset when exec() is+
−
  called.+
−
+
−
  Example:+
−
+
−
  \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 34+
−
+
−
  \sa isActive(), isValid(), next(), previous(), first(), last(),+
−
  seek()+
−
*/+
−
+
−
bool QSqlQuery::exec(const QString& query)+
−
{+
−
    if (d->ref != 1) {+
−
        bool fo = isForwardOnly();+
−
        *this = QSqlQuery(driver()->createResult());+
−
        d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());+
−
        setForwardOnly(fo);+
−
    } else {+
−
        d->sqlResult->clear();+
−
        d->sqlResult->setActive(false);+
−
        d->sqlResult->setLastError(QSqlError());+
−
        d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
        d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());+
−
    }+
−
    d->sqlResult->setQuery(query.trimmed());+
−
    if (!driver()->isOpen() || driver()->isOpenError()) {+
−
        qWarning("QSqlQuery::exec: database not open");+
−
        return false;+
−
    }+
−
    if (query.isEmpty()) {+
−
        qWarning("QSqlQuery::exec: empty query");+
−
        return false;+
−
    }+
−
#ifdef QT_DEBUG_SQL+
−
    qDebug("\n QSqlQuery: %s", query.toLocal8Bit().constData());+
−
#endif+
−
    return d->sqlResult->reset(query);+
−
}+
−
+
−
/*!+
−
    Returns the value of field \a index in the current record.+
−
+
−
    The fields are numbered from left to right using the text of the+
−
    \c SELECT statement, e.g. in+
−
+
−
    \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 0+
−
+
−
    field 0 is \c forename and field 1 is \c+
−
    surname. Using \c{SELECT *} is not recommended because the order+
−
    of the fields in the query is undefined.+
−
+
−
    An invalid QVariant is returned if field \a index does not+
−
    exist, if the query is inactive, or if the query is positioned on+
−
    an invalid record.+
−
+
−
    \sa previous() next() first() last() seek() isActive() isValid()+
−
*/+
−
+
−
QVariant QSqlQuery::value(int index) const+
−
{+
−
    if (isActive() && isValid() && (index > QSql::BeforeFirstRow))+
−
        return d->sqlResult->data(index);+
−
    qWarning("QSqlQuery::value: not positioned on a valid record");+
−
    return QVariant();+
−
}+
−
+
−
/*!+
−
    Returns the current internal position of the query. The first+
−
    record is at position zero. If the position is invalid, the+
−
    function returns QSql::BeforeFirstRow or+
−
    QSql::AfterLastRow, which are special negative values.+
−
+
−
    \sa previous() next() first() last() seek() isActive() isValid()+
−
*/+
−
+
−
int QSqlQuery::at() const+
−
{+
−
    return d->sqlResult->at();+
−
}+
−
+
−
/*!+
−
    Returns the text of the current query being used, or an empty+
−
    string if there is no current query text.+
−
+
−
    \sa executedQuery()+
−
*/+
−
+
−
QString QSqlQuery::lastQuery() const+
−
{+
−
    return d->sqlResult->lastQuery();+
−
}+
−
+
−
/*!+
−
    Returns the database driver associated with the query.+
−
*/+
−
+
−
const QSqlDriver *QSqlQuery::driver() const+
−
{+
−
    return d->sqlResult->driver();+
−
}+
−
+
−
/*!+
−
    Returns the result associated with the query.+
−
*/+
−
+
−
const QSqlResult* QSqlQuery::result() const+
−
{+
−
    return d->sqlResult;+
−
}+
−
+
−
/*!+
−
  Retrieves the record at position \a index, 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 \l{isActive()}+
−
  {active} state and isSelect() must return true before calling this+
−
  function.+
−
+
−
  If \a relative is false (the default), the following rules apply:+
−
+
−
  \list+
−
+
−
  \o If \a index is negative, the result is positioned before the+
−
  first record and false is returned.+
−
+
−
  \o Otherwise, an attempt is made to move to the record at position+
−
  \a index. If the record at position \a index 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.+
−
+
−
  \endlist+
−
+
−
  If \a relative is true, the following rules apply:+
−
+
−
  \list+
−
+
−
  \o If the result is currently positioned before the first record or+
−
  on the first record, and \a index is negative, there is no change,+
−
  and false is returned.+
−
+
−
  \o If the result is currently located after the last record, and \a+
−
  index is positive, there is no change, and false is returned.+
−
+
−
  \o If the result is currently located somewhere in the middle, and+
−
  the relative offset \a index moves the result below zero, the result+
−
  is positioned before the first record and false is returned.+
−
+
−
  \o Otherwise, an attempt is made to move to the record \a index+
−
  records ahead of the current record (or \a index records behind the+
−
  current record if \a index is negative). If the record at offset \a+
−
  index could not be retrieved, the result is positioned after the+
−
  last record if \a index >= 0, (or before the first record if \a+
−
  index is negative), and false is returned. If the record is+
−
  successfully retrieved, true is returned.+
−
+
−
  \endlist+
−
+
−
  \sa next() previous() first() last() at() isActive() isValid()+
−
*/+
−
bool QSqlQuery::seek(int index, bool relative)+
−
{+
−
    if (!isSelect() || !isActive())+
−
        return false;+
−
    int actualIdx;+
−
    if (!relative) { // arbitrary seek+
−
        if (index < 0) {+
−
            d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
            return false;+
−
        }+
−
        actualIdx = index;+
−
    } else {+
−
        switch (at()) { // relative seek+
−
        case QSql::BeforeFirstRow:+
−
            if (index > 0)+
−
                actualIdx = index;+
−
            else {+
−
                return false;+
−
            }+
−
            break;+
−
        case QSql::AfterLastRow:+
−
            if (index < 0) {+
−
                d->sqlResult->fetchLast();+
−
                actualIdx = at() + index;+
−
            } else {+
−
                return false;+
−
            }+
−
            break;+
−
        default:+
−
            if ((at() + index) < 0) {+
−
                d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
                return false;+
−
            }+
−
            actualIdx = at() + index;+
−
            break;+
−
        }+
−
    }+
−
    // let drivers optimize+
−
    if (isForwardOnly() && actualIdx < at()) {+
−
        qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");+
−
        return false;+
−
    }+
−
    if (actualIdx == (at() + 1) && at() != QSql::BeforeFirstRow) {+
−
        if (!d->sqlResult->fetchNext()) {+
−
            d->sqlResult->setAt(QSql::AfterLastRow);+
−
            return false;+
−
        }+
−
        return true;+
−
    }+
−
    if (actualIdx == (at() - 1)) {+
−
        if (!d->sqlResult->fetchPrevious()) {+
−
            d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
            return false;+
−
        }+
−
        return true;+
−
    }+
−
    if (!d->sqlResult->fetch(actualIdx)) {+
−
        d->sqlResult->setAt(QSql::AfterLastRow);+
−
        return false;+
−
    }+
−
    return true;+
−
}+
−
+
−
/*!+
−
  +
−
  Retrieves the next record in the result, if available, and positions+
−
  the query on the retrieved record. Note that the result must be in+
−
  the \l{isActive()}{active} state and isSelect() must return true+
−
  before calling this function or it will do nothing and return false.+
−
+
−
  The following rules apply:+
−
+
−
  \list+
−
+
−
  \o If the result is currently located before the first record,+
−
  e.g. immediately after a query is executed, an attempt is made to+
−
  retrieve the first record.+
−
+
−
  \o If the result is currently located after the last record, there+
−
  is no change and false is returned.+
−
+
−
  \o If the result is located somewhere in the middle, an attempt is+
−
  made to retrieve the next record.+
−
+
−
  \endlist+
−
+
−
  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.+
−
+
−
  \sa previous() first() last() seek() at() isActive() isValid()+
−
*/+
−
bool QSqlQuery::next()+
−
{+
−
    if (!isSelect() || !isActive())+
−
        return false;+
−
    bool b = false;+
−
    switch (at()) {+
−
    case QSql::BeforeFirstRow:+
−
        b = d->sqlResult->fetchFirst();+
−
        return b;+
−
    case QSql::AfterLastRow:+
−
        return false;+
−
    default:+
−
        if (!d->sqlResult->fetchNext()) {+
−
            d->sqlResult->setAt(QSql::AfterLastRow);+
−
            return false;+
−
        }+
−
        return true;+
−
    }+
−
}+
−
+
−
/*!+
−
+
−
  Retrieves the previous record in the result, if available, and+
−
  positions the query on the retrieved record. Note that the result+
−
  must be in the \l{isActive()}{active} state and isSelect() must+
−
  return true before calling this function or it will do nothing and+
−
  return false.+
−
+
−
  The following rules apply:+
−
+
−
  \list+
−
+
−
  \o If the result is currently located before the first record, there+
−
  is no change and false is returned.+
−
+
−
  \o If the result is currently located after the last record, an+
−
  attempt is made to retrieve the last record.+
−
+
−
  \o If the result is somewhere in the middle, an attempt is made to+
−
  retrieve the previous record.+
−
+
−
  \endlist+
−
+
−
  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.+
−
+
−
  \sa next() first() last() seek() at() isActive() isValid()+
−
*/+
−
bool QSqlQuery::previous()+
−
{+
−
    if (!isSelect() || !isActive())+
−
        return false;+
−
    if (isForwardOnly()) {+
−
        qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");+
−
        return false;+
−
    }+
−
+
−
    bool b = false;+
−
    switch (at()) {+
−
    case QSql::BeforeFirstRow:+
−
        return false;+
−
    case QSql::AfterLastRow:+
−
        b = d->sqlResult->fetchLast();+
−
        return b;+
−
    default:+
−
        if (!d->sqlResult->fetchPrevious()) {+
−
            d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
            return false;+
−
        }+
−
        return true;+
−
    }+
−
}+
−
+
−
/*!+
−
  Retrieves the first record in the result, if available, and+
−
  positions the query on the retrieved record. Note that the result+
−
  must be in the \l{isActive()}{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.+
−
+
−
  \sa next() previous() last() seek() at() isActive() isValid()+
−
 */+
−
bool QSqlQuery::first()+
−
{+
−
    if (!isSelect() || !isActive())+
−
        return false;+
−
    if (isForwardOnly() && at() > QSql::BeforeFirstRow) {+
−
        qWarning("QSqlQuery::seek: cannot seek backwards in a forward only query");+
−
        return false;+
−
    }+
−
    bool b = false;+
−
    b = d->sqlResult->fetchFirst();+
−
    return b;+
−
}+
−
+
−
/*!+
−
+
−
  Retrieves the last record in the result, if available, and positions+
−
  the query on the retrieved record. Note that the result must be in+
−
  the \l{isActive()}{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.+
−
+
−
  \sa next() previous() first() seek() at() isActive() isValid()+
−
*/+
−
+
−
bool QSqlQuery::last()+
−
{+
−
    if (!isSelect() || !isActive())+
−
        return false;+
−
    bool b = false;+
−
    b = d->sqlResult->fetchLast();+
−
    return b;+
−
}+
−
+
−
/*!+
−
  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-\c 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-\c SELECT+
−
  statement, use numRowsAffected().+
−
+
−
  \sa isActive() numRowsAffected() QSqlDriver::hasFeature()+
−
*/+
−
int QSqlQuery::size() const+
−
{+
−
    if (isActive() && d->sqlResult->driver()->hasFeature(QSqlDriver::QuerySize))+
−
        return d->sqlResult->size();+
−
    return -1;+
−
}+
−
+
−
/*!+
−
  Returns the number of rows affected by the result's SQL statement,+
−
  or -1 if it cannot be determined. Note that for \c SELECT+
−
  statements, the value is undefined; use size() instead. If the query+
−
  is not \l{isActive()}{active}, -1 is returned.+
−
+
−
  \sa size() QSqlDriver::hasFeature()+
−
*/+
−
+
−
int QSqlQuery::numRowsAffected() const+
−
{+
−
    if (isActive())+
−
        return d->sqlResult->numRowsAffected();+
−
    return -1;+
−
}+
−
+
−
/*!+
−
  Returns error information about the last error (if any) that+
−
  occurred with this query.+
−
+
−
  \sa QSqlError, QSqlDatabase::lastError()+
−
*/+
−
+
−
QSqlError QSqlQuery::lastError() const+
−
{+
−
    return d->sqlResult->lastError();+
−
}+
−
+
−
/*!+
−
  Returns true if the query is currently positioned on a valid+
−
  record; otherwise returns false.+
−
*/+
−
+
−
bool QSqlQuery::isValid() const+
−
{+
−
    return d->sqlResult->isValid();+
−
}+
−
+
−
/*!+
−
  +
−
  Returns true if the query is \e{active}. An active QSqlQuery is one+
−
  that has been \l{QSqlQuery::exec()} {exec()'d} successfully but not+
−
  yet finished with.  When you are finished with an active query, you+
−
  can make make the query inactive by calling finish() or clear(), or+
−
  you can delete the QSqlQuery instance.+
−
+
−
  \note Of particular interest is an active query that is a \c{SELECT}+
−
  statement. For some databases that support transactions, an active+
−
  query that is a \c{SELECT} statement can cause a \l{QSqlDatabase::}+
−
  {commit()} or a \l{QSqlDatabase::} {rollback()} to fail, so before+
−
  committing or rolling back, you should make your active \c{SELECT}+
−
  statement query inactive using one of the ways listed above.+
−
+
−
  \sa isSelect()+
−
 */+
−
bool QSqlQuery::isActive() const+
−
{+
−
    return d->sqlResult->isActive();+
−
}+
−
+
−
/*!+
−
  Returns true if the current query is a \c SELECT statement;+
−
  otherwise returns false.+
−
*/+
−
+
−
bool QSqlQuery::isSelect() const+
−
{+
−
    return d->sqlResult->isSelect();+
−
}+
−
+
−
/*!+
−
  Returns true if you can only scroll forward through a result set;+
−
  otherwise returns false.+
−
+
−
  \sa setForwardOnly(), next()+
−
*/+
−
bool QSqlQuery::isForwardOnly() const+
−
{+
−
    return d->sqlResult->isForwardOnly();+
−
}+
−
+
−
/*!+
−
  Sets forward only mode to \a forward. If \a forward is true, only+
−
  next() and seek() with positive values, are allowed for navigating+
−
  the results.+
−
+
−
  Forward only mode can be (depending on the driver) more memory+
−
  efficient since results do not need to be cached. It will also+
−
  improve performance on some databases. For this to be true, you must+
−
  call \c setForwardOnly() before the query is prepared or executed.+
−
  Note that the constructor that takes a query and a database may+
−
  execute the query.+
−
+
−
  Forward only mode is off by default.+
−
+
−
  Setting forward only to false is a suggestion to the database engine,+
−
  which has the final say on whether a result set is forward only or+
−
  scrollable. isForwardOnly() will always return the correct status of+
−
  the result set.+
−
+
−
  \note Calling setForwardOnly after execution of the query will result+
−
  in unexpected results at best, and crashes at worst.+
−
+
−
  \sa isForwardOnly(), next(), seek(), QSqlResult::setForwardOnly()+
−
*/+
−
void QSqlQuery::setForwardOnly(bool forward)+
−
{+
−
    d->sqlResult->setForwardOnly(forward);+
−
}+
−
+
−
/*!+
−
  Returns a QSqlRecord containing the field information for the+
−
  current query. If the query points to a valid row (isValid() returns+
−
  true), the record is populated with the row's values.  An empty+
−
  record is returned when there is no active query (isActive() returns+
−
  false).+
−
+
−
  To retrieve values from a query, value() should be used since+
−
  its index-based lookup is faster.+
−
+
−
  In the following example, a \c{SELECT * FROM} query is executed.+
−
  Since the order of the columns is not defined, QSqlRecord::indexOf()+
−
  is used to obtain the index of a column.+
−
+
−
  \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 1+
−
+
−
  \sa value()+
−
*/+
−
QSqlRecord QSqlQuery::record() const+
−
{+
−
    QSqlRecord rec = d->sqlResult->record();+
−
+
−
    if (isValid()) {+
−
        for (int i = 0; i < rec.count(); ++i)+
−
            rec.setValue(i, value(i));+
−
    }+
−
    return rec;+
−
}+
−
+
−
/*!+
−
  Clears the result set and releases any resources held by the+
−
  query. Sets the query state to inactive. You should rarely if ever+
−
  need to call this function.+
−
*/+
−
void QSqlQuery::clear()+
−
{+
−
    *this = QSqlQuery(driver()->createResult());+
−
}+
−
+
−
/*!+
−
  Prepares the SQL query \a query for execution. Returns true if the+
−
  query is prepared successfully; otherwise returns false.+
−
+
−
  The query may contain placeholders for binding values. Both Oracle+
−
  style colon-name (e.g., \c{:surname}), and ODBC style (\c{?})+
−
  placeholders are supported; but they cannot be mixed in the same+
−
  query. See the \l{QSqlQuery examples}{Detailed Description} for+
−
  examples.+
−
+
−
  Portability note: Some databases choose to delay preparing a query+
−
  until it is executed the first time. In this case, preparing a+
−
  syntactically wrong query succeeds, but every consecutive exec()+
−
  will fail.+
−
+
−
  Example:+
−
+
−
  \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9+
−
+
−
  \sa exec(), bindValue(), addBindValue()+
−
*/+
−
bool QSqlQuery::prepare(const QString& query)+
−
{+
−
    if (d->ref != 1) {+
−
        bool fo = isForwardOnly();+
−
        *this = QSqlQuery(driver()->createResult());+
−
        setForwardOnly(fo);+
−
        d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());+
−
    } else {+
−
        d->sqlResult->setActive(false);+
−
        d->sqlResult->setLastError(QSqlError());+
−
        d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
        d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());+
−
    }+
−
    if (!driver()) {+
−
        qWarning("QSqlQuery::prepare: no driver");+
−
        return false;+
−
    }+
−
    if (!driver()->isOpen() || driver()->isOpenError()) {+
−
        qWarning("QSqlQuery::prepare: database not open");+
−
        return false;+
−
    }+
−
    if (query.isEmpty()) {+
−
        qWarning("QSqlQuery::prepare: empty query");+
−
        return false;+
−
    }+
−
#ifdef QT_DEBUG_SQL+
−
    qDebug("\n QSqlQuery::prepare: %s", query.toLocal8Bit().constData());+
−
#endif+
−
    return d->sqlResult->savePrepare(query);+
−
}+
−
+
−
/*!+
−
  Executes a previously prepared SQL query. Returns true if the query+
−
  executed successfully; otherwise returns false.+
−
+
−
  Note that the last error for this query is reset when exec() is+
−
  called.+
−
+
−
  \sa prepare() bindValue() addBindValue() boundValue() boundValues()+
−
*/+
−
bool QSqlQuery::exec()+
−
{+
−
    d->sqlResult->resetBindCount();+
−
+
−
    if (d->sqlResult->lastError().isValid())+
−
        d->sqlResult->setLastError(QSqlError());+
−
+
−
    return d->sqlResult->exec();+
−
}+
−
+
−
/*! \enum QSqlQuery::BatchExecutionMode+
−
+
−
    \value ValuesAsRows - Updates multiple rows. Treats every entry in a QVariantList as a value for updating the next row.+
−
    \value ValuesAsColumns - Updates a single row. Treats every entry in a QVariantList as a single value of an array type.+
−
*/+
−
+
−
/*!+
−
    \since 4.2+
−
+
−
  Executes a previously prepared SQL query in a batch. All the bound+
−
  parameters have to be lists of variants. If the database doesn't+
−
  support batch executions, the driver will simulate it using+
−
  conventional exec() calls.+
−
+
−
  Returns true if the query is executed successfully; otherwise+
−
  returns false.+
−
+
−
  Example:+
−
+
−
  \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 2+
−
+
−
  The example above inserts four new rows into \c myTable:+
−
+
−
  \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 3+
−
+
−
  To bind NULL values, a null QVariant of the relevant type has to be+
−
  added to the bound QVariantList; for example, \c+
−
  {QVariant(QVariant::String)} should be used if you are using+
−
  strings.+
−
+
−
  \note Every bound QVariantList must contain the same amount of+
−
  variants.+
−
+
−
  \note The type of the QVariants in a list must not change. For+
−
  example, you cannot mix integer and string variants within a+
−
  QVariantList.+
−
+
−
  The \a mode parameter indicates how the bound QVariantList will be+
−
  interpreted.  If \a mode is \c ValuesAsRows, every variant within+
−
  the QVariantList will be interpreted as a value for a new row. \c+
−
  ValuesAsColumns is a special case for the Oracle driver. In this+
−
  mode, every entry within a QVariantList will be interpreted as+
−
  array-value for an IN or OUT value within a stored procedure.  Note+
−
  that this will only work if the IN or OUT value is a table-type+
−
  consisting of only one column of a basic type, for example \c{TYPE+
−
  myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;}+
−
+
−
  \sa prepare(), bindValue(), addBindValue()+
−
*/+
−
bool QSqlQuery::execBatch(BatchExecutionMode mode)+
−
{+
−
    return d->sqlResult->execBatch(mode == ValuesAsColumns);+
−
}+
−
+
−
/*!+
−
  Set the placeholder \a placeholder to be bound to value \a val in+
−
  the prepared statement. Note that the placeholder mark (e.g \c{:})+
−
  must be included when specifying the placeholder name. If \a+
−
  paramType is QSql::Out or QSql::InOut, the placeholder will be+
−
  overwritten with data from the database after the exec() call.+
−
  In this case, sufficient space must be pre-allocated to store+
−
  the result into.+
−
+
−
  To bind a NULL value, use a null QVariant; for example, use+
−
  \c {QVariant(QVariant::String)} if you are binding a string.+
−
+
−
  Values cannot be bound to multiple locations in the query, eg:+
−
  \code+
−
  INSERT INTO testtable (id, name, samename) VALUES (:id, :name, :name)+
−
  \endcode+
−
  Binding to name will bind to the first :name, but not the second.+
−
+
−
  \sa addBindValue(), prepare(), exec(), boundValue() boundValues()+
−
*/+
−
void QSqlQuery::bindValue(const QString& placeholder, const QVariant& val,+
−
                          QSql::ParamType paramType+
−
)+
−
{+
−
    d->sqlResult->bindValue(placeholder, val, paramType);+
−
}+
−
+
−
/*!+
−
  Set the placeholder in position \a pos to be bound to value \a val+
−
  in the prepared statement. Field numbering starts at 0. If \a+
−
  paramType is QSql::Out or QSql::InOut, the placeholder will be+
−
  overwritten with data from the database after the exec() call.+
−
*/+
−
void QSqlQuery::bindValue(int pos, const QVariant& val, QSql::ParamType paramType)+
−
{+
−
    d->sqlResult->bindValue(pos, val, paramType);+
−
}+
−
+
−
/*!+
−
  Adds the value \a 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 \a paramType is QSql::Out or QSql::InOut, the placeholder will be+
−
  overwritten with data from the database after the exec() call.+
−
+
−
  To bind a NULL value, use a null QVariant; for example, use \c+
−
  {QVariant(QVariant::String)} if you are binding a string.+
−
+
−
  \sa bindValue(), prepare(), exec(), boundValue() boundValues()+
−
*/+
−
void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType)+
−
{+
−
    d->sqlResult->addBindValue(val, paramType);+
−
}+
−
+
−
/*!+
−
  Returns the value for the \a placeholder.+
−
+
−
  \sa boundValues() bindValue() addBindValue()+
−
*/+
−
QVariant QSqlQuery::boundValue(const QString& placeholder) const+
−
{+
−
    return d->sqlResult->boundValue(placeholder);+
−
}+
−
+
−
/*!+
−
  Returns the value for the placeholder at position \a pos.+
−
*/+
−
QVariant QSqlQuery::boundValue(int pos) const+
−
{+
−
    return d->sqlResult->boundValue(pos);+
−
}+
−
+
−
/*!+
−
  Returns a map of the bound values.+
−
+
−
  With named binding, the bound values can be examined in the+
−
  following ways:+
−
+
−
  \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 14+
−
+
−
  With positional binding, the code becomes:+
−
+
−
  \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 15+
−
+
−
  \sa boundValue() bindValue() addBindValue()+
−
*/+
−
QMap<QString,QVariant> QSqlQuery::boundValues() const+
−
{+
−
    QMap<QString,QVariant> map;+
−
+
−
    const QVector<QVariant> values(d->sqlResult->boundValues());+
−
    for (int i = 0; i < values.count(); ++i)+
−
        map[d->sqlResult->boundValueName(i)] = values.at(i);+
−
    return map;+
−
}+
−
+
−
/*!+
−
  Returns the last query that was successfully executed.+
−
+
−
  In most cases this function returns the same string 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. It is mostly useful for debugging purposes.+
−
+
−
  \sa lastQuery()+
−
*/+
−
QString QSqlQuery::executedQuery() const+
−
{+
−
    return d->sqlResult->executedQuery();+
−
}+
−
+
−
/*!+
−
  \fn bool QSqlQuery::prev()+
−
+
−
  Use previous() instead.+
−
*/+
−
+
−
/*!+
−
  Returns the object ID of the most recent inserted row if the+
−
  database supports it.  An invalid QVariant will be returned if the+
−
  query did not insert any value or if the database does not report+
−
  the id back.  If more than one row was touched by the insert, the+
−
  behavior is undefined.+
−
+
−
  For MySQL databases the row's auto-increment field will be returned.+
−
    +
−
  \note For this function to work in PSQL, the table table must+
−
  contain OIDs, which may not have been created by default.  Check the+
−
  \c default_with_oids configuration variable to be sure.+
−
+
−
  \sa QSqlDriver::hasFeature()+
−
*/+
−
QVariant QSqlQuery::lastInsertId() const+
−
{+
−
    return d->sqlResult->lastInsertId();+
−
}+
−
+
−
/*!+
−
+
−
  Instruct the database driver to return numerical values with a+
−
  precision specified by \a precisionPolicy.+
−
+
−
  The Oracle driver, for example, can retrieve numerical values as+
−
  strings to prevent the loss of precision. If high precision doesn't+
−
  matter, use this method to increase execution speed by bypassing+
−
  string conversions.+
−
+
−
  Note: Drivers that don't support fetching numerical values with low+
−
  precision will ignore the precision policy. You can use+
−
  QSqlDriver::hasFeature() to find out whether a driver supports this+
−
  feature.+
−
+
−
  Note: Setting the precision policy doesn't affect the currently+
−
  active query. Call \l{exec()}{exec(QString)} or prepare() in order+
−
  to activate the policy.+
−
+
−
  \sa QSql::NumericalPrecisionPolicy, numericalPrecisionPolicy()+
−
*/+
−
void QSqlQuery::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)+
−
{+
−
    d->sqlResult->setNumericalPrecisionPolicy(precisionPolicy);+
−
}+
−
+
−
/*!+
−
  Returns the current precision policy.+
−
+
−
  \sa QSql::NumericalPrecisionPolicy, setNumericalPrecisionPolicy()+
−
*/+
−
QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const+
−
{+
−
    return d->sqlResult->numericalPrecisionPolicy();+
−
}+
−
+
−
/*!+
−
  \since 4.3.2+
−
+
−
  Instruct the database driver that no more data will be fetched from+
−
  this query until it is re-executed. There is normally no need to+
−
  call this function, but it may be helpful in order to free resources+
−
  such as locks or cursors if you intend to re-use the query at a+
−
  later time.+
−
    +
−
  Sets the query to inactive. Bound values retain their values.+
−
+
−
  \sa prepare() exec() isActive()+
−
*/+
−
void QSqlQuery::finish()+
−
{+
−
    if (isActive()) {+
−
        d->sqlResult->setLastError(QSqlError());+
−
        d->sqlResult->setAt(QSql::BeforeFirstRow);+
−
        d->sqlResult->detachFromResultSet();+
−
        d->sqlResult->setActive(false);+
−
    }+
−
}+
−
+
−
/*!+
−
  \since 4.4+
−
 +
−
  Discards the current result set and navigates to the next if available.+
−
+
−
  Some databases are capable of returning multiple result sets for+
−
  stored procedures or SQL batches (a query strings that contains+
−
  multiple statements). If multiple result sets are available after+
−
  executing a query this function can be used to navigate to the next+
−
  result set(s).+
−
    +
−
  If a new result set is available this function will return true.+
−
  The query will be repositioned on an \e invalid record in the new+
−
  result set and must be navigated to a valid record before data+
−
  values can be retrieved. If a new result set isn't available the+
−
  function returns false and the query is set to inactive. In any+
−
  case the old result set will be discarded.+
−
+
−
  When one of the statements is a non-select statement a count of+
−
  affected rows may be available instead of a result set.+
−
+
−
  Note that some databases, i.e. Microsoft SQL Server, requires+
−
  non-scrollable cursors when working with multiple result sets.  Some+
−
  databases may execute all statements at once while others may delay+
−
  the execution until the result set is actually accessed, and some+
−
  databases may have restrictions on which statements are allowed to+
−
  be used in a SQL batch.+
−
+
−
  \sa QSqlDriver::hasFeature() setForwardOnly() next() isSelect() numRowsAffected() isActive() lastError()+
−
*/+
−
bool QSqlQuery::nextResult()+
−
{+
−
    if (isActive())+
−
        return d->sqlResult->nextResult();+
−
    return false;+
−
}+
−
+
−
QT_END_NAMESPACE+
−