qsqlquery.3qt

这个是Linux的qt源代码

'\" t
.TH QSqlQuery 3qt "10 November 2003" "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 "explicit \fBQSqlQuery\fR ( QSqlDatabase * db )"
.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
.ti -1c
.BI "void \fBbindValue\fR ( const QString & placeholder, const QVariant & val, QSql::ParameterType type )"
.br
.ti -1c
.BI "void \fBbindValue\fR ( int pos, const QVariant & val, QSql::ParameterType type )"
.br
.ti -1c
.BI "void \fBaddBindValue\fR ( const QVariant & val, QSql::ParameterType type )"
.br
.ti -1c
.BI "QVariant \fBboundValue\fR ( const QString & placeholder ) const"
.br
.ti -1c
.BI "QVariant \fBboundValue\fR ( int pos ) const"
.br
.ti -1c
.BI "QMap<QString, QVariant> \fBboundValues\fR () const"
.br
.ti -1c
.BI "QString \fBexecutedQuery\fR () const"
.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. If you only need to move forward through the results, e.g. using next() or using seek() with a positive offset, you can use setForwardOnly() and save a significant amount of memory overhead. Once an active query is positioned on a valid record, data can be retrieved using value(). All data is transferred from the SQL backend using 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. This makes using \fCSELECT *\fR queries inadvisable because the order of the fields returned is indeterminate. For the sake of efficiency there are no methods to access a field by name. (The QSqlCursor class provides a higher level interface that generates SQL automatically and through which fields are accessible by name.)
.PP
QSqlQuery supports prepared query execution and the binding of parameter values to placeholders. Some databases don't support these features, so for them 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.
.PP
Oracle databases identify placeholders by using a colon-name syntax, e.g \fC:name\fR. ODBC simply uses \fC?\fR characters. Qt supports both syntaxes (although you can't mix them in the same query).
.PP
Below we present the same example using each of the four different binding approaches.
.PP
\fBNamed binding using named placeholders\fR
.PP
.nf
.br
    QSqlQuery query;
.br
    query.prepare( "INSERT INTO atable (id, forename, surname) "
.br
                   "VALUES (:id, :forename, :surname)" );
.br
    query.bindValue( ":id", 1001 );
.br
    query.bindValue( ":forename", "Bart" );
.br
    query.bindValue( ":surname", "Simpson" );
.br
    query.exec();
.br
.fi
.PP
\fBPositional binding using named placeholders\fR
.PP
.nf
.br
    QSqlQuery query;
.br
    query.prepare( "INSERT INTO atable (id, forename, surname) "
.br
                   "VALUES (:id, :forename, :surname)" );
.br
    query.bindValue( 0, 1001 );
.br
    query.bindValue( 1, "Bart" );
.br
    query.bindValue( 2, "Simpson" );
.br
    query.exec();
.br
.fi
.PP
\fBBinding values using positional placeholders #1\fR
.PP
.nf
.br
    QSqlQuery query;
.br
    query.prepare( "INSERT INTO atable (id, forename, surname) "
.br
                   "VALUES (?, ?, ?)" );
.br
    query.bindValue( 0, 1001 );
.br
    query.bindValue( 1, "Bart" );
.br
    query.bindValue( 2, "Simpson" );
.br
    query.exec();
.br
.fi
.PP
\fBBinding values using positional placeholders #2\fR
.PP
.nf
.br
    query.prepare( "INSERT INTO atable (id, forename, surname) "
.br
                   "VALUES (?, ?, ?)" );
.br
    query.addBindValue( 1001 );
.br
    query.addBindValue( "Bart" );
.br
    query.addBindValue( "Simpson" );
.br
    query.exec();
.br
.fi
.PP
\fBBinding values to a stored procedure\fR This code calls a stored procedure called \fCAsciiToInt()\fR, passing it a character through its in parameter, and taking its result in the out parameter.
.PP
.nf
.br
    QSqlQuery query;
.br
    query.prepare( "call AsciiToInt(?, ?)" );
.br
    query.bindValue( 0, "A" );
.br
    query.bindValue( 1, 0, QSql::Out );
.br
    query.exec();
.br
    int i = query.boundValue( 1 ).toInt(); // i is 65.
.br
.fi
.PP
See also QSqlDatabase, QSqlCursor, QVariant, and Database Classes.
.SH MEMBER FUNCTION DOCUMENTATION