diff options
Diffstat (limited to 'doc/html/sql-driver.html')
| -rw-r--r-- | doc/html/sql-driver.html | 635 |
1 files changed, 635 insertions, 0 deletions
diff --git a/doc/html/sql-driver.html b/doc/html/sql-driver.html new file mode 100644 index 000000000..03ea58003 --- /dev/null +++ b/doc/html/sql-driver.html @@ -0,0 +1,635 @@ +<!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/doc/sql-driver.doc:35 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>SQL Module - Drivers</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>SQL Module - Drivers</h1> + + +<p> <ul> +<li> <a href="#Introduction">Introduction</a> +<li> <a href="#building">Building the drivers using configure</a> +<li> <a href="#buildingmanually">Building the plugins manually</a> +<ul> +<li> <a href="#TQDB2">TQDB2</a> - IBM DB2 Driver (v7.1 and higher) +<li> <a href="#TQIBASE">TQIBASE</a> - Borland Interbase Driver +<li> <a href="#TQMYSQL3">TQMYSQL3</a> - MySQL Driver +<li> <a href="#TQOCI8">TQOCI8</a> - Oracle Call Interface Driver, version 8 and 9 +<li> <a href="#TQODBC3">TQODBC3</a> - Open Database Connectivity Driver +<li> <a href="#TQPSQL7">TQPSQL7</a> - PostgreSQL v6.x and v7.x Driver +<li> <a href="#TQSQLITE">TQSQLITE</a> - SQLite Driver +<li> <a href="#TQTDS7">TQTDS7</a> - Sybase Adaptive Server +</ul> +<li> <a href="#troubleshooting">Troubleshooting</a> +<li> <a href="#development">How to write your own database driver</a> +</ul> +<p> <a name="Introduction"></a> +<h2> Introduction +</h2> +<a name="1"></a><p> The <a href="sql.html">SQL Module</a> uses driver <a href="plugins-howto.html">plugins</a> in order to communicate with +different database APIs. Since the SQL Module API is +database-independent, all database-specific code is contained within +these drivers. Several drivers are supplied with TQt and other drivers +can be added. The driver source code is supplied and can be used as a +model for <a href="#development">writing your own drivers</a>. +<p> <em>Note:</em> To build a driver plugin you need to have the appropriate +client library for your Database Management System (DBMS). This provides +access to the API exposed by the DBMS, and is typically shipped with it. +Most installation programs also allow you to install "development +libraries", and these are what you need. These libraries are responsible +for the low-level communication with the DBMS. +<p> The drivers shipped with TQt are: +<ul> +<li> <a href="#TQDB2">TQDB2</a> - IBM DB2 Driver (v7.1 and higher) +<li> <a href="#TQIBASE">TQIBASE</a> - Borland Interbase Driver +<li> <a href="#TQMYSQL3">TQMYSQL3</a> - MySQL Driver +<li> <a href="#TQOCI8">TQOCI8</a> - Oracle Call Interface Driver, version 8, 9 and 10 +<li> <a href="#TQODBC3">TQODBC3</a> - Open Database Connectivity Driver +<li> <a href="#TQPSQL7">TQPSQL7</a> - PostgreSQL v6.x and v7.x Driver +<li> <a href="#TQSQLITE">TQSQLITE</a> - SQLite Driver +<li> <a href="#TQTDS7">TQTDS7</a> - Sybase Adaptive Server +</ul> +<p> Note that not all of the plugins are shipped with the TQt Open Source Edition +due to license incompatibilities with the GPL. +<p> <a name="building"></a> +<h2> Building the drivers using configure +</h2> +<a name="2"></a><p> The TQt configure script automatically detects the available client +libraries on your machine. Run "configure -help" to see what drivers +can be built. You should get an output similar to this: +<p> <pre> +Possible values for <driver>: [ mysql oci odbc psql tds ] +Auto-Detected on this system: [ mysql psql ] +</pre> + +<p> Note that on Windows, the configure script doesn't do any +auto-detection. +<p> The configure script cannot detect the neccessary libraries and include +files if they are not in the standard paths, so it may be necessary to +specify these paths using the "-I" and "-L" switches. For example, if +your MySQL include files are installed in <tt>/usr/local/mysql</tt> (or in +<tt>C:\mysql\include</tt> + +configure: <tt>-I/usr/local/mysql</tt> (or <tt>-I C:\mysql\include</tt> + +Windows). +<p> On Windows the -I parameter doesn't accept spaces in +filenames, so use the 8.3 name instead, i.e. use <tt>C:\progra~1\mysql</tt> +instead of <tt>C:\program files\mysql</tt>. +<p> Use the <tt>-qt-sql-<driver></tt> parameter to build the database driver +statically into your TQt library or <tt>-plugin-sql-<driver></tt> to build +the driver as a plugin. Look at the sections that follow for +additional information about retquired libraries. +<p> <a name="buildingmanually"></a> +<h2> Building the plugins manually +</h2> +<a name="3"></a><p> <a name="TQMYSQL3"></a> +<h3> TQMYSQL3 - MySQL 3.x and MySQL 4.x +</h3> +<a name="3-1"></a><p> <!-- index TQMYSQL3 --><a name="TQMYSQL3"></a> +<p> <h4> General information +</h4> +<a name="3-1-1"></a><p> MySQL 3.x doesn't support SQL transactions by default. There are some +backends which offer this functionality. Recent versions of the MySQL +client libraries (>3.23.34) allow you to use transactions on those +modified servers. +<p> If you have a recent client library and connect to a +transaction-enabled MySQL server, a call to the +<a href="qsqldriver.html#hasFeature">TQSqlDriver::hasFeature</a>( TQSqlDriver::Transactions ) function returns +TRUE and SQL transactions can be used. +<p> If the plugin is compiled against MySQL 4.x client libraries, +transactions are enabled by default. +<p> You can find information about MySQL on <a href="http://www.mysql.com">http://www.mysql.com</a> +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-1-2"></a><p> You need the MySQL header files and as well as the shared library +<tt>libmysqlclient.so</tt>. Depending on your Linux distribution you need to +install a package which is usually called "mysql-devel". +<p> Tell <a href="qmake-manual.html">qmake</a> where to find the MySQL +header files and shared libraries (here it is assumed that MySQL is +installed in <tt>/usr/local</tt>) and run <tt>make</tt>: +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/mysql +qmake -o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient" mysql.pro +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-1-3"></a><p> You need to get the MySQL installation files. Run SETUP.EXE and +choose "Custom Install". Install the "Libs & Include Files" Module. +Build the plugin as follows (here it is assumed that MySQL is +installed in <tt>C:\MYSQL</tt>): +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\mysql +qmake -o Makefile "INCLUDEPATH+=C:\MYSQL\INCLUDE" "LIBS+=C:\MYSQL\LIB\OPT\LIBMYSQL.LIB" mysql.pro +nmake +</pre> + +<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above. +<p> <a name="TQOCI8"></a> +<h3> TQOCI8 - Oracle Call Interface (OCI) +</h3> +<a name="3-2"></a><p> <!-- index TQOCI8 --><a name="TQOCI8"></a> +<p> <h4> General information +</h4> +<a name="3-2-1"></a><p> The TQt OCI plugin supports both Oracle 8 and Oracle 9. After +connecting to the Oracle server, the plugin will auto-detect the +database version and enable features accordingly. +<p> <h4> Unicode support +</h4> +<a name="3-2-2"></a><p> If the Oracle server supports Unicode, the OCI plugin will use UTF-8 +encoding to communicate with the server. +<p> <h4> BLOB/LOB support +</h4> +<a name="3-2-3"></a><p> Binary Large Objects (BLOBs) can be read and written, but be aware +that this process may retquire a lot of memory. +<p> Note that Oracle 9 doesn't support scrollable result sets with LOB +columns, you have to use a forward only query to select LOB fields +(see <a href="qsqlquery.html#setForwardOnly">TQSqlQuery::setForwardOnly</a>()). +<p> Inserting BLOBs should be done using either a prepared query where the +BLOBs are bound to placeholders, or <a href="qsqlcursor.html">TQSqlCursor</a> which uses a prepared +query to do this internally (see $QTDIR/examples/sql/blob). +<p> <h4> Know problems +</h4> +<a name="3-2-4"></a><p> When a query is in forward only mode a call to <a href="qsqlquery.html#last">TQSqlQuery::last</a>() will +position the query on the last record and return TRUE, but subsequent +calls to <a href="qsqlquery.html#value">TQSqlQuery::value</a>() will only return NULLs. +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-2-5"></a><p> All files retquired to build driver should ship with the standard Oracle +Client install. +<p> Oracle library files retquired to build driver: +<p> <ul> +<li> <tt>libclntsh.so</tt> (all versions) +<li> <tt>libwtc8.so</tt> (only Oracle 8) or <tt>libwtc9.so</tt> (only Oracle 9) +</ul> +<p> Tell <tt>qmake</tt> where to find the Oracle header files and shared +libraries (it is assumed that the variable <tt>$ORACLE_HOME</tt> points to +the directory where Oracle is installed) and run make: +<p> If you are using Oracle 8: +<pre> +cd $QTDIR/plugins/src/sqldrivers/oci +qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc8" oci.pro +make +</pre> + +<p> For Oracle version 9: +<pre> +cd $QTDIR/plugins/src/sqldrivers/oci +qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro +make +</pre> + +<p> For Oracle version 10: +<pre> +cd $QTDIR/plugins/src/sqldrivers/oci +qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh" oci.pro +make +</pre> + +<p> Note that some versions of the OCI client libraries contain a bug +that makes programs linked to these libraries segfault on exit. This +only happens if the TQOCI8 driver is compiled as a plugin. To work +around this problem, either compile the driver into the TQt libray +itself, or configure TQt with the option '-DQT_NO_LIBRARY_UNLOAD'. +For Oracle 9, it is possible to link to the static OCI library by +using "LIBS+=$ORACLE_HOME/lib/libclntst9.a". +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-2-6"></a><p> Choosing the option "Programmer" in the Oracle Client Installer from +the Oracle Client Installation CD is sufficient to build the plugin. +<p> Build the plugin as follows (here it is assumed that Oracle Client is +installed in <tt>C:\oracle</tt>): +<p> <pre> +set INCLUDE=%INCLUDE%;c:\oracle\oci\include +set LIB=%LIB%;c:\oracle\oci\lib\msvc +cd %QTDIR%\plugins\src\sqldrivers\oci +qmake -o Makefile oci.pro +nmake +</pre> + +<p> When you run your application you will also need to add the <tt>oci.dll</tt> +path to your <tt>PATH</tt> environment variable: +<p> <pre> +set PATH=%PATH%;c:\oracle\bin +</pre> + +<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above. +<p> <a name="TQODBC3"></a> +<h3> TQODBC3 - Open Database Connectivity (ODBC) +</h3> +<a name="3-3"></a><p> <!-- index TQODBC3 --><a name="TQODBC3"></a> +<p> <h4> General information +</h4> +<a name="3-3-1"></a><p> ODBC is a general interface that allows you to connect to multiple +DBMS using a common interface. The TQODBC3 driver allows you to connect +to an ODBC driver manager and access the available data sources. Note +that you also need to install and configure ODBC drivers for the ODBC +driver manager that is installed on your system. The TQODBC3 plugin +then allows you to use these data sources in your TQt project. +<p> On Windows systems after 95 an ODBC driver manager should be installed +by default, for Unix systems there are some implementations which must +be installed first. Note that every client that uses your application +is retquired to have an ODBC driver manager installed, otherwise the +TQODBC3 plugin will not work. +<p> Be aware that when connecting to an ODBC datasource you must pass in +the name of the ODBC datasource to the <a href="qsqldatabase.html#setDatabaseName">TQSqlDatabase::setDatabaseName</a>() +function: not the actual database name. +<p> The TQODBC3 Plugin needs an ODBC compliant driver manager version 2.0 or +later to work. Some ODBC drivers claim to be version 2.0 compliant, +but do not offer all the necessary functionality. The TQODBC3 plugin +therefore checks whether the data source can be used after a +connection has been established and refuses to work if the check +fails. If you don't like this behaviour, you can remove the <tt>#define ODBC_CHECK_DRIVER</tt> line from the file <tt>qsql_odbc.cpp</tt>. Do this at +your own risk! +<p> If you experience very slow access of the ODBC datasource, make sure +that ODBC call tracing is turned off in the ODBC datasource manager. +<p> <h4> Unicode support +</h4> +<a name="3-3-2"></a><p> The TQODBC3 Plugin will use the Unicode API if UNICODE is defined. On +Windows NT based systems, this is the default. Note that the ODBC +driver and the DBMS have to support Unicode as well. +<p> For the Oracle 9 ODBC driver (Windows), it is neccessary to check +"SQL_WCHAR support" in the ODBC driver manager otherwise Oracle +will convert all Unicode strings to local 8 bit. +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-3-3"></a><p> It is recommended that you use unixODBC. You can find the latest +version and ODBC drivers at <a href="http://www.unixodbc.org">http://www.unixodbc.org</a>. +You need the unixODBC header files and shared libraries. +<p> Tell <tt>qmake</tt> where to find the unixODBC header files and shared +libraries (here it is assumed that unixODBC is installed in +<tt>/usr/local/unixODBC</tt>) and run <tt>make</tt>: +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/odbc +qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-3-4"></a><p> The ODBC header and include files should already be installed in the +right directories. You just have to build the plugin as follows: +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\odbc +qmake -o Makefile odbc.pro +nmake +</pre> + +<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above. +<p> <a name="TQPSQL7"></a> +<h3> TQPSQL7 - PostgreSQL version 6 and 7 +</h3> +<a name="3-4"></a><p> <!-- index TQPSQL7 --><a name="TQPSQL7"></a> +<p> <h4> General information +</h4> +<a name="3-4-1"></a><p> The TQPSQL7 driver supports both version 6 and 7 of PostgreSQL. We +recommend compiling the plugin with a recent version of the PostgreSQL +client library (libpq) because it is more stable and still backwards +compatible. +<p> If you want to link the plugin against the libpq shipped with version +6 we recommend a recent version like PostgreSQL 6.5.3, otherwise a +connection to a version 7 server may not work. +<p> The driver auto-detects the server version of PostgreSQL after a +connection was successful. If the server is too old or the version +information cannot be determined a warning is issued. +<p> For more information about PostgreSQL visit <a href="http://www.postgresql.org">http://www.postgresql.org</a>. +<p> <h4> Unicode support +</h4> +<a name="3-4-2"></a><p> The TQPSQL7 driver automatically detects whether the PostgreSQL +database you are connecting to supports Unicode or not. Unicode is +automatically used if the server supports it. Note that the driver +only supports the UTF-8 encoding. If your database uses any other +encoding, the server must be compiled with Unicode conversion +support. +<p> Unicode support was introduced in PostgreSQL version 7.1 and it will +only work if both the server and the client library have been compiled +with multibyte support. More information about how to set up a +multibyte enabled PostgreSQL server can be found in the PostgreSQL +Administrator Guide, Chapter 5. +<p> <h4> BLOB support +</h4> +<a name="3-4-3"></a><p> Binary Large Objects are supported through the <tt>BYTEA</tt> field type in +PostgreSQL versions >= 7.1. Fields of type <tt>OID</tt> can be read, but not +written. Use the PostgreSQL command <tt>lo_import</tt> to insert binary data +into <tt>OID</tt> fields. +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-4-4"></a><p> Just installing the pq client library and the corresponding header +files is not sufficient. You have to get the PostgreSQL source +distribution and run the configure script. If you've already installed +a binary distribution you don't need to build it. The source +distribution is needed because the TQPSQL7 plugin relies on a couple of +header files that are usually not a part of the binary distribution. +<p> To make <tt>qmake</tt> find the PostgreSQL header files and shared +libraries, run <tt>qmake</tt> the following way (assuming that the +PostgreSQL sources can be found in <tt>/usr/src/psql</tt>): +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/psql +qmake -o Makefile "INCLUDEPATH+=/usr/src/psql/src/include /usr/src/psql/src/interfaces/libpq" "LIBS+=-L/usr/lib -lpq" psql.pro +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-4-5"></a><p> Unpack and build the PostgreSQL source distribution as described in +the PostgreSQL documentation. Assuming the PostgreSQL sources resides +in <tt>C:\psql</tt>, build the plugin as follows: +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\psql +qmake -o Makefile "INCLUDEPATH+=C:\psql\src\include C:\psql\src\interfaces\libpq" psql.pro +nmake +</pre> + +<p> Remember to add the path to the <tt>libpq.dll</tt> library to your PATH +environment variable so that Windows can find it. In this case that +would be <tt>C:\psql\src\interfaces\libpq\Release</tt>. If you are not using a +Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement +above. +<p> <a name="TQTDS7"></a> +<h3> TQTDS7 - Sybase Adaptive Server +</h3> +<a name="3-5"></a><p> <!-- index TQTDS7 --><a name="TQTDS7"></a> +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-5-1"></a><p> Under Unix, two libraries are available which support the TDS protocol: +<p> - FreeTDS, a free implementation of the TDS protocol +(<a href="http://www.freetds.org">http://www.freetds.org</a>). Note that FreeTDS is not yet stable, +so some functionality may not work as expected. +<p> - Sybase Open Client, available from <a href="http://www.sybase.com">http://www.sybase.com</a>. +Note for Linux users: Get the Open Client RPM from +<a href="http://linux.sybase.com">http://linux.sybase.com</a>. +<p> Regardless of which library you use, the shared object file +<tt>libsybdb.so</tt> is needed. Set the SYBASE environment variable to +point to the directory where you installed the client library and +execute <tt>qmake</tt>: +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/tds +qmake -o Makefile "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb" +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-5-2"></a><p> You can either use the DB-Library supplied by Microsoft or the Sybase +Open Client (<a href="http://www.sybase.com">http://www.sybase.com</a>). You must include <tt>NTWDBLIB.LIB</tt> to build the plugin: +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\tds +qmake -o Makefile "LIBS+=NTWDBLIB.LIB" tds.pro +nmake +</pre> + +<p> By default the Microsoft library is used on Windows, if you want to force +the use of the Sybase Open Client, you must define +<tt>Q_USE_SYBASE</tt> in <tt>%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp</tt>. +<p> <a name="TQDB2"></a> +<h3> TQDB2 - IBM DB2 Driver (v7.1 or higher) +</h3> +<a name="3-6"></a><p> <!-- index TQDB2 --><a name="TQDB2"></a> +<p> <h4> General information +</h4> +<a name="3-6-1"></a><p> The TQt DB2 plugin makes it possible to access IBM DB2 databases. It +has been tested with IBM DB2 v7.1 and 7.2. You have to install the IBM +DB2 development client library, which contains the header and library +files necessary for compiling the TQDB2 plugin. +<p> The TQDB2 driver supports prepared queries, reading/writing of Unicode +strings and reading/writing of BLOBs. +<p> We suggest using a forward-only query when calling stored procedures +in DB2 (see <a href="qsqlquery.html#setForwardOnly">TQSqlQuery::setForwardOnly</a>()). +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-6-2"></a><p> <pre> +cd $QTDIR/plugins/src/sqldrivers/db2 +qmake -o Makefile "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2" +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-6-3"></a><p> The DB2 header and include files should already be installed in the +right directories. You just have to build the plugin as follows: +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\db2 +qmake -o Makefile "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib" +nmake +</pre> + +<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> +with <tt>make</tt> in the statement above. +<p> <a name="TQSQLITE"></a> +<h3> TQSQLITE - SQLite Driver +</h3> +<a name="3-7"></a><p> <!-- index TQSQLITE --><a name="TQSQLITE"></a> +<p> The TQt SQLite plugin makes it possible to access SQLite databases. +SQLite is an in-process database, meaning that it is not necessary +to have a database server. SQLite operates on a single file, which has +to be set as database name when opening a connection. If the file does +not exist, SQLite will try to create it. SQLite also supports in-memory +databases, simply pass ":memory:" as the database name. +<p> SQLite has some restrictions regarding multiple users and +multiple transactions. If you try to read/write on a resource from different +transactions, your application might freeze until one transaction commits +or rolls back. +<p> SQLite has no support for types, every value is treated as character data. +BLOBs are therefore not supported. +<p> You can find information about SQLite on <a href="http://www.sqlite.org">http://www.sqlite.org</a>. +<p> SQLite is shipped as third party library within TQt. It can be built by +passing the following parameters to the configure script: +<tt>-plugin-sql-sqlite</tt> (as plugin) or <tt>-qt-sql-sqlite</tt> (linked +directly into the TQt library). +<p> If you don't want to use the SQLite library shipped with TQt, you can +build it manually (replace <tt>$SQLITE</tt> by the directory where SQLite +resides): +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/sqlite +qmake -o Makefile "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite" +make +</pre> + +<p> <a name="TQIBASE"></a> +<h3> TQIBASE - Borland Interbase Driver +</h3> +<a name="3-8"></a><p> <!-- index TQIBASE --><a name="TQIBASE"></a> +<p> <h4> General information +</h4> +<a name="3-8-1"></a><p> The TQt Interbase plugin makes it possible to access the Interbase and +Firebird databases. Interbase can either be used as a client/server or +without a server operating on local files. The database file must +exist before a connection can be established. +<p> Note that Interbase retquires you to specify the full path to the +database file, no matter whether it is stored locally or on another +server. +<p> <pre> + myDatabase->setHostName("MyServer"); + myDatabase->setDatabaseName("C:\\test.gdb"); +</pre> + +<p> You need the Interbase/Firebird development headers and libraries +to build this plugin. +<p> Due to the GPL, users of the TQt Open Source Edition are not allowed to link +this plugin to the commercial editions of Interbase. Please use Firebird +or the free edition of Interbase. +<p> <h4> How to build the plugin on Unix/Linux +</h4> +<a name="3-8-2"></a><p> The following assumes Interbase or Firebird is installed in +<tt>/opt/interbase</tt>: +<p> <pre> +cd $QTDIR/plugins/src/sqldrivers/ibase +qmake -o Makefile "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro +make +</pre> + +<p> <h4> How to build the plugin on Windows +</h4> +<a name="3-8-3"></a><p> The following assumes Interbase or Firebird is installed in +<tt>C:\interbase</tt>: +<p> <pre> +cd %QTDIR%\plugins\src\sqldrivers\ibase +qmake -o Makefile "INCLUDEPATH+=C:\interbase\include" ibase.pro +nmake +</pre> + +<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> +with <tt>make</tt> in the statement above. +<p> Note that <tt>C:\interbase\bin</tt> must be in the PATH. +<p> <a name="troubleshooting"></a> +<h2> Troubleshooting +</h2> +<a name="4"></a><p> You should always use client libraries that have been compiled with +the same compiler as you are using for your project. If you cannot get +a source distibution to compile the client libraries yourself, you +must make sure that the pre-compiled library is compatible with +your compiler, otherwise you will get a lot of "undefined symbols" +errors. Some compilers have tools to convert libraries, e.g. Borland +ships the tool <tt>COFF2OMF.EXE</tt> to convert libraries that have been +generated with Microsoft Visual C++. +<p> If the compilation of a plugin succeeds but it cannot be loaded, +make sure that the following retquirements are met: +<p> <ul> +<li> Ensure that you are using a shared TQt library; you cannot use the +plugins with a static build. +<li> Ensure that the environment variable <tt>QTDIR</tt> points to the right +directory. Go to the <tt>$QTDIR/plugins/sqldrivers</tt> directory and +make sure that the plugin exists in that directory. +<li> Ensure that the client libraries of the DBMS are available on the +system. On Unix, run the command <tt>ldd</tt> and pass the name of the +plugin as parameter, for example <tt>ldd libqsqlmysql.so</tt>. You will +get a warning if any of the client libraries couldn't be found. +On Windows, you can use the dependency walker of Visual Studio. +</ul> +<p> If you are experiencing problems with loading plugins, and see output +like this +<p> <pre> +TQSqlDatabase warning: TQMYSQL3 driver not loaded +TQSqlDatabase: available drivers: TQMYSQL3 +</pre> + +<p> the problem is probably that the plugin had the wrong build key. For +debugging purposes, remove the corresponding entry in the +$HOME/.qt/qt_plugins_(qtversion).rc file. +<p> The next time you try to load this plugin, it will give you a more detailed +error message. +<p> <a name="development"></a> +<h2> How to write your own database driver +</h2> +<a name="5"></a><p> <a href="qsqldatabase.html">TQSqlDatabase</a> is responsible for loading and managing database driver +plugins. When a database is added (see <a href="qsqldatabase.html#addDatabase">TQSqlDatabase::addDatabase</a>()), +the appropriate driver plugin is loaded (using <a href="qsqldriverplugin.html">TQSqlDriverPlugin</a>). +TQSqlDatabase relies on the driver plugin to provide interfaces for +<a href="qsqldriver.html">TQSqlDriver</a> and <a href="qsqlresult.html">TQSqlResult</a>. +<p> TQSqlDriver is an abstract base class which defines the functionality +of a SQL database driver. This includes functions such as +<a href="qsqldriver.html#open">TQSqlDriver::open</a>() and <a href="qsqldriver.html#close">TQSqlDriver::close</a>(). TQSqlDriver is responsible +for connecting to a database, establish the proper environment, etc. +In addition, TQSqlDriver can create <a href="qsqlquery.html">TQSqlQuery</a> objects appropriate for +the particular database API. TQSqlDatabase forwards many of its +function calls directly to TQSqlDriver which provides the concrete +implementation. +<p> TQSqlResult is an abstract base class which defines the functionality +of a SQL database query. This includes statements such as <tt>SELECT</tt>, +<tt>UPDATE</tt>, and <tt>ALTER TABLE</tt>. TQSqlResult contains functions such as +TQSqlResult::next() and TQSqlResult::value(). TQSqlResult is responsible +for sending queries to the database, returning result data, etc. +TQSqlQuery forwards many of its function calls directly to <a href="qsqlresult.html">TQSqlResult</a> +which provides the concrete implementation. +<p> <a href="qsqldriver.html">TQSqlDriver</a> and TQSqlResult are closely connected. When implementing a +TQt SQL driver, both of these classes must to be subclassed and the +abstract virtual methods in each class must be implemented. +<p> To implement a TQt SQL driver as a plugin (so that it is recognized and +loaded by the TQt library at runtime), the driver must use the +<tt>Q_EXPORT_PLUGIN</tt> macro. Read the <a href="plugins-howto.html">TQt +Plugin</a> documentation for more information on this. You can +also check out how this is done in the SQL plugins that is provided +with TQt in <tt>QTDIR/plugins/src/sqldrivers</tt> and +<tt>QTDIR/src/sql/drivers</tt>. +<p> The following code can be used as a skeleton for a SQL driver: +<p> <pre> +class TQNullResult : public <a href="qsqlresult.html">TQSqlResult</a> +{ +public: + TQNullResult( const <a href="qsqldriver.html">TQSqlDriver</a>* d ): <a href="qsqlresult.html">TQSqlResult</a>( d ) {} + ~TQNullResult() {} +protected: + <a href="qvariant.html">TQVariant</a> data( int ) { return TQVariant(); } + bool reset ( const <a href="qstring.html">TQString</a>& ) { return FALSE; } + bool fetch( int ) { return FALSE; } + bool fetchFirst() { return FALSE; } + bool fetchLast() { return FALSE; } + bool isNull( int ) { return FALSE; } + <a href="qsqlrecord.html">TQSqlRecord</a> record() { return TQSqlRecord(); } + int size() { return 0; } + int numRowsAffected() { return 0; } +}; + +class TQNullDriver : public <a href="qsqldriver.html">TQSqlDriver</a> +{ +public: + TQNullDriver(): <a href="qsqldriver.html">TQSqlDriver</a>() {} + ~TQNullDriver() {} + bool hasFeature( DriverFeature ) const { return FALSE; } + bool open( const <a href="qstring.html">TQString</a>&, + const <a href="qstring.html">TQString</a>&, + const <a href="qstring.html">TQString</a>&, + const <a href="qstring.html">TQString</a>&, + int ) { return FALSE; } + void close() {} + <a href="qsqlquery.html">TQSqlQuery</a> createQuery() const { return TQSqlQuery( new TQNullResult( this ) ); } +}; +</pre> + +<p> +<!-- eof --> +<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> |