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(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 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:
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.
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.