MCL/sf/mw/qt: comparison doc/src/sql-programming/sql-driver.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page sql-driver.html
+\title SQL Database Drivers
+\brief How to configure and install QtSql drivers for supported databases.
+\ingroup best-practices
+The QtSql module uses driver \l{How to Create Qt
+Plugins}{plugins} to communicate with the different database
+APIs. Since Qt's 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
+\l{#development}{writing your own drivers}.
+\tableofcontents
+\section1 Supported Databases
+The table below lists the drivers included with Qt. Due to
+license incompatibilities with the GPL, not all of the plugins
+are provided with Open Source Versions of Qt.
+\table
+\header \o Driver name \o DBMS
+\row \o \link #QDB2 QDB2\endlink \o IBM DB2 (version 7.1 and above)
+\row \o \link #QIBASE QIBASE\endlink \o Borland InterBase
+\row \o \link #QMYSQL QMYSQL\endlink \o MySQL
+\row \o \link #QOCI QOCI\endlink \o Oracle Call Interface Driver
+\row \o \link #QODBC QODBC\endlink
+\o Open Database Connectivity (ODBC) - Microsoft SQL Server and other
+ODBC-compliant databases
+\row \o \link #QPSQL QPSQL\endlink \o PostgreSQL (versions 7.3 and above)
+\row \o \link #QSQLITE2 QSQLITE2\endlink \o SQLite version 2
+\row \o \link #QSQLITE QSQLITE\endlink \o SQLite version 3
+\row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server
+\endtable
+SQLite is the in-process database system with the best test coverage
+and support on all platforms. Oracle via OCI, and PostreSQL and MySQL
+through either ODBC or a native driver are well-tested on Windows and
+Linux. The completeness of the support for other systems depends on the
+availability and quality of client libraries.
+\bold{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.
+\target building
+\section1 Building the Drivers Using Configure
+On Unix and Mac OS X, the Qt \c configure script tries to
+automatically detect the available client libraries on your
+machine. Run \c{configure -help} to see what drivers can be
+built. You should get an output similar to this:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 0
+The \c 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 \c -I and \c -L
+command-line options. 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 \c -I parameter doesn't accept spaces in
+filenames, so use the 8.3 name instead; for example, 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 QMYSQL
+\section2 QMYSQL for MySQL 4 and higher
+\section3 QMYSQL Stored Procedure Support
+MySQL 5 introduces stored procedure support at the SQL level, but no
+API to control IN, OUT and INOUT parameters. Therefore, parameters
+have to be set and read using SQL commands instead of QSqlQuery::bindValue().
+Example stored procedure:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 1
+Source code to access the OUT values:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 2
+\bold{Note:} \c{@outval1} and \c{@outval2} are variables local to the current
+connection and will not be affected by queries sent from another host
+or connection.
+\section3 Embedded MySQL Server
+The MySQL embedded server is a drop-in replacement for the normal
+client library. With the embedded MySQL server, a MySQL server is
+not required to use MySQL functionality.
+To use the embedded MySQL server, simply link the Qt plugin to \c
+libmysqld instead of libmysqlclient. This can be done by replacing
+\c -lmysqlclient_r by \c -lmysqld in the \c qmake command in the
+section below.
+Please refer to the MySQL documentation, chapter "libmysqld, the Embedded
+MySQL Server Library" for more information about the MySQL embedded server.
+\section3 How to Build the QMYSQL Plugin on Unix and Mac OS X
+You need the MySQL header files and as well as the shared library
+\c{libmysqlclient.so}. Depending on your Linux distribution you may
+need to install a package which is usually called "mysql-devel".
+Tell \l qmake 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}:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 3
+After installing Qt, as described in the \l{Installing Qt on X11
+Platforms} document, you also need to install the plugin in the
+standard location:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 4
+\section3 How to Build the QMYSQL Plugin on Windows
+You need to get the MySQL installation files. Run \c 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}):
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 5
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the line above.
+\note This database plugin is not supported for Windows CE.
+\note Including \c{"-o Makefile"} as an argument to \l qmake to
+tell it where to build the makefile can cause the plugin to be
+built in release mode only. If you are expecting a debug version
+to be built as well, don't use the \c{"-o Makefile"} option.
+\target QOCI
+\section2 QOCI for the Oracle Call Interface (OCI)
+\section3 General Information about the OCI plugin
+The Qt OCI plugin supports Oracle 9i, 10g and higher. After
+connecting to the Oracle server, the plugin will auto-detect the
+database version and enable features accordingly.
+It's possible to connect to a Oracle database without a tnsnames.ora file.
+This requires that the database SID is passed to the driver as the database
+name and that a hostname is given.
+\section3 OCI User Authentication
+The Qt OCI plugin supports authentication using
+external credentials (OCI_CRED_EXT). Usually, this means that the database
+server will use the user authentication provided by the operating system
+instead of its own authentication mechanism.
+Leave the username and password empty when opening a connection with
+QSqlDatabase to use the external credentials authentication.
+\section3 OCI BLOB/LOB Support
+Binary Large Objects (BLOBs) can be read and written, but be aware
+that this process may require a lot of memory. You should 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 QSqlTableModel, which uses a prepared
+query to do this internally.
+\section3 How to Build the OCI Plugin on Unix and Mac OS X
+For Oracle 10g, all you need is the "Instant Client Package - Basic" and
+"Instant Client Package - SDK". For Oracle prior to 10g, you require
+the standard Oracle client and the SDK packages.
+Oracle library files required to build the driver:
+\list
+\i \c libclntsh.so (all versions)
+\i \c libwtc9.so (only Oracle 9)
+\endlist
+Tell \c qmake where to find the Oracle header files and shared
+libraries and run make:
+For Oracle version 9:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 6
+For Oracle version 10, we assume that you installed the RPM packages of the
+Instant Client Package SDK (you need to adjust the version number accordingly):
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 7
+\bold{Note:} If you are using the Oracle Instant Client package,
+you will need to set LD_LIBRARY_PATH when building the OCI SQL plugin
+and when running an applicaiton that uses the OCI SQL plugin. You can
+avoid this requirement by setting and RPATH and listing all of the
+libraries to link to. Here is an example:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 32
+If you wish to build the OCI plugin manually with this method the procedure looks like this:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 33
+\section3 How to Build the OCI 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}):
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 8
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the line above.
+When you run your application you will also need to add the \c oci.dll
+path to your \c PATH environment variable:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 9
+\bold{Note:} This database plugin is not supported for Windows CE.
+\target QODBC
+\section2 QODBC for Open Database Connectivity (ODBC)
+\section3 General Information about the ODBC plugin
+ODBC is a general interface that allows you to connect to multiple
+DBMSs using a common interface. The QODBC 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 QODBC plugin
+then allows you to use these data sources in your Qt applications.
+\bold{Note:} You should use native drivers in preference to the ODBC
+driver where they are available. ODBC support can be used as a fallback
+for compliant databases if no native drivers are available.
+On Windows 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
+QODBC 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 rather than the actual database name.
+The QODBC 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 QODBC 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 behavior, you can remove the \c{#define
+ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at
+your own risk!
+By default, Qt instructs the ODBC driver to behave as an ODBC 2.x
+driver. However, for some \e{driver-manager/ODBC 3.x-driver}
+combinations (e.g., \e{unixODBC/MaxDB ODBC}), telling the ODBC
+driver to behave as a 2.x driver can cause the driver plugin to
+have unexpected behavior. To avoid this problem, instruct the ODBC
+driver to behave as a 3.x driver by
+\l{QSqlDatabase::setConnectOptions()} {setting the connect option}
+\c{"SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3"} before you
+\l{QSqlDatabase::open()} {open your database connection}. Note
+that this will affect multiple aspects of ODBC driver behavior,
+e.g., the SQLSTATEs.  Before setting this connect option, consult
+your ODBC documentation about behavior differences you can expect.
+If you experience very slow access of the ODBC datasource, make sure
+that ODBC call tracing is turned off in the ODBC datasource manager.
+Some drivers don't support scrollable cursors. In that case case only
+queries in forwardOnly mode can be used successfully.
+\section3 ODBC Stored Procedure Support
+With Microsoft SQL Server the result set returned by a stored
+procedure that uses the return statement, or returns multiple result
+sets, will be accessible only if you set the query's forward only
+mode to \e forward using \l QSqlQuery::setForwardOnly().
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 10
+\bold{Note:} The value returned by the stored procedure's return statement
+is discarded.
+\section3 ODBC Unicode Support
+The QODBC 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 must also support Unicode.
+Some driver managers and drivers don't support UNICODE. To use the
+QODBC plugin with such drivers it has to be compiled with the
+Q_ODBC_VERSION_2 defined.
+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 ODBC Plugin on Unix and Mac OS X
+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}:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 11
+\section3 How to Build the ODBC 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:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 12
+If you are not using a Microsoft compiler, replace \c nmake with \c
+make in the line above.
+\bold{Note:} This database plugin is not officially supported for Windows CE.
+\target QPSQL
+\section2 QPSQL for PostgreSQL (Version 7.3 and Above)
+\section3 General Information about the QPSQL driver
+The QPSQL driver supports version 7.3 and higher of the PostgreSQL server.
+We recommend that you use a client library from version 7.3.15, 7.4.13,
+8.0.8, 8.1.4 or more recent as these versions contain security fixes, and
+as the QPSQL driver might not build with older versions of the client
+library depending on your platform.
+For more information about PostgreSQL visit \l http://www.postgresql.org.
+\section3 QPSQL Unicode Support
+The QPSQL 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 QPSQL BLOB Support
+Binary Large Objects are supported through the \c BYTEA field type in
+PostgreSQL server versions >= 7.1.
+\section3 How to Build the QPSQL Plugin on Unix and Mac OS X
+You need the PostgreSQL client library and headers installed.
+To make \c qmake find the PostgreSQL header files and shared
+libraries, run \c qmake the following way (assuming that the
+PostgreSQL client is installed in \c{/usr}):
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 13
+After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document,
+you also need to install the plugin in the standard location:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 14
+\section3 How to Build the QPSQL Plugin on Windows
+Install the appropriate PostgreSQL developer libraries for your
+compiler. Assuming that PostgreSQL was installed in \c{C:\psql},
+build the plugin as follows:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 15
+Users of MinGW may wish to consult the following online document:
+\l{Compiling PostgreSQL On Native Win32 FAQ}.
+\bold{Note:} This database plugin is not supported for Windows CE.
+\target QTDS
+\section2 QTDS for Sybase Adaptive Server
+\section3 General Information about QTDS
+It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the
+Sybase client library. Refer to the Sybase documentation for information on how to set up
+a Sybase client configuration file to enable connections to databases on non-default ports.
+\section3 How to Build the QTDS Plugin on Unix and Mac OS X
+Under Unix, two libraries are available which support the TDS protocol:
+\list
+\i 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.
+\i 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}.
+\endlist
+Regardless of which library you use, the shared object file
+\c{libsybdb.so} is needed. Set the \c SYBASE environment variable to
+point to the directory where you installed the client library and
+execute \c{qmake}:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 16
+\section3 How to Build the QDTS 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:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 17
+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}. If you
+are not using a Microsoft compiler, replace \c nmake with \c make in
+the line above.
+\bold{Note:} This database plugin is not supported for Windows CE.
+\target QDB2
+\section2 QDB2 for IBM DB2 (Version 7.1 and Above)
+\section3 General Information about QDB2
+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 must 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 QDB2 Plugin on Unix and Mac OS X
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 18
+After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document,
+you also need to install the plugin in the standard location:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 19
+\section3 How to Build the QDB2 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:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 20
+If you are not using a Microsoft compiler, replace \c nmake
+with \c make in the line above.
+\bold{Note:} This database plugin is not supported for Windows CE.
+\target QSQLITE2
+\section2 QSQLITE2 for SQLite Version 2
+The Qt SQLite 2 plugin is offered for compatibility. Whenever
+possible, use the \l{#QSQLITE}{version 3 plugin} instead. The
+build instructions for version 3 apply to version 2 as well.
+\target QSQLITE
+\section2 QSQLITE for SQLite (Version 3 and Above)
+\section3 General Information about QSQLITE
+The Qt SQLite plugin makes it possible to access SQLite
+databases. SQLite is an in-process database, which means that it
+is not necessary to have a database server. SQLite operates on a
+single file, which must be set as the 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. The Qt SQLite driver will retry to write to a locked resource
+until it runs into a timeout (see \c{QSQLITE_BUSY_TIMEOUT}
+at QSqlDatabase::setConnectOptions()).
+In SQLite any column, with the exception of an INTEGER PRIMARY KEY column,
+may be used to store any type of value. For instance, a column declared as
+INTEGER may contain an integer value in one row and a text value in the
+next. This is due to SQLite associating the type of a value with the value
+itself rather than with the column it is stored in. A consequence of this
+is that the type returned by QSqlField::type() only indicates the field's
+recommended type. No assumption of the actual type should be made from
+this and the type of the individual values should be checked.
+The driver is locked for updates while a select is executed. This
+may cause problems when using QSqlTableModel because Qt's item views
+fetch data as needed (with QSqlQuery::fetchMore() in the case of
+QSqlTableModel).
+You can find information about SQLite on \l{http://www.sqlite.org}.
+\section3 How to Build the QSQLITE Plugin
+SQLite version 3 is included as a third-party library within Qt.
+It can be built by passing the following parameters to the
+configure script: \c{-plugin-sql-sqlite} (build as a plugin) or
+\c{-qt-sql-sqlite} (linked directly into the Qt library).
+If you don't want to use the SQLite library included with Qt, you
+can build it manually (replace \c $SQLITE by the directory where
+SQLite resides):
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 21
+After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document,
+you also need to install the plugin in the standard location:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 22
+On Windows:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 23
+\section3 QSQLITE File Format Compatibility
+SQLite minor releases sometimes break file format forward compatibility.
+For example, SQLite 3.3 can read database files created with SQLite 3.2,
+but databases created with SQLite 3.3 cannot be read by SQLite 3.2.
+Please refer to the SQLite documentation and change logs for information about
+file format compatibility between versions.
+Qt minor releases usually follow the SQLite minor releases, while Qt patch releases
+follow SQLite patch releases. Patch releases are therefore both backward and forward
+compatible.
+To force SQLite to use a specific file format, it is neccessary to build and
+ship your own database plugin with your own SQLite library as illustrated above.
+Some versions of SQLite can be forced to write a specific file format by setting
+the \c{SQLITE_DEFAULT_FILE_FORMAT} define when building SQLite.
+\target QIBASE
+\section2 QIBASE for Borland InterBase
+\section3 General Information about QIBASE
+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 in which case it operates on local files. The
+database file must exist before a connection can be established. Firebird
+must be used with a server configuration.
+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.
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 24
+You need the InterBase/Firebird development headers and libraries
+to build this plugin.
+Due to license incompatibilities with 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 QIBASE Unicode Support and Text Encoding
+By default the driver connects to the database using UNICODE_FSS. This can
+be overridden by setting the ISC_DPB_LC_CTYPE parameter with
+QSqlDatabase::setConnectOptions() before opening the connection.
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 25
+If Qt doesn't support the given text encoding the driver will issue a
+warning message and connect to the database using UNICODE_FSS.
+Note that if the text encoding set when connecting to the database is
+not the same as in the database, problems with transliteration might arise.
+\section3 QIBASE Stored procedures
+InterBase/Firebird return OUT values as result set, so when calling stored
+procedure, only IN values need to be bound via QSqlQuery::bindValue(). The
+RETURN/OUT values can be retrieved via QSqlQuery::value(). Example:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 26
+\section3 How to Build the QIBASE Plugin on Unix and Mac OS X
+The following assumes InterBase or Firebird is installed in
+\c{/opt/interbase}:
+If you are using InterBase:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 27
+If you are using Firebird, the Firebird library has to be set explicitly:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 28
+\section3 How to Build the QIBASE Plugin on Windows
+The following assumes InterBase or Firebird is installed in
+\c{C:\interbase}:
+If you are using InterBase:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 29
+If you are using Firebird, the Firebird library has to be set explicitely:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 30
+If you are not using a Microsoft compiler, replace \c nmake
+with \c make in the line above.
+Note that \c{C:\interbase\bin} must be in the \c PATH.
+\bold{Note:} This database plugin is not supported for Windows CE.
+\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 plugin is in the correct directory. You can use
+QApplication::libraryPaths() to determine where Qt looks for plugins.
+\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 Visual Studio's dependency walker.
+\i Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose
+debug output when loading plugins.
+\endlist
+Make sure you have followed the guide to \l{Deploying Plugins}.
+If you experience plugin load problems and see output like this:
+\snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 31
+the problem is usually that the plugin had the wrong \l{Deploying
+Plugins#The Build Key}{build key}. This might require removing an
+entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}.
+\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} \c{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 Q_EXPORT_PLUGIN2() macro. Read \l{How to Create Qt
+Plugins} for more information on this. You can also check out how
+this is done in the SQL plugins that are provided with Qt in
+\c{QTDIR/src/plugins/sqldrivers} and \c{QTDIR/src/sql/drivers}.
+The following code can be used as a skeleton for a SQL driver:
+\snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 47
+\codeline
+\snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 48
+*/