qsqlcursor.3qt

Trolltech公司发布的基于C++图形开发环境

The \fIfilter\fR is a string containing a SQL \fCWHERE\fR clause but without the 'WHERE' keyword. The cursor is initially positioned at an invalid row after this function is called. To move to a valid row, use seek(), first(), last(), prev() or next().
.PP
Example:
.PP
.nf
.br
    QSqlCursor cur( "Employee" ); // Use the Employee table or view
.br
    cur.select( "deptno=10" ); // select all records in department 10
.br
    while( cur.next() ) {
.br
        ... // process data
.br
    }
.br
    ...
.br
    // select records in other departments, ordered by department number
.br
    cur.select( "deptno>10", cur.index( "deptno" ) );
.br
    ...
.br
.fi
.PP
The filter will apply to any subsequent select() calls that do not explicitly specify another filter. Similarly the sort will apply to any subsequent select() calls that do not explicitly specify another sort.
.PP
.nf
.br
    QSqlCursor cur( "Employee" );
.br
    cur.select( "deptno=10" ); // select all records in department 10
.br
    while( cur.next() ) {
.br
        ... // process data
.br
    }
.br
    ...
.br
    cur.select(); // re-selects all records in department 10
.br
    ...
.br
.fi
.PP
Examples:
.)l sql/overview/delete/main.cpp, sql/overview/extract/main.cpp, sql/overview/order1/main.cpp, sql/overview/order2/main.cpp, sql/overview/retrieve2/main.cpp, sql/overview/table3/main.cpp, and sql/overview/update/main.cpp.
.SH "bool QSqlCursor::select ()"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Selects all fields in the cursor from the database. The rows are returned in the order specified by the last call to setSort() or the last call to select() that specified a sort, whichever is the most recent. If there is no current sort, the order in which the rows are returned is undefined. The records are filtered according to the filter specified by the last call to setFilter() or the last call to select() that specified a filter, whichever is the most recent. If there is no current filter, all records are returned. The cursor is initially positioned at an invalid row. To move to a valid row, use seek(), first(), last(), prev() or next().
.PP
See also setSort() and setFilter().
.SH "bool QSqlCursor::select ( const QSqlIndex & sort )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Selects all fields in the cursor from the database. The data is returned in the order specified by the index \fIsort\fR. The records are filtered according to the filter specified by the last call to setFilter() or the last call to select() that specified a filter, whichever is the most recent. The cursor is initially positioned at an invalid row. To move to a valid row, use seek(), first(), last(), prev() or next().
.SH "bool QSqlCursor::select ( const QSqlIndex & filter, const QSqlIndex & sort )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Selects all fields in the cursor matching the filter index \fIfilter\fR. The data is returned in the order specified by the index \fIsort\fR. The \fIfilter\fR index works by constructing a WHERE clause using the names of the fields from the \fIfilter\fR and their values from the current cursor record. The cursor is initially positioned at an invalid row. To move to a valid row, use seek(), first(), last(), prev() or next(). This function is useful, for example, for retrieving data based upon a table's primary index:
.PP
.nf
.br
    QSqlCursor cur( "Employee" );
.br
    QSqlIndex pk = cur.primaryIndex();
.br
    cur.setValue( "id", 10 );
.br
    cur.select( pk, pk ); // generates "SELECT ... FROM Employee WHERE id=10 ORDER BY id"
.br
    ...
.br
.fi
.PP
In this example the QSqlIndex, pk, is used for two different purposes. When used as the filter (first) argument, the field names it contains are used to construct the WHERE clause, each set to the current cursor value, \fCWHERE id=10\fR, in this case. When used as the sort (second) argument the field names it contains are used for the ORDER BY clause, \fCORDER BY id\fR in this example.
.SH "void QSqlCursor::setCalculated ( const QString & name, bool calculated )\fC [virtual]\fR"
Sets field \fIname\fR to \fIcalculated\fR. If the field \fIname\fR does not exist, nothing happens. The value of a calculated field is set by the calculateField() virtual function which you must reimplement (or the field value will be an invalid QVariant). Calculated fields do not appear in generated SQL statements sent to the database.
.PP
See also calculateField() and QSqlRecord::setGenerated().
.SH "void QSqlCursor::setFilter ( const QString & filter )\fC [virtual]\fR"
Sets the current filter to \fIfilter\fR. Note that no new records are selected. To select new records, use select(). The \fIfilter\fR will apply to any subsequent select() calls that do not explicitly specify a filter.
.PP
The filter is a SQL \fCWHERE\fR clause without the keyword 'WHERE', e.g. \fCname='Dave'\fR which will be processed by the DBMS.
.SH "void QSqlCursor::setGenerated ( const QString & name, bool generated )\fC [virtual]\fR"
Sets the generated flag for the field \fIname\fR to \fIgenerated\fR. If the field does not exist, nothing happens. Only fields that have \fIgenerated\fR set to TRUE are included in the SQL that is generated.
.PP
See also isGenerated().
.PP
Reimplemented from QSqlRecord.
.SH "void QSqlCursor::setGenerated ( int i, bool generated )\fC [virtual]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Sets the generated flag for the field \fIi\fR to \fIgenerated\fR.
.PP
See also isGenerated().
.PP
Reimplemented from QSqlRecord.
.SH "void QSqlCursor::setMode ( int mode )\fC [virtual]\fR"
Sets the cursor mode to \fImode\fR. This value can be an OR'ed combination of QSqlCursor::Mode values. The default mode for a cursor is QSqlCursor::Writable.
.PP
.nf
.br
    QSqlCursor cur( "Employee" );
.br
    cur.setMode( QSqlCursor::Writable ); // allow insert/update/delete
.br
    ...
.br
    cur.setMode( QSqlCursor::Insert | QSqlCursor::Update ); // allow inserts and updates only
.br
    ...
.br
    cur.setMode( QSqlCursor::ReadOnly ); // no inserts/updates/deletes allowed
.br
.br
.fi
.SH "void QSqlCursor::setName ( const QString & name, bool autopopulate = TRUE )\fC [virtual]\fR"
Sets the name of the cursor to \fIname\fR. If \fIautopopulate\fR is TRUE (the default), the \fIname\fR must correspond to a valid table or view name in the database. Also, note that all references to the cursor edit buffer become invalidated when fields are auto-populated. See the QSqlCursor constructor documentation for more information.
.SH "void QSqlCursor::setPrimaryIndex ( const QSqlIndex & idx )\fC [virtual]\fR"
Sets the primary index associated with the cursor to the index \fIidx\fR. Note that this index must contain a field or set of fields which identify a unique record within the underlying database table or view so that update() and del() will execute as expected.
.PP
See also update() and del().
.SH "void QSqlCursor::setSort ( const QSqlIndex & sort )\fC [virtual]\fR"
Sets the current sort to \fIsort\fR. Note that no new records are selected. To select new records, use select(). The \fIsort\fR will apply to any subsequent select() calls that do not explicitly specify a sort.
.SH "void QSqlCursor::setTrimmed ( const QString & name, bool trim )\fC [virtual]\fR"
Sets field \fIname\fR's trimmed status to \fItrim\fR. If the field \fIname\fR does not exist, nothing happens.
.PP
When a trimmed field of type string or cstring is read from the database any trailing (right-most) spaces are removed.
.PP
See also isTrimmed() and QVariant.
.SH "QSqlIndex QSqlCursor::sort () const"
Returns the current sort, or an empty index if there is no current sort.
.SH "QString QSqlCursor::toString ( QSqlRecord * rec, const QString & prefix, const QString & fieldSep, const QString & sep ) const\fC [virtual protected]\fR"
Returns a formatted string composed of all the fields in \fIrec\fR. Each field is composed of the \fIprefix\fR (e.g. table or view name),"
.", the field name, the \fIfieldSep\fR and the field value. If the
\fIprefix\fR is empty then each field will begin with the field name. The fields are then joined together separated by \fIsep\fR. Fields where isGenerated() returns FALSE are not included. This function is useful for generating SQL statements.
.SH "QString QSqlCursor::toString ( const QString & prefix, QSqlField * field, const QString & fieldSep ) const\fC [virtual protected]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns a formatted string composed of the \fIprefix\fR (e.g. table or view name), ".", the \fIfield\fR name, the \fIfieldSep\fR and the field value. If the \fIprefix\fR is empty then the string will begin with the \fIfield\fR name. This function is useful for generating SQL statements.
.SH "QString QSqlCursor::toString ( const QSqlIndex & i, QSqlRecord * rec, const QString & prefix, const QString & fieldSep, const QString & sep ) const\fC [virtual protected]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns a formatted string composed of all the fields in the index \fIi\fR. Each field is composed of the \fIprefix\fR (e.g. table or view name), ".", the field name, the \fIfieldSep\fR and the field value. If the \fIprefix\fR is empty then each field will begin with the field name. The field values are taken from \fIrec\fR. The fields are then joined together separated by \fIsep\fR. Fields where isGenerated() returns FALSE are ignored. This function is useful for generating SQL statements.
.SH "int QSqlCursor::update ( bool invalidate = TRUE )\fC [virtual]\fR"
Updates the database with the current contents of the edit buffer. Returns the number of records which were updated. For error information, use lastError().
.PP
Only records which meet the filter criteria specified by the cursor's primary index are updated. If the cursor does not contain a primary index, no update is performed and 0 is returned.
.PP
If \fIinvalidate\fR is TRUE (the default), the current cursor can no longer be navigated. A new select() call must be made before you can move to a valid record. For example:
.PP
.nf
.br
            QSqlCursor cur( "prices" );
.br
            cur.select( "id=202" );
.br
            if ( cur.next() ) {
.br
                QSqlRecord *buffer = cur.primeUpdate();
.br
                double price = buffer->value( "price" ).toDouble();
.br
                double newprice = price * 1.05;
.br
                buffer->setValue( "price", newprice );
.br
                cur.update();
.br
            }
.fi
.PP
In the above example, a cursor is created on the 'prices' table and is positioned on the record to be updated. Then a pointer to the cursor's edit buffer is acquired using primeUpdate(). A new value is calculated and placed into the edit buffer with the setValue() call. Finally, an update() call is made on the cursor which uses the tables's primary index to update the record in the database with the contents of the cursor's edit buffer. Remember: all edit operations (insert(), update() and delete()) operate on the contents of the cursor edit buffer and not on the contents of the cursor itself.
.PP
Note that if the primary index does not uniquely distinguish records the database may be changed into an inconsistent state.
.PP
See also setMode() and lastError().
.PP
Example: sql/overview/update/main.cpp.
.SH "int QSqlCursor::update ( const QString & filter, bool invalidate = TRUE )\fC [virtual protected]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Updates the database with the current contents of the cursor edit buffer using the specified \fIfilter\fR. Returns the number of records which were updated. For error information, use lastError().
.PP
Only records which meet the filter criteria are updated, otherwise all records in the table are updated.
.PP
If \fIinvalidate\fR is TRUE (the default), the cursor can no longer be navigated. A new select() call must be made before you can move to a valid record.
.PP
See also primeUpdate(), setMode(), and lastError().

.SH "SEE ALSO"
.BR http://doc.trolltech.com/qsqlcursor.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech. 
.P
If you find errors in this manual page, please report them to
.BR [e-mail] .
Please include the name of the manual page (qsqlcursor.3qt) and the Qt
version (3.3.4).