qsqlquery.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QSqlQuery 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QSqlQuery \- Means of executing and manipulating SQL statements
.SH SYNOPSIS
\fC#include <qsqlquery.h>\fR
.PP
Inherited by QSqlCursor.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQSqlQuery\fR ( QSqlResult * r )"
.br
.ti -1c
.BI "\fBQSqlQuery\fR ( const QString & query = QString::null, QSqlDatabase * db = 0 )"
.br
.ti -1c
.BI "\fBQSqlQuery\fR ( const QSqlQuery & other )"
.br
.ti -1c
.BI "QSqlQuery & \fBoperator=\fR ( const QSqlQuery & other )"
.br
.ti -1c
.BI "virtual \fB~QSqlQuery\fR ()"
.br
.ti -1c
.BI "bool \fBisValid\fR () const"
.br
.ti -1c
.BI "bool \fBisActive\fR () const"
.br
.ti -1c
.BI "bool \fBisNull\fR ( int field ) const"
.br
.ti -1c
.BI "int \fBat\fR () const"
.br
.ti -1c
.BI "QString \fBlastQuery\fR () const"
.br
.ti -1c
.BI "int \fBnumRowsAffected\fR () const"
.br
.ti -1c
.BI "QSqlError \fBlastError\fR () const"
.br
.ti -1c
.BI "bool \fBisSelect\fR () const"
.br
.ti -1c
.BI "int \fBsize\fR () const"
.br
.ti -1c
.BI "const QSqlDriver * \fBdriver\fR () const"
.br
.ti -1c
.BI "const QSqlResult * \fBresult\fR () const"
.br
.ti -1c
.BI "bool \fBisForwardOnly\fR () const"
.br
.ti -1c
.BI "void \fBsetForwardOnly\fR ( bool forward )"
.br
.ti -1c
.BI "virtual bool \fBexec\fR ( const QString & query )"
.br
.ti -1c
.BI "virtual QVariant \fBvalue\fR ( int i ) const"
.br
.ti -1c
.BI "virtual bool \fBseek\fR ( int i, bool relative = FALSE )"
.br
.ti -1c
.BI "virtual bool \fBnext\fR ()"
.br
.ti -1c
.BI "virtual bool \fBprev\fR ()"
.br
.ti -1c
.BI "virtual bool \fBfirst\fR ()"
.br
.ti -1c
.BI "virtual bool \fBlast\fR ()"
.br
.ti -1c
.BI "bool \fBexec\fR ()"
.br
.ti -1c
.BI "bool \fBprepare\fR ( const QString & query )"
.br
.ti -1c
.BI "void \fBbindValue\fR ( const QString & placeholder, const QVariant & val )"
.br
.ti -1c
.BI "void \fBbindValue\fR ( int pos, const QVariant & val )"
.br
.ti -1c
.BI "void \fBaddBindValue\fR ( const QVariant & val )"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBbeforeSeek\fR ()"
.br
.ti -1c
.BI "virtual void \fBafterSeek\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QSqlQuery class provides a means of executing and manipulating SQL statements.
.PP
QSqlQuery encapsulates the functionality involved in creating, navigating and retrieving data from SQL queries which are executed on a QSqlDatabase. It can be used to execute DML (data manipulation language) statements, e.g. \fCSELECT\fR, \fCINSERT\fR, \fCUPDATE\fR and \fCDELETE\fR, and also DDL (data definition language) statements, e.g. \fCCREATE TABLE\fR. It can also be used to execute database-specific commands which are not standard SQL (e.g. \fCSET DATESTYLE=ISO\fR for PostgreSQL).
.PP
Successfully executed SQL statements set the query's state to active (isActive() returns TRUE); otherwise the query's state is set to inactive. In either case, when executing a new SQL statement, the query is positioned on an invalid record; an active query must be navigated to a valid record (so that isValid() returns TRUE) before values can be retrieved.
.PP
Navigating records is performed with the following functions:
.TP
next()
.TP
prev()
.TP
first()
.TP
last()
.TP
\fC\fRseek(int)
.PP
These functions allow the programmer to move forward, backward or arbitrarily through the records returned by the query. 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.
.PP
For example:
.PP
.nf
.br
    QSqlQuery query( "SELECT name FROM customer" );
.br
    while ( query.next() ) {
.br
        QString name = query.value(0).toString();
.br
        doSomething( name );
.br
    }
.br
.fi
.PP
To access the data returned by a query, use the value() method. Each field in the data returned by a SELECT statement is accessed by passing the field's position in the statement, starting from 0. For the sake of efficiency there are no methods to access a field by name. (The QSqlCursor class provides a higher level interface for that generates SQL automatically and through which fields are accessed by name.)
.PP
QSqlQuery supports prepared query execution and binding of parameter values to placeholders. Note that only input values may be bound. Be aware that not all databases support these features. Currently only the Oracle and ODBC drivers have proper prepared query support, but the rest of the drivers support this by emulating the missing features (the placeholders are simply replaced with the actual value when the query is executed). It is also important to know that different databases use different placeholder marks for value binding. Oracle uses a \fC:\fR character followed by a placeholder name, while ODBC only uses a \fC?\fR character to identify a placeholder. In an attempt to make this database independant we substitute the markers if you try to use ODBC markers in a query to an Oracle database and vice versa. Note that you can't mix the different bind styles by binding some values using named placeholders and some using positional placeholders.
.PP
Example:
.PP
.nf
.br
    // Named binding using named placeholders
.br
    QSqlQuery q;
.br
    q.prepare( "insert into mytable (id, name, lastname) values (:id, :name, :lname)" );
.br
    q.bindValue( ":id", 0 );
.br
    q.bindValue( ":name", "Testname" );
.br
    q.bindValue( ":lname", "Lastname" );
.br
    q.exec();
.br
.br
    // Positional binding using named placeholders
.br
    QSqlQuery q;
.br
    q.prepare( "insert into mytable (id, name, lastname) values (:id, :name, :lname)" );
.br
    q.bindValue( 0, 0 );
.br
    q.bindValue( 1, "Testname" );
.br
    q.bindValue( 2, "Lastname" );
.br
    q.exec();
.br
.br
    // Binding values using positional placeholders
.br
    QSqlQuery q;
.br
    q.prepare( "insert into mytable (id, name, lastname) values (?, ?, ?)" );
.br
    q.bindValue( 0, 0 );
.br
    q.bindValue( 1, "Testname" );
.br
    q.bindValue( 2, "Lastname" );
.br
    q.exec();
.br
.br
.br
    // or alternatively
.br
    q.prepare( "insert into mytable (id, name, lastname) values (?, ?, ?)" );
.br
    q.addBindValue( 0 );