Linux/UNIX ODBC

This document contains all the information you need to get started accessing ODBC data sources on Linux and UNIX platforms. The document provides background information about ODBC and its implementation on Linux and UNIX, describes the unixODBC ODBC Driver Manager in detail and lists some commonly used Linux/UNIX applications and interfaces that support ODBC.

Contents

Introduction

This document was written to help people understand ODBC on Linux and UNIX.

What is ODBC?

Open Database Connectivity (ODBC) is a standard software API specification for using database management systems (DBMS). ODBC is independent of programming language, database system and operating system.

ODBC was created by the SQL Access Group and first released in September, 1992. ODBC is based on the Call Level Interface (CLI) specifications from SQL, X/Open (now part of The Open Group), and the ISO/IEC.

The ODBC API is a library of ODBC functions that let ODBC-enabled applications connect to any database for which an ODBC driver is available, execute SQL statements, and retrieve results.

The goal of ODBC is to make it possible to access any data from any application, regardless of which database management system (DBMS) is handling the data. ODBC achieves this by inserting a middle layer called a database driver between an application and the DBMS. This layer translates the application's data queries into commands that the DBMS understands.

ODBC Versions

There are (to date) 4 significant versions of ODBC:

VersionDescription
1.0 (c1993) The first version of ODBC. Only a few ODBC 1.0 applications and drivers still exist (on Windows) and none we know of on Linux.
2.0 (c1994)

The second version of ODBC. Small reorganisation of API (e.g. new SQLBindParameter replacing SQLSetParam) core, level 1 and 2 conformance changes, new data types.

There are still a number of ODBC 2.0 applications and drivers around. On Linux, most ODBC drivers are ODBC 3 and the few that are still ODBC 2.0 are generally moving to 3.

There was also an ODBC 2.5.

3.0 (c1995). ODBC 3.0 introduced a large number of new APIs and ODBC descriptor handles. Most ODBC drivers on Linux are now ODBC 3.0 and many applications are also 3.0.
3.5x (c1997). Introduction of Unicode.

Components of ODBC

A basic implementation of ODBC on Linux is comprised of:

However, ODBC also includes:

What is the state of Linux ODBC?

ODBC on Linux is in a healthy state today with many applications and interfaces having ODBC support and a wealth of available ODBC drivers.

The general goal of ODBC for Linux was to:

  1. Replicate the ODBC functionality available on Windows so that application authors could write ODBC applications that worked on Windows and Linux/UNIX. This required the writing of an ODBC Driver Manager.

    For the most part this has been achieved in unixODBC which provides a full ODBC 3.5 compatible driver manager including the full ODBC API, all the driver utility functions, installer, deinstaller and configuration library for ODBC drivers, a GUI administrator, an odbctest utility, the full development headers, a non-GUI administration utility (odbcinst) and a command line ODBC application to test data sources and issue SQL to the underlying ODBC driver.

  2. Make available ODBC drivers on Linux. There are now a large number of commercial and Open Source drivers available for Linux/UNIX.

ODBC Driver Managers

There are two open source ODBC driver managers for UNIX (unixODBC and iODBC). This document describes the unixODBC Driver Manager as it is the one included with most (if not all) Linux distributions and some UNIX distributions.

What does the ODBC driver manager do?

The ODBC driver manager is the interface between an ODBC application and the ODBC driver. The driver manager principally provides the ODBC API so ODBC applications may link with a single shared object and be able to talk to a range of ODBC drivers. e.g. an application on Linux links with libodbc.so (the main driver manager shared object) without having to know at link time which ODBC driver it is going to be using. At run time the application provides a connection string which defines the ODBC data source it wants to connect to and this in turn defines the ODBC driver which will handle this data source. The driver manager loads the requested ODBC driver (with dlopen(3)) and passes all ODBC API calls on to the driver. In this way, an ODBC application can be built and distributed without knowing which ODBC driver it will be using.

However, this is a rather simplistic description of what the driver manager does. The ODBC driver manager also:

ODBC Drivers

An ODBC driver exports the ODBC API such that an ODBC application can communicate with a DBMS. Sometimes the ODBC driver is single tier where the driver accesses the files directly and sometimes the the driver is multi-tier where it communicates with the DBMS via another layer.

There are a large number of commercial and open source ODBC drivers available for Linux/UNIX. Easysoft have available a number of commercial ODBC drivers available for Linux including:

In addition, you can find Open Source ODBC drivers for MySQL and Postgres.

ODBC Bridges and Gateways

An ODBC bridge or gateway provides an ODBC API at one end of the bridge/gateway and a different API at the other end. The most popular API people want to bridge to/from ODBC is JDBC.

ODBC-JDBC Gateways

An ODBC-JDBC gateway allows an application that uses the ODBC API to talk to a JDBC Driver:

application <-> ODBC API <-> JDBC API <-> database

An example of this is the Easysoft ODBC-JDBC Gateway.

You would typically use an ODBC-JDBC gateway if you had an existing application that used the ODBC API to access databases, and wanted to use that application to access a database for which there was no ODBC driver available, but a JDBC driver was available.

The ODBC calls your application makes are converted to JDBC calls and passed to the JDBC driver. As far as the JDBC driver is concerned, the ODBC driver is just another JDBC application. As far as the application is concerned, it is using a normal ODBC driver.

The ODBC-JDBC gateway is installed on the same machine as your application, and depending on how the gateway was written you:

The first of these configurations is the most popular, probably because:

  1. It avoids any proprietary interfaces.
  2. Java is available for most platforms.
  3. Most JDBC drivers are capable of communication over a network anyway.
  4. It avoids any extra services/processes.
  5. Nothing has to be installed on the server/database machine.

What may influence your use of an ODBC-JDBC gateway is:

Some compromises are nearly always inherent in translating the ODBC API to the JDBC API, but these are usually less than you might think, and a good gateway will be very transparent. A common misconception is that adding a bridge between your ODBC application and JDBC driver will introduce a lot of overhead, but you might be surprised at how quick a good gateway can be.

JDBC-ODBC Bridges

A JDBC-ODBC bridge is the opposite of an ODBC-JDBC one. A JDBC-ODBC bridge allows a Java application using JDBC to access an ODBC driver:

Java application <-> JDBC <-> ODBC driver <-> database

An example of this is the Easysoft JDBC-ODBC Bridge.

You would typically use a JDBC-ODBC bridge if you had an existing Java application that used the JDBC API, and wanted to access a database for which an ODBC driver was available, but a JDBC driver was not.

For instance, you may want to access an MS Access database from Java, but there is no Microsoft JDBC driver for MS Access.

The JDBC calls your application makes are converted to ODBC calls and passed to the ODBC driver. As far as the Java application is concerned, it is using a normal JDBC driver. As far as the database is concerned, it is being accessed via the normal ODBC driver.

Because ODBC drivers are always written in C (the ODBC API is a C interface), they are built for particular operating systems and architectures. As a result, the most flexible configuration is one where a server process is installed on the machine containing the ODBC driver, and the JDBC side of the bridge communicates with it over the network from the client side where the JDBC driver is installed. Obviously, at the Java application end, Java will already be in use, and so use of the JDBC client end driver at this side of the bridge is not a problem (in fact, some bridges offer zero installation JDBC access).

JDBC is inherently Unicode, and so a good JDBC-ODBC bridge will convert JDBC calls into the ODBC API wide functions (SQLxxxW) and request SQL_WCHAR characters from the database where they are available.

What may influence your use of a JDBC-ODBC Bridge is:

The unixODBC ODBC Driver Manager

What is unixODBC?

unixODBC is a project created to provide ODBC on non-Windows platforms. It includes:

unixODBC is distributed with RedHat, Debian, Slackware, Ubuntu, Suse, CentOS and most of the other Linux distributions and is available as source code (see Obtaining unixODBC).

unixODBC is a mature Open Source product having made its first beta release in in January 1999, version 1.0.0 in May 1999 and there have been many release since. At the time of writing (July 2012) the current version of unixODBC is 2.3.1.

ODBC-ODBC Bridges

ODBC-ODBC Bridges are mostly used to access an ODBC driver on one architecture from another where it is not available e.g., you have got an ODBC Driver for database X on Windows, but your application needs to run on Linux where the X ODBC driver is not available. However, since 64-bit Windows was released, a new problem has arisen; you have got a 32-bit application, which you cannot rebuild, but works on 64-bit Windows and the 32-bit ODBC driver is no longer available for that version of Windows or you need to write a new 64-bit application but only have access to a 32-bit ODBC Driver. ODBC-ODBC Bridges like the Easysoft ODBC-ODBC Bridge can solve these problems.

Obtaining, Configuring and Building unixODBC

Obtaining unixODBC

unixODBC's web site is at www.unixodbc.org. unixODBC also has a sourceforge project at sourceforge.net/projects/unixodbc. You can download RPMs and the source from either site and you can find the latest development release at ftp.unixodbc.org/pub/unixODBC.

Note that all Easysoft ODBC drivers for Linux/UNIX come with unixODBC prebuilt.

Configuring and building unixODBC

The unixODBC source distribution is a gzipped tar file. Uncompress it and then untar the resultant file e.g.

gunzip unixODBC-2.2.12.tar.gz
tar -xvf unixODBC-2.2.12.tar

Change into the resultant directory and run:

./configure --help

which will list all the options configure accepts. The principle ones you need to pay attention to are:

OptionDescription
--prefix This defines where you want to install unixODBC. If you do not specify this it will default to /usr/local. If you do not want unixODBC all under a single directory you can use other configure options like --bindir, --sbindir etc for finer control.
--sysconfdir This defines where you want unixODBC configuration files to be stored. This defaults to <prefix>/etc. The configuration files affected are odbcinst.ini (where ODBC drivers are defined), the system odbc.ini (where system data sources are defined) and ODBCDataSources (where system file DSNs are stored).
--enable-gui The default is "yes" if QT is found. If you want to build the GUI ODBC Administrator, odbctest and DataManager set this to "yes" (e.g. --enable-gui=yes). You will need QT libraries and header files to build the GUI components (see later). You should probably also set --with-x.

NOTE In unixODBC 2.3.0, the default for --enable-drivers was changed to "no" and the GUI components were moved into a new project.

--enable-threads The default is "yes" if thread-support is found on your machine. All modern Linuxes will have pthreads support in glibc so it is probably best to leave this to default.
--enable-readline The default is "yes" if libreadline and its headers are found on your machine. This principally only affects unixODBC isql program. If readline support is found then you can edit text entered at the SQL prompt in isql.
--enable-drivers The default is "yes". When enabled this will build all the ODBC drivers included with unixODBC. This includes MySQL, Postgres, MiniSQL and a text file driver.
--enable-iconv This defaults to "yes" if libiconv and its header files are found on your machine. If you build with iconv and access then unixODBC can do Unicode translations.

If you enable the GUI components then configure will try and find QT, its libraries and header files. If you have installed QT in a single place you can provide a hint to configure by setting the environment QTDIR (or --with-qt-dir) to point to the top of the tree where QT is installed. If QT libraries and header files are installed in separate trees and not the default places like /usr/lib and /usr/include you can use --with-qt-includes=DIR and --with-qt-libraries=DIR.

NOTE In unixODBC 2.3.0, the default for --enable-drivers was changed to "no" and the GUI components were moved into a new project.

NOTE For information about configuring and building unixODBC on 64-bit platforms, see 64-bit ODBC.

Where are ODBC drivers defined?

In unixODBC ODBC drivers are defined in the odbcinst.ini file. The location of this file is a configure-time variable defined with --sysconfdir but is always the file odbcinst.ini in the --sysconfdir defined path. If unixODBC is already installed you can use unixODBC's odbcinst program to locate the odbcinst.ini file used to defined drivers:

$ odbcinst -j
unixODBC 2.3.1
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/auser/.odbc.ini
SQLULEN Size.......: 4
SQLLEN Size........: 4
SQLSETPOSIROW Size.: 2

In this example drivers are defined in /etc/odbcinst.ini.

You can tell unixODBC to look in a different path (to that which it was configured) for the odbcinst.ini file and SYSTEM DSN file (odbc.ini) by defining and exporting the ODBCSYSINI environment variable. You can tell unixODBC to look in a different file for driver definitions (odbcinst.ini, by default) by defining and exporting the ODBCINSTINI environment variable.

If you are using the GUI ODBC Administrator (ODBCConfig) you can view data sources in User and System DSN tabs:

Linux ODBC Drivers

How do you create an ODBC data source

There are three main ways of defining an ODBC data source:

  1. If your driver has a setup library (see your odbcinst.ini file) then you may be able to define a SYSTEM or USER data source using the unixODBC ODBC administrator. Start the ODBC administrator using ODBCConfig, select USER or SYSTEM, add, select the ODBC driver and click OK. You should be presented with a dialogue specific to the ODBC driver - fill in the fields and click on OK. e.g. with the Easysoft ODBC-ODBC Bridge driver you get a tabbed dialogue like:

    Linux ODBC OOB DSN

  2. Edit the SYSTEM or USER DSN ini file ( odbc.ini or .odbc.ini) and add a data source using the syntax:
        [ODBC_datasource_name}
        Driver = driver_name
        Description = description_of_data_source
        attribute1 = value
        .
        .
        attributen = value
      
    where, ODBC_datasource_name is the name you want to assign to this data source, Driver is assigned the name of the driver (see odbcinst.ini file for installed drivers and "attributen = value" is the name of an attribute and its value that the ODBC driver needs. e.g. for the Easysoft ODBC-ODBC Bridge you might define
    [my_datasource]
    Driver = OOB
    Description = description_of_data_source
    ServerPort = myoobserver:8888
    TargetDSN = mytargetdsn
    LogonUser = server_username
    LogonAuth = password_for_LogonUser
    
    You need to check with the ODBC Driver you are using to see what attributes you need to define, but at a minimum you must specify the Driver attribute and it is always advisable to include the Description attribute.
  3. Create a FileDSN. ODBCConfig does not yet handle file DSNs properly but you can still use them if they are manually created or produced using the SAVEFILE connection attribute to SQLDriverConnect. A file DSN definition is basically the same as above (in the user and system ini files) except it is a file containing a single data source and the data source is always named ODBC. e.g.
    [ODBC]
    Driver = OOB
    Description = description_of_data_source
    ServerPort = myoobserver:8888
    TargetDSN = mytargetdsn
    LogonUser = server_username
    LogonAuth = password_for_LogonUser
    

    Note that File DSNs may be stored anywhere as they are referenced by including in the connection string FileDSN=/path_to_file_dsn.

You can list user and system data sources with:

$ /usr/local/easysoft/unixODBC/bin/odbcinst  -q -s
[sqlserver]
[ODBCNINETWO]
[aix]
[bugs]
[ib7]
[ODBC_JDBC_SAMPLE]
[postgres]
[EASYSOFT_JOINENGINE1]
[SYBASEA]

How do you install an ODBC driver?

There are three methods of installing an ODBC driver under unixODBC:

  1. You write a program which links with libodbcinst.so and calls SQLInstallDriver.
  2. You create an ODBC driver template file and run odbcinst. e.g.
        odbcinst -f template_file -d -i
      
    In this case your template file must contain the Driver and Description attributes at a minimum and optionally the Setup attribute e.g.
      [DRIVER_NAME]
      Description = description of the ODBC driver
      Driver = path_to_odbc_driver_shared_object
      Setup = path_to_driver_setup_shared_object
      
  3. You directly edit your odbcinst.ini file and add the driver definition.

In the odbcinst.ini each driver definition begins with the driver name in square brackets. The driver name is followed by Driver and Setup attributes where Driver is the path to the ODBC driver shared object (exporting the ODBC API) and Setup is the path to the ODBC driver setup library (exporting the ConfigDriver and ConfigDSN APIs used to install/remove the driver and create/edit/delete data sources). Few ODBC drivers for UNIX have a setup dialogue.

You can list all installed ODBC drivers with:

$ /usr/local/easysoft/unixODBC/bin/odbcinst  -s -q
[sqlserver]
[ODBCNINETWO]
[aix]
[bugs]
[ib7]
[ODBC_JDBC_SAMPLE]
[postgres]
[EASYSOFT_JOINENGINE1]
[SYBASEA]

What are System and User data sources

SYSTEM data sources are those accessible by anyone on the machine which defines the data source. Typically, these are defined in some system defined location that everyone has read access to (e.g. /etc/odbc.ini). USER data sources are defined in a users home directory in the file (.odbc.ini) and are only readable by that user (dependent on the value of your umask at the time the file is created).

Whether you can access USER DSNs depends on the ODBC driver you are using and whether it is built with unixODBC support.

How your driver locates SYSTEM and USER DSNs depends on whether it was built to use SQLGetPrivateProfileString in unixODBC or not. Drivers which know about the unixODBC driver manager use the ODBC API SQLGetPrivateProfileString() to obtain DSN attributes. If a driver does this it does not matter where SYSTEM or USER DSNs are defined, as unixODBC knows where to look for them and what the format of the odbc.ini (or .odbc.ini) file is. If your driver does not have built in support which uses the SQLGetPrivateProfileString then:

  1. It will not know where your ODBC data sources are defined.
  2. It may not be capable of parsing the odbc.ini file format.

ODBC Drivers supporting the unixODBC Driver Manager link against libodbcinst.so and include odbcinstext.h. If you are an ODBC driver writer we strongly recommend you install unixODBC and build your driver with:

-I /path/include \
  -L/path/lib -l odbcinst

and include odbcinst.h.

Some Server applications that use ODBC do not support user credentials or change to the specified user so they run in the context that the server application was started in. In this case they cannot access USER DSNs since they are not running as the user in which the user DSN is defined. A common error with Apache is to define a user DSN in the .odbc.ini file in user FRED’s account then run Apache under the nobody account. Bridges like the Easysoft ODBC-ODBC Bridge require a logonuser and logonauth which require the server application to change to the specified user and hence they have access to that user's DSNs. If you are using an application which runs as a specific user and you want to use USER DSNs then you need to define the USER DSN in that user's account or use a SYSTEM DSN.

Where are ODBC data sources defined?

ODBC data sources are defined in two different files depending on whether they are a USER DSN or a SYSTEM DSN (see What are System And User data sources). USER DSNs are defined in the .odbc.ini file in the current user's HOME directory. SYSTEM DSNs are defined is some single path defined at compile time for unixODBC with --sysconfdir. You can locate this directory after unixODBC has been built with:

$ odbcinst -j
unixODBC 2.3.1
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/auser/.odbc.ini
SQLULEN Size.......: 4
SQLLEN Size........: 4
SQLSETPOSIROW Size.: 2

In this case USER DSNs are defined in /home/auser/.odbc.ini because the user running the odbcinst command was auser and his home account is /home/auser.

You can tell unixODBC to look in a different file for SYSTEM DSNs by defining and exporting the ODBCINI environment variable. Include the file name and path when setting this variable.

If you are using the GUI ODBC Administrator (ODBCConfig) you can view data sources in User and System DSN tabs:

Linux ODBC System DSNs

What does a data source look like?

Generally speaking a DSN is comprised of a name and a list of attribute/value pairs. Usually these attributes are passed to the ODBC API SQLDriverConnect as a semicolon delimited string such as:

DSN=mydsn;attribute1=value;attribute2=value;attributen=value;

What a specific ODBC driver needs is dependent on that ODBC driver. Each ODBC driver should support a number of ODBC connection attributes which are passed to the ODBC API SQLDriverConnect. Any attributes which are not defined in the ODBC connection string may be looked up in any DSN defined in the ODBC connection string. e.g. Suppose your ODBC application calls SQLDriverConnect with the connection string "DSN=fred;" but it needs the name of a server where the database is located. Since the connection string does not contain the attribute this driver needs to locate the server (e.g. Server=xxxxx) the ODBC driver can look up the DSN "fred" and see if this defines a "Server" attribute.

Any driver supporting unixODBC will use SQLGetPrivateProfileString to lookup any attributes it needs using the DSN name as a key. Generally your ODBC application either passes all the attribute=value pairs in the connection string or it lets you choose a DSN from a list then calls SQLDriverConnect("DSN=mydsn;") and then the ODBC driver looks up the additional attributes in the DSN definition.

Each ODBC driver should define the attributes which it needs to connect to a particular database. e.g. For the Easysoft ODBC-0DBC Bridge each DSN must define at a minimum, TargetDSN, LogonUser, LogonAuth and ServerPort where ServerPort is the name of the server where the ODBC-ODBC Bridge Server is running and the port it is listening on, TargetDSN is the name of the SYSTEM DSN on the server machine you want to connect to and LogonUser/LogonAuth are a valid username/password to logon to the server machine.

For unixODBC, SYSTEM DSNs are defined in an odbc.ini in the system defined path and USER DSNs are defined the the current user's home directory (in a file called .odbc.ini). The format of this file is:

[DSN_NAME]
Driver = driver_name_defined_in_odbcinst.ini
attribute1 = value
attribute2 = value
.
.
attributen = value

Testing DSN connections

Once you have installed your ODBC driver and defined an ODBC data source you can test connection to it via unixODBC's isql utility. The format of isql's command line for testing connection is:

isql -v DSN_NAME db_username db_password

You should use the -v option because this causes isql to output any ODBC diagnostics if the connection fails. The db_username and db_password are optional but you must supply them if your ODBC driver requires a database username and password to login to the DBMS.

If isql successfully connects to your DSN it should display a banner and a "SQL>" prompt:

bash-2.05$ isql -v my_dsn username password
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
SQL>

If it fails to connect (and you specified -v) then any ODBC diagnostic from the ODBC driver explaining why it could not connect should be displayed.

$isql -v mysql_db username password
[unixODBC][MySQL][ODBC 3.51 Driver]
Access denied for user 'username'@'xxx.easysoft.local' (using password: YES)
[ISQL]ERROR: Could not SQLConnect

What this ODBC diagnostic says depends on the ODBC Driver and you should look up it in the documentation for your ODBC Driver.

Some errors may be reported by the unixODBC driver manager itself (if for instance it could not connect to the ODBC driver). An example is

$isql -v dsn_does_not_exist username
 password
[unixODBC][Driver Manager]
Data source name not found, and no default driver specified
[ISQL]ERROR: Could not SQLConnect

In this case unixODBC could not locate the DSN "dsn_does_not_exist" and hence could not load the ODBC driver. Common reasons for this error are:

See Also

isql beyond testing connections

NOTE: Unless you are running isql in batch mode we strongly suggest you run isql with the -v (verbose) argument because that will show ODBC diagnostics on failed commands and other useful information. Any examples in this section assume isql was run with the -v argument unless stipulated otherwise.

In Testing DSN connections we saw how isql can be used to test connection to your data sources. isql can do quite a lot more. Once connected to you data source you are provided with an SQL prompt at which you can:

Anything entered at the SQL prompt in isql which is not a recognised isql command (see above) is passed to the ODBC driver via the ODBC API's SQLPrepare then SQLExecute. If the SQLExecute fails (or returns SQL_SUCCESS_WITH_INFO), isql will use SQLError to obtain ODBC diagnostics. e.g.:

SQL> select * from table_does_not_exist
[S0002][unixODBC][Microsoft][ODBC SQL Server Driver][SQL Server]
Invalid object name 'table_does_not_exist'.
[37000][unixODBC][Microsoft][ODBC SQL Server Driver][SQL Server]
Statement(s) could not be prepared.
[ISQL]ERROR: Could not SQLExecute
SQL> 

If the SQLExecute for your SQL succeeds then isql will use SQLNumResultCols to ascertain if the SQL returned a result-set (e.g. you executed a select). If a result-set is found, it will be fetched and displayed using the any settings from the command line settings -d or -x (how to delimit columns), -w (output in HTML table), -c (column names on first row if -d/-x used) and -m (limit column display width).

After any SQL succeeds, isql will call SQLRowCount to see how many rows were affected. You should note that many ODBC drivers return -1 if the SQL was a result-set generating statement, otherwise this should be the number of rows inserted, deleted or updated.

As each command or SQL statement enterered at the prompt and terminated with a newline will be passed to the ODBC driver you can run isql with stdin redirected to a file containing SQL. e.g. Suppose you created the file myfile.sql containing:

create table test (a integer)
insert into test values (1)
insert into test values (2)

then you can use:

isql -v mydsn dbuser dbauth < myfile.sql

to execute multiple SQL commands in one go. Obviously, you can also redirect stdout.

Tracing ODBC calls

The unixODBC driver manager can write a trace of all ODBC calls made to a file. This can be a very useful debugging aid but it should be remembered that tracing will slow your application down. You enable tracing using one of the following methods:

Be careful when running ODBC applications as different users and tracing because most users will set their umask such that other users cannot write to newly created files. If user A enables tracing and connects to the driver manager the trace file will be created and then when user B uses the driver manager it is likely nothing is traced because user B does not have write permission to the trace file.

Trace files generally contain a log of every entry and exit to each ODBC API. e.g.

[ODBC][9155][SQLAllocHandle.c][345]
                Entry:
                        Handle Type = 2
                        Input Handle = 0x80899d0
[ODBC][9155][SQLAllocHandle.c][463]
                Exit:[SQL_SUCCESS]
                        Output Handle = 0x8089f60

The general form is:

[ODBC][Process ID][C source containing the ODBC API][source line number]
      Entry:
         argument 1 = value
         argument 2 = value
         argument n = value
[ODBC][Process ID][C source containing the ODBC API][source line number]
      Exit: [ODBC status]
            output argument 1 = value
            output argument 2 = value
            output argument n = value

With this tracing you can see:

What does the cursor library do?

The cursor library is included in unixODBC for applications which require cursors (more than forward-only cursors) but the driver does not support any cursor other than forward-only. Whether the cursor library is used depends on:

The cursor library is a shared object called libodbccr.so which will exist in the lib subdirectory of wherever you set --prefix to when you build/configure unixODBC. When the cursor library is in use the normal ODBC entry points to the ODBC driver are replaced with entry points in the cursor library which then go on to call the same entry points in the ODBC driver but they apply extra processing to imitate the required cursor.

Setting ODBC driver environment variables automatically

Unicode in unixODBC

The original ODBC specification was mostly written by Microsoft and handed over to X/Open. However, since then Microsoft have made a number of changes to their ODBC specification, including adding some support for Unicode.

Unicode in ODBC is supported by the so-called wide APIs (because every supported ODBC API has an equivalent one ending in 'W') and some new types like SQL_WCHAR. The wide APIs accept and return UCS-2 encoded data (although more later on UTF-16). There is also a define in the C headers (UNICODE) that determines if any call to the ODBC API SQLxxx ends up calling SQLxxxA (ANSI version) or SQLxxxW (wide version) - but do not define it unless you are sure all the data you will pass to the ODBC APIs is really UCS-2.

Supported Unicode APIs

There is an equivalent wide API for almost every ANSI ODBC API. e.g., SQLPrepareA expects 8-bit characters and SQLPrepareW expects UCS-2. Notable omissions are SQLGetData, because SQLGetData accepts a type you want the data returned as (e.g., you can ask for SQL_CHAR or SQL_WCHAR). You can find a list of wide APIs in sqlucode.h that comes with your ODBC Driver Manager.

Mismatched applications and drivers

Not all ODBC drivers will support Unicode and not all applications will support Unicode, so the unixODBC Driver Manager has some work to do when there is a mismatch. In general, ODBC Driver Managers will always call the wide APIs in a supporting ODBC driver (the Microsoft one does this) even if the application is ANSI and hence the Driver Manager needs to convert the characters to UCS-2 first. A similar issue arises with Unicode data returned by the ODBC driver to an ANSI application, only in this case, data is effectively lost if it does not fit in 8 bits. However, unixODBC attempts to side step that work and if it spots the application is ANSI it will use the ANSI ODBC APIs in the ODBC driver. If you truly want to always use the wide APIs in a supporting ODBC driver (e.g., your application is Unicode ready), you must tell unixODBC by calling SQLDriverConnectW.

NOTE unixODBC does not get involved with returned bound column data or sent bound parameters. If you bind an SQL_WCHAR, it should be returned as wide characters and you should set parameters as wide characters.

But UCS-2 is not Unicode

Correct, UCS-2 is an encoding that supports up to 64K characters (up to 0xFFFF) and Unicode contains a lot more than that. More recent versions of some ODBC drivers and databases support UTF-16 and hence surrogate pairs.

For instance, MS SQL Server 2012 introduces a new collation sequence suffix (_SC) and it supports surrogate pairs.

However, as always, be careful when using SQLGetData (see later).

But Unicode on UNIX is stored in wchar_t

wchar_t can be 2 bytes or 4 bytes on various UNIX platforms and is totally incompatible with ODBC, which uses UCS-2 and UTF-16.

UTF-8 and ODBC

Some ODBC drivers support the sending and receiving of character data encoded in UTF-8 and hence all of the Unicode character set can be supported. However, there is potential problem with SQLGetData (see later). Usually, a driver has some flag to enable this and you continue to use the ANSI APIs and not the wide APIs.

e.g., the Easysoft ODBC-SQL Server Driver has a flag called ConvToUTF. When enabled, UTF-8 encoded data sent to MS SQL Server is converted to UCS-2 and returned data is converted from UCS-2 to UTF-8. This flag is enabled in the following example, in which isql, an ANSI application that uses the ANSI APIs, retrieves some Unicode data from a SQL Server database:

$ /usr/local/easysoft/unixODBC/bin/isql.sh -v MY_SQL_SERVER_DSN
SQL> select ncharcol from my_table
+------------+
| ncharcol   |
+------------+
| Űńĩćōđě    | 
+------------+

The SQLGetData problem

When you call SQLGetData, you specify the type you would like the data returned as and a buffer to accept the data. Obviously, if you are asking for Unicode data you had better make sure that your buffer length (in bytes) is divisible by 2.

Some of the ODBC APIs are declared in terms of characters and some in terms of bytes and some we are not sure about (e.g. SQLGetData).

SQLGetData returns in StrLen_or_IndPtr the length or indicator value, which is not defined as bytes or characters so, if too small, a buffer is passed to SQLGetData for the column. In this case, does the StrLen_or_IndPtr contain the number of characters required in the buffer to retrieve the whole column or the number of bytes? Some applications call SQLGetData with a zero length buffer simply to find our how big a buffer to pass for real by looking at StrLen_or_IndPtr.

Also, the ODBC specification says if you call SQLGetData with a buffer that is too small, it will fill the buffer and you need to call SQLGetData again to get the remaining data.

So what if you are using a driver that supposedly does UTF-8 and you pass SQLGetData a buffer of n bytes, but n+1 bytes were required and the last character in the buffer requires 2 bytes in UTF-8 encoding? Does the driver part fill the buffer leaving one whole UTF-8 character off or does it fill the buffer thus leaving you with 1/2 a character? If it does not fill the buffer then it contradicts the ODBC specification and if it does you cannot use your data until you have retrieved all of it.

Drivers supporting UTF-8 seem to handle this in different ways, but the only safe way for an application to deal with it is to ensure you pass a big enough buffer in the first place (in which case you might as well bind the column).

Incidentally, the same issue exists with UTF-16 and asking for SQL_WCHAR characters.

Other unixODBC Utilities

The unixODBC distribution includes a few binaries, which can prove useful:

odbcinst

The odbcinst binary can be used to perform a number of unixODBC administration functions or query the unixODBC configuration. If you run odbcinst without any arguments it will list all the things you can do with it. Here are a few examples:

odbcinst -j will print the unixODBC configuration which will list:

odbcinst -q -d will list all the ODBC drivers that have registered with unixODBC.

odbcinst -q -s will list all the ODBC data sources you have defined.

There are other options to install DSNs and ODBC drivers.

odbc_config

This utility is only in more recent unixODBCs.

You can use odbc_config to find out how unixODBC was built and also some of the information odbcinst provides. This is usually most useful for people building applications and drivers against unixODBC e.g., Perl's DBD::ODBC module can use it to find the cflags required to build its ODBC XS code. Some examples are:

$ odbc_config --odbcini # show the SYSTEM DSN ini file
   /etc/odbc.ini
$ odbc_config --odbcinstini # show the driver ini file
  /etc/odbcinst.ini
$ odbc_config --prefix # shows what --prefix was set to when configured
  /usr/
$ odbc_config --libs # lib line to add to linker
  -L//usr/lib -lodbc

ODBC support in applications and interfaces

ODBC abstraction libraries

libodbc++

C

Perl

PHP

Python

Rexx/SQL

Ruby

QT

OpenOffice.org

StarOffice

DG4ODBC

hsODBC

FreeRADIUS

IBM UniVerse/UniData

Lotus Notes/Domino

Micro Focus COBOL

mnoGoSearch

OpenLDAP

Snort

Delphi and Kylix

Appendix A: unixODBC ini files format

unixODBC uses 3 ini files:

In all files, the following rules apply:

  1. a '#' or ';' character at the start of a line means the rest of the line is a comment and will be ignored. NOTE, '#' or ';' characters anywhere else on a line other than the first characters will be interpreted literally.
  2. sections of an ini file begin with a string in square brackets [,].

    In the odbcinst.ini file the section defining a driver begins with the driver name in [ ].

    In the odbc.ini file the DSN name is placed in [ ].

    In a file DSN the data source name is always ODBC, (in square brackets) and there can only be one in each file.

  3. when specifying attributes

    e.g. attribute_1 = value_1

    the white space either side of the assignment operator ('=') is ignored but white space elsewhere is taken literally

    e.g. attribute_1 = attribute 1 value

    assigns the value "attribute 1 value" to attribute_1.

  4. In general you should avoid using braces {, } unless your driver documentation tells you otherwise as an existing issue with unixODBC stops anything after a line containing {} from being seen.

Appendix B: unixODBC installed files

If you build unixODBC yourself from the source distribution and restrict the build to unixODBC itself and not any of the included drivers (--enable-drivers=no) the following files are installed:

NOTE: not all UNIX platforms use ".so" as the shared object file extension. Some versions of HP-UX use ".sl" and AIX uses archives (".a") containing shared objects using the ".o" extension.

Appendix C: Resources

Article Feedback

* Did this content help you?
* Please select one option based on your first choice:

(* Required Fields)