diff options
Diffstat (limited to 'doc/html/ntqsqlquery.html')
| -rw-r--r-- | doc/html/ntqsqlquery.html | 595 |
1 files changed, 595 insertions, 0 deletions
diff --git a/doc/html/ntqsqlquery.html b/doc/html/ntqsqlquery.html new file mode 100644 index 000000000..3f5e54fa5 --- /dev/null +++ b/doc/html/ntqsqlquery.html @@ -0,0 +1,595 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/sql/qsqlquery.cpp:79 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>TQSqlQuery Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>TQSqlQuery Class Reference<br><small>[<a href="sql.html">sql module</a>]</small></h1> + +<p>The TQSqlQuery class provides a means of executing and +manipulating SQL statements. +<a href="#details">More...</a> +<p><tt>#include <<a href="qsqlquery-h.html">ntqsqlquery.h</a>></tt> +<p>Inherited by <a href="ntqsqlcursor.html">TQSqlCursor</a>. +<p><a href="qsqlquery-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#TQSqlQuery"><b>TQSqlQuery</b></a> ( TQSqlResult * r )</li> +<li class=fn><a href="#TQSqlQuery-2"><b>TQSqlQuery</b></a> ( const TQString & query = TQString::null, TQSqlDatabase * db = 0 )</li> +<li class=fn>explicit <a href="#TQSqlQuery-3"><b>TQSqlQuery</b></a> ( TQSqlDatabase * db )</li> +<li class=fn><a href="#TQSqlQuery-4"><b>TQSqlQuery</b></a> ( const TQSqlQuery & other )</li> +<li class=fn>TQSqlQuery & <a href="#operator-eq"><b>operator=</b></a> ( const TQSqlQuery & other )</li> +<li class=fn>virtual <a href="#~TQSqlQuery"><b>~TQSqlQuery</b></a> ()</li> +<li class=fn>bool <a href="#isValid"><b>isValid</b></a> () const</li> +<li class=fn>bool <a href="#isActive"><b>isActive</b></a> () const</li> +<li class=fn>bool <a href="#isNull"><b>isNull</b></a> ( int field ) const</li> +<li class=fn>int <a href="#at"><b>at</b></a> () const</li> +<li class=fn>TQString <a href="#lastQuery"><b>lastQuery</b></a> () const</li> +<li class=fn>int <a href="#numRowsAffected"><b>numRowsAffected</b></a> () const</li> +<li class=fn>TQSqlError <a href="#lastError"><b>lastError</b></a> () const</li> +<li class=fn>bool <a href="#isSelect"><b>isSelect</b></a> () const</li> +<li class=fn>int <a href="#size"><b>size</b></a> () const</li> +<li class=fn>const TQSqlDriver * <a href="#driver"><b>driver</b></a> () const</li> +<li class=fn>const TQSqlResult * <a href="#result"><b>result</b></a> () const</li> +<li class=fn>bool <a href="#isForwardOnly"><b>isForwardOnly</b></a> () const</li> +<li class=fn>void <a href="#setForwardOnly"><b>setForwardOnly</b></a> ( bool forward )</li> +<li class=fn>virtual bool <a href="#exec"><b>exec</b></a> ( const TQString & query )</li> +<li class=fn>virtual TQVariant <a href="#value"><b>value</b></a> ( int i ) const</li> +<li class=fn>virtual bool <a href="#seek"><b>seek</b></a> ( int i, bool relative = FALSE )</li> +<li class=fn>virtual bool <a href="#next"><b>next</b></a> ()</li> +<li class=fn>virtual bool <a href="#prev"><b>prev</b></a> ()</li> +<li class=fn>virtual bool <a href="#first"><b>first</b></a> ()</li> +<li class=fn>virtual bool <a href="#last"><b>last</b></a> ()</li> +<li class=fn>bool <a href="#exec-2"><b>exec</b></a> ()</li> +<li class=fn>bool <a href="#prepare"><b>prepare</b></a> ( const TQString & query )</li> +<li class=fn>void <a href="#bindValue-2"><b>bindValue</b></a> ( const TQString & placeholder, const TQVariant & val )</li> +<li class=fn>void <a href="#bindValue-3"><b>bindValue</b></a> ( int pos, const TQVariant & val )</li> +<li class=fn>void <a href="#addBindValue-2"><b>addBindValue</b></a> ( const TQVariant & val )</li> +<li class=fn>void <a href="#bindValue"><b>bindValue</b></a> ( const TQString & placeholder, const TQVariant & val, TQSql::ParameterType type )</li> +<li class=fn>void <a href="#bindValue-4"><b>bindValue</b></a> ( int pos, const TQVariant & val, TQSql::ParameterType type )</li> +<li class=fn>void <a href="#addBindValue"><b>addBindValue</b></a> ( const TQVariant & val, TQSql::ParameterType type )</li> +<li class=fn>TQVariant <a href="#boundValue"><b>boundValue</b></a> ( const TQString & placeholder ) const</li> +<li class=fn>TQVariant <a href="#boundValue-2"><b>boundValue</b></a> ( int pos ) const</li> +<li class=fn>TQMap<TQString, TQVariant> <a href="#boundValues"><b>boundValues</b></a> () const</li> +<li class=fn>TQString <a href="#executedQuery"><b>executedQuery</b></a> () const</li> +</ul> +<h2>Protected Members</h2> +<ul> +<li class=fn>virtual void <a href="#beforeSeek"><b>beforeSeek</b></a> ()</li> +<li class=fn>virtual void <a href="#afterSeek"><b>afterSeek</b></a> ()</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + +The TQSqlQuery class provides a means of executing and +manipulating SQL statements. +<p> + + +<p> TQSqlQuery encapsulates the functionality involved in creating, +navigating and retrieving data from SQL queries which are executed +on a <a href="ntqsqldatabase.html">TQSqlDatabase</a>. It can be used to execute DML (data +manipulation language) statements, e.g. <tt>SELECT</tt>, <tt>INSERT</tt>, <tt>UPDATE</tt> and <tt>DELETE</tt>, and also DDL (data definition language) +statements, e.g. <tt>CREATE TABLE</tt>. It can also be used to +execute database-specific commands which are not standard SQL +(e.g. <tt>SET DATESTYLE=ISO</tt> for PostgreSQL). +<p> Successfully executed SQL statements set the query's state to +active (<a href="#isActive">isActive</a>() returns TRUE); otherwise the query's state is +set to inactive. In either case, when executing a new SQL +statement, the query is positioned on an invalid record; an active +query must be navigated to a valid record (so that <a href="#isValid">isValid</a>() +returns TRUE) before values can be retrieved. +<p> Navigating records is performed with the following functions: +<p> <ul> +<li> <a href="#next">next</a>() +<li> <a href="#prev">prev</a>() +<li> <a href="#first">first</a>() +<li> <a href="#last">last</a>() +<li> <tt></tt><a href="#seek">seek</a>(int) +</ul> +<p> These functions allow the programmer to move forward, backward or +arbitrarily through the records returned by the query. If you only +need to move forward through the results, e.g. using <a href="#next">next</a>() or +using <a href="#seek">seek</a>() with a positive offset, you can use <a href="#setForwardOnly">setForwardOnly</a>() +and save a significant amount of memory overhead. Once an active +query is positioned on a valid record, data can be retrieved using +<a href="#value">value</a>(). All data is transferred from the SQL backend using +TQVariants. +<p> For example: +<p> <pre> + TQSqlQuery query( "SELECT name FROM customer" ); + while ( query.<a href="#next">next</a>() ) { + <a href="ntqstring.html">TQString</a> name = query.<a href="#value">value</a>(0).toString(); + doSomething( name ); + } + </pre> + +<p> To access the data returned by a query, use the value() method. +Each field in the data returned by a SELECT statement is accessed +by passing the field's position in the statement, starting from 0. +Information about the fields can be obtained via <a href="ntqsqldatabase.html#record">TQSqlDatabase::record</a>(). +For the sake of efficiency there are no functions to access a field +by name. (The <a href="ntqsqlcursor.html">TQSqlCursor</a> class provides a higher-level interface +with field access by name and automatic SQL generation.) +<p> TQSqlQuery supports prepared query execution and the binding of +parameter values to placeholders. Some databases don't support +these features, so for them TQt emulates the required +functionality. For example, the Oracle and ODBC drivers have +proper prepared query support, and TQt makes use of it; but for +databases that don't have this support, TQt implements the feature +itself, e.g. by replacing placeholders with actual values when a +query is executed. The exception is positional binding using named +placeholders, which requires that the database supports prepared +queries. +<p> Oracle databases identify placeholders by using a colon-name +syntax, e.g <tt>:name</tt>. ODBC simply uses <tt>?</tt> characters. TQt +supports both syntaxes (although you can't mix them in the same +query). +<p> Below we present the same example using each of the four different +binding approaches. +<p> <b>Named binding using named placeholders</b> +<pre> + TQSqlQuery query; + query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) " + "VALUES (:id, :forename, :surname)" ); + query.<a href="#bindValue">bindValue</a>( ":id", 1001 ); + query.<a href="#bindValue">bindValue</a>( ":forename", "Bart" ); + query.<a href="#bindValue">bindValue</a>( ":surname", "Simpson" ); + query.<a href="#exec">exec</a>(); + </pre> + +<p> <b>Positional binding using named placeholders</b> +<pre> + TQSqlQuery query; + query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) " + "VALUES (:id, :forename, :surname)" ); + query.<a href="#bindValue">bindValue</a>( 0, 1001 ); + query.<a href="#bindValue">bindValue</a>( 1, "Bart" ); + query.<a href="#bindValue">bindValue</a>( 2, "Simpson" ); + query.<a href="#exec">exec</a>(); + </pre> + +<b>Note:</b> Using positional binding with named placeholders will +only work if the database supports prepared queries. This can be +checked with <a href="ntqsqldriver.html#hasFeature">TQSqlDriver::hasFeature</a>() using TQSqlDriver::PreparedQueries +as argument for driver feature. +<p> <b>Binding values using positional placeholders #1</b> +<pre> + TQSqlQuery query; + query.<a href="#prepare">prepare</a>( "INSERT INTO atable (id, forename, surname) " + "VALUES (?, ?, ?)" ); + query.<a href="#bindValue">bindValue</a>( 0, 1001 ); + query.<a href="#bindValue">bindValue</a>( 1, "Bart" ); + query.<a href="#bindValue">bindValue</a>( 2, "Simpson" ); + query.<a href="#exec">exec</a>(); + </pre> + +<p> <b>Binding values using positional placeholders #2</b> +<pre> + query.prepare( "INSERT INTO atable (id, forename, surname) " + "VALUES (?, ?, ?)" ); + query.addBindValue( 1001 ); + query.addBindValue( "Bart" ); + query.addBindValue( "Simpson" ); + query.exec(); + </pre> + +<p> <b>Binding values to a stored procedure</b> +This code calls a stored procedure called <tt>AsciiToInt()</tt>, passing +it a character through its in parameter, and taking its result in +the out parameter. +<pre> + TQSqlQuery query; + query.<a href="#prepare">prepare</a>( "call AsciiToInt(?, ?)" ); + query.<a href="#bindValue">bindValue</a>( 0, "A" ); + query.<a href="#bindValue">bindValue</a>( 1, 0, TQSql::Out ); + query.<a href="#exec">exec</a>(); + int i = query.<a href="#boundValue">boundValue</a>( 1 ).toInt(); // i is 65. + </pre> + +<p> <p>See also <a href="ntqsqldatabase.html">TQSqlDatabase</a>, <a href="ntqsqlcursor.html">TQSqlCursor</a>, <a href="ntqvariant.html">TQVariant</a>, and <a href="database.html">Database Classes</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="TQSqlQuery"></a>TQSqlQuery::TQSqlQuery ( <a href="ntqsqlresult.html">TQSqlResult</a> * r ) +</h3> +Creates a TQSqlQuery object which uses the <a href="ntqsqlresult.html">TQSqlResult</a> <em>r</em> to +communicate with a database. + +<h3 class=fn><a name="TQSqlQuery-2"></a>TQSqlQuery::TQSqlQuery ( const <a href="ntqstring.html">TQString</a> & query = TQString::null, <a href="ntqsqldatabase.html">TQSqlDatabase</a> * db = 0 ) +</h3> +Creates a TQSqlQuery object using the SQL <em>query</em> and the database +<em>db</em>. If <em>db</em> is 0, (the default), the application's default +database is used. If <em>query</em> is not a null string, it will be +executed. +<p> <p>See also <a href="ntqsqldatabase.html">TQSqlDatabase</a>. + +<h3 class=fn>explicit <a name="TQSqlQuery-3"></a>TQSqlQuery::TQSqlQuery ( <a href="ntqsqldatabase.html">TQSqlDatabase</a> * db ) +</h3> +Creates a TQSqlQuery object using the database <em>db</em>. If <em>db</em> is +0, the application's default database is used. +<p> <p>See also <a href="ntqsqldatabase.html">TQSqlDatabase</a>. + +<h3 class=fn><a name="TQSqlQuery-4"></a>TQSqlQuery::TQSqlQuery ( const <a href="ntqsqlquery.html">TQSqlQuery</a> & other ) +</h3> +Constructs a copy of <em>other</em>. + +<h3 class=fn><a name="~TQSqlQuery"></a>TQSqlQuery::~TQSqlQuery ()<tt> [virtual]</tt> +</h3> +Destroys the object and frees any allocated resources. + +<h3 class=fn>void <a name="addBindValue"></a>TQSqlQuery::addBindValue ( const <a href="ntqvariant.html">TQVariant</a> & val, <a href="ntqsql.html#ParameterType-enum">TQSql::ParameterType</a> type ) +</h3> +Adds the value <em>val</em> to the list of values when using positional +value binding. The order of the <a href="#addBindValue">addBindValue</a>() calls determines +which placeholder a value will be bound to in the prepared query. +If <em>type</em> is <a href="ntqsql.html#ParameterType-enum">TQSql::Out</a> or <a href="ntqsql.html#ParameterType-enum">TQSql::InOut</a>, the placeholder will +be overwritten with data from the database after the <a href="#exec">exec</a>() call. +<p> <p>See also <a href="#bindValue">bindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>(). + +<h3 class=fn>void <a name="addBindValue-2"></a>TQSqlQuery::addBindValue ( const <a href="ntqvariant.html">TQVariant</a> & val ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Binds the placeholder with type <a href="ntqsql.html#ParameterType-enum">TQSql::In</a>. + +<h3 class=fn>void <a name="afterSeek"></a>TQSqlQuery::afterSeek ()<tt> [virtual protected]</tt> +</h3> +Protected virtual function called after the internal record +pointer is moved to a new record. The default implementation does +nothing. + +<h3 class=fn>int <a name="at"></a>TQSqlQuery::at () const +</h3> +Returns the current internal position of the query. The first +record is at position zero. If the position is invalid, a +TQSql::Location will be returned indicating the invalid position. +<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>(). + +<p>Example: <a href="sql.html#x2169">sql/overview/navigating/main.cpp</a>. +<h3 class=fn>void <a name="beforeSeek"></a>TQSqlQuery::beforeSeek ()<tt> [virtual protected]</tt> +</h3> +Protected virtual function called before the internal record +pointer is moved to a new record. The default implementation does +nothing. + +<h3 class=fn>void <a name="bindValue"></a>TQSqlQuery::bindValue ( const <a href="ntqstring.html">TQString</a> & placeholder, const <a href="ntqvariant.html">TQVariant</a> & val, <a href="ntqsql.html#ParameterType-enum">TQSql::ParameterType</a> type ) +</h3> +Set the placeholder <em>placeholder</em> to be bound to value <em>val</em> in +the prepared statement. Note that the placeholder mark (e.g <tt>:</tt>) +must be included when specifying the placeholder name. If <em>type</em> +is <a href="ntqsql.html#ParameterType-enum">TQSql::Out</a> or <a href="ntqsql.html#ParameterType-enum">TQSql::InOut</a>, the placeholder will be +overwritten with data from the database after the <a href="#exec">exec</a>() call. +<p> <p>See also <a href="#addBindValue">addBindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>(). + +<h3 class=fn>void <a name="bindValue-2"></a>TQSqlQuery::bindValue ( const <a href="ntqstring.html">TQString</a> & placeholder, const <a href="ntqvariant.html">TQVariant</a> & val ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Binds the placeholder with type <a href="ntqsql.html#ParameterType-enum">TQSql::In</a>. + +<h3 class=fn>void <a name="bindValue-3"></a>TQSqlQuery::bindValue ( int pos, const <a href="ntqvariant.html">TQVariant</a> & val ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Binds the placeholder at position <em>pos</em> with type <a href="ntqsql.html#ParameterType-enum">TQSql::In</a>. + +<h3 class=fn>void <a name="bindValue-4"></a>TQSqlQuery::bindValue ( int pos, const <a href="ntqvariant.html">TQVariant</a> & val, <a href="ntqsql.html#ParameterType-enum">TQSql::ParameterType</a> type ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Set the placeholder in position <em>pos</em> to be bound to value <em>val</em> +in the prepared statement. Field numbering starts at 0. If <em>type</em> +is <a href="ntqsql.html#ParameterType-enum">TQSql::Out</a> or <a href="ntqsql.html#ParameterType-enum">TQSql::InOut</a>, the placeholder will be +overwritten with data from the database after the <a href="#exec">exec</a>() call. +<p> <p>See also <a href="#addBindValue">addBindValue</a>(), <a href="#prepare">prepare</a>(), and <a href="#exec">exec</a>(). + +<h3 class=fn><a href="ntqvariant.html">TQVariant</a> <a name="boundValue"></a>TQSqlQuery::boundValue ( const <a href="ntqstring.html">TQString</a> & placeholder ) const +</h3> +Returns the value for the <em>placeholder</em>. + +<h3 class=fn><a href="ntqvariant.html">TQVariant</a> <a name="boundValue-2"></a>TQSqlQuery::boundValue ( int pos ) const +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Returns the value for the placeholder at position <em>pos</em>. + +<h3 class=fn><a href="ntqmap.html">TQMap</a><TQString, TQVariant> <a name="boundValues"></a>TQSqlQuery::boundValues () const +</h3> +Returns a map of the bound values. +<p> The bound values can be examined in the following way: +<pre> + TQSqlQuery query; + ... + // Examine the bound values - bound using named binding + TQMap<TQString, TQVariant>::ConstIterator it; + <a href="ntqmap.html">TQMap</a><TQString, TQVariant> vals = query.<a href="#boundValues">boundValues</a>(); + for ( it = vals.<a href="ntqmap.html#begin">begin</a>(); it != vals.<a href="ntqmap.html#end">end</a>(); ++it ) + <a href="ntqapplication.html#qWarning">qWarning</a>( "Placeholder: " + it.key() + ", Value: " + (*it).toString() ); + ... + + // Examine the bound values - bound using positional binding + TQValueList<TQVariant>::ConstIterator it; + <a href="ntqvaluelist.html">TQValueList</a><TQVariant> list = query.<a href="#boundValues">boundValues</a>().values(); + int i = 0; + for ( it = list.<a href="ntqvaluelist.html#begin">begin</a>(); it != list.<a href="ntqvaluelist.html#end">end</a>(); ++it ) + <a href="ntqapplication.html#qWarning">qWarning</a>( "Placeholder pos: %d, Value: " + (*it).toString(), i++ ); + ... + + </pre> + + +<h3 class=fn>const <a href="ntqsqldriver.html">TQSqlDriver</a> * <a name="driver"></a>TQSqlQuery::driver () const +</h3> +Returns the database driver associated with the query. + +<h3 class=fn>bool <a name="exec"></a>TQSqlQuery::exec ( const <a href="ntqstring.html">TQString</a> & query )<tt> [virtual]</tt> +</h3> +Executes the SQL in <em>query</em>. Returns TRUE and sets the query +state to active if the query was successful; otherwise returns +FALSE and sets the query state to inactive. The <em>query</em> string +must use syntax appropriate for the SQL database being queried, +for example, standard SQL. +<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 +data values can be retrieved, e.g. using <a href="#next">next</a>(). +<p> Note that the last error for this query is reset when <a href="#exec">exec</a>() is +called. +<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>(). + +<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>. +<h3 class=fn>bool <a name="exec-2"></a>TQSqlQuery::exec () +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Executes a previously prepared SQL query. Returns TRUE if the +query executed successfully; otherwise returns FALSE. +<p> <p>See also <a href="#prepare">prepare</a>(), <a href="#bindValue">bindValue</a>(), and <a href="#addBindValue">addBindValue</a>(). + +<h3 class=fn><a href="ntqstring.html">TQString</a> <a name="executedQuery"></a>TQSqlQuery::executedQuery () const +</h3> +Returns the last query that was executed. +<p> In most cases this function returns the same as <a href="#lastQuery">lastQuery</a>(). If a +prepared query with placeholders is executed on a DBMS that does +not support it, the preparation of this query is emulated. The +placeholders in the original query are replaced with their bound +values to form a new query. This function returns the modified +query. Useful for debugging purposes. +<p> <p>See also <a href="#lastQuery">lastQuery</a>(). + +<h3 class=fn>bool <a name="first"></a>TQSqlQuery::first ()<tt> [virtual]</tt> +</h3> +Retrieves the first record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before +calling this function or it will do nothing and return FALSE. +Returns TRUE if successful. If unsuccessful the query position is +set to an invalid position and FALSE is returned. +<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>(). + +<p>Example: <a href="sql.html#x2170">sql/overview/navigating/main.cpp</a>. +<h3 class=fn>bool <a name="isActive"></a>TQSqlQuery::isActive () const +</h3> +Returns TRUE if the query is currently active; otherwise returns +FALSE. + +<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>. +<h3 class=fn>bool <a name="isForwardOnly"></a>TQSqlQuery::isForwardOnly () const +</h3> +Returns TRUE if you can only scroll <em>forward</em> through a result +set; otherwise returns FALSE. +<p> <p>See also <a href="#setForwardOnly">setForwardOnly</a>(). + +<h3 class=fn>bool <a name="isNull"></a>TQSqlQuery::isNull ( int field ) const +</h3> +Returns TRUE if the query is active and positioned on a valid +record and the <em>field</em> is NULL; otherwise returns FALSE. Note +that for some drivers <a href="#isNull">isNull</a>() will not return accurate +information until after an attempt is made to retrieve data. +<p> <p>See also <a href="#isActive">isActive</a>(), <a href="#isValid">isValid</a>(), and <a href="#value">value</a>(). + +<h3 class=fn>bool <a name="isSelect"></a>TQSqlQuery::isSelect () const +</h3> +Returns TRUE if the current query is a <tt>SELECT</tt> statement; +otherwise returns FALSE. + +<h3 class=fn>bool <a name="isValid"></a>TQSqlQuery::isValid () const +</h3> +Returns TRUE if the query is currently positioned on a valid +record; otherwise returns FALSE. + +<h3 class=fn>bool <a name="last"></a>TQSqlQuery::last ()<tt> [virtual]</tt> +</h3> +Retrieves the last record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before +calling this function or it will do nothing and return FALSE. +Returns TRUE if successful. If unsuccessful the query position is +set to an invalid position and FALSE is returned. +<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>(). + +<p>Example: <a href="sql.html#x2172">sql/overview/navigating/main.cpp</a>. +<h3 class=fn><a href="ntqsqlerror.html">TQSqlError</a> <a name="lastError"></a>TQSqlQuery::lastError () const +</h3> +Returns error information about the last error (if any) that +occurred. +<p> <p>See also <a href="ntqsqlerror.html">TQSqlError</a>. + +<h3 class=fn><a href="ntqstring.html">TQString</a> <a name="lastQuery"></a>TQSqlQuery::lastQuery () const +</h3> +Returns the text of the current query being used, or <a href="ntqstring.html#TQString-null">TQString::null</a> +if there is no current query text. +<p> <p>See also <a href="#executedQuery">executedQuery</a>(). + +<h3 class=fn>bool <a name="next"></a>TQSqlQuery::next ()<tt> [virtual]</tt> +</h3> +Retrieves the next record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before +calling this function or it will do nothing and return FALSE. +<p> The following rules apply: +<p> <ul> +<li> If the result is currently located before the first +record, e.g. immediately after a query is executed, an attempt is +made to retrieve the first record. +<p> <li> If the result is currently located after the last record, +there is no change and FALSE is returned. +<p> <li> If the result is located somewhere in the middle, an attempt +is made to retrieve the next record. +</ul> +<p> If the record could not be retrieved, the result is positioned after +the last record and FALSE is returned. If the record is successfully +retrieved, TRUE is returned. +<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>(). + +<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>. +<h3 class=fn>int <a name="numRowsAffected"></a>TQSqlQuery::numRowsAffected () const +</h3> +Returns the number of rows affected by the result's SQL statement, +or -1 if it cannot be determined. Note that for <tt>SELECT</tt> +statements, the value is undefined; see <a href="#size">size</a>() instead. If the +query is not active (<a href="#isActive">isActive</a>() returns FALSE), -1 is returned. +<p> <p>See also <a href="#size">size</a>() and <a href="ntqsqldriver.html#hasFeature">TQSqlDriver::hasFeature</a>(). + +<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>. +<h3 class=fn><a href="ntqsqlquery.html">TQSqlQuery</a> & <a name="operator-eq"></a>TQSqlQuery::operator= ( const <a href="ntqsqlquery.html">TQSqlQuery</a> & other ) +</h3> +Assigns <em>other</em> to the query. + +<h3 class=fn>bool <a name="prepare"></a>TQSqlQuery::prepare ( const <a href="ntqstring.html">TQString</a> & query ) +</h3> +Prepares the SQL query <em>query</em> for execution. The query may +contain placeholders for binding values. Both Oracle style +colon-name (e.g. <tt>:surname</tt>), and ODBC style (e.g. <tt>?</tt>) +placeholders are supported; but they cannot be mixed in the same +query. See the <a href="#details">Description</a> for examples. +<p> <p>See also <a href="#exec">exec</a>(), <a href="#bindValue">bindValue</a>(), and <a href="#addBindValue">addBindValue</a>(). + +<h3 class=fn>bool <a name="prev"></a>TQSqlQuery::prev ()<tt> [virtual]</tt> +</h3> +Retrieves the previous record in the result, if available, and +positions the query on the retrieved record. Note that the result +must be in an active state and <a href="#isSelect">isSelect</a>() must return TRUE before +calling this function or it will do nothing and return FALSE. +<p> The following rules apply: +<p> <ul> +<li> If the result is currently located before the first record, +there is no change and FALSE is returned. +<p> <li> If the result is currently located after the last record, an +attempt is made to retrieve the last record. +<p> <li> If the result is somewhere in the middle, an attempt is made +to retrieve the previous record. +</ul> +<p> If the record could not be retrieved, the result is positioned +before the first record and FALSE is returned. If the record is +successfully retrieved, TRUE is returned. +<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>(). + +<h3 class=fn>const <a href="ntqsqlresult.html">TQSqlResult</a> * <a name="result"></a>TQSqlQuery::result () const +</h3> +Returns the result associated with the query. + +<h3 class=fn>bool <a name="seek"></a>TQSqlQuery::seek ( int i, bool relative = FALSE )<tt> [virtual]</tt> +</h3> +Retrieves the record at position (offset) <em>i</em>, if available, and +positions the query on the retrieved record. The first record is +at position 0. Note that the query must be in an active state and +<a href="#isSelect">isSelect</a>() must return TRUE before calling this function. +<p> If <em>relative</em> is FALSE (the default), the following rules apply: +<p> <ul> +<li> If <em>i</em> is negative, the result is positioned before the +first record and FALSE is returned. +<li> Otherwise, an attempt is made to move to the record at position +<em>i</em>. If the record at position <em>i</em> could not be retrieved, the +result is positioned after the last record and FALSE is returned. If +the record is successfully retrieved, TRUE is returned. +</ul> +<p> If <em>relative</em> is TRUE, the following rules apply: +<p> <ul> +<li> If the result is currently positioned before the first +record or on the first record, and <em>i</em> is negative, there is no +change, and FALSE is returned. +<li> If the result is currently located after the last record, and +<em>i</em> is positive, there is no change, and FALSE is returned. +<li> If the result is currently located somewhere in the middle, +and the relative offset <em>i</em> moves the result below zero, the +result is positioned before the first record and FALSE is +returned. +<li> Otherwise, an attempt is made to move to the record <em>i</em> +records ahead of the current record (or <em>i</em> records behind the +current record if <em>i</em> is negative). If the record at offset <em>i</em> +could not be retrieved, the result is positioned after the last +record if <em>i</em> >= 0, (or before the first record if <em>i</em> is +negative), and FALSE is returned. If the record is successfully +retrieved, TRUE is returned. +</ul> +<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>(). + +<p>Example: <a href="sql.html#x2173">sql/overview/navigating/main.cpp</a>. +<h3 class=fn>void <a name="setForwardOnly"></a>TQSqlQuery::setForwardOnly ( bool forward ) +</h3> +Sets forward only mode to <em>forward</em>. If forward is TRUE only +<a href="#next">next</a>(), and <a href="#seek">seek</a>() with positive values, are allowed for +navigating the results. Forward only mode needs far less memory +since results do not need to be cached. +<p> Forward only mode is off by default. +<p> Forward only mode cannot be used with data aware widgets like +<a href="ntqdatatable.html">TQDataTable</a>, since they must to be able to scroll backward as well +as forward. +<p> <p>See also <a href="#isForwardOnly">isForwardOnly</a>(), <a href="#next">next</a>(), and <a href="#seek">seek</a>(). + +<h3 class=fn>int <a name="size"></a>TQSqlQuery::size () const +</h3> +Returns the size of the result, (number of rows returned), or -1 +if the size cannot be determined or if the database does not +support reporting information about query sizes. Note that for +non-<tt>SELECT</tt> statements (<a href="#isSelect">isSelect</a>() returns FALSE), <a href="#size">size</a>() will +return -1. If the query is not active (<a href="#isActive">isActive</a>() returns FALSE), +-1 is returned. +<p> To determine the number of rows affected by a non-SELECT +statement, use <a href="#numRowsAffected">numRowsAffected</a>(). +<p> <p>See also <a href="#isActive">isActive</a>(), <a href="#numRowsAffected">numRowsAffected</a>(), and <a href="ntqsqldriver.html#hasFeature">TQSqlDriver::hasFeature</a>(). + +<p>Example: <a href="sql.html#x2174">sql/overview/navigating/main.cpp</a>. +<h3 class=fn><a href="ntqvariant.html">TQVariant</a> <a name="value"></a>TQSqlQuery::value ( int i ) const<tt> [virtual]</tt> +</h3> +Returns the value of the <em>i</em>-th field in the query (zero based). +<p> The fields are numbered from left to right using the text of the +<tt>SELECT</tt> statement, e.g. in <tt>SELECT forename, surname FROM people</tt>, +field 0 is <tt>forename</tt> and field 1 is <tt>surname</tt>. Using <tt>SELECT *</tt> +is not recommended because the order of the fields in the query is +undefined. +<p> An invalid <a href="ntqvariant.html">TQVariant</a> is returned if field <em>i</em> does not exist, if +the query is inactive, or if the query is positioned on an invalid +record. +<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>(). + +<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>. +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">TQt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>TQt 3.3.8</div> +</table></div></address></body> +</html> |