Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
tdbc::odbc(n)		   Tcl Database	Connectivity		 tdbc::odbc(n)


       tdbc::odbc - TDBC-ODBC bridge

       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::datasource command driverName ?keyword-value?...

       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 ad-
       ditional	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

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

	      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.

	      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.

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

       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 op-
       tion,  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.

       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 \
       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-

	      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	\
       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]] \
       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.

       tdbc(n),	tdbc::connection(n),  tdbc::resultset(n), tdbc::statement(n)

       TDBC, SQL, ODBC,	database, connectivity,	connection

       Copyright (c) 2008 by Kevin B. Kenny.

Tcl				      8.6			 tdbc::odbc(n)


Want to link to this manual page? Use this URL:

home | help