Add Qt3 development HEAD version

1 files changed, 739 insertions, 0 deletions

diff --git a/doc/sql-driver.doc b/doc/sql-driver.doc
new file mode 100644
index 0000000..0c96125
--- /dev/null
+++ b/doc/sql-driver.doc
@@ -0,0 +1,739 @@
+/****************************************************************************
+**
+** Documentation for sql driver programming
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*! \page sql-driver.html
+
+\title SQL Module - Drivers
+
+\list
+\i \link #Introduction Introduction\endlink
+\i \link #building Building the drivers using configure\endlink
+\i \link #buildingmanually Building the plugins manually\endlink
+    \list
+    \i \link #QDB2 QDB2\endlink - IBM DB2 Driver (v7.1 and higher)
+    \i \link #QIBASE QIBASE\endlink - Borland Interbase Driver
+    \i \link #QMYSQL3 QMYSQL3\endlink - MySQL Driver
+    \i \link #QOCI8 QOCI8\endlink - Oracle Call Interface Driver, version 8, 9 and 10
+    \i \link #QODBC3 QODBC3\endlink - Open Database Connectivity Driver
+    \i \link #QPSQL7 QPSQL7\endlink - PostgreSQL v6.x and v7.x Driver
+    \i \link #QSQLITE QSQLITE\endlink - SQLite Driver
+    \i \link #QTDS7 QTDS7\endlink - Sybase Adaptive Server
+    \endlist
+\i \link #troubleshooting Troubleshooting\endlink
+\i \link #development How to write your own database driver\endlink
+\endlist
+
+\target Introduction
+\section1 Introduction
+
+The \link sql.html SQL Module\endlink uses driver \link
+plugins-howto.html plugins\endlink 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 Qt and other drivers
+can be added. The driver source code is supplied and can be used as a
+model for \link #development writing your own drivers\endlink.
+
+\e{Note:} 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.
+
+The drivers shipped with Qt are:
+\list
+\i \link #QDB2 QDB2\endlink - IBM DB2 Driver (v7.1 and higher)
+\i \link #QIBASE QIBASE\endlink - Borland Interbase Driver
+\i \link #QMYSQL3 QMYSQL3\endlink - MySQL Driver
+\i \link #QOCI8 QOCI8\endlink - Oracle Call Interface Driver, version 8, 9 and 10
+\i \link #QODBC3 QODBC3\endlink - Open Database Connectivity Driver
+\i \link #QPSQL7 QPSQL7\endlink - PostgreSQL v6.x and v7.x Driver
+\i \link #QSQLITE QSQLITE\endlink - SQLite Driver
+\i \link #QTDS7 QTDS7\endlink - Sybase Adaptive Server
+\endlist
+
+Note that not all of the plugins are shipped with the Qt Open Source Edition
+due to license incompatibilities with the GPL.
+
+\target building
+\section1 Building the drivers using configure
+
+The Qt 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:
+
+\code
+Possible values for <driver>: [ mysql oci odbc psql tds ]
+Auto-Detected on this system: [ mysql psql ]
+\endcode
+
+Note that on Windows, the configure script doesn't do any
+auto-detection.
+
+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 \c /usr/local/mysql (or in
+\c{C:\mysql\include} on Windows), then pass the following parameter to
+configure: \c -I/usr/local/mysql (or \c{-I C:\mysql\include} for
+Windows).
+
+On Windows the -I parameter doesn't accept spaces in
+filenames, so use the 8.3 name instead, i.e. use \c{C:\progra~1\mysql}
+instead of \c{C:\program files\mysql}.
+
+Use the \c{-qt-sql-<driver>} parameter to build the database driver
+statically into your Qt library or \c{-plugin-sql-<driver>} to build
+the driver as a plugin. Look at the sections that follow for
+additional information about required libraries.
+
+\target buildingmanually
+\section1 Building the plugins manually
+
+\target QMYSQL3
+\section2 QMYSQL3 - MySQL 3.x and MySQL 4.x
+
+\keyword QMYSQL3
+
+\section3 General information
+
+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.
+
+If you have a recent client library and connect to a
+transaction-enabled MySQL server, a call to the
+QSqlDriver::hasFeature( QSqlDriver::Transactions ) function returns
+TRUE and SQL transactions can be used.
+
+If the plugin is compiled against MySQL 4.x client libraries,
+transactions are enabled by default.
+
+You can find information about MySQL on \l http://www.mysql.com
+
+\section3 How to build the plugin on Unix/Linux
+
+You need the MySQL header files and as well as the shared library
+\c{libmysqlclient.so}. Depending on your Linux distribution you need to
+install a package which is usually called "mysql-devel".
+
+Tell \link qmake-manual.book qmake\endlink where to find the MySQL
+header files and shared libraries (here it is assumed that MySQL is
+installed in \c{/usr/local}) and run \c{make}:
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/mysql
+qmake -o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient" mysql.pro
+make
+\endcode
+
+\section3 How to build the plugin on Windows
+
+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 \c{C:\MYSQL}):
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\mysql
+qmake -o Makefile "INCLUDEPATH+=C:\MYSQL\INCLUDE" "LIBS+=C:\MYSQL\LIB\OPT\LIBMYSQL.LIB" mysql.pro
+nmake
+\endcode
+
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the statement above.
+
+\target QOCI8
+\section2 QOCI8 - Oracle Call Interface (OCI)
+
+\keyword QOCI8
+
+\section3 General information
+
+The Qt OCI plugin supports Oracle 8, 9 and 10. After
+connecting to the Oracle server, the plugin will auto-detect the
+database version and enable features accordingly.
+
+\section3 Unicode support
+
+If the Oracle server supports Unicode, the OCI plugin will use UTF-8
+encoding to communicate with the server.
+
+\section3 BLOB/LOB support
+
+Binary Large Objects (BLOBs) can be read and written, but be aware
+that this process may require a lot of memory.
+
+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 QSqlQuery::setForwardOnly()).
+
+Inserting BLOBs should be done using either a prepared query where the
+BLOBs are bound to placeholders, or QSqlCursor which uses a prepared
+query to do this internally (see $QTDIR/examples/sql/blob).
+
+\section3 Know problems 
+
+When a query is in forward only mode a call to QSqlQuery::last() will
+position the query on the last record and return TRUE, but subsequent 
+calls to QSqlQuery::value() will only return NULLs.
+
+\section3 How to build the plugin on Unix/Linux
+
+All files required to build driver should ship with the standard Oracle
+Client install.
+
+Oracle library files required to build driver:
+
+\list
+\i \c libclntsh.so (all versions)
+\i \c libwtc8.so (only Oracle 8) or \c libwtc9.so (only Oracle 9)
+\endlist
+
+Tell \c qmake where to find the Oracle header files and shared
+libraries (it is assumed that the variable \c $ORACLE_HOME points to
+the directory where Oracle is installed) and run make:
+
+If you are using Oracle 8:
+\code
+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
+\endcode
+
+For Oracle version 9:
+\code
+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
+\endcode
+
+For Oracle version 10:
+\code
+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
+\endcode
+
+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 QOCI8 driver is compiled as a plugin. To work
+around this problem, either compile the driver into the Qt libray
+itself, or configure Qt 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".
+
+\section3 How to build the plugin on Windows
+
+Choosing the option "Programmer" in the Oracle Client Installer from
+the Oracle Client Installation CD is sufficient to build the plugin.
+
+Build the plugin as follows (here it is assumed that Oracle Client is
+installed in \c{C:\oracle}):
+
+\code
+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
+\endcode
+
+When you run your application you will also need to add the \c oci.dll
+path to your \c PATH environment variable:
+
+\code
+set PATH=%PATH%;c:\oracle\bin
+\endcode
+
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the statement above.
+
+\target QODBC3
+\section2 QODBC3 - Open Database Connectivity (ODBC)
+
+\keyword QODBC3
+
+\section3 General information
+
+ODBC is a general interface that allows you to connect to multiple
+DBMS using a common interface. The QODBC3 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 QODBC3 plugin
+then allows you to use these data sources in your Qt project.
+
+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 required to have an ODBC driver manager installed, otherwise the
+QODBC3 plugin will not work.
+
+Be aware that when connecting to an ODBC datasource you must pass in
+the name of the ODBC datasource to the QSqlDatabase::setDatabaseName()
+function: not the actual database name.
+
+The QODBC3 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 QODBC3 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 \c{#define
+ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at
+your own risk!
+
+If you experience very slow access of the ODBC datasource, make sure
+that ODBC call tracing is turned off in the ODBC datasource manager.
+
+\section3 Unicode support
+
+The QODBC3 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.
+
+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.
+
+\section3 How to build the plugin on Unix/Linux
+
+It is recommended that you use unixODBC. You can find the latest
+version and ODBC drivers at \l http://www.unixodbc.org.
+You need the unixODBC header files and shared libraries.
+
+Tell \c qmake where to find the unixODBC header files and shared
+libraries (here it is assumed that unixODBC is installed in
+\c{/usr/local/unixODBC}) and run \c{make}:
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/odbc
+qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc"
+make
+\endcode
+
+\section3 How to build the plugin on Windows
+
+The ODBC header and include files should already be installed in the
+right directories. You just have to build the plugin as follows:
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\odbc
+qmake -o Makefile odbc.pro
+nmake
+\endcode
+
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the statement above.
+
+\target QPSQL7
+\section2 QPSQL7 - PostgreSQL version 6 and 7
+
+\keyword QPSQL7
+
+\section3 General information
+
+The QPSQL7 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.
+
+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.
+
+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.
+
+For more information about PostgreSQL visit \l http://www.postgresql.org.
+
+\section3 Unicode support
+
+The QPSQL7 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.
+
+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.
+
+\section3 BLOB support
+
+Binary Large Objects are supported through the \c BYTEA field type in
+PostgreSQL versions >= 7.1. Fields of type \c OID can be read, but not
+written. Use the PostgreSQL command \c lo_import to insert binary data
+into \c OID fields.
+
+\section3 How to build the plugin on Unix/Linux
+
+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 QPSQL7 plugin relies on a couple of
+header files that are usually not a part of the binary distribution.
+
+To make \c qmake find the PostgreSQL header files and shared
+libraries, run \c qmake the following way (assuming that the
+PostgreSQL sources can be found in \c{/usr/src/psql}):
+
+\code
+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
+\endcode
+
+\section3 How to build the plugin on Windows
+
+Unpack and build the PostgreSQL source distribution as described in
+the PostgreSQL documentation. Assuming the PostgreSQL sources resides
+in \c{C:\psql}, build the plugin as follows:
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\psql
+qmake -o Makefile "INCLUDEPATH+=C:\psql\src\include C:\psql\src\interfaces\libpq" psql.pro
+nmake
+\endcode
+
+Remember to add the path to the \c{libpq.dll} library to your PATH
+environment variable so that Windows can find it. In this case that
+would be \c{C:\psql\src\interfaces\libpq\Release}. If you are not using a
+Microsoft compiler, replace \c nmake with \c make in the statement
+above.
+
+\target QTDS7
+\section2 QTDS7 - Sybase Adaptive Server
+
+\keyword QTDS7
+
+\section3 How to build the plugin on Unix/Linux
+
+Under Unix, two libraries are available which support the TDS protocol:
+
+- FreeTDS, a free implementation of the TDS protocol
+  (\l{http://www.freetds.org}). Note that FreeTDS is not yet stable,
+  so some functionality may not work as expected.
+
+- Sybase Open Client, available from \l{http://www.sybase.com}.
+  Note for Linux users: Get the Open Client RPM from
+  \l{http://linux.sybase.com}.
+
+Regardless of which library you use, the shared object file
+\c{libsybdb.so} is needed. Set the SYBASE environment variable to
+point to the directory where you installed the client library and
+execute \c{qmake}:
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/tds
+qmake -o Makefile "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb"
+make
+\endcode
+
+\section3 How to build the plugin on Windows
+
+You can either use the DB-Library supplied by Microsoft or the Sybase
+Open Client (\l{http://www.sybase.com}). You must include \c
+NTWDBLIB.LIB to build the plugin:
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\tds
+qmake -o Makefile "LIBS+=NTWDBLIB.LIB" tds.pro
+nmake
+\endcode
+
+By default the Microsoft library is used on Windows, if you want to force
+the use of the Sybase Open Client, you must define
+\c Q_USE_SYBASE in \c{%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp}.
+
+\target QDB2
+\section2 QDB2 - IBM DB2 Driver (v7.1 or higher)
+
+\keyword QDB2
+
+\section3 General information
+
+The Qt 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 QDB2 plugin.
+
+The QDB2 driver supports prepared queries, reading/writing of Unicode
+strings and reading/writing of BLOBs.
+
+We suggest using a forward-only query when calling stored procedures
+in DB2 (see QSqlQuery::setForwardOnly()).
+
+\section3 How to build the plugin on Unix/Linux
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/db2
+qmake -o Makefile "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2"
+make
+\endcode
+
+\section3 How to build the plugin on Windows
+
+The DB2 header and include files should already be installed in the
+right directories. You just have to build the plugin as follows:
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\db2
+qmake -o Makefile "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib"
+nmake
+\endcode
+
+If you are not using a Microsoft compiler, replace \c nmake
+with \c make in the statement above.
+
+\target QSQLITE
+\section2 QSQLITE - SQLite Driver
+
+\keyword QSQLITE
+
+The Qt 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.
+
+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.
+
+SQLite has no support for types, every value is treated as character data.
+BLOBs are therefore not supported.
+
+You can find information about SQLite on \l{http://www.sqlite.org}.
+
+SQLite is shipped as third party library within Qt. It can be built by
+passing the following parameters to the configure script:
+\c{-plugin-sql-sqlite} (as plugin) or \c{-qt-sql-sqlite} (linked
+directly into the Qt library).
+
+If you don't want to use the SQLite library shipped with Qt, you can
+build it manually (replace \c $SQLITE by the directory where SQLite
+resides):
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/sqlite
+qmake -o Makefile "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite"
+make
+\endcode
+
+\target QIBASE
+\section2 QIBASE - Borland Interbase Driver
+
+\keyword QIBASE
+
+\section3 General information
+
+The Qt 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.
+
+Note that Interbase requires you to specify the full path to the
+database file, no matter whether it is stored locally or on another
+server. 
+
+\code
+    myDatabase->setHostName("MyServer");
+    myDatabase->setDatabaseName("C:\\test.gdb");
+\endcode
+
+You need the Interbase/Firebird development headers and libraries
+to build this plugin.
+
+Due to the GPL, users of the Qt 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.
+
+\section3 How to build the plugin on Unix/Linux
+
+The following assumes Interbase or Firebird is installed in
+\c{/opt/interbase}:
+
+\code
+cd $QTDIR/plugins/src/sqldrivers/ibase
+qmake -o Makefile "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro
+make
+\endcode
+
+\section3 How to build the plugin on Windows
+
+The following assumes Interbase or Firebird is installed in
+\c{C:\interbase}:
+
+\code
+cd %QTDIR%\plugins\src\sqldrivers\ibase
+qmake -o Makefile "INCLUDEPATH+=C:\interbase\include" ibase.pro
+nmake
+\endcode
+
+If you are not using a Microsoft compiler, replace \c nmake
+with \c make in the statement above.
+
+Note that \c{C:\interbase\bin} must be in the PATH.
+
+\target troubleshooting
+\section1 Troubleshooting
+
+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 \c{COFF2OMF.EXE} to convert libraries that have been
+generated with Microsoft Visual C++.
+
+If the compilation of a plugin succeeds but it cannot be loaded,
+make sure that the following requirements are met:
+
+\list
+\i Ensure that you are using a shared Qt library; you cannot use the
+    plugins with a static build.
+\i Ensure that the environment variable \c QTDIR points to the right
+    directory. Go to the \c{$QTDIR/plugins/sqldrivers} directory and
+    make sure that the plugin exists in that directory.
+\i Ensure that the client libraries of the DBMS are available on the 
+    system. On Unix, run the command \c{ldd} and pass the name of the
+    plugin as parameter, for example \c{ldd libqsqlmysql.so}. 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.
+\endlist
+
+If you are experiencing problems with loading plugins, and see output
+like this
+
+\code
+QSqlDatabase warning: QMYSQL3 driver not loaded
+QSqlDatabase: available drivers: QMYSQL3
+\endcode
+
+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.
+
+The next time you try to load this plugin, it will give you a more detailed
+error message.
+
+\target development
+\section1 How to write your own database driver
+
+QSqlDatabase is responsible for loading and managing database driver
+plugins. When a database is added (see QSqlDatabase::addDatabase()),
+the appropriate driver plugin is loaded (using QSqlDriverPlugin).
+QSqlDatabase relies on the driver plugin to provide interfaces for
+QSqlDriver and QSqlResult.
+
+QSqlDriver is an abstract base class which defines the functionality
+of a SQL database driver. This includes functions such as
+QSqlDriver::open() and QSqlDriver::close(). QSqlDriver is responsible
+for connecting to a database, establish the proper environment, etc.
+In addition, QSqlDriver can create QSqlQuery objects appropriate for
+the particular database API. QSqlDatabase forwards many of its
+function calls directly to QSqlDriver which provides the concrete
+implementation.
+
+QSqlResult is an abstract base class which defines the functionality
+of a SQL database query. This includes statements such as \c{SELECT},
+\c{UPDATE}, and \c{ALTER TABLE}. QSqlResult contains functions such as
+QSqlResult::next() and QSqlResult::value(). QSqlResult is responsible
+for sending queries to the database, returning result data, etc.
+QSqlQuery forwards many of its function calls directly to QSqlResult
+which provides the concrete implementation.
+
+QSqlDriver and QSqlResult are closely connected. When implementing a
+Qt SQL driver, both of these classes must to be subclassed and the
+abstract virtual methods in each class must be implemented. 
+
+To implement a Qt SQL driver as a plugin (so that it is recognized and
+loaded by the Qt library at runtime), the driver must use the
+\c Q_EXPORT_PLUGIN macro. Read the \link plugins-howto.html Qt
+Plugin\endlink documentation for more information on this. You can
+also check out how this is done in the SQL plugins that is provided
+with Qt in \c{QTDIR/plugins/src/sqldrivers} and
+\c{QTDIR/src/sql/drivers}.
+
+The following code can be used as a skeleton for a SQL driver:
+
+\code
+class QNullResult : public QSqlResult
+{
+public:
+    QNullResult( const QSqlDriver* d ): QSqlResult( d ) {}
+    ~QNullResult() {}
+protected:
+    QVariant    data( int ) { return QVariant(); }
+    bool        reset ( const QString& ) { return FALSE; }
+    bool        fetch( int ) { return FALSE; }
+    bool        fetchFirst() { return FALSE; }
+    bool        fetchLast() { return FALSE; }
+    bool        isNull( int ) { return FALSE; }
+    QSqlRecord  record() { return QSqlRecord(); }
+    int         size()  { return 0; }
+    int         numRowsAffected() { return 0; }
+};
+
+class QNullDriver : public QSqlDriver
+{
+public:
+    QNullDriver(): QSqlDriver() {}
+    ~QNullDriver() {}
+    bool    hasFeature( DriverFeature ) const { return FALSE; }
+    bool    open( const QString&,
+                  const QString&,
+                  const QString&,
+                  const QString&,
+                  int ) { return FALSE; }
+    void    close() {}
+    QSqlQuery createQuery() const { return QSqlQuery( new QNullResult( this ) ); }
+};
+\endcode
+
+*/