Doc: Fix most qdoc errors in QtSql.

- Move 2 images from qtdoc.
- Add "make docs" command for qtsql
- Fix qdoc command usage errors.

Change-Id: Id2f0548d09ed8f77b2317863d443c19d1cccdd83
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>

1 files changed, 0 insertions, 830 deletions

diff --git a/doc/src/sql/sql-programming/sql-driver.qdoc b/doc/src/sql/sql-programming/sql-driver.qdoc
deleted file mode 100644
index 41995d8d38..0000000000
--- a/doc/src/sql/sql-programming/sql-driver.qdoc
+++ /dev/null
@@ -1,830 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** GNU Free Documentation License
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file.
-**
-** Other Usage
-** Alternatively, this file may be used in accordance with the terms
-** and conditions contained in a signed written agreement between you
-** and Nokia.
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-    \page sql-driver.html
-    \title SQL Database Drivers
-    \brief How to configure and install Qt SQL drivers for supported databases.
-
-    \ingroup qt-sql
-
-    The Qt SQL 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 \li Driver name \li DBMS
-    \row \li \link #QDB2 QDB2\endlink \li IBM DB2 (version 7.1 and above)
-    \row \li \link #QIBASE QIBASE\endlink \li Borland InterBase
-    \row \li \link #QMYSQL QMYSQL\endlink \li MySQL
-    \row \li \link #QOCI QOCI\endlink \li Oracle Call Interface Driver
-    \row \li \link #QODBC QODBC\endlink
-         \li Open Database Connectivity (ODBC) - Microsoft SQL Server and other
-            ODBC-compliant databases
-    \row \li \link #QPSQL QPSQL\endlink \li PostgreSQL (versions 7.3 and above)
-    \row \li \link #QSQLITE2 QSQLITE2\endlink \li SQLite version 2
-    \row \li \link #QSQLITE QSQLITE\endlink \li SQLite version 3
-    \row \li \link #QTDS QTDS\endlink \li Sybase Adaptive Server \note obsolete from Qt 4.7
-    \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.
-
-    \b{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 necessary 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.cpp 2
-
-    \b{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 for 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.
-
-    \section3 How to build the MySQL driver for MinGW users
-
-    The following steps have been used successfully for WinXP SP3. In
-    this example, Qt 4.6.2 is shown.
-
-    \list
-
-    \li Download the following components:
-    \list
-    \li \c{MinGW-5.1.6.exe}
-    \li \c{mingw-utils-0.3.tar.gz}
-    \li Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip}
-    \li \c{mysql-5.1.35-win32.msi}
-    \endlist
-
-    \li Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}.
-
-    \li Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}.
-
-    \li Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable,
-       e.g. \c{C:\MinGW\bin;}
-
-    \li Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}),
-     into, e.g. \c{C:\Qt}.
-
-    \li Add the path for the eventual Qt binary to your \c{PATH} variable,
-       e.g. \c{C:\Qt\4.6.2\bin;}.
-
-    \li Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the
-       components. Select only the headers and libraries. Install in,
-       e.g. \c{C:\MySQL\MySQL51}.
-
-    \li Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run
-       the following commands:
-       \list 
-       \li \c{reimp -d libmysql.lib}
-       \li \c{dlltool -k -d libmysql.def -l libmysql.a}
-       \endlist
-
-    \li Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands:
-    \list
-       \li \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql
-         -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt}
-       \li \c{mingw32-make sub-src}
-    \endlist
-    This step takes a long time.
-
-    \li Open the DOS prompt, go to
-        \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the
-        following command: 
-	\list
-        \li \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro}
-	\endlist
-
-    \li Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}.
-    \list
-       \li \c{libqsqlmysql4.a}
-       \li \c{libqsqlmysqld4.a}
-       \li \c{qsqlmysql4.dll}
-       \li \c{qsqlmysqld4.dll}
-    \endlist
-    To use the SDK and QtCreator directly, copy these libraries to
-    your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy
-    \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}.
-
-    \endlist
-
-    \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
-    \li \c libclntsh.so (all versions)
-    \li \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
-
-    \b{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 application 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 generally sufficient to build the
-    plugin.  For some versions of Oracle Client, you may also need to select
-    the "Call Interface (OCI)" option if it is available.
-
-    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
-
-    \b{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.
-
-    \b{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.cpp 10
-
-    \b{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 necessary 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.
-
-    \b{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 for 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{PostgreSQL MinGW/Native Windows}.
-
-    \b{Note:} This database plugin is not supported for Windows CE.
-
-    \target QTDS
-    \section2 QTDS for Sybase Adaptive Server
-
-    \note TDS is no longer used by MS Sql Server, and is superceded by
-    \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7.
-
-    \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
-    \li 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.
-
-    \li 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.
-
-    \b{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 for 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.
-
-    \b{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 pass \c{-system-sqlite} to the configure script to use sqlite
-    libraries in the operating system. Alternatively, you can build
-    it manually (replace \c $SQLITE with 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 for 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 necessary 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.cpp 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.cpp 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.cpp 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 explicitly:
-
-    \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.
-
-    \b{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
-    \li Ensure that you are using a shared Qt library; you cannot use the
-        plugins with a static build.
-    \li Ensure that the plugin is in the correct directory. You can use
-        QApplication::libraryPaths() to determine where Qt looks for plugins.
-    \li 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.
-    \li 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.cpp 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
-*/