You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
596 lines
36 KiB
596 lines
36 KiB
<!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">tqWarning</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">tqWarning</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>
|