1QSqlQuery(3qt)                                                  QSqlQuery(3qt)
2
3
4

NAME

6       QSqlQuery - Means of executing and manipulating SQL statements
7

SYNOPSIS

9       #include <qsqlquery.h>
10
11       Inherited by QSqlCursor.
12
13   Public Members
14       QSqlQuery ( QSqlResult * r )
15       QSqlQuery ( const QString & query = QString::null, QSqlDatabase * db =
16           0 )
17       explicit QSqlQuery ( QSqlDatabase * db )
18       QSqlQuery ( const QSqlQuery & other )
19       QSqlQuery & operator= ( const QSqlQuery & other )
20       virtual ~QSqlQuery ()
21       bool isValid () const
22       bool isActive () const
23       bool isNull ( int field ) const
24       int at () const
25       QString lastQuery () const
26       int numRowsAffected () const
27       QSqlError lastError () const
28       bool isSelect () const
29       int size () const
30       const QSqlDriver * driver () const
31       const QSqlResult * result () const
32       bool isForwardOnly () const
33       void setForwardOnly ( bool forward )
34       virtual bool exec ( const QString & query )
35       virtual QVariant value ( int i ) const
36       virtual bool seek ( int i, bool relative = FALSE )
37       virtual bool next ()
38       virtual bool prev ()
39       virtual bool first ()
40       virtual bool last ()
41       bool exec ()
42       bool prepare ( const QString & query )
43       void bindValue ( const QString & placeholder, const QVariant & val )
44       void bindValue ( int pos, const QVariant & val )
45       void addBindValue ( const QVariant & val )
46       void bindValue ( const QString & placeholder, const QVariant & val,
47           QSql::ParameterType type )
48       void bindValue ( int pos, const QVariant & val, QSql::ParameterType
49           type )
50       void addBindValue ( const QVariant & val, QSql::ParameterType type )
51       QVariant boundValue ( const QString & placeholder ) const
52       QVariant boundValue ( int pos ) const
53       QMap<QString, QVariant> boundValues () const
54       QString executedQuery () const
55
56   Protected Members
57       virtual void beforeSeek ()
58       virtual void afterSeek ()
59

DESCRIPTION

61       The QSqlQuery class provides a means of executing and manipulating SQL
62       statements.
63
64       QSqlQuery encapsulates the functionality involved in creating,
65       navigating and retrieving data from SQL queries which are executed on a
66       QSqlDatabase. It can be used to execute DML (data manipulation
67       language) statements, e.g. SELECT, INSERT, UPDATE and DELETE, and also
68       DDL (data definition language) statements, e.g. CREATE TABLE. It can
69       also be used to execute database-specific commands which are not
70       standard SQL (e.g. SET DATESTYLE=ISO for PostgreSQL).
71
72       Successfully executed SQL statements set the query's state to active
73       (isActive() returns TRUE); otherwise the query's state is set to
74       inactive. In either case, when executing a new SQL statement, the query
75       is positioned on an invalid record; an active query must be navigated
76       to a valid record (so that isValid() returns TRUE) before values can be
77       retrieved.
78
79       Navigating records is performed with the following functions:
80
81       next()
82
83       prev()
84
85       first()
86
87       last()
88
89       seek(int)
90
91       These functions allow the programmer to move forward, backward or
92       arbitrarily through the records returned by the query. If you only need
93       to move forward through the results, e.g. using next() or using seek()
94       with a positive offset, you can use setForwardOnly() and save a
95       significant amount of memory overhead. Once an active query is
96       positioned on a valid record, data can be retrieved using value(). All
97       data is transferred from the SQL backend using QVariants.
98
99       For example:
100
101           QSqlQuery query( "SELECT name FROM customer" );
102           while ( query.next() ) {
103               QString name = query.value(0).toString();
104               doSomething( name );
105           }
106
107       To access the data returned by a query, use the value() method. Each
108       field in the data returned by a SELECT statement is accessed by passing
109       the field's position in the statement, starting from 0. Information
110       about the fields can be obtained via QSqlDatabase::record(). For the
111       sake of efficiency there are no functions to access a field by name.
112       (The QSqlCursor class provides a higher-level interface with field
113       access by name and automatic SQL generation.)
114
115       QSqlQuery supports prepared query execution and the binding of
116       parameter values to placeholders. Some databases don't support these
117       features, so for them Qt emulates the required functionality. For
118       example, the Oracle and ODBC drivers have proper prepared query
119       support, and Qt makes use of it; but for databases that don't have this
120       support, Qt implements the feature itself, e.g. by replacing
121       placeholders with actual values when a query is executed. The exception
122       is positional binding using named placeholders, which requires that the
123       database supports prepared queries.
124
125       Oracle databases identify placeholders by using a colon-name syntax,
126       e.g :name. ODBC simply uses ? characters. Qt supports both syntaxes
127       (although you can't mix them in the same query).
128
129       Below we present the same example using each of the four different
130       binding approaches.
131
132       Named binding using named placeholders
133
134           QSqlQuery query;
135           query.prepare( "INSERT INTO atable (id, forename, surname) "
136                          "VALUES (:id, :forename, :surname)" );
137           query.bindValue( ":id", 1001 );
138           query.bindValue( ":forename", "Bart" );
139           query.bindValue( ":surname", "Simpson" );
140           query.exec();
141
142       Positional binding using named placeholders
143
144           QSqlQuery query;
145           query.prepare( "INSERT INTO atable (id, forename, surname) "
146                          "VALUES (:id, :forename, :surname)" );
147           query.bindValue( 0, 1001 );
148           query.bindValue( 1, "Bart" );
149           query.bindValue( 2, "Simpson" );
150           query.exec();
151       Note: Using positional binding with named placeholders will only work
152       if the database supports prepared queries. This can be checked with
153       QSqlDriver::hasFeature() using QSqlDriver::PreparedQueries as argument
154       for driver feature.
155
156       Binding values using positional placeholders #1
157
158           QSqlQuery query;
159           query.prepare( "INSERT INTO atable (id, forename, surname) "
160                          "VALUES (?, ?, ?)" );
161           query.bindValue( 0, 1001 );
162           query.bindValue( 1, "Bart" );
163           query.bindValue( 2, "Simpson" );
164           query.exec();
165
166       Binding values using positional placeholders #2
167
168           query.prepare( "INSERT INTO atable (id, forename, surname) "
169                          "VALUES (?, ?, ?)" );
170           query.addBindValue( 1001 );
171           query.addBindValue( "Bart" );
172           query.addBindValue( "Simpson" );
173           query.exec();
174
175       Binding values to a stored procedure This code calls a stored procedure
176       called AsciiToInt(), passing it a character through its in parameter,
177       and taking its result in the out parameter.
178
179           QSqlQuery query;
180           query.prepare( "call AsciiToInt(?, ?)" );
181           query.bindValue( 0, "A" );
182           query.bindValue( 1, 0, QSql::Out );
183           query.exec();
184           int i = query.boundValue( 1 ).toInt(); // i is 65.
185
186       See also QSqlDatabase, QSqlCursor, QVariant, and Database Classes.
187

MEMBER FUNCTION DOCUMENTATION

QSqlQuery::QSqlQuery ( QSqlResult * r )

190       Creates a QSqlQuery object which uses the QSqlResult r to communicate
191       with a database.
192

QSqlQuery::QSqlQuery ( const QString & query = QString::null, QSqlDatabase *

194       db = 0 )
195       Creates a QSqlQuery object using the SQL query and the database db. If
196       db is 0, (the default), the application's default database is used. If
197       query is not a null string, it will be executed.
198
199       See also QSqlDatabase.
200

explicit QSqlQuery::QSqlQuery ( QSqlDatabase * db )

202       Creates a QSqlQuery object using the database db. If db is 0, the
203       application's default database is used.
204
205       See also QSqlDatabase.
206

QSqlQuery::QSqlQuery ( const QSqlQuery & other )

208       Constructs a copy of other.
209

QSqlQuery::~QSqlQuery () [virtual]

211       Destroys the object and frees any allocated resources.
212

void QSqlQuery::addBindValue ( const QVariant & val, QSql::ParameterType type

214       )
215       Adds the value val to the list of values when using positional value
216       binding. The order of the addBindValue() calls determines which
217       placeholder a value will be bound to in the prepared query. If type is
218       QSql::Out or QSql::InOut, the placeholder will be overwritten with data
219       from the database after the exec() call.
220
221       See also bindValue(), prepare(), and exec().
222

void QSqlQuery::addBindValue ( const QVariant & val )

224       This is an overloaded member function, provided for convenience. It
225       behaves essentially like the above function.
226
227       Binds the placeholder with type QSql::In.
228

void QSqlQuery::afterSeek () [virtual protected]

230       Protected virtual function called after the internal record pointer is
231       moved to a new record. The default implementation does nothing.
232

int QSqlQuery::at () const

234       Returns the current internal position of the query. The first record is
235       at position zero. If the position is invalid, a QSql::Location will be
236       returned indicating the invalid position.
237
238       See also prev(), next(), first(), last(), seek(), isActive(), and
239       isValid().
240
241       Example: sql/overview/navigating/main.cpp.
242

void QSqlQuery::beforeSeek () [virtual protected]

244       Protected virtual function called before the internal record pointer is
245       moved to a new record. The default implementation does nothing.
246

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

248       QSql::ParameterType type )
249       Set the placeholder placeholder to be bound to value val in the
250       prepared statement. Note that the placeholder mark (e.g :) must be
251       included when specifying the placeholder name. If type is QSql::Out or
252       QSql::InOut, the placeholder will be overwritten with data from the
253       database after the exec() call.
254
255       See also addBindValue(), prepare(), and exec().
256

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

258       )
259       This is an overloaded member function, provided for convenience. It
260       behaves essentially like the above function.
261
262       Binds the placeholder with type QSql::In.
263

void QSqlQuery::bindValue ( int pos, const QVariant & val )

265       This is an overloaded member function, provided for convenience. It
266       behaves essentially like the above function.
267
268       Binds the placeholder at position pos with type QSql::In.
269

void QSqlQuery::bindValue ( int pos, const QVariant & val, QSql::ParameterType

271       type )
272       This is an overloaded member function, provided for convenience. It
273       behaves essentially like the above function.
274
275       Set the placeholder in position pos to be bound to value val in the
276       prepared statement. Field numbering starts at 0. If type is QSql::Out
277       or QSql::InOut, the placeholder will be overwritten with data from the
278       database after the exec() call.
279
280       See also addBindValue(), prepare(), and exec().
281

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

283       Returns the value for the placeholder.
284

QVariant QSqlQuery::boundValue ( int pos ) const

286       This is an overloaded member function, provided for convenience. It
287       behaves essentially like the above function.
288
289       Returns the value for the placeholder at position pos.
290

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

292       Returns a map of the bound values.
293
294       The bound values can be examined in the following way:
295
296           QSqlQuery query;
297           ...
298           // Examine the bound values - bound using named binding
299           QMap<QString, QVariant>::ConstIterator it;
300           QMap<QString, QVariant> vals = query.boundValues();
301           for ( it = vals.begin(); it != vals.end(); ++it )
302               qWarning( "Placeholder: " + it.key() + ", Value: " + (*it).toString() );
303           ...
304           // Examine the bound values - bound using positional binding
305           QValueList<QVariant>::ConstIterator it;
306           QValueList<QVariant> list = query.boundValues().values();
307           int i = 0;
308           for ( it = list.begin(); it != list.end(); ++it )
309               qWarning( "Placeholder pos: %d, Value: " + (*it).toString(), i++ );
310           ...
311

const QSqlDriver * QSqlQuery::driver () const

313       Returns the database driver associated with the query.
314

bool QSqlQuery::exec ( const QString & query ) [virtual]

316       Executes the SQL in query. Returns TRUE and sets the query state to
317       active if the query was successful; otherwise returns FALSE and sets
318       the query state to inactive. The query string must use syntax
319       appropriate for the SQL database being queried, for example, standard
320       SQL.
321
322       After the query is executed, the query is positioned on an invalid
323       record, and must be navigated to a valid record before data values can
324       be retrieved, e.g. using next().
325
326       Note that the last error for this query is reset when exec() is called.
327
328       See also isActive(), isValid(), next(), prev(), first(), last(), and
329       seek().
330
331       Examples:
332

bool QSqlQuery::exec ()

334       This is an overloaded member function, provided for convenience. It
335       behaves essentially like the above function.
336
337       Executes a previously prepared SQL query. Returns TRUE if the query
338       executed successfully; otherwise returns FALSE.
339
340       See also prepare(), bindValue(), and addBindValue().
341

QString QSqlQuery::executedQuery () const

343       Returns the last query that was executed.
344
345       In most cases this function returns the same as lastQuery(). If a
346       prepared query with placeholders is executed on a DBMS that does not
347       support it, the preparation of this query is emulated. The placeholders
348       in the original query are replaced with their bound values to form a
349       new query. This function returns the modified query. Useful for
350       debugging purposes.
351
352       See also lastQuery().
353

bool QSqlQuery::first () [virtual]

355       Retrieves the first record in the result, if available, and positions
356       the query on the retrieved record. Note that the result must be in an
357       active state and isSelect() must return TRUE before calling this
358       function or it will do nothing and return FALSE. Returns TRUE if
359       successful. If unsuccessful the query position is set to an invalid
360       position and FALSE is returned.
361
362       See also next(), prev(), last(), seek(), at(), isActive(), and
363       isValid().
364
365       Example: sql/overview/navigating/main.cpp.
366

bool QSqlQuery::isActive () const

368       Returns TRUE if the query is currently active; otherwise returns FALSE.
369
370       Examples:
371

bool QSqlQuery::isForwardOnly () const

373       Returns TRUE if you can only scroll forward through a result set;
374       otherwise returns FALSE.
375
376       See also setForwardOnly().
377

bool QSqlQuery::isNull ( int field ) const

379       Returns TRUE if the query is active and positioned on a valid record
380       and the field is NULL; otherwise returns FALSE. Note that for some
381       drivers isNull() will not return accurate information until after an
382       attempt is made to retrieve data.
383
384       See also isActive(), isValid(), and value().
385

bool QSqlQuery::isSelect () const

387       Returns TRUE if the current query is a SELECT statement; otherwise
388       returns FALSE.
389

bool QSqlQuery::isValid () const

391       Returns TRUE if the query is currently positioned on a valid record;
392       otherwise returns FALSE.
393

bool QSqlQuery::last () [virtual]

395       Retrieves the last record in the result, if available, and positions
396       the query on the retrieved record. Note that the result must be in an
397       active state and isSelect() must return TRUE before calling this
398       function or it will do nothing and return FALSE. Returns TRUE if
399       successful. If unsuccessful the query position is set to an invalid
400       position and FALSE is returned.
401
402       See also next(), prev(), first(), seek(), at(), isActive(), and
403       isValid().
404
405       Example: sql/overview/navigating/main.cpp.
406

QSqlError QSqlQuery::lastError () const

408       Returns error information about the last error (if any) that occurred.
409
410       See also QSqlError.
411

QString QSqlQuery::lastQuery () const

413       Returns the text of the current query being used, or QString::null if
414       there is no current query text.
415
416       See also executedQuery().
417

bool QSqlQuery::next () [virtual]

419       Retrieves the next record in the result, if available, and positions
420       the query on the retrieved record. Note that the result must be in an
421       active state and isSelect() must return TRUE before calling this
422       function or it will do nothing and return FALSE.
423
424       The following rules apply:
425
426       If the result is currently located before the first record, e.g.
427       immediately after a query is executed, an attempt is made to retrieve
428       the first record.
429
430       If the result is currently located after the last record, there is no
431       change and FALSE is returned.
432
433       If the result is located somewhere in the middle, an attempt is made to
434       retrieve the next record.
435
436       If the record could not be retrieved, the result is positioned after
437       the last record and FALSE is returned. If the record is successfully
438       retrieved, TRUE is returned.
439
440       See also prev(), first(), last(), seek(), at(), isActive(), and
441       isValid().
442
443       Examples:
444

int QSqlQuery::numRowsAffected () const

446       Returns the number of rows affected by the result's SQL statement, or
447       -1 if it cannot be determined. Note that for SELECT statements, the
448       value is undefined; see size() instead. If the query is not active
449       (isActive() returns FALSE), -1 is returned.
450
451       See also size() and QSqlDriver::hasFeature().
452
453       Examples:
454

QSqlQuery & QSqlQuery::operator= ( const QSqlQuery & other )

456       Assigns other to the query.
457

bool QSqlQuery::prepare ( const QString & query )

459       Prepares the SQL query query for execution. The query may contain
460       placeholders for binding values. Both Oracle style colon-name (e.g.
461       :surname), and ODBC style (e.g. ?) placeholders are supported; but they
462       cannot be mixed in the same query. See the Description for examples.
463
464       See also exec(), bindValue(), and addBindValue().
465

bool QSqlQuery::prev () [virtual]

467       Retrieves the previous record in the result, if available, and
468       positions the query on the retrieved record. Note that the result must
469       be in an active state and isSelect() must return TRUE before calling
470       this function or it will do nothing and return FALSE.
471
472       The following rules apply:
473
474       If the result is currently located before the first record, there is no
475       change and FALSE is returned.
476
477       If the result is currently located after the last record, an attempt is
478       made to retrieve the last record.
479
480       If the result is somewhere in the middle, an attempt is made to
481       retrieve the previous record.
482
483       If the record could not be retrieved, the result is positioned before
484       the first record and FALSE is returned. If the record is successfully
485       retrieved, TRUE is returned.
486
487       See also next(), first(), last(), seek(), at(), isActive(), and
488       isValid().
489

const QSqlResult * QSqlQuery::result () const

491       Returns the result associated with the query.
492

bool QSqlQuery::seek ( int i, bool relative = FALSE ) [virtual]

494       Retrieves the record at position (offset) i, if available, and
495       positions the query on the retrieved record. The first record is at
496       position 0. Note that the query must be in an active state and
497       isSelect() must return TRUE before calling this function.
498
499       If relative is FALSE (the default), the following rules apply:
500
501       If i is negative, the result is positioned before the first record and
502       FALSE is returned.
503
504       Otherwise, an attempt is made to move to the record at position i. If
505       the record at position i could not be retrieved, the result is
506       positioned after the last record and FALSE is returned. If the record
507       is successfully retrieved, TRUE is returned.
508
509       If relative is TRUE, the following rules apply:
510
511       If the result is currently positioned before the first record or on the
512       first record, and i is negative, there is no change, and FALSE is
513       returned.
514
515       If the result is currently located after the last record, and i is
516       positive, there is no change, and FALSE is returned.
517
518       If the result is currently located somewhere in the middle, and the
519       relative offset i moves the result below zero, the result is positioned
520       before the first record and FALSE is returned.
521
522       Otherwise, an attempt is made to move to the record i records ahead of
523       the current record (or i records behind the current record if i is
524       negative). If the record at offset i could not be retrieved, the result
525       is positioned after the last record if i >= 0, (or before the first
526       record if i is negative), and FALSE is returned. If the record is
527       successfully retrieved, TRUE is returned.
528
529       See also next(), prev(), first(), last(), at(), isActive(), and
530       isValid().
531
532       Example: sql/overview/navigating/main.cpp.
533

void QSqlQuery::setForwardOnly ( bool forward )

535       Sets forward only mode to forward. If forward is TRUE only next(), and
536       seek() with positive values, are allowed for navigating the results.
537       Forward only mode needs far less memory since results do not need to be
538       cached.
539
540       Forward only mode is off by default.
541
542       Forward only mode cannot be used with data aware widgets like
543       QDataTable, since they must to be able to scroll backward as well as
544       forward.
545
546       See also isForwardOnly(), next(), and seek().
547

int QSqlQuery::size () const

549       Returns the size of the result, (number of rows returned), or -1 if the
550       size cannot be determined or if the database does not support reporting
551       information about query sizes. Note that for non-SELECT statements
552       (isSelect() returns FALSE), size() will return -1. If the query is not
553       active (isActive() returns FALSE), -1 is returned.
554
555       To determine the number of rows affected by a non-SELECT statement, use
556       numRowsAffected().
557
558       See also isActive(), numRowsAffected(), and QSqlDriver::hasFeature().
559
560       Example: sql/overview/navigating/main.cpp.
561

QVariant QSqlQuery::value ( int i ) const [virtual]

563       Returns the value of the i-th field in the query (zero based).
564
565       The fields are numbered from left to right using the text of the SELECT
566       statement, e.g. in SELECT forename, surname FROM people, field 0 is
567       forename and field 1 is surname. Using SELECT * is not recommended
568       because the order of the fields in the query is undefined.
569
570       An invalid QVariant is returned if field i does not exist, if the query
571       is inactive, or if the query is positioned on an invalid record.
572
573       See also prev(), next(), first(), last(), seek(), isActive(), and
574       isValid().
575
576       Examples:
577
578

SEE ALSO

580       http://doc.trolltech.com/qsqlquery.html
581       http://www.trolltech.com/faq/tech.html
582
584       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
585       license file included in the distribution for a complete license
586       statement.
587

AUTHOR

589       Generated automatically from the source code.
590

BUGS

592       If you find a bug in Qt, please report it as described in
593       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
594       help you. Thank you.
595
596       The definitive Qt documentation is provided in HTML format; it is
597       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
598       web browser. This man page is provided as a convenience for those users
599       who prefer man pages, although this format is not officially supported
600       by Trolltech.
601
602       If you find errors in this manual page, please report them to qt-
603       bugs@trolltech.com.  Please include the name of the manual page
604       (qsqlquery.3qt) and the Qt version (3.3.8).
605
606
607
608Trolltech AS                    2 February 2007                 QSqlQuery(3qt)
Impressum