source: trunk/doc/html/qsqlquery.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 35.7 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/sql/qsqlquery.cpp:79 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QSqlQuery Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QSqlQuery Class Reference<br><small>[<a href="sql.html">sql module</a>]</small></h1>
33
34<p>The QSqlQuery class provides a means of executing and
35manipulating SQL statements.
36<a href="#details">More...</a>
37<p><tt>#include &lt;<a href="qsqlquery-h.html">qsqlquery.h</a>&gt;</tt>
38<p>Inherited by <a href="qsqlcursor.html">QSqlCursor</a>.
39<p><a href="qsqlquery-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn><a href="#QSqlQuery"><b>QSqlQuery</b></a> ( QSqlResult&nbsp;*&nbsp;r )</li>
43<li class=fn><a href="#QSqlQuery-2"><b>QSqlQuery</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;query = QString::null, QSqlDatabase&nbsp;*&nbsp;db = 0 )</li>
44<li class=fn>explicit <a href="#QSqlQuery-3"><b>QSqlQuery</b></a> ( QSqlDatabase&nbsp;*&nbsp;db )</li>
45<li class=fn><a href="#QSqlQuery-4"><b>QSqlQuery</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;other )</li>
46<li class=fn>QSqlQuery &amp; <a href="#operator-eq"><b>operator=</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;other )</li>
47<li class=fn>virtual <a href="#~QSqlQuery"><b>~QSqlQuery</b></a> ()</li>
48<li class=fn>bool <a href="#isValid"><b>isValid</b></a> () const</li>
49<li class=fn>bool <a href="#isActive"><b>isActive</b></a> () const</li>
50<li class=fn>bool <a href="#isNull"><b>isNull</b></a> ( int&nbsp;field ) const</li>
51<li class=fn>int <a href="#at"><b>at</b></a> () const</li>
52<li class=fn>QString <a href="#lastQuery"><b>lastQuery</b></a> () const</li>
53<li class=fn>int <a href="#numRowsAffected"><b>numRowsAffected</b></a> () const</li>
54<li class=fn>QSqlError <a href="#lastError"><b>lastError</b></a> () const</li>
55<li class=fn>bool <a href="#isSelect"><b>isSelect</b></a> () const</li>
56<li class=fn>int <a href="#size"><b>size</b></a> () const</li>
57<li class=fn>const QSqlDriver * <a href="#driver"><b>driver</b></a> () const</li>
58<li class=fn>const QSqlResult * <a href="#result"><b>result</b></a> () const</li>
59<li class=fn>bool <a href="#isForwardOnly"><b>isForwardOnly</b></a> () const</li>
60<li class=fn>void <a href="#setForwardOnly"><b>setForwardOnly</b></a> ( bool&nbsp;forward )</li>
61<li class=fn>virtual bool <a href="#exec"><b>exec</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;query )</li>
62<li class=fn>virtual QVariant <a href="#value"><b>value</b></a> ( int&nbsp;i ) const</li>
63<li class=fn>virtual bool <a href="#seek"><b>seek</b></a> ( int&nbsp;i, bool&nbsp;relative = FALSE )</li>
64<li class=fn>virtual bool <a href="#next"><b>next</b></a> ()</li>
65<li class=fn>virtual bool <a href="#prev"><b>prev</b></a> ()</li>
66<li class=fn>virtual bool <a href="#first"><b>first</b></a> ()</li>
67<li class=fn>virtual bool <a href="#last"><b>last</b></a> ()</li>
68<li class=fn>bool <a href="#exec-2"><b>exec</b></a> ()</li>
69<li class=fn>bool <a href="#prepare"><b>prepare</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;query )</li>
70<li class=fn>void <a href="#bindValue-2"><b>bindValue</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;placeholder, const&nbsp;QVariant&nbsp;&amp;&nbsp;val )</li>
71<li class=fn>void <a href="#bindValue-3"><b>bindValue</b></a> ( int&nbsp;pos, const&nbsp;QVariant&nbsp;&amp;&nbsp;val )</li>
72<li class=fn>void <a href="#addBindValue-2"><b>addBindValue</b></a> ( const&nbsp;QVariant&nbsp;&amp;&nbsp;val )</li>
73<li class=fn>void <a href="#bindValue"><b>bindValue</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;placeholder, const&nbsp;QVariant&nbsp;&amp;&nbsp;val, QSql::ParameterType&nbsp;type )</li>
74<li class=fn>void <a href="#bindValue-4"><b>bindValue</b></a> ( int&nbsp;pos, const&nbsp;QVariant&nbsp;&amp;&nbsp;val, QSql::ParameterType&nbsp;type )</li>
75<li class=fn>void <a href="#addBindValue"><b>addBindValue</b></a> ( const&nbsp;QVariant&nbsp;&amp;&nbsp;val, QSql::ParameterType&nbsp;type )</li>
76<li class=fn>QVariant <a href="#boundValue"><b>boundValue</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;placeholder ) const</li>
77<li class=fn>QVariant <a href="#boundValue-2"><b>boundValue</b></a> ( int&nbsp;pos ) const</li>
78<li class=fn>QMap&lt;QString, QVariant&gt; <a href="#boundValues"><b>boundValues</b></a> () const</li>
79<li class=fn>QString <a href="#executedQuery"><b>executedQuery</b></a> () const</li>
80</ul>
81<h2>Protected Members</h2>
82<ul>
83<li class=fn>virtual void <a href="#beforeSeek"><b>beforeSeek</b></a> ()</li>
84<li class=fn>virtual void <a href="#afterSeek"><b>afterSeek</b></a> ()</li>
85</ul>
86<hr><a name="details"></a><h2>Detailed Description</h2>
87
88
89The QSqlQuery class provides a means of executing and
90manipulating SQL statements.
91<p>
92
93
94<p> QSqlQuery encapsulates the functionality involved in creating,
95navigating and retrieving data from SQL queries which are executed
96on a <a href="qsqldatabase.html">QSqlDatabase</a>. It can be used to execute DML (data
97manipulation language) statements, e.g. <tt>SELECT</tt>, <tt>INSERT</tt>, <tt>UPDATE</tt> and <tt>DELETE</tt>, and also DDL (data definition language)
98statements, e.g. <tt>CREATE TABLE</tt>. It can also be used to
99execute database-specific commands which are not standard SQL
100(e.g. <tt>SET DATESTYLE=ISO</tt> for PostgreSQL).
101<p> Successfully executed SQL statements set the query's state to
102active (<a href="#isActive">isActive</a>() returns TRUE); otherwise the query's state is
103set to inactive. In either case, when executing a new SQL
104statement, the query is positioned on an invalid record; an active
105query must be navigated to a valid record (so that <a href="#isValid">isValid</a>()
106returns TRUE) before values can be retrieved.
107<p> Navigating records is performed with the following functions:
108<p> <ul>
109<li> <a href="#next">next</a>()
110<li> <a href="#prev">prev</a>()
111<li> <a href="#first">first</a>()
112<li> <a href="#last">last</a>()
113<li> <tt></tt><a href="#seek">seek</a>(int)
114</ul>
115<p> These functions allow the programmer to move forward, backward or
116arbitrarily through the records returned by the query. If you only
117need to move forward through the results, e.g. using <a href="#next">next</a>() or
118using <a href="#seek">seek</a>() with a positive offset, you can use <a href="#setForwardOnly">setForwardOnly</a>()
119and save a significant amount of memory overhead. Once an active
120query is positioned on a valid record, data can be retrieved using
121<a href="#value">value</a>(). All data is transferred from the SQL backend using
122QVariants.
123<p> For example:
124<p> <pre>
125 QSqlQuery query( "SELECT name FROM customer" );
126 while ( query.<a href="#next">next</a>() ) {
127 <a href="qstring.html">QString</a> name = query.<a href="#value">value</a>(0).toString();
128 doSomething( name );
129 }
130 </pre>
131
132<p> To access the data returned by a query, use the value() method.
133Each field in the data returned by a SELECT statement is accessed
134by passing the field's position in the statement, starting from 0.
135Information about the fields can be obtained via <a href="qsqldatabase.html#record">QSqlDatabase::record</a>().
136For the sake of efficiency there are no functions to access a field
137by name. (The <a href="qsqlcursor.html">QSqlCursor</a> class provides a higher-level interface
138with field access by name and automatic SQL generation.)
139<p> QSqlQuery supports prepared query execution and the binding of
140parameter values to placeholders. Some databases don't support
141these features, so for them Qt emulates the required
142functionality. For example, the Oracle and ODBC drivers have
143proper prepared query support, and Qt makes use of it; but for
144databases that don't have this support, Qt implements the feature
145itself, e.g. by replacing placeholders with actual values when a
146query is executed. The exception is positional binding using named
147placeholders, which requires that the database supports prepared
148queries.
149<p> Oracle databases identify placeholders by using a colon-name
150syntax, e.g <tt>:name</tt>. ODBC simply uses <tt>?</tt> characters. Qt
151supports both syntaxes (although you can't mix them in the same
152query).
153<p> Below we present the same example using each of the four different
154binding approaches.
155<p> <b>Named binding using named placeholders</b>
156<pre>
157 QSqlQuery query;
158 query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) "
159 "VALUES (:id, :forename, :surname)" );
160 query.<a href="#bindValue">bindValue</a>( ":id", 1001 );
161 query.<a href="#bindValue">bindValue</a>( ":forename", "Bart" );
162 query.<a href="#bindValue">bindValue</a>( ":surname", "Simpson" );
163 query.<a href="#exec">exec</a>();
164 </pre>
165
166<p> <b>Positional binding using named placeholders</b>
167<pre>
168 QSqlQuery query;
169 query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) "
170 "VALUES (:id, :forename, :surname)" );
171 query.<a href="#bindValue">bindValue</a>( 0, 1001 );
172 query.<a href="#bindValue">bindValue</a>( 1, "Bart" );
173 query.<a href="#bindValue">bindValue</a>( 2, "Simpson" );
174 query.<a href="#exec">exec</a>();
175 </pre>
176
177<b>Note:</b> Using positional binding with named placeholders will
178only work if the database supports prepared queries. This can be
179checked with <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>() using QSqlDriver::PreparedQueries
180as argument for driver feature.
181<p> <b>Binding values using positional placeholders #1</b>
182<pre>
183 QSqlQuery query;
184 query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) "
185 "VALUES (?, ?, ?)" );
186 query.<a href="#bindValue">bindValue</a>( 0, 1001 );
187 query.<a href="#bindValue">bindValue</a>( 1, "Bart" );
188 query.<a href="#bindValue">bindValue</a>( 2, "Simpson" );
189 query.<a href="#exec">exec</a>();
190 </pre>
191
192<p> <b>Binding values using positional placeholders #2</b>
193<pre>
194 query.prepare( "INSERT INTO atable (id, forename, surname) "
195 "VALUES (?, ?, ?)" );
196 query.addBindValue( 1001 );
197 query.addBindValue( "Bart" );
198 query.addBindValue( "Simpson" );
199 query.exec();
200 </pre>
201
202<p> <b>Binding values to a stored procedure</b>
203This code calls a stored procedure called <tt>AsciiToInt()</tt>, passing
204it a character through its in parameter, and taking its result in
205the out parameter.
206<pre>
207 QSqlQuery query;
208 query.<a href="#prepare">prepare</a>( "call AsciiToInt(?, ?)" );
209 query.<a href="#bindValue">bindValue</a>( 0, "A" );
210 query.<a href="#bindValue">bindValue</a>( 1, 0, QSql::Out );
211 query.<a href="#exec">exec</a>();
212 int i = query.<a href="#boundValue">boundValue</a>( 1 ).toInt(); // i is 65.
213 </pre>
214
215<p> <p>See also <a href="qsqldatabase.html">QSqlDatabase</a>, <a href="qsqlcursor.html">QSqlCursor</a>, <a href="qvariant.html">QVariant</a>, and <a href="database.html">Database Classes</a>.
216
217<hr><h2>Member Function Documentation</h2>
218<h3 class=fn><a name="QSqlQuery"></a>QSqlQuery::QSqlQuery ( <a href="qsqlresult.html">QSqlResult</a>&nbsp;*&nbsp;r )
219</h3>
220Creates a QSqlQuery object which uses the <a href="qsqlresult.html">QSqlResult</a> <em>r</em> to
221communicate with a database.
222
223<h3 class=fn><a name="QSqlQuery-2"></a>QSqlQuery::QSqlQuery ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;query = QString::null, <a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;*&nbsp;db = 0 )
224</h3>
225Creates a QSqlQuery object using the SQL <em>query</em> and the database
226<em>db</em>. If <em>db</em> is 0, (the default), the application's default
227database is used. If <em>query</em> is not a null string, it will be
228executed.
229<p> <p>See also <a href="qsqldatabase.html">QSqlDatabase</a>.
230
231<h3 class=fn>explicit <a name="QSqlQuery-3"></a>QSqlQuery::QSqlQuery ( <a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;*&nbsp;db )
232</h3>
233Creates a QSqlQuery object using the database <em>db</em>. If <em>db</em> is
2340, the application's default database is used.
235<p> <p>See also <a href="qsqldatabase.html">QSqlDatabase</a>.
236
237<h3 class=fn><a name="QSqlQuery-4"></a>QSqlQuery::QSqlQuery ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;other )
238</h3>
239Constructs a copy of <em>other</em>.
240
241<h3 class=fn><a name="~QSqlQuery"></a>QSqlQuery::~QSqlQuery ()<tt> [virtual]</tt>
242</h3>
243Destroys the object and frees any allocated resources.
244
245<h3 class=fn>void <a name="addBindValue"></a>QSqlQuery::addBindValue ( const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val, <a href="qsql.html#ParameterType-enum">QSql::ParameterType</a>&nbsp;type )
246</h3>
247Adds the value <em>val</em> to the list of values when using positional
248value binding. The order of the <a href="#addBindValue">addBindValue</a>() calls determines
249which placeholder a value will be bound to in the prepared query.
250If <em>type</em> is <a href="qsql.html#ParameterType-enum">QSql::Out</a> or <a href="qsql.html#ParameterType-enum">QSql::InOut</a>, the placeholder will
251be overwritten with data from the database after the <a href="#exec">exec</a>() call.
252<p> <p>See also <a href="#bindValue">bindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>().
253
254<h3 class=fn>void <a name="addBindValue-2"></a>QSqlQuery::addBindValue ( const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val )
255</h3>
256This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
257<p> Binds the placeholder with type <a href="qsql.html#ParameterType-enum">QSql::In</a>.
258
259<h3 class=fn>void <a name="afterSeek"></a>QSqlQuery::afterSeek ()<tt> [virtual protected]</tt>
260</h3>
261Protected virtual function called after the internal record
262pointer is moved to a new record. The default implementation does
263nothing.
264
265<h3 class=fn>int <a name="at"></a>QSqlQuery::at () const
266</h3>
267Returns the current internal position of the query. The first
268record is at position zero. If the position is invalid, a
269QSql::Location will be returned indicating the invalid position.
270<p> <p>See also <a href="#prev">prev</a>(), <a href="#next">next</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), <a href="#seek">seek</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
271
272<p>Example: <a href="sql.html#x2169">sql/overview/navigating/main.cpp</a>.
273<h3 class=fn>void <a name="beforeSeek"></a>QSqlQuery::beforeSeek ()<tt> [virtual protected]</tt>
274</h3>
275Protected virtual function called before the internal record
276pointer is moved to a new record. The default implementation does
277nothing.
278
279<h3 class=fn>void <a name="bindValue"></a>QSqlQuery::bindValue ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;placeholder, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val, <a href="qsql.html#ParameterType-enum">QSql::ParameterType</a>&nbsp;type )
280</h3>
281Set the placeholder <em>placeholder</em> to be bound to value <em>val</em> in
282the prepared statement. Note that the placeholder mark (e.g <tt>:</tt>)
283must be included when specifying the placeholder name. If <em>type</em>
284is <a href="qsql.html#ParameterType-enum">QSql::Out</a> or <a href="qsql.html#ParameterType-enum">QSql::InOut</a>, the placeholder will be
285overwritten with data from the database after the <a href="#exec">exec</a>() call.
286<p> <p>See also <a href="#addBindValue">addBindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>().
287
288<h3 class=fn>void <a name="bindValue-2"></a>QSqlQuery::bindValue ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;placeholder, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val )
289</h3>
290This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
291<p> Binds the placeholder with type <a href="qsql.html#ParameterType-enum">QSql::In</a>.
292
293<h3 class=fn>void <a name="bindValue-3"></a>QSqlQuery::bindValue ( int&nbsp;pos, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val )
294</h3>
295This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
296<p> Binds the placeholder at position <em>pos</em> with type <a href="qsql.html#ParameterType-enum">QSql::In</a>.
297
298<h3 class=fn>void <a name="bindValue-4"></a>QSqlQuery::bindValue ( int&nbsp;pos, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;val, <a href="qsql.html#ParameterType-enum">QSql::ParameterType</a>&nbsp;type )
299</h3>
300This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
301<p> Set the placeholder in position <em>pos</em> to be bound to value <em>val</em>
302in the prepared statement. Field numbering starts at 0. If <em>type</em>
303is <a href="qsql.html#ParameterType-enum">QSql::Out</a> or <a href="qsql.html#ParameterType-enum">QSql::InOut</a>, the placeholder will be
304overwritten with data from the database after the <a href="#exec">exec</a>() call.
305<p> <p>See also <a href="#addBindValue">addBindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>().
306
307<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="boundValue"></a>QSqlQuery::boundValue ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;placeholder ) const
308</h3>
309Returns the value for the <em>placeholder</em>.
310
311<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="boundValue-2"></a>QSqlQuery::boundValue ( int&nbsp;pos ) const
312</h3>
313This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
314<p> Returns the value for the placeholder at position <em>pos</em>.
315
316<h3 class=fn><a href="qmap.html">QMap</a>&lt;QString,&nbsp;QVariant&gt; <a name="boundValues"></a>QSqlQuery::boundValues () const
317</h3>
318Returns a map of the bound values.
319<p> The bound values can be examined in the following way:
320<pre>
321 QSqlQuery query;
322 ...
323 // Examine the bound values - bound using named binding
324 QMap&lt;QString, QVariant&gt;::ConstIterator it;
325 <a href="qmap.html">QMap</a>&lt;QString, QVariant&gt; vals = query.<a href="#boundValues">boundValues</a>();
326 for ( it = vals.<a href="qmap.html#begin">begin</a>(); it != vals.<a href="qmap.html#end">end</a>(); ++it )
327 <a href="qapplication.html#qWarning">qWarning</a>( "Placeholder: " + it.key() + ", Value: " + (*it).toString() );
328 ...
329
330 // Examine the bound values - bound using positional binding
331 QValueList&lt;QVariant&gt;::ConstIterator it;
332 <a href="qvaluelist.html">QValueList</a>&lt;QVariant&gt; list = query.<a href="#boundValues">boundValues</a>().values();
333 int i = 0;
334 for ( it = list.<a href="qvaluelist.html#begin">begin</a>(); it != list.<a href="qvaluelist.html#end">end</a>(); ++it )
335 <a href="qapplication.html#qWarning">qWarning</a>( "Placeholder pos: %d, Value: " + (*it).toString(), i++ );
336 ...
337
338 </pre>
339
340
341<h3 class=fn>const&nbsp;<a href="qsqldriver.html">QSqlDriver</a>&nbsp;* <a name="driver"></a>QSqlQuery::driver () const
342</h3>
343Returns the database driver associated with the query.
344
345<h3 class=fn>bool <a name="exec"></a>QSqlQuery::exec ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;query )<tt> [virtual]</tt>
346</h3>
347Executes the SQL in <em>query</em>. Returns TRUE and sets the query
348state to active if the query was successful; otherwise returns
349FALSE and sets the query state to inactive. The <em>query</em> string
350must use syntax appropriate for the SQL database being queried,
351for example, standard SQL.
352<p> After the query is executed, the query is positioned on an <em>invalid</em> record, and must be navigated to a valid record before
353data values can be retrieved, e.g. using <a href="#next">next</a>().
354<p> Note that the last error for this query is reset when <a href="#exec">exec</a>() is
355called.
356<p> <p>See also <a href="#isActive">isActive</a>(), <a href="#isValid">isValid</a>(), <a href="#next">next</a>(), <a href="#prev">prev</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), and <a href="#seek">seek</a>().
357
358<p>Examples: <a href="sql.html#x2157">sql/overview/basicbrowsing/main.cpp</a>, <a href="sql.html#x2161">sql/overview/basicbrowsing2/main.cpp</a>, <a href="sql.html#x2166">sql/overview/basicdatamanip/main.cpp</a>, and <a href="sql.html#x2154">sql/overview/connection.cpp</a>.
359<h3 class=fn>bool <a name="exec-2"></a>QSqlQuery::exec ()
360</h3>
361This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
362<p> Executes a previously prepared SQL query. Returns TRUE if the
363query executed successfully; otherwise returns FALSE.
364<p> <p>See also <a href="#prepare">prepare</a>(), <a href="#bindValue">bindValue</a>(), and <a href="#addBindValue">addBindValue</a>().
365
366<h3 class=fn><a href="qstring.html">QString</a> <a name="executedQuery"></a>QSqlQuery::executedQuery () const
367</h3>
368Returns the last query that was executed.
369<p> In most cases this function returns the same as <a href="#lastQuery">lastQuery</a>(). If a
370prepared query with placeholders is executed on a DBMS that does
371not support it, the preparation of this query is emulated. The
372placeholders in the original query are replaced with their bound
373values to form a new query. This function returns the modified
374query. Useful for debugging purposes.
375<p> <p>See also <a href="#lastQuery">lastQuery</a>().
376
377<h3 class=fn>bool <a name="first"></a>QSqlQuery::first ()<tt> [virtual]</tt>
378</h3>
379Retrieves the first record in the result, if available, and
380positions the query on the retrieved record. Note that the result
381must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before
382calling this function or it will do nothing and return FALSE.
383Returns TRUE if successful. If unsuccessful the query position is
384set to an invalid position and FALSE is returned.
385<p> <p>See also <a href="#next">next</a>(), <a href="#prev">prev</a>(), <a href="#last">last</a>(), <a href="#seek">seek</a>(), <a href="#at">at</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
386
387<p>Example: <a href="sql.html#x2170">sql/overview/navigating/main.cpp</a>.
388<h3 class=fn>bool <a name="isActive"></a>QSqlQuery::isActive () const
389</h3>
390Returns TRUE if the query is currently active; otherwise returns
391FALSE.
392
393<p>Examples: <a href="sql.html#x2158">sql/overview/basicbrowsing/main.cpp</a>, <a href="sql.html#x2162">sql/overview/basicbrowsing2/main.cpp</a>, <a href="sql.html#x2167">sql/overview/basicdatamanip/main.cpp</a>, <a href="sql.html#x2171">sql/overview/navigating/main.cpp</a>, and <a href="sql.html#x2175">sql/overview/retrieve1/main.cpp</a>.
394<h3 class=fn>bool <a name="isForwardOnly"></a>QSqlQuery::isForwardOnly () const
395</h3>
396Returns TRUE if you can only scroll <em>forward</em> through a result
397set; otherwise returns FALSE.
398<p> <p>See also <a href="#setForwardOnly">setForwardOnly</a>().
399
400<h3 class=fn>bool <a name="isNull"></a>QSqlQuery::isNull ( int&nbsp;field ) const
401</h3>
402Returns TRUE if the query is active and positioned on a valid
403record and the <em>field</em> is NULL; otherwise returns FALSE. Note
404that for some drivers <a href="#isNull">isNull</a>() will not return accurate
405information until after an attempt is made to retrieve data.
406<p> <p>See also <a href="#isActive">isActive</a>(), <a href="#isValid">isValid</a>(), and <a href="#value">value</a>().
407
408<h3 class=fn>bool <a name="isSelect"></a>QSqlQuery::isSelect () const
409</h3>
410Returns TRUE if the current query is a <tt>SELECT</tt> statement;
411otherwise returns FALSE.
412
413<h3 class=fn>bool <a name="isValid"></a>QSqlQuery::isValid () const
414</h3>
415Returns TRUE if the query is currently positioned on a valid
416record; otherwise returns FALSE.
417
418<h3 class=fn>bool <a name="last"></a>QSqlQuery::last ()<tt> [virtual]</tt>
419</h3>
420Retrieves the last record in the result, if available, and
421positions the query on the retrieved record. Note that the result
422must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before
423calling this function or it will do nothing and return FALSE.
424Returns TRUE if successful. If unsuccessful the query position is
425set to an invalid position and FALSE is returned.
426<p> <p>See also <a href="#next">next</a>(), <a href="#prev">prev</a>(), <a href="#first">first</a>(), <a href="#seek">seek</a>(), <a href="#at">at</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
427
428<p>Example: <a href="sql.html#x2172">sql/overview/navigating/main.cpp</a>.
429<h3 class=fn><a href="qsqlerror.html">QSqlError</a> <a name="lastError"></a>QSqlQuery::lastError () const
430</h3>
431Returns error information about the last error (if any) that
432occurred.
433<p> <p>See also <a href="qsqlerror.html">QSqlError</a>.
434
435<h3 class=fn><a href="qstring.html">QString</a> <a name="lastQuery"></a>QSqlQuery::lastQuery () const
436</h3>
437Returns the text of the current query being used, or <a href="qstring.html#QString-null">QString::null</a>
438if there is no current query text.
439<p> <p>See also <a href="#executedQuery">executedQuery</a>().
440
441<h3 class=fn>bool <a name="next"></a>QSqlQuery::next ()<tt> [virtual]</tt>
442</h3>
443Retrieves the next record in the result, if available, and
444positions the query on the retrieved record. Note that the result
445must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before
446calling this function or it will do nothing and return FALSE.
447<p> The following rules apply:
448<p> <ul>
449<li> If the result is currently located before the first
450record, e.g. immediately after a query is executed, an attempt is
451made to retrieve the first record.
452<p> <li> If the result is currently located after the last record,
453there is no change and FALSE is returned.
454<p> <li> If the result is located somewhere in the middle, an attempt
455is made to retrieve the next record.
456</ul>
457<p> If the record could not be retrieved, the result is positioned after
458the last record and FALSE is returned. If the record is successfully
459retrieved, TRUE is returned.
460<p> <p>See also <a href="#prev">prev</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), <a href="#seek">seek</a>(), <a href="#at">at</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
461
462<p>Examples: <a href="sql.html#x2159">sql/overview/basicbrowsing/main.cpp</a>, <a href="sql.html#x2163">sql/overview/basicbrowsing2/main.cpp</a>, <a href="sql.html#x2208">sql/overview/delete/main.cpp</a>, <a href="sql.html#x2183">sql/overview/order1/main.cpp</a>, <a href="sql.html#x2176">sql/overview/retrieve1/main.cpp</a>, <a href="sql.html#x2265">sql/overview/subclass4/main.cpp</a>, and <a href="sql.html#x2268">sql/overview/subclass5/main.cpp</a>.
463<h3 class=fn>int <a name="numRowsAffected"></a>QSqlQuery::numRowsAffected () const
464</h3>
465Returns the number of rows affected by the result's SQL statement,
466or -1 if it cannot be determined. Note that for <tt>SELECT</tt>
467statements, the value is undefined; see <a href="#size">size</a>() instead. If the
468query is not active (<a href="#isActive">isActive</a>() returns FALSE), -1 is returned.
469<p> <p>See also <a href="#size">size</a>() and <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>().
470
471<p>Examples: <a href="sql.html#x2164">sql/overview/basicbrowsing2/main.cpp</a> and <a href="sql.html#x2168">sql/overview/basicdatamanip/main.cpp</a>.
472<h3 class=fn><a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp; <a name="operator-eq"></a>QSqlQuery::operator= ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;other )
473</h3>
474Assigns <em>other</em> to the query.
475
476<h3 class=fn>bool <a name="prepare"></a>QSqlQuery::prepare ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;query )
477</h3>
478Prepares the SQL query <em>query</em> for execution. The query may
479contain placeholders for binding values. Both Oracle style
480colon-name (e.g. <tt>:surname</tt>), and ODBC style (e.g. <tt>?</tt>)
481placeholders are supported; but they cannot be mixed in the same
482query. See the <a href="#details">Description</a> for examples.
483<p> <p>See also <a href="#exec">exec</a>(), <a href="#bindValue">bindValue</a>(), and <a href="#addBindValue">addBindValue</a>().
484
485<h3 class=fn>bool <a name="prev"></a>QSqlQuery::prev ()<tt> [virtual]</tt>
486</h3>
487Retrieves the previous record in the result, if available, and
488positions the query on the retrieved record. Note that the result
489must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before
490calling this function or it will do nothing and return FALSE.
491<p> The following rules apply:
492<p> <ul>
493<li> If the result is currently located before the first record,
494there is no change and FALSE is returned.
495<p> <li> If the result is currently located after the last record, an
496attempt is made to retrieve the last record.
497<p> <li> If the result is somewhere in the middle, an attempt is made
498to retrieve the previous record.
499</ul>
500<p> If the record could not be retrieved, the result is positioned
501before the first record and FALSE is returned. If the record is
502successfully retrieved, TRUE is returned.
503<p> <p>See also <a href="#next">next</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), <a href="#seek">seek</a>(), <a href="#at">at</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
504
505<h3 class=fn>const&nbsp;<a href="qsqlresult.html">QSqlResult</a>&nbsp;* <a name="result"></a>QSqlQuery::result () const
506</h3>
507Returns the result associated with the query.
508
509<h3 class=fn>bool <a name="seek"></a>QSqlQuery::seek ( int&nbsp;i, bool&nbsp;relative = FALSE )<tt> [virtual]</tt>
510</h3>
511Retrieves the record at position (offset) <em>i</em>, if available, and
512positions the query on the retrieved record. The first record is
513at position 0. Note that the query must be in an active state and
514<a href="#isSelect">isSelect</a>() must return TRUE before calling this function.
515<p> If <em>relative</em> is FALSE (the default), the following rules apply:
516<p> <ul>
517<li> If <em>i</em> is negative, the result is positioned before the
518first record and FALSE is returned.
519<li> Otherwise, an attempt is made to move to the record at position
520<em>i</em>. If the record at position <em>i</em> could not be retrieved, the
521result is positioned after the last record and FALSE is returned. If
522the record is successfully retrieved, TRUE is returned.
523</ul>
524<p> If <em>relative</em> is TRUE, the following rules apply:
525<p> <ul>
526<li> If the result is currently positioned before the first
527record or on the first record, and <em>i</em> is negative, there is no
528change, and FALSE is returned.
529<li> If the result is currently located after the last record, and
530<em>i</em> is positive, there is no change, and FALSE is returned.
531<li> If the result is currently located somewhere in the middle,
532and the relative offset <em>i</em> moves the result below zero, the
533result is positioned before the first record and FALSE is
534returned.
535<li> Otherwise, an attempt is made to move to the record <em>i</em>
536records ahead of the current record (or <em>i</em> records behind the
537current record if <em>i</em> is negative). If the record at offset <em>i</em>
538could not be retrieved, the result is positioned after the last
539record if <em>i</em> >= 0, (or before the first record if <em>i</em> is
540negative), and FALSE is returned. If the record is successfully
541retrieved, TRUE is returned.
542</ul>
543<p> <p>See also <a href="#next">next</a>(), <a href="#prev">prev</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), <a href="#at">at</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
544
545<p>Example: <a href="sql.html#x2173">sql/overview/navigating/main.cpp</a>.
546<h3 class=fn>void <a name="setForwardOnly"></a>QSqlQuery::setForwardOnly ( bool&nbsp;forward )
547</h3>
548Sets forward only mode to <em>forward</em>. If forward is TRUE only
549<a href="#next">next</a>(), and <a href="#seek">seek</a>() with positive values, are allowed for
550navigating the results. Forward only mode needs far less memory
551since results do not need to be cached.
552<p> Forward only mode is off by default.
553<p> Forward only mode cannot be used with data aware widgets like
554<a href="qdatatable.html">QDataTable</a>, since they must to be able to scroll backward as well
555as forward.
556<p> <p>See also <a href="#isForwardOnly">isForwardOnly</a>(), <a href="#next">next</a>(), and <a href="#seek">seek</a>().
557
558<h3 class=fn>int <a name="size"></a>QSqlQuery::size () const
559</h3>
560Returns the size of the result, (number of rows returned), or -1
561if the size cannot be determined or if the database does not
562support reporting information about query sizes. Note that for
563non-<tt>SELECT</tt> statements (<a href="#isSelect">isSelect</a>() returns FALSE), <a href="#size">size</a>() will
564return -1. If the query is not active (<a href="#isActive">isActive</a>() returns FALSE),
565-1 is returned.
566<p> To determine the number of rows affected by a non-SELECT
567statement, use <a href="#numRowsAffected">numRowsAffected</a>().
568<p> <p>See also <a href="#isActive">isActive</a>(), <a href="#numRowsAffected">numRowsAffected</a>(), and <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>().
569
570<p>Example: <a href="sql.html#x2174">sql/overview/navigating/main.cpp</a>.
571<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="value"></a>QSqlQuery::value ( int&nbsp;i ) const<tt> [virtual]</tt>
572</h3>
573Returns the value of the <em>i</em>-th field in the query (zero based).
574<p> The fields are numbered from left to right using the text of the
575<tt>SELECT</tt> statement, e.g. in <tt>SELECT forename, surname FROM people</tt>,
576field 0 is <tt>forename</tt> and field 1 is <tt>surname</tt>. Using <tt>SELECT *</tt>
577is not recommended because the order of the fields in the query is
578undefined.
579<p> An invalid <a href="qvariant.html">QVariant</a> is returned if field <em>i</em> does not exist, if
580the query is inactive, or if the query is positioned on an invalid
581record.
582<p> <p>See also <a href="#prev">prev</a>(), <a href="#next">next</a>(), <a href="#first">first</a>(), <a href="#last">last</a>(), <a href="#seek">seek</a>(), <a href="#isActive">isActive</a>(), and <a href="#isValid">isValid</a>().
583
584<p>Examples: <a href="sql.html#x2160">sql/overview/basicbrowsing/main.cpp</a>, <a href="sql.html#x2165">sql/overview/basicbrowsing2/main.cpp</a>, <a href="sql.html#x2177">sql/overview/retrieve1/main.cpp</a>, <a href="sql.html#x2262">sql/overview/subclass3/main.cpp</a>, <a href="sql.html#x2266">sql/overview/subclass4/main.cpp</a>, <a href="sql.html#x2269">sql/overview/subclass5/main.cpp</a>, and <a href="sql.html#x2252">sql/overview/table4/main.cpp</a>.
585<!-- eof -->
586<hr><p>
587This file is part of the <a href="index.html">Qt toolkit</a>.
588Copyright &copy; 1995-2007
589<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
590<table width=100% cellspacing=0 border=0><tr>
591<td>Copyright &copy; 2007
592<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
593<td align=right><div align=right>Qt 3.3.8</div>
594</table></div></address></body>
595</html>
Note: See TracBrowser for help on using the repository browser.