Chapter 4. Preparing ODBC

Table of Contents
Background and Terminology
Connection attributes
DSN-less configuration
ODBC-only configuration
ODBC-combined configuration
Troubleshooting ODBC connections

Background and Terminology

To connect to a database server, a library such as FreeTDS needs some information about the connection. By server, which IP address and port is do you mean? Which user is requesting the connection, and what authentication does he offer? Every database library needs a way to capture and convey that information.

ODBC was conceived as a general interface definition, not tied to any particular database or access library. For that reason, ODBC also needs to know which driver to use with a given server.

The original ODBC solution to this conundrum employed the odbc.ini file. odbc.ini stored information about a server, known generically as a Data Source Name (DSN). ODBC applications connected to the server by calling the function SQLConnect(DSN, UID, PWD), where DSN is the Data Source Name entry in odbc.ini, UID is the username, and PWD the password. Any and all information about the DSN was kept in odbc.ini. And all was right with the world.

The ODBC 3.0 specification introduced a new function: SQLDriverConnect. The connection attributes are provided as a single argument, a string of concatenated name-value pairs. SQLDriverConnect subsumed the functionality of SQLConnect, in that the name-value pair string allowed the caller to pass — in addition the the original DSN, UID, and PWD — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to SQLDriverConnect, obviating the need for odbc.ini. This led to the use of the so-called DSN-less configuration, a setup with no odbc.ini.

But FreeTDS did not start out as an ODBC driver (remember DB-Library and CT-Library), and has always had its own way to store server properties: freetds.conf. When Brian added the FreeTDS ODBC driver, he began by supporting the old SQLConnect, using odbc.ini to describe the DSN. That choice complied with the expectations of the Driver Managers, and minimized the amount of duplicated information in the configuration files. But it can be a little confusing, too, because odbc.ini in effect points to freetds.conf. We call this configuration ODBC-combined, because it supports all three FreeTDS libraries.

As progress on the the FreeTDS ODBC library progressed, the driver was made able to read the connection attributes directly from odbc.ini, rather than leaning on freetds.conf. For installations that don't need DB-Library and CT-Library, this ODBC-only setup is simpler.

More recently, SQLDriverConnect was added to FreeTDS. As described above, this function allows the application to specify connection attributes with reference to either, or neither, configuration file. It's your choice. In making that choice, keep the following terms clear in your mind:

Important FreeTDS ODBC terms


specifies the [servername] entry in freetds.conf.


specifies the real server i.e., the TCP/IP name of the machine hosting the database server.

DSN, Driver

In your connection string, you can decide to use a DSN entry in odbc.ini using the DSN attribute, or to specify the driver you want with the Driver attribute.

In sum, FreeTDS supports three ODBC choices:

ODBC configuration choices


No connection information is specified in odbc.ini. Advantageous if you're using more of FreeTDS than just the ODBC driver.


All connection information is specified in odbc.ini, without the need for freetds.conf. This is the "traditional" ODBC setup.


Connection information maintained in freetds.conf. odbc.ini contains DSN entries that refer to servernames in freetds.conf.

TipLibrary or Driver?

What's a library and what's a driver? Technically, they're the same thing: bodies of subroutines whose names are exported to a linker (static or runtime). By convention, a "library" is used directly by an application, whose programmer will require documentation and header files. A "driver", by contrast, is defined by a binary API and is used in some kind of framework, hence printer driver and video driver.

An ODBC driver is a hybrid. For the most part, an application relies on a driver manager to define manifest constants, and links to the DM's library. But because the ODBC specification leaves behavior up to the driver, the application is forced to include the driver's header files, too, to exploit driver-specific functions.