/************************************************************************ **** ** ** Documentation for sql driver programming ** ** Copyright (C) 1992-2002 Trolltech AS. All rights reserved. ** ** This file is part of the Qt GUI Toolkit.

tenderlaSoftware and s/w Development

Dec 13, 2013 (3 years and 8 months ago)

295 views

/************************************************************************
****

**

** Documentation for sql driver programming

**

** Copyright (C) 1992
-
2002 Trolltech AS. All rights reserved.

**

** This file is part of the Qt GUI Toolkit.

**

** This file ma
y be distributed under the terms of the Q Public License

** as defined by Trolltech AS of Norway and appearing in the file

** LICENSE.QPL included in the packaging of this file.

**

** This file may be distributed and/or modified under the terms of the

** G
NU General Public License version 2 as published by the Free Software

** Foundation and appearing in the file LICENSE.GPL included in the

** packaging of this file.

**

** Licensees holding valid Qt Enterprise Edition or Qt Professional
Edition

** 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

** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOS
E.

**

** See http://www.trolltech.com/pricing.html or email sales@trolltech.com
for

** information about Qt Commercial License Agreements.

** See http://www.trolltech.com/qpl/ for QPL licensing information.

** See http://www.trolltech.com/gpl/ for GPL li
censing information.

**

** Contact info@trolltech.com if any conditions of this licensing are

** not clear to you.

**

**********************************************************************/


/*!
\
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
\
l
ink #QIBASE QIBASE
\
endlink
-

Borland Interbase Driver


\
i
\
link #QMYSQL3 QMYSQL3
\
endlink
-

MySQL Driver


\
i
\
link #QOCI8 QOCI8
\
endlink
-

Oracle Call Interface Driver, version
8 and 9


\
i
\
link #QODBC3 QODBC3
\
endlink
-

Open Database Connectivity Dr
iver


\
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 and Microsoft
SQL Server Driver


\
endlist

\
i
\
link #troubleshooti
ng 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 com
municate 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 a
nd can be used as a

model for
\
link #development writing your own drivers
\
endlink.


To build a driver plugin you need the client API that is shipped with

your Database Management System (DBMS). Most installation programs

also allow you to install "developm
ent 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
\
endli
nk
-

Borland Interbase Driver

\
i
\
link #QMYSQL3 QMYSQL3
\
endlink
-

MySQL Driver

\
i
\
link #QOCI8 QOCI8
\
endlink
-

Oracle Call Interface Driver, version 8
and 9

\
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 and Microsoft SQL
Server Driver

\
endlist


Note that not all of the plugins are shipped with the Qt Free 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 buil
t. 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 sc
ript 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/mys
ql (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. u
se
\
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 foll
ow 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 suppo
rt 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

inst
all 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/plu
gins/src/sqldrivers/mysql

qmake
-
o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=
-
L/usr/local/lib" 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 Ins
tall". 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 Q
t OCI plugin supports both Oracle 8 and Oracle 9. After

connecting to the Oracle server, the plugin will auto
-
detect the

database version and enable features accordingly.


\
section3 Unicode support


If the Oracle server supports Unicode, the OCI plugin wil
l 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 w
ith 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 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 li
bclntsh.so

\
i
\
c libclntsh.so.8.0 (Oracle 8) or
\
c libclntsh.so.9.0 (Oracle 9)

\
i
\
c libwtc8.so or
\
c libwtc9.so

\
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

t
he 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.p
ro

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


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 co
nfigure 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 Oracl
e 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 tha
t 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 ma
nager 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 whic
h 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_CH
ECK_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 Pl
ugin 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 sup
port" 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 d
irectories. 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 QPS
QL7

\
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 (libp
q) 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 drive
r 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.


\
se
ction3 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. I
f 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 multibyt
e 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 v
ersions >= 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 correspond
ing 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 r
elies 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:
\
psq
l
\
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}. I
f you are not using a

Microsoft compiler, replace
\
c nmake with
\
c make in the statement

above.


\
target QTDS7

\
section2 QTDS7
-

Sybase Adaptive Server and Microsoft SQL Server


\
keyword QTDS7


\
section3 How to build the plugin on Unix/Linux


Under Unix, t
wo 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, a
vailable 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

poin
t 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 Wi
ndows


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 Dri
ver (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 th
e 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 (s
ee 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 W
indows


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 a
ccess 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, y
our 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}.


S
QLite 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 SQ
Lite 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

witho
ut 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 Free Edition are not allowed to li
nk

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:
\
inte
rbase}:


\
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:
\
interba
se
\
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{COFF2OM
F.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; yo
u 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 th
at 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


\
target development

\
section1 How to write your own database driver


QSqlDatabase is responsible for loading and managing database driver

plugins. When a database is a
dded (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, et
c.

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

abs
tract 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

P
lugin
\
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 f
or 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


*/