manpagez: man pages & more
man tdbc_odbc(n)
Home | html | info | man
tdbc::odbc(n)              Tcl Database Connectivity             tdbc::odbc(n)



______________________________________________________________________________


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 con-
       nection  handle,  followed  by a standard ODBC connection string. As an
       alternative, tdbc::odbc::connection new may be used to create  a  data-
       base  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(n) 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 opera-
       tion to be performed, the name of a driver for the  database  in  ques-
       tion,  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 usu-
              ally  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 -encod-
       ing, -isolation, -readonly and -timeout  options  common  to  all  TDBC
       drivers. The -encoding option will succeed only if the requested encod-
       ing 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 dia-
       log, at which point the connection is made.


EXAMPLES

       Sincs ODBC connection strings are driver specific, it is  often  diffi-
       cult  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  con-
       nection.

              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 con-
       nection 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 connec-
       tion  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(n), tdbc::connection(n),  tdbc::resultset(n), tdbc::statement(n)


KEYWORDS

       TDBC, SQL, ODBC, database, connectivity, connection


COPYRIGHT

       Copyright (c) 2008 by Kevin B. Kenny.



Tcl                                   8.6                        tdbc::odbc(n)

tcl 8.6.5 - Generated Fri Mar 4 19:08:37 CST 2016
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.