1QSqlQuery(3qt) QSqlQuery(3qt)
2
6 QSqlQuery - Means of executing and manipulating SQL statements
7
9 #include <qsqlquery.h>
10 Inherited by QSqlCursor.
12 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 Protected Members
57 virtual void beforeSeek ()
58 virtual void afterSeek ()
59
61 The QSqlQuery class provides a means of executing and manipulating SQL
62 statements.
63 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 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 Navigating records is performed with the following functions:
80 next()
82 prev()
84 first()
86 last()
88 seek(int)
90 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 For example:
100 QSqlQuery query( "SELECT name FROM customer" );
102 while ( query.next() ) {
103 QString name = query.value(0).toString();
104 doSomething( name );
105 }
106 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 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 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 Below we present the same example using each of the four different
130 binding approaches.
131 Named binding using named placeholders
133 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 Positional binding using named placeholders
143 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 Binding values using positional placeholders #1
157 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 Binding values using positional placeholders #2
167 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 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 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 See also QSqlDatabase, QSqlCursor, QVariant, and Database Classes.
187
190 Creates a QSqlQuery object which uses the QSqlResult r to communicate
191 with a database.
192
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 See also QSqlDatabase.
200
202 Creates a QSqlQuery object using the database db. If db is 0, the
203 application's default database is used.
204 See also QSqlDatabase.
206
208 Constructs a copy of other.
209
211 Destroys the object and frees any allocated resources.
212
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 See also bindValue(), prepare(), and exec().
222
224 This is an overloaded member function, provided for convenience. It
225 behaves essentially like the above function.
226 Binds the placeholder with type QSql::In.
228
230 Protected virtual function called after the internal record pointer is
231 moved to a new record. The default implementation does nothing.
232
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 See also prev(), next(), first(), last(), seek(), isActive(), and
239 isValid().
240 Example: sql/overview/navigating/main.cpp.
242
244 Protected virtual function called before the internal record pointer is
245 moved to a new record. The default implementation does nothing.
246
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 See also addBindValue(), prepare(), and exec().
256
258 )
259 This is an overloaded member function, provided for convenience. It
260 behaves essentially like the above function.
261 Binds the placeholder with type QSql::In.
263
265 This is an overloaded member function, provided for convenience. It
266 behaves essentially like the above function.
267 Binds the placeholder at position pos with type QSql::In.
269
271 type )
272 This is an overloaded member function, provided for convenience. It
273 behaves essentially like the above function.
274 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 See also addBindValue(), prepare(), and exec().
281
283 Returns the value for the placeholder.
284
286 This is an overloaded member function, provided for convenience. It
287 behaves essentially like the above function.
288 Returns the value for the placeholder at position pos.
290
292 Returns a map of the bound values.
293 The bound values can be examined in the following way:
295 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
313 Returns the database driver associated with the query.
314
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 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 Note that the last error for this query is reset when exec() is called.
327 See also isActive(), isValid(), next(), prev(), first(), last(), and
329 seek().
330 Examples:
332
334 This is an overloaded member function, provided for convenience. It
335 behaves essentially like the above function.
336 Executes a previously prepared SQL query. Returns TRUE if the query
338 executed successfully; otherwise returns FALSE.
339 See also prepare(), bindValue(), and addBindValue().
341
343 Returns the last query that was executed.
344 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 See also lastQuery().
353
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 See also next(), prev(), last(), seek(), at(), isActive(), and
363 isValid().
364 Example: sql/overview/navigating/main.cpp.
366
368 Returns TRUE if the query is currently active; otherwise returns FALSE.
369 Examples:
371
373 Returns TRUE if you can only scroll forward through a result set;
374 otherwise returns FALSE.
375 See also setForwardOnly().
377
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 See also isActive(), isValid(), and value().
385
387 Returns TRUE if the current query is a SELECT statement; otherwise
388 returns FALSE.
389
391 Returns TRUE if the query is currently positioned on a valid record;
392 otherwise returns FALSE.
393
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 See also next(), prev(), first(), seek(), at(), isActive(), and
403 isValid().
404 Example: sql/overview/navigating/main.cpp.
406
408 Returns error information about the last error (if any) that occurred.
409 See also QSqlError.
411
413 Returns the text of the current query being used, or QString::null if
414 there is no current query text.
415 See also executedQuery().
417
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 The following rules apply:
425 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 If the result is currently located after the last record, there is no
431 change and FALSE is returned.
432 If the result is located somewhere in the middle, an attempt is made to
434 retrieve the next record.
435 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 See also prev(), first(), last(), seek(), at(), isActive(), and
441 isValid().
442 Examples:
444
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 See also size() and QSqlDriver::hasFeature().
452 Examples:
454
456 Assigns other to the query.
457
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 See also exec(), bindValue(), and addBindValue().
465
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 The following rules apply:
473 If the result is currently located before the first record, there is no
475 change and FALSE is returned.
476 If the result is currently located after the last record, an attempt is
478 made to retrieve the last record.
479 If the result is somewhere in the middle, an attempt is made to
481 retrieve the previous record.
482 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 See also next(), first(), last(), seek(), at(), isActive(), and
488 isValid().
489
491 Returns the result associated with the query.
492
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 If relative is FALSE (the default), the following rules apply:
500 If i is negative, the result is positioned before the first record and
502 FALSE is returned.
503 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 If relative is TRUE, the following rules apply:
510 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 If the result is currently located after the last record, and i is
516 positive, there is no change, and FALSE is returned.
517 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 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 See also next(), prev(), first(), last(), at(), isActive(), and
530 isValid().
531 Example: sql/overview/navigating/main.cpp.
533
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 Forward only mode is off by default.
541 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 See also isForwardOnly(), next(), and seek().
547
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 To determine the number of rows affected by a non-SELECT statement, use
556 numRowsAffected().
557 See also isActive(), numRowsAffected(), and QSqlDriver::hasFeature().
559 Example: sql/overview/navigating/main.cpp.
561
563 Returns the value of the i-th field in the query (zero based).
564 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 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 See also prev(), next(), first(), last(), seek(), isActive(), and
574 isValid().
575 Examples:
577
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
589 Generated automatically from the source code.
590
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 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 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).
605Trolltech AS 2 February 2007 QSqlQuery(3qt)