ODBC is a package to provide connectivity to databases supporting the
ODBC interface.  The package should be platform independent and
provide access to any database for which a driver exists.  It has been
tested with MySQL and PostgreSQL on both Linix and Windows (and to
those DBMSs on Linux hosts from R under Windows), Microsoft Access,
SQL Server and Excel spreadsheets (read-only), and users have reported
success with connections to Oracle and DBase.

Usage is covered in the R Data Import/Export manual.

Character fields in the database are limited to 255 characters, and
will be truncated on reading.


ODBC under Windows
==================

ODBC is often installed by applications that can use this interface
(it is part of MDAC).  A freely available (in the free-of-charge not
the copyleft sense) implementation can be downloaded from
http://www.microsoft.com/data/odbc/.  Updated drivers are also
available here for several data sources.

DSNs are usually set up using the "ODBC data sources" control panel
(`Data Sources (ODBC)' in the `Administrative Tools' section on 2000/XP).
If using RGui a DSN can be prepared via dialog boxes using

R> channel <- odbcDriverConnect("")

and this is often the simplest way for new users to ODBC or for
rarely-used data sources.  There are convenience functions
odbcConnectAccess/Dbase/Excel to ease connecting to one of these systems.


ODBC under Unix/Linux
=====================

An ODBC driver manager needs to be installed, as well as an ODBC
driver for each database to be used.  Testing is done using unixODBC
(http://www.unixODBC.org), but iOBDC (http://www.iODBC.org) has also
been used.  The RODBC package is installed in the standard way (R CMD
INSTALL RODBC) and needs the ODBC driver manager library (-lodbc or
-lodbc32 or -liodbc) to be in the library search path (and library run
path).

DSNs are described in files: the user's file is ~/.odbc.ini.  Mine is:

gannet% cat .odbc.ini
[test]
Description     = myodbc
Driver          = myodbc3
Trace           = No
TraceFile       =
Server          = localhost
Port            = 3306
Socket          =
Database        = test

[testpg]
Description     = testpg
Driver          = PostgreSQL
Trace           = No
TraceFile       =
ServerName      = localhost
UserName        = ripley
Port            = 5432
Socket          =
Database        = testdb


This can be used via

R> channel <- odbcConnect("test")

as MySQL provides open access to the `test' database, but for real
examples you will need to provide a uid and pwd entry as in

R> channel <- odbcConnect("test", uid="ripley", pwd="secret")

More sophisticated connections, e.g. to remote machines, can be built
using odbcDriverConnect or as DSNs.

Note that you need to ensure that .../etc/odbcinst.ini contains the
driver information.  We have

gannet% cat /usr/local/etc/odbcinst.ini
[myodbc3]
Description = MySQL driver.
Driver      = /usr/local/lib/libmyodbc3.so
Setup       = /usr/local/lib/libodbcmyS.so
FileUsage   = 1

[PostgreSQL]
Description  = PostgreSQL driver
Driver       = /usr/local/lib/psqlodbc.so
Setup        = /usr/local/lib/libodbcpsqlS.so
FileUsage    = 1


for use with MySQL using the MyODBC 3.51 driver (both from
http://www.mysql.com), and PostgreSQL using the latest unbundled
driver from the psqlodbc project
(http://gborg.postgresql.org/project/psqlodbc).

One quirk to be watched is the use of connections to the DBMS via the
Unix sockets vs ports.  The PostgreSQL driver bundled with unixODBC
will use Unix sockets to `localhost', but this driver seems unreliable
(see the ChangeLog).  The current driver will only use a TCP/IP port,
and to use that needs postmaster started with the -i flag (which is
not the default) and with tcp/ip enabled in the configuration file
(which is the default).  The PostgreSQL drivers are seriously
under-documented!
