NAME

       tdbc::odbc - TDBC-ODBC bridge

SYNOPSIS

       package require tdbc::odbc 1.0

       tdbc::odbc::connection create db connectionString ?-option value...?
       tdbc::odbc::connection new connectionString ?-option value...?

       tdbc::odbc::datasources ?-system|-user?

       tdbc::odbc::drivers

       tdbc::odbc::datasource command driverName ?keyword-value?...
________________________________________________________________________________________________________________

DESCRIPTION

       The tdbc::odbc driver provides a database interface that conforms to Tcl DataBase Connectivity (TDBC) and
       allows a Tcl script to connect to any SQL database presenting an ODBC interface.  It is also provided  as
       a worked example of how to write a database driver in C, so that driver authors have a starting point for
       further development.

       Connection to an ODBC database is established by invoking tdbc::odbc::connection create, passing  it  the
       name to be used as a connection handle, followed by a standard ODBC connection string. As an alternative,
       tdbc::odbc::connection new may be used to create a database connection  with  an  automatically  assigned
       name.  The  return  value  from tdbc::odbc::connection new is the name that was chosen for the connection
       handle.

       The connection string will include at least a DRIVER or DSN keyword, and  may  include  others  that  are
       defined  by  a particular ODBC driver. (If the local ODBC system supports a graphical user interface, the
       -parent option (see below) may allow calling  tdbc::odbc::connection  create  with  an  empty  connection
       string.)

       The  side  effect  of  tdbc::odbc::connection  create  is  to  create  a  new  database  connection.. See
       tdbc::connection(3tcl) for the details of how to use the connection to manipulate a database.

       In addition to a standard TDBC interface, tdbc::odbc supports three additional ccommands.  The  first  of
       these,  tdbc::odbc::datasources, which returns a Tcl list enumerating the named data sources available to
       the  program  (for  connection  with  the  DSN  keyword  in  the  connection  string).   The  result   of
       tdbc::odbc::datasources  may  be  constrained  to  only  system data sources or only user data sources by
       including the -system or -user options, respectively.

       The tdbc::odbc::drivers command returns a dictionary whose keys are the names of  drivers  available  for
       the DRIVER keyword in the connection string, and whose values are descriptions of the drivers.

       The  tdbc::odbc::datasource  command  allows  configuration  of  named data sources on those systems that
       support the ODBC Installer application programming interface. It accepts a command, which  specifies  the
       operation  to be performed, the name of a driver for the database in question, and a set of keyword-value
       pairs that are interpreted by the given driver. The command must be one of the following:

       add    Adds a user data source. The keyword-value pairs must include at least a  DSN  option  naming  the
              data source

       add_system
              Adds  a  system data source. The keyword-value pairs must include at least a DSN option naming the
              data source

       configure
              Configures a user data source. The keyword-value pairs will usually include a  DSN  option  naming
              the  data  source.  Some  drivers  will support other options, such as the CREATE_DB option to the
              Microsoft Access driver on Windows.

       configure_system
              Configures a system data source.

       remove Removes a user data source. The keyword-value pairs must include a DSN option specifying the  data
              source to remove.

       remove_system
              Removes  a  system  data  source. The keyword-value pairs must include a DSN option specifying the
              data source to remove.

CONNECTION OPTIONS

       The tdbc::odbc::connection create object  command  supports  the  -encoding,  -isolation,  -readonly  and
       -timeout  options  common  to  all  TDBC drivers. The -encoding option will succeed only if the requested
       encoding is the same as the system encoding; tdbc::odbc does not attempt to specify alternative encodings
       to an ODBC driver. (Some drivers accept encoding specifications in the connection string.)

       In  addition,  if Tk is present in the requesting interpreter, and the local system's ODBC driver manager
       supports a graphical user interface, the tdbc::odbc::connection create object command supports a  -parent
       option, whose value is the path name of a Tk window. If this option is specified, and a connection string
       does not specify all the information needed to connect to an interface,  the  ODBC  driver  manager  will
       display  a  dialog box to request whatever additional information is required. The requesting interpreter
       will block until the user dismisses the dialog, at which point the connection is made.

EXAMPLES

       Sincs ODBC connection strings are driver specific, it is often difficult to find the documentation needed
       to  compose them. The following examples are known to work on most Windows systems and provide at least a
       few useful things that a program can do.

              tdbc::odbc::connection create db \
                  "DSN={PAYROLL};UID={aladdin};PWD={Sesame}"
       Connects to a named data source "PAYROLL", providing "aladdin" as a user name and "Sesame" as a password.
       Uses db as the name of the connection.

              set connString {DRIVER={Microsoft Access Driver (*.mdb)};}
              append connString {FIL={MS Access}\;}
              append connString {DBQ=} \
                  [file nativename [file normalize $fileName]]
              tdbc::odbc::connection create db2 -readonly 1 $connString
       Opens a connection to a Microsoft Access database file whose name is in $fileName. The database is opened
       in read-only mode. The resulting connection is called "db2".

              tdbc::odbc::connection create db3 \
                  "DRIVER=SQLite3;DATABASE=$fileName"
       Opens a connection to a SQLite3 database whose name is in "$fileName".

              tdbc::odbc::datasource add \
                  {Microsoft Access Driver (*.mdb)} \
                  DSN=MyTestDatabase \
                  DBQ=[file native [file normalize $fileName]]
       Creates a new user data source with the name, "MyTestDatabase" bound to a  Microsoft  Access  file  whose
       path  name  is  in  "$fileName".  No  connection  is  made  to  the  data  source until the program calls
       tdbc::odbc::connection create.

              tdbc::odbc::datasource configure \
                  {Microsoft Access Driver (*.mdb)} \
                  CREATE_DB=[file native [file normalize $fileName]] \
                  General
       Creates a new, empty Microsoft Access database in the file identified by "$fileName".  No  connection  is
       made to the database until the program calls tdbc::odbc::connection create.

SEE ALSO

       tdbc(3tcl), tdbc::connection(3tcl),  tdbc::resultset(3tcl), tdbc::statement(3tcl)

KEYWORDS

       TDBC, SQL, ODBC, database, connectivity, connection

COPYRIGHT

       Copyright (c) 2008 by Kevin B. Kenny.