		  *** tQL - SQL queries from TCL ***

tQL is a definition of an interface between TCL programs and SQL
databases. It also comprises utility functions and an implementation
of the interface for the Postgres database. Hopefully, more database
implementations will come soon.

tQL is a new project, and so is only at a proof-of-concept
stage. Hopefully, it should be useful, as it stands, for writing
simple database front-ends. However, it's primary purpose for the
moment is to explore the possibility of a common TCL/SQL interface,
and so it may well not do what you want it to do, or not do anything
terribly well. If you want to help develop tQL, contact Timothy
Fisken.

tQL was written by Timothy Fisken (tim@rose-cottage.demon.co.uk) and
is distributed under the GNU General Public License. See the file
COPYING for details.

1. Compiling and Installing tQL

To compile tQL, you will need TCL 8.0 or higher, as well as the PQ
library, distributed with Postgres.

tQL uses GNU autoconf, so to configure tQL type

	./configure

If TCL is not installed in /usr/lib or /usr/local/lib, you will need
to pass the option:

	--with-tcl=DIR

where dir is the directory in which tclConfig.sh can be found.

You can also specify where tQL should install itself with the option

	--prefix=DIR

and tQL will install itself in DIR/lib/tcl8.0 (or tclX.Y for tcl
version X.Y). The default prefix is /usr/local. For more informatin
about configure, see the file INSTALL.

If configure completes running succesfully, type

	make

to compile tQL. When this has finished run

	make install

(you will probably need to be root).

If you have installed tQL in a different directory to the rest of your
TCL distribution, then you may need to tell TCL to look for files in
the directory tQL is installed in. To do this, add the directories you
have tQL installed in to TCLLIBPATH and LD_LIBRARY_PATH.

Now, to test tQL is working, load tclsh and type

	package require tQL	
        tQL::Init Postgres
	set db [tQL::OpenDB]
	
Assuming Postgres is running, then this should open a connection to
the database.

tQL has only been tested on one Redhat 5.1 system (my own), so it is
possible that you may have trouble getting it to work. If that is the case,
please contact tim@rose-cottage.demon.co.uk.

2. Using tQL

The tQL interface is roughly modelled on the libpq interface. The
general way to use it is -

	tQL::Init Postgres

This will initialize the tQL system, and tell it to use the Postgres
back end. In the future, hopefully other options than Postgres could
be specified to open different databases.

	set db [tQL::OpenDB -host host -db mydb]

This opens the database 'mydb' on host 'host'.

	tQL::Query name { arg1 arg2 ... argn } {
		... SQL Statements ...
	}

This creates a procedure, called name, that can be called like this:

	array set result [name $db arg1 arg2]

The procedure executes the SQL statements, and returns a TCL array
such that

	$result(0,field)

is the value of row 0, field 'field' in the table that results from
the query.

For more information, see 'reference.txt' and 'test.tcl'.

3. Future plans

My hope is that tQL will become a general interface, that will connect
TCL programs to a variety of databases. In order to do this, I really
need the help of people with experience of other database systems, to
port tQL, and to give me their opinion of the interface. Is it too
limited? Is it too tied to the way Postgres works? If you have any
comments, or want to offer your help, please contact
tim@rose-cottage.demon.co.uk.

4. Copyright

tQL is released under the GNU General Public License. Please see the
file COPYING, or contact the Free Software Foundation.
