Using ODBC in QT
================

Contents:
  o ODBC support under QT
  o Building QT with ODBC support
  o Defining/Testing Datasources
  o Example QT code to use ODBC
  o Using the Easysoft ODBC drivers with QT

ODBC support under QT
=====================

Our example assumes you have built (or are using) QT with ODBC support
provided by the unixODBC driver manager. There are other ODBC Driver
Managers for UNIX but Easysoft recommend unixODBC.

Building QT with ODBC support
=============================

You can use ODBC under QT in two ways:

1. as a plugin
2. with ODBC built into libqt

If you build QT yourself you will need to use:

o -plugin-sql-odbc to build ODBC support as a plugin
o -qt-sql-odbc to build ODBC support into libqt

In either case if you use unixODBC as distributed with Easysoft ODBC
drivers you will need to tell QT where to locate the unixODBC header
files and the unixODBC libraries. You do this with the -I and -L arguments
to QT's configure:

build as plugin:

./configure -I /usr/local/easysoft/unixODBC/include
  -L /usr/local/easysoft/unixODBC/lib
 -plugin-sql-odbc

to build ODBC support directly into libqt:

./configure -I /usr/local/easysoft/unixODBC/include
  -L /usr/local/easysoft/unixODBC/lib
  -qt-sql-odbc

Defining/Testing Datasources
============================

Before you run any QT code which uses any of the QSql classes you should
create an ODBC datasource and test it works with unixODBC's isql.
There are two types of ODBC datasource:

o SYSTEM datasources are available to everyone
o USER datasources are only available to the current user (what id says).

You can use odbcinst -j to locate the files where unixODBC stores system
and user datasources. e.g. say you were logged in as martin:

$ /usr/local/easysoft/unixODBC/bin/odbcinst -j
unixODBC 2.2.12
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
USER DATA SOURCES..: /home/martin/.odbc.ini

says we are using unixODBC 2.2.12, the definitions for ODBC drivers
are stored in /etc/odbcinst.ini, system datasources are defined in
/etc/odbc.ini and user datasources are defined in
/home/martin/.odbc.ini (for user martin).

In this example, user datasources defined in /home/martin/.odbc.ini
are only available to the user martin (i.e. any programs run as
user martin will consult /home/martin/.odbc.ini for user datasources
but another file if run as user fred).

When you install Easysoft ODBC drivers they will typically create a
system datasource during the installation which is either based on
information you provided during the install or is a fixed datasource
available at easysoft.com. e.g. if you install the Easysoft ODBC-ODBC
Bridge the installation will typically install a "demo" datasource
which points to an OOB Server at easysoft.com and optionally a
datasource pointing to your installed OOB Server.

Once this datasource is defined in either the user or system
ini file you can test it with isql e.g.

/usr/local/easysoft/bin/isql -v <dsn_name> <username> <password>

e.g. for OOB's demo datasource you might use:

/usr/local/easysoft/unixODBC/bin/isql -v demo demo easysoft

The username and password arguments are a valid username and password
for the database you are connecting to.

Example QT code to use ODBC
===========================

QT contains a number of classes which you can use to run queries,
insert data etc into databases for which you have an ODBC driver
(see the QT documentation and "SQL" under modules).

This example uses a simple QT program to list the tables in a database,
pick the first table listed, show the names of the fields and then
display all the rows in the first table. The example deliberately
does not use any of the GUI classes to concentrate on the Sql*
classes in QT.

The code for the example program is in example.cpp. To build this you 
need to:

Create a project file example.pro containing:

SOURCES = example.cpp
HEADERS =
TARGET = example
CONFIG = qt debug

then run:

qmake -o Makefile example.pro

This creates a Makefile which you can process with make i.e.
just type make. This will compile the example.cpp code into a
binary called example. You can then run the example program
from the shell using:

./example

The example code is heavily commented. You should refer to the
QT documentation for more detailed explanations of the QSql classes.

Using the Easysoft ODBC drivers with QT
=======================================

Easysoft have tested our ODBC drivers with QT 3 and 4.

You can use the Easysoft ODBC-ODBC Bridge with QT to access any remote
ODBC driver e.g. access MS SQL Server from any UNIX platform.

You can use our Oracle, Sybase, Interbase, ISAM, System Z,
Tetra and Firebird ODBC drivers to access those databases.

All Easysoft ODBC drivers come with unixODBC and create datasources in
/etc/odbc.ini during installation. You can use these datasources with
QT. By default all Easysoft products install unixODBC in
/usr/local/easysoft/unixODBC and you will find isql and odbcinst in
the bin subdirectory.
