source: trunk/doc/html/qsqldatabase.html

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

reference documentation added
File size: 39.2 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/qsqldatabase.cpp:353 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QSqlDatabase 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>QSqlDatabase Class Reference<br><small>[<a href="sql.html">sql module</a>]</small></h1>
33
34<p>The QSqlDatabase class is used to create SQL database
35connections and to provide transaction handling.
36<a href="#details">More...</a>
37<p><tt>#include &lt;<a href="qsqldatabase-h.html">qsqldatabase.h</a>&gt;</tt>
38<p>Inherits <a href="qobject.html">QObject</a>.
39<p><a href="qsqldatabase-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn><a href="#~QSqlDatabase"><b>~QSqlDatabase</b></a> ()</li>
43<li class=fn>bool <a href="#open"><b>open</b></a> ()</li>
44<li class=fn>bool <a href="#open-2"><b>open</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;user, const&nbsp;QString&nbsp;&amp;&nbsp;password )</li>
45<li class=fn>void <a href="#close"><b>close</b></a> ()</li>
46<li class=fn>bool <a href="#isOpen"><b>isOpen</b></a> () const</li>
47<li class=fn>bool <a href="#isOpenError"><b>isOpenError</b></a> () const</li>
48<li class=fn>QStringList <a href="#tables-2"><b>tables</b></a> () const</li>
49<li class=fn>QStringList <a href="#tables"><b>tables</b></a> ( QSql::TableType&nbsp;type ) const</li>
50<li class=fn>QSqlIndex <a href="#primaryIndex"><b>primaryIndex</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tablename ) const</li>
51<li class=fn>QSqlRecord <a href="#record"><b>record</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tablename ) const</li>
52<li class=fn>QSqlRecord <a href="#record-2"><b>record</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;query ) const</li>
53<li class=fn>QSqlRecordInfo <a href="#recordInfo"><b>recordInfo</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;tablename ) const</li>
54<li class=fn>QSqlRecordInfo <a href="#recordInfo-2"><b>recordInfo</b></a> ( const&nbsp;QSqlQuery&nbsp;&amp;&nbsp;query ) const</li>
55<li class=fn>QSqlQuery <a href="#exec"><b>exec</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;query = QString::null ) const</li>
56<li class=fn>QSqlError <a href="#lastError"><b>lastError</b></a> () const</li>
57<li class=fn>bool <a href="#transaction"><b>transaction</b></a> ()</li>
58<li class=fn>bool <a href="#commit"><b>commit</b></a> ()</li>
59<li class=fn>bool <a href="#rollback"><b>rollback</b></a> ()</li>
60<li class=fn>virtual void <a href="#setDatabaseName"><b>setDatabaseName</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
61<li class=fn>virtual void <a href="#setUserName"><b>setUserName</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
62<li class=fn>virtual void <a href="#setPassword"><b>setPassword</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;password )</li>
63<li class=fn>virtual void <a href="#setHostName"><b>setHostName</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;host )</li>
64<li class=fn>virtual void <a href="#setPort"><b>setPort</b></a> ( int&nbsp;p )</li>
65<li class=fn>void <a href="#setConnectOptions"><b>setConnectOptions</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;options = QString::null )</li>
66<li class=fn>QString <a href="#databaseName"><b>databaseName</b></a> () const</li>
67<li class=fn>QString <a href="#userName"><b>userName</b></a> () const</li>
68<li class=fn>QString <a href="#password"><b>password</b></a> () const</li>
69<li class=fn>QString <a href="#hostName"><b>hostName</b></a> () const</li>
70<li class=fn>QString <a href="#driverName"><b>driverName</b></a> () const</li>
71<li class=fn>int <a href="#port"><b>port</b></a> () const</li>
72<li class=fn>QString <a href="#connectOptions"><b>connectOptions</b></a> () const</li>
73<li class=fn>QSqlDriver * <a href="#driver"><b>driver</b></a> () const</li>
74</ul>
75<h2>Static Public Members</h2>
76<ul>
77<li class=fn>QSqlDatabase * <a href="#addDatabase"><b>addDatabase</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;type, const&nbsp;QString&nbsp;&amp;&nbsp;connectionName = defaultConnection )</li>
78<li class=fn>QSqlDatabase * <a href="#addDatabase-2"><b>addDatabase</b></a> ( QSqlDriver&nbsp;*&nbsp;driver, const&nbsp;QString&nbsp;&amp;&nbsp;connectionName = defaultConnection )</li>
79<li class=fn>QSqlDatabase * <a href="#database"><b>database</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;connectionName = defaultConnection, bool&nbsp;open = TRUE )</li>
80<li class=fn>void <a href="#removeDatabase"><b>removeDatabase</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;connectionName )</li>
81<li class=fn>void <a href="#removeDatabase-2"><b>removeDatabase</b></a> ( QSqlDatabase&nbsp;*&nbsp;db )</li>
82<li class=fn>bool <a href="#contains"><b>contains</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;connectionName = defaultConnection )</li>
83<li class=fn>QStringList <a href="#drivers"><b>drivers</b></a> ()</li>
84<li class=fn>void <a href="#registerSqlDriver"><b>registerSqlDriver</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, const&nbsp;QSqlDriverCreatorBase&nbsp;*&nbsp;creator )</li>
85<li class=fn>bool <a href="#isDriverAvailable"><b>isDriverAvailable</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
86</ul>
87<h2>Properties</h2>
88<ul>
89<li class=fn>QString <a href="#connectOptions-prop"><b>connectOptions</b></a>&nbsp;- the database connect options</li>
90<li class=fn>QString <a href="#databaseName-prop"><b>databaseName</b></a>&nbsp;- the name of the database</li>
91<li class=fn>QString <a href="#hostName-prop"><b>hostName</b></a>&nbsp;- the host name where the database resides</li>
92<li class=fn>QString <a href="#password-prop"><b>password</b></a>&nbsp;- the password used to connect to the database</li>
93<li class=fn>int <a href="#port-prop"><b>port</b></a>&nbsp;- the port used to connect to the database</li>
94<li class=fn>QString <a href="#userName-prop"><b>userName</b></a>&nbsp;- the user name connected to the database</li>
95</ul>
96<h2>Protected Members</h2>
97<ul>
98<li class=fn><a href="#QSqlDatabase"><b>QSqlDatabase</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;type, const&nbsp;QString&nbsp;&amp;&nbsp;name, QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;objname = 0 )</li>
99<li class=fn><a href="#QSqlDatabase-2"><b>QSqlDatabase</b></a> ( QSqlDriver&nbsp;*&nbsp;driver, QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;objname = 0 )</li>
100</ul>
101<hr><a name="details"></a><h2>Detailed Description</h2>
102
103
104The QSqlDatabase class is used to create SQL database
105connections and to provide transaction handling.
106<p>
107
108
109<p> Note that transaction handling is not supported by every SQL
110database. You can find out whether transactions are supported
111using <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>().
112<p> The QSqlDatabase class provides an abstract interface for
113accessing many types of database backends. Database-specific
114drivers are used internally to actually access and manipulate
115data, (see <a href="qsqldriver.html">QSqlDriver</a>). Result set objects provide the interface
116for executing and manipulating SQL queries (see <a href="qsqlquery.html">QSqlQuery</a>).
117<p>See also <a href="database.html">Database Classes</a>.
118
119<hr><h2>Member Function Documentation</h2>
120<h3 class=fn><a name="QSqlDatabase"></a>QSqlDatabase::QSqlDatabase ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;type, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;objname = 0 )<tt> [protected]</tt>
121</h3>
122Creates a QSqlDatabase connection called <em>name</em> that uses the
123driver referred to by <em>type</em>, with the parent <em>parent</em> and the
124object name <em>objname</em>. If the <em>type</em> is not recognized, the
125database connection will have no functionality.
126<p> The currently available drivers are:
127<p> <center><table cellpadding="4" cellspacing="2" border="0">
128<tr bgcolor="#a2c511"> <th valign="top">Driver Type <th valign="top">Description
129<tr bgcolor="#f0f0f0"> <td valign="top"><a href="sql-driver.html#QODBC3">QODBC3</a> <td valign="top">ODBC Driver (includes Microsoft SQL Server)
130<tr bgcolor="#d0d0d0"> <td valign="top"><a href="sql-driver.html#QOCI8">QOCI8</a> <td valign="top">Oracle Call Interface Driver
131<tr bgcolor="#f0f0f0"> <td valign="top"><a href="sql-driver.html#QPSQL7">QPSQL7</a> <td valign="top">PostgreSQL v6.x and v7.x Driver
132<tr bgcolor="#d0d0d0"> <td valign="top"><a href="sql-driver.html#QTDS7">QTDS7</a> <td valign="top">Sybase Adaptive Server
133<tr bgcolor="#f0f0f0"> <td valign="top"><a href="sql-driver.html#QMYSQL3">QMYSQL3</a> <td valign="top">MySQL Driver
134<tr bgcolor="#d0d0d0"> <td valign="top"><a href="sql-driver.html#QDB2">QDB2</a> <td valign="top">IBM DB2, v7.1 and higher
135<tr bgcolor="#f0f0f0"> <td valign="top"><a href="sql-driver.html#QSQLITE">QSQLITE</a> <td valign="top">SQLite Driver
136<tr bgcolor="#d0d0d0"> <td valign="top"><a href="sql-driver.html#QIBASE">QIBASE</a> <td valign="top">Borland Interbase Driver
137</table></center>
138<p> Additional third party drivers, including your own custom drivers,
139can be loaded dynamically.
140<p> <p>See also <a href="#registerSqlDriver">registerSqlDriver</a>().
141
142<h3 class=fn><a name="QSqlDatabase-2"></a>QSqlDatabase::QSqlDatabase ( <a href="qsqldriver.html">QSqlDriver</a>&nbsp;*&nbsp;driver, <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;objname = 0 )<tt> [protected]</tt>
143</h3>
144This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
145<p> Creates a database connection using the driver <em>driver</em>, with
146the parent <em>parent</em> and the object name <em>objname</em>.
147<p> <b>Warning:</b> The framework takes ownership of the <em>driver</em> pointer,
148so it should not be deleted.
149
150<h3 class=fn><a name="~QSqlDatabase"></a>QSqlDatabase::~QSqlDatabase ()
151</h3>
152Destroys the object and frees any allocated resources.
153
154<h3 class=fn><a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;* <a name="addDatabase"></a>QSqlDatabase::addDatabase ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;type, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connectionName = defaultConnection )<tt> [static]</tt>
155</h3>
156Adds a database to the list of database connections using the
157driver <em>type</em> and the connection name <em>connectionName</em>.
158<p> The database connection is referred to by <em>connectionName</em>. The
159newly added database connection is returned. This pointer is owned
160by QSqlDatabase and will be deleted on program exit or when
161<a href="#removeDatabase">removeDatabase</a>() is called.
162<p> If <em>connectionName</em> is not specified, the newly added database
163connection becomes the default database connection for the
164application, and subsequent calls to <a href="#database">database</a>() (without a
165database name parameter) will return a pointer to it. If <em>connectionName</em> is given, use <a href="#database">database(connectionName)</a> to retrieve a pointer to the
166database connection.
167<p> <b>Warning:</b> If you add a database with the same name as an
168existing database, the new database will replace the old one.
169This will happen automatically if you call this function more
170than once without specifying <em>connectionName</em>.
171<p> <p>See also <a href="#database">database</a>() and <a href="#removeDatabase">removeDatabase</a>().
172
173<p>Examples: <a href="sql.html#x2141">sql/overview/connect1/main.cpp</a>, <a href="sql.html#x2147">sql/overview/connection.cpp</a>, and <a href="sqltable-example.html#x2454">sql/sqltable/main.cpp</a>.
174<h3 class=fn><a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;* <a name="addDatabase-2"></a>QSqlDatabase::addDatabase ( <a href="qsqldriver.html">QSqlDriver</a>&nbsp;*&nbsp;driver, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connectionName = defaultConnection )<tt> [static]</tt>
175</h3> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
176<p> This function is useful if you need to set up the database
177connection and instantiate the driver yourself. If you do this, it
178is recommended that you include the driver code in your own
179application. For example, setting up a custom PostgreSQL
180connection and instantiating the <a href="sql-driver.html#QPSQL7">QPSQL7</a> driver can be done the
181following way:
182<p> <pre>
183 #include "qtdir/src/sql/drivers/psql/qsql_psql.cpp"
184 </pre>
185
186(We assume that <tt>qtdir</tt> is the directory where Qt is installed.)
187This will pull in the code that is needed to use the PostgreSQL
188client library and to instantiate a QPSQLDriver object, assuming
189that you have the PostgreSQL headers somewhere in your include
190search path.
191<p> <pre>
192 PGconn* con = PQconnectdb( "host=server user=bart password=simpson dbname=springfield" );
193 QPSQLDriver* drv = new QPSQLDriver( con );
194 QSqlDatabase* db = QSqlDatabase::<a href="#addDatabase">addDatabase</a>( drv ); // becomes the new default connection
195 <a href="qsqlquery.html">QSqlQuery</a> q;
196 q.<a href="qsqlquery.html#exec">exec</a>( "SELECT * FROM people" );
197 ...
198 </pre>
199
200<p> The above code sets up a PostgreSQL connection and instantiates a
201QPSQLDriver object. Next, <a href="#addDatabase">addDatabase</a>() is called to add the
202connection to the known connections so that it can be used by the
203Qt SQL classes. When a driver is instantiated with a connection
204handle (or set of handles), Qt assumes that you have already
205opened the database connection.
206<p> Remember that you must link your application against the database
207client library as well. The simplest way to do this is to add
208lines like those below to your <tt>.pro</tt> file:
209<p> <pre>
210 unix:LIBS += -lpq
211 win32:LIBS += libpqdll.lib
212 </pre>
213
214<p> You will need to have the client library in your linker's search
215path.
216<p> The method described above will work for all the drivers, the only
217difference is the arguments the driver constructors take. Below is
218an overview of the drivers and their constructor arguments.
219<p> <center><table cellpadding="4" cellspacing="2" border="0">
220<tr bgcolor="#a2c511"> <th valign="top">Driver <th valign="top">Class name <th valign="top">Constructor arguments <th valign="top">File to include
221<tr bgcolor="#f0f0f0">
222<td valign="top">QPSQL7
223<td valign="top">QPSQLDriver
224<td valign="top">PGconn* connection
225<td valign="top"><tt>qsql_psql.cpp</tt>
226<tr bgcolor="#d0d0d0">
227<td valign="top"><a href="sql-driver.html#QMYSQL3">QMYSQL3</a>
228<td valign="top">QMYSQLDriver
229<td valign="top">MYSQL* connection
230<td valign="top"><tt>qsql_mysql.cpp</tt>
231<tr bgcolor="#f0f0f0">
232<td valign="top"><a href="sql-driver.html#QOCI8">QOCI8</a>
233<td valign="top">QOCIDriver
234<td valign="top">OCIEnv* environment, OCIError* error, OCISvcCtx* serviceContext
235<td valign="top"><tt>qsql_oci.cpp</tt>
236<tr bgcolor="#d0d0d0">
237<td valign="top"><a href="sql-driver.html#QODBC3">QODBC3</a>
238<td valign="top">QODBCDriver
239<td valign="top">SQLHANDLE environment, SQLHANDLE connection
240<td valign="top"><tt>qsql_odbc.cpp</tt>
241<tr bgcolor="#f0f0f0">
242<td valign="top"><a href="sql-driver.html#QDB2">QDB2</a>
243<td valign="top">QDB2
244<td valign="top">SQLHANDLE environment, SQLHANDLE connection
245<td valign="top"><tt>qsql_db2.cpp</tt>
246<tr bgcolor="#d0d0d0">
247<td valign="top"><a href="sql-driver.html#QTDS7">QTDS7</a>
248<td valign="top">QTDSDriver
249<td valign="top">LOGINREC* loginRecord, DBPROCESS* dbProcess, const <a href="qstring.html">QString</a>& hostName
250<td valign="top"><tt>qsql_tds.cpp</tt>
251<tr bgcolor="#f0f0f0">
252<td valign="top"><a href="sql-driver.html#QSQLITE">QSQLITE</a>
253<td valign="top">QSQLiteDriver
254<td valign="top">sqlite* connection
255<td valign="top"><tt>qsql_sqlite.cpp</tt>
256<tr bgcolor="#d0d0d0">
257<td valign="top"><a href="sql-driver.html#QIBASE">QIBASE</a>
258<td valign="top">QIBaseDriver
259<td valign="top">isc_db_handle connection
260<td valign="top"><tt>qsql_ibase.cpp</tt>
261</table></center>
262<p> Note: The host name (or service name) is needed when constructing
263the QTDSDriver for creating new connections for internal
264queries. This is to prevent the simultaneous usage of several
265<a href="qsqlquery.html">QSqlQuery</a>/<a href="qsqlcursor.html">QSqlCursor</a> objects from blocking each other.
266<p> <b>Warning:</b> The SQL framework takes ownership of the <em>driver</em> pointer,
267and it should not be deleted. The returned QSqlDatabase object is
268owned by the framework and must not be deleted. If you want to
269explicitly remove the connection, use <a href="#removeDatabase">removeDatabase</a>()
270<p> <p>See also <a href="#drivers">drivers</a>().
271
272<h3 class=fn>void <a name="close"></a>QSqlDatabase::close ()
273</h3>
274Closes the database connection, freeing any resources acquired.
275<p> <p>See also <a href="#removeDatabase">removeDatabase</a>().
276
277<h3 class=fn>bool <a name="commit"></a>QSqlDatabase::commit ()
278</h3>
279Commits a transaction to the database if the driver supports
280transactions. Returns TRUE if the operation succeeded; otherwise
281returns FALSE.
282<p> <p>See also <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>() and <a href="#rollback">rollback</a>().
283
284<h3 class=fn><a href="qstring.html">QString</a> <a name="connectOptions"></a>QSqlDatabase::connectOptions () const
285</h3><p>Returns the database connect options.
286See the <a href="qsqldatabase.html#connectOptions-prop">"connectOptions"</a> property for details.
287<h3 class=fn>bool <a name="contains"></a>QSqlDatabase::contains ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connectionName = defaultConnection )<tt> [static]</tt>
288</h3>
289Returns TRUE if the list of database connections contains <em>connectionName</em>; otherwise returns FALSE.
290
291<h3 class=fn><a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;* <a name="database"></a>QSqlDatabase::database ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connectionName = defaultConnection, bool&nbsp;open = TRUE )<tt> [static]</tt>
292</h3>
293Returns the database connection called <em>connectionName</em>. The
294database connection must have been previously added with
295<a href="#addDatabase">addDatabase</a>(). If <em>open</em> is TRUE (the default) and the database
296connection is not already open it is opened now. If no <em>connectionName</em> is specified the default connection is used. If <em>connectionName</em> does not exist in the list of databases, 0 is
297returned. The pointer returned is owned by QSqlDatabase and should
298<em>not</em> be deleted.
299<p> <b>Warning:</b> There are restrictions on the use of database connections
300in threaded applications. Please see the <a href="threads.html#threads-sql">Thread Support in Qt</a> document for more information about
301threading and SQL databases.
302
303<p>Examples: <a href="sql.html#x2156">sql/overview/basicbrowsing/main.cpp</a> and <a href="sql.html#x2155">sql/overview/create_connections/main.cpp</a>.
304<h3 class=fn><a href="qstring.html">QString</a> <a name="databaseName"></a>QSqlDatabase::databaseName () const
305</h3><p>Returns the name of the database.
306See the <a href="qsqldatabase.html#databaseName-prop">"databaseName"</a> property for details.
307<h3 class=fn><a href="qsqldriver.html">QSqlDriver</a>&nbsp;* <a name="driver"></a>QSqlDatabase::driver () const
308</h3>
309Returns the database driver used to access the database
310connection.
311
312<h3 class=fn><a href="qstring.html">QString</a> <a name="driverName"></a>QSqlDatabase::driverName () const
313</h3>
314Returns the name of the driver used by the database connection.
315
316<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="drivers"></a>QSqlDatabase::drivers ()<tt> [static]</tt>
317</h3>
318Returns a list of all the available database drivers.
319<p> Note that if you want to iterate over the list, you should iterate
320over a copy, e.g.
321<pre>
322 <a href="qstringlist.html">QStringList</a> list = QSqlDatabase::<a href="#drivers">drivers</a>();
323 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
324 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
325 myProcessing( *it );
326 ++it;
327 }
328 </pre>
329
330
331<h3 class=fn><a href="qsqlquery.html">QSqlQuery</a> <a name="exec"></a>QSqlDatabase::exec ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;query = QString::null ) const
332</h3>
333Executes a SQL statement (e.g. an <tt>INSERT</tt>, <tt>UPDATE</tt> or <tt>DELETE</tt> statement) on the database, and returns a <a href="qsqlquery.html">QSqlQuery</a> object.
334Use <a href="#lastError">lastError</a>() to retrieve error information. If <em>query</em> is
335<a href="qstring.html#QString-null">QString::null</a>, an empty, invalid query is returned and lastError()
336is not affected.
337<p> <p>See also <a href="qsqlquery.html">QSqlQuery</a> and <a href="#lastError">lastError</a>().
338
339<h3 class=fn><a href="qstring.html">QString</a> <a name="hostName"></a>QSqlDatabase::hostName () const
340</h3><p>Returns the host name where the database resides.
341See the <a href="qsqldatabase.html#hostName-prop">"hostName"</a> property for details.
342<h3 class=fn>bool <a name="isDriverAvailable"></a>QSqlDatabase::isDriverAvailable ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [static]</tt>
343</h3>
344Returns TRUE if a driver called <em>name</em> is available; otherwise
345returns FALSE.
346<p> <p>See also <a href="#drivers">drivers</a>().
347
348<h3 class=fn>bool <a name="isOpen"></a>QSqlDatabase::isOpen () const
349</h3>
350Returns TRUE if the database connection is currently open;
351otherwise returns FALSE.
352
353<h3 class=fn>bool <a name="isOpenError"></a>QSqlDatabase::isOpenError () const
354</h3>
355Returns TRUE if there was an error opening the database
356connection; otherwise returns FALSE. Error information can be
357retrieved using the <a href="#lastError">lastError</a>() function.
358
359<h3 class=fn><a href="qsqlerror.html">QSqlError</a> <a name="lastError"></a>QSqlDatabase::lastError () const
360</h3>
361Returns information about the last error that occurred on the
362database. See <a href="qsqlerror.html">QSqlError</a> for more information.
363
364<p>Examples: <a href="sql.html#x2148">sql/overview/connection.cpp</a> and <a href="sqltable-example.html#x2455">sql/sqltable/main.cpp</a>.
365<h3 class=fn>bool <a name="open"></a>QSqlDatabase::open ()
366</h3>
367Opens the database connection using the current connection values.
368Returns TRUE on success; otherwise returns FALSE. Error
369information can be retrieved using the <a href="#lastError">lastError</a>() function.
370<p> <p>See also <a href="#lastError">lastError</a>().
371
372<p>Examples: <a href="sql.html#x2142">sql/overview/connect1/main.cpp</a>, <a href="sql.html#x2149">sql/overview/connection.cpp</a>, and <a href="sqltable-example.html#x2456">sql/sqltable/main.cpp</a>.
373<h3 class=fn>bool <a name="open-2"></a>QSqlDatabase::open ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;user, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;password )
374</h3>
375This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
376<p> Opens the database connection using the given <em>user</em> name and <em>password</em>. Returns TRUE on success; otherwise returns FALSE. Error
377information can be retrieved using the <a href="#lastError">lastError</a>() function.
378<p> This function does not store the password it is given. Instead,
379the password is passed directly to the driver for opening a
380connection and is then discarded.
381<p> <p>See also <a href="#lastError">lastError</a>().
382
383<h3 class=fn><a href="qstring.html">QString</a> <a name="password"></a>QSqlDatabase::password () const
384</h3><p>Returns the password used to connect to the database.
385See the <a href="qsqldatabase.html#password-prop">"password"</a> property for details.
386<h3 class=fn>int <a name="port"></a>QSqlDatabase::port () const
387</h3><p>Returns the port used to connect to the database.
388See the <a href="qsqldatabase.html#port-prop">"port"</a> property for details.
389<h3 class=fn><a href="qsqlindex.html">QSqlIndex</a> <a name="primaryIndex"></a>QSqlDatabase::primaryIndex ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tablename ) const
390</h3>
391Returns the primary index for table <em>tablename</em>. If no primary
392index exists an empty <a href="qsqlindex.html">QSqlIndex</a> will be returned.
393
394<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a> <a name="record"></a>QSqlDatabase::record ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tablename ) const
395</h3>
396Returns a <a href="qsqlrecord.html">QSqlRecord</a> populated with the names of all the fields in
397the table (or view) called <em>tablename</em>. The order in which the
398fields appear in the record is undefined. If no such table (or
399view) exists, an empty record is returned.
400<p> <p>See also <a href="#recordInfo">recordInfo</a>().
401
402<h3 class=fn><a href="qsqlrecord.html">QSqlRecord</a> <a name="record-2"></a>QSqlDatabase::record ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;query ) const
403</h3>
404This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
405<p> Returns a <a href="qsqlrecord.html">QSqlRecord</a> populated with the names of all the fields
406used in the SQL <em>query</em>. If the query is a "SELECT *" the order
407in which fields appear in the record is undefined.
408<p> <p>See also <a href="#recordInfo">recordInfo</a>().
409
410<h3 class=fn><a href="qsqlrecordinfo.html">QSqlRecordInfo</a> <a name="recordInfo"></a>QSqlDatabase::recordInfo ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;tablename ) const
411</h3>
412Returns a <a href="qsqlrecordinfo.html">QSqlRecordInfo</a> populated with meta data about the table
413or view <em>tablename</em>. If no such table (or view) exists, an empty
414record is returned.
415<p> <p>See also <a href="qsqlrecordinfo.html">QSqlRecordInfo</a>, <a href="qsqlfieldinfo.html">QSqlFieldInfo</a>, and <a href="#record">record</a>().
416
417<h3 class=fn><a href="qsqlrecordinfo.html">QSqlRecordInfo</a> <a name="recordInfo-2"></a>QSqlDatabase::recordInfo ( const&nbsp;<a href="qsqlquery.html">QSqlQuery</a>&nbsp;&amp;&nbsp;query ) const
418</h3>
419This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
420<p> Returns a <a href="qsqlrecordinfo.html">QSqlRecordInfo</a> object with meta data for the <a href="qsqlquery.html">QSqlQuery</a>
421<em>query</em>. Note that this overloaded function may return less
422information than the <a href="#recordInfo">recordInfo</a>() function which takes the name of
423a table as parameter.
424<p> <p>See also <a href="qsqlrecordinfo.html">QSqlRecordInfo</a>, <a href="qsqlfieldinfo.html">QSqlFieldInfo</a>, and <a href="#record">record</a>().
425
426<h3 class=fn>void <a name="registerSqlDriver"></a>QSqlDatabase::registerSqlDriver ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, const&nbsp;QSqlDriverCreatorBase&nbsp;*&nbsp;creator )<tt> [static]</tt>
427</h3>
428This function registers a new SQL driver called <em>name</em>, within
429the SQL framework. This is useful if you have a custom SQL driver
430and don't want to compile it as a plugin.
431<p> Example usage:
432<p> <pre>
433 QSqlDatabase::<a href="#registerSqlDriver">registerSqlDriver</a>( "MYDRIVER", new QSqlDriverCreator&lt;MyDatabaseDriver&gt; );
434 QSqlDatabase* db = QSqlDatabase::<a href="#addDatabase">addDatabase</a>( "MYDRIVER" );
435 ...
436 </pre>
437
438<p> <b>Warning:</b> The framework takes ownership of the <em>creator</em> pointer,
439so it should not be deleted.
440
441<h3 class=fn>void <a name="removeDatabase"></a>QSqlDatabase::removeDatabase ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;connectionName )<tt> [static]</tt>
442</h3>
443Removes the database connection <em>connectionName</em> from the list of
444database connections.
445<p> <b>Warning:</b> There should be no open queries on the database
446connection when this function is called, otherwise a resource leak
447will occur.
448
449<h3 class=fn>void <a name="removeDatabase-2"></a>QSqlDatabase::removeDatabase ( <a href="qsqldatabase.html">QSqlDatabase</a>&nbsp;*&nbsp;db )<tt> [static]</tt>
450</h3>
451This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
452<p> Removes the database connection <em>db</em> from the list of database
453connections. The QSqlDatabase object is destroyed when it is removed
454from the list.
455<p> <b>Warning:</b> The <em>db</em> pointer is not valid after this function has
456been called. There should be no open queries on the database
457connection when this function is called, otherwise a resource leak
458will occur.
459
460<h3 class=fn>bool <a name="rollback"></a>QSqlDatabase::rollback ()
461</h3>
462Rolls a transaction back on the database if the driver supports
463transactions. Returns TRUE if the operation succeeded; otherwise
464returns FALSE.
465<p> <p>See also <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>(), <a href="#commit">commit</a>(), and <a href="#transaction">transaction</a>().
466
467<h3 class=fn>void <a name="setConnectOptions"></a>QSqlDatabase::setConnectOptions ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;options = QString::null )
468</h3><p>Sets the database connect options to <em>options</em>.
469See the <a href="qsqldatabase.html#connectOptions-prop">"connectOptions"</a> property for details.
470<h3 class=fn>void <a name="setDatabaseName"></a>QSqlDatabase::setDatabaseName ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [virtual]</tt>
471</h3><p>Sets the name of the database to <em>name</em>.
472See the <a href="qsqldatabase.html#databaseName-prop">"databaseName"</a> property for details.
473<h3 class=fn>void <a name="setHostName"></a>QSqlDatabase::setHostName ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;host )<tt> [virtual]</tt>
474</h3><p>Sets the host name where the database resides to <em>host</em>.
475See the <a href="qsqldatabase.html#hostName-prop">"hostName"</a> property for details.
476<h3 class=fn>void <a name="setPassword"></a>QSqlDatabase::setPassword ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;password )<tt> [virtual]</tt>
477</h3><p>Sets the password used to connect to the database to <em>password</em>.
478See the <a href="qsqldatabase.html#password-prop">"password"</a> property for details.
479<h3 class=fn>void <a name="setPort"></a>QSqlDatabase::setPort ( int&nbsp;p )<tt> [virtual]</tt>
480</h3><p>Sets the port used to connect to the database to <em>p</em>.
481See the <a href="qsqldatabase.html#port-prop">"port"</a> property for details.
482<h3 class=fn>void <a name="setUserName"></a>QSqlDatabase::setUserName ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [virtual]</tt>
483</h3><p>Sets the user name connected to the database to <em>name</em>.
484See the <a href="qsqldatabase.html#userName-prop">"userName"</a> property for details.
485<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="tables"></a>QSqlDatabase::tables ( <a href="qsql.html#TableType-enum">QSql::TableType</a>&nbsp;type ) const
486</h3>
487Returns a list of the database's tables, system tables and views,
488as specified by the parameter <em>type</em>.
489<p> Note that if you want to iterate over the list, you should iterate
490over a copy, e.g.
491<pre>
492 <a href="qstringlist.html">QStringList</a> list = myDatabase.tables( QSql::Tables | QSql::Views );
493 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
494 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
495 myProcessing( *it );
496 ++it;
497 }
498 </pre>
499
500
501<p>Example: <a href="sqltable-example.html#x2461">sql/sqltable/main.cpp</a>.
502<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="tables-2"></a>QSqlDatabase::tables () const
503</h3>
504This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
505<p> Returns a list of the database's tables that are visible to the
506user. To include views or system tables, use the version of this
507function that takes a table <tt>type</tt> parameter.
508<p> Note that if you want to iterate over the list, you should iterate
509over a copy, e.g.
510<pre>
511 <a href="qstringlist.html">QStringList</a> list = myDatabase.tables();
512 QStringList::Iterator it = list.<a href="qvaluelist.html#begin">begin</a>();
513 while( it != list.<a href="qvaluelist.html#end">end</a>() ) {
514 myProcessing( *it );
515 ++it;
516 }
517 </pre>
518
519
520<h3 class=fn>bool <a name="transaction"></a>QSqlDatabase::transaction ()
521</h3>
522Begins a transaction on the database if the driver supports
523transactions. Returns TRUE if the operation succeeded; otherwise
524returns FALSE.
525<p> <p>See also <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>(), <a href="#commit">commit</a>(), and <a href="#rollback">rollback</a>().
526
527<h3 class=fn><a href="qstring.html">QString</a> <a name="userName"></a>QSqlDatabase::userName () const
528</h3><p>Returns the user name connected to the database.
529See the <a href="qsqldatabase.html#userName-prop">"userName"</a> property for details.
530<hr><h2>Property Documentation</h2>
531<h3 class=fn><a href="qstring.html">QString</a> <a name="connectOptions-prop"></a>connectOptions</h3>
532<p>This property holds the database connect options.
533<p>The format of the options string is a semi-colon separated list of
534option names or option = value pairs. The options depend on the
535database client used:
536<p> <center><table cellpadding="4" cellspacing="2" border="0">
537<tr bgcolor="#a2c511"> <th valign="top">ODBC <th valign="top">MySQL <th valign="top">PostgreSQL
538<tr bgcolor="#f0f0f0">
539<p> <td valign="top">
540<ul>
541<li> SQL_ATTR_ACCESS_MODE
542<li> SQL_ATTR_LOGIN_TIMEOUT
543<li> SQL_ATTR_CONNECTION_TIMEOUT
544<li> SQL_ATTR_CURRENT_CATALOG
545<li> SQL_ATTR_METADATA_ID
546<li> SQL_ATTR_PACKET_SIZE
547<li> SQL_ATTR_TRACEFILE
548<li> SQL_ATTR_TRACE
549</ul>
550<p> <td valign="top">
551<ul>
552<li> CLIENT_COMPRESS
553<li> CLIENT_FOUND_ROWS
554<li> CLIENT_IGNORE_SPACE
555<li> CLIENT_SSL
556<li> CLIENT_ODBC
557<li> CLIENT_NO_SCHEMA
558<li> CLIENT_INTERACTIVE
559</ul>
560<p> <td valign="top">
561<ul>
562<li> connect_timeout
563<li> options
564<li> tty
565<li> requiressl
566<li> service
567</ul>
568<tr bgcolor="#a2c511"> <th valign="top">DB2 <th valign="top">OCI <th valign="top">TDS
569<tr bgcolor="#d0d0d0">
570<p> <td valign="top">
571<ul>
572<li> SQL_ATTR_ACCESS_MODE
573<li> SQL_ATTR_LOGIN_TIMEOUT
574</ul>
575<p> <td valign="top">
576<em>none</em>
577<p> <td valign="top">
578<em>none</em>
579<p> </table></center>
580<p> Example of usage:
581<pre>
582 ...
583 // MySQL connection
584 db-&gt;setConnectOptions( "CLIENT_SSL;CLIENT_IGNORE_SPACE" ); // use an SSL connection to the server
585 if ( !db-&gt;open() ) {
586 db-&gt;setConnectOptions(); // clears the connect option string
587 ...
588 }
589 ...
590 // PostgreSQL connection
591 db-&gt;setConnectOptions( "requiressl=1" ); // enable PostgreSQL SSL connections
592 if ( !db-&gt;open() ) {
593 db-&gt;setConnectOptions(); // clear options
594 ...
595 }
596 ...
597 // ODBC connection
598 db-&gt;setConnectOptions( "SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON" ); // set ODBC options
599 if ( !db-&gt;open() ) {
600 db-&gt;setConnectOptions(); // don't try to set this option
601 ...
602 }
603 </pre>
604
605<p> Please refer to the client library documentation for more
606information about the different options. The options will be set
607prior to opening the database connection. Setting new options
608without re-opening the connection does nothing.
609<p> <p>See also
610<p>Set this property's value with <a href="#setConnectOptions">setConnectOptions</a>() and get this property's value with <a href="#connectOptions">connectOptions</a>().
611<h3 class=fn><a href="qstring.html">QString</a> <a name="databaseName-prop"></a>databaseName</h3>
612<p>This property holds the name of the database.
613<p>Note that the database name is the TNS Service Name for the <a href="sql-driver.html#QOCI8">QOCI8</a>
614(Oracle) driver.
615<p> For the <a href="sql-driver.html#QODBC3">QODBC3</a> driver it can either be a DSN, a DSN filename (the
616file must have a <tt>.dsn</tt> extension), or a connection string. MS
617Access users can for example use the following connection string
618to open a <tt>.mdb</tt> file directly, instead of having to create a DSN
619entry in the ODBC manager:
620<p> <pre>
621 ...
622 db = QSqlDatabase::<a href="#addDatabase">addDatabase</a>( "QODBC3" );
623 db-&gt;setDatabaseName( "DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb" );
624 if ( db-&gt;open() ) {
625 // success!
626 }
627 ...
628 </pre>
629
630("FIL" is the required spelling in Microsoft's API.)
631<p> There is no default value.
632
633<p>Set this property's value with <a href="#setDatabaseName">setDatabaseName</a>() and get this property's value with <a href="#databaseName">databaseName</a>().
634<h3 class=fn><a href="qstring.html">QString</a> <a name="hostName-prop"></a>hostName</h3>
635<p>This property holds the host name where the database resides.
636<p>There is no default value.
637
638<p>Set this property's value with <a href="#setHostName">setHostName</a>() and get this property's value with <a href="#hostName">hostName</a>().
639<h3 class=fn><a href="qstring.html">QString</a> <a name="password-prop"></a>password</h3>
640<p>This property holds the password used to connect to the database.
641<p>There is no default value.
642<p> <b>Warning:</b> This function stores the password in plain text within
643Qt. Use the <a href="#open">open</a>() call that takes a password as parameter to
644avoid this behaviour.
645<p> <p>See also <a href="#open">open</a>().
646
647<p>Set this property's value with <a href="#setPassword">setPassword</a>() and get this property's value with <a href="#password">password</a>().
648<h3 class=fn>int <a name="port-prop"></a>port</h3>
649<p>This property holds the port used to connect to the database.
650<p>There is no default value.
651
652<p>Set this property's value with <a href="#setPort">setPort</a>() and get this property's value with <a href="#port">port</a>().
653<h3 class=fn><a href="qstring.html">QString</a> <a name="userName-prop"></a>userName</h3>
654<p>This property holds the user name connected to the database.
655<p>There is no default value.
656
657<p>Set this property's value with <a href="#setUserName">setUserName</a>() and get this property's value with <a href="#userName">userName</a>().
658<!-- eof -->
659<hr><p>
660This file is part of the <a href="index.html">Qt toolkit</a>.
661Copyright &copy; 1995-2007
662<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
663<table width=100% cellspacing=0 border=0><tr>
664<td>Copyright &copy; 2007
665<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
666<td align=right><div align=right>Qt 3.3.8</div>
667</table></div></address></body>
668</html>
Note: See TracBrowser for help on using the repository browser.