			*** tQL Reference ***

This file containg a list of all tQL commands, and descriptions of how
they work. For more information, have a look at 'test.tcl'

All tQL commands are in the tQL namespace.

* Init dbtype ?namespace

This initializes the tQL functions. In order to do this, it calls
dbtype_Init. For example,

	tQL::Init Postgres

calls Postgres_Init. This procedure will have been provided by however
wrote the interface to the database. If the namespace option is
specified, then the functions will be loaded into that
namespace. Otherwise, they are loaded into the tQL namespace.

* OpenDB ?options...

Opens a database. The return value is a value that can be passed to
the rest of the functions below. Its precise type depends on the way
the database interface has been written - you should not try and
manipulate it directly. A number of options can be specified, and more
may be provided by the database implementation -

	-host host
		the hostname of the database server
	-port port
		the port on which the database server is listening
	-db name
		the name of the database to open

All these options can be omitted, and defaults will be used.

The database will be closed when the return value is no longer
referenced - to force a database to close, use

	set db ""

* Exec database query

Sends an SQL query to the database. The database must be a value
returned from OpenDB, and the query is a string. The return value is
an opaque structure representing the resulting table, which can be
passed to the functions below.

* Rows result

Returns the number of rows in a result table.

* Fields result

Returns the number of fields in a result table.

* Fieldname result fieldnumber

Returns the name of the specified field (0 is the first field).

* Value result rownumber fieldnumber

Returns the value (as a string) of the entry at the specified row and
field.

* Tabulate result

Returns an array containing entries of the form (rowno,fieldname),
containing the value at that position in the result table. There is
also an entry (result), that is the result structure passed to
tabulate.

* Query name { args } { query }

Creates a procedure, called 'name', that, when called, and passed a
database and the arguments specified as 'args', will execute the
query, returning an array produced using the Tabulate function,
above. The query string can contain variable and command substitutions
(so, square brackets and dollar signs need to be quoted).

A database interface can include other functions if it likes, but
these should not normally be exported to the tQL namespace. Instead,
they should be exported to the tQL::lowlevel namespace. These commands
need not follow any pattern, and can take advantage of any extensions
the database developer wishes to use.

For an example of how to use tQL, see 'test.tcl'

