SCCS ID	@(#)README	2.2	7/25/95

This directory contains sources for an SQL interface for Tk/Tcl.

These programs expect Tcl 7.4 or later.

The SQL interface works with Tcl, standalone.  This was implemented and
tested with the following databases, and should be easy to port to other
database systems.  We tried to stick to generic embedded SQL.  However,
there is a surprising amount of variation in the SQL syntax for some
operations.

Supported database systems:
	Oracle/Digital Rdb	6.1
	Ingres			6.4
	Informix		7.10.UC1


Files in this distribution
--------------------------

configure	Configuration script, generated by GNU autoconf.
		You should not need to modify this file.

configure.in	Configuration specification, used by GNU autoconf.
		You should not need to use or modify this file.  It is
		provided for dire configuration problems.

Makefile.in	Makefile template for the accessories and test programs.

tcl_sql.sc.in	Tcl interface to SQL.  This is an Embedded SQL source file,
		which undergoes some preprocessing *before* that, to handle
		database-specific variations in SQL syntax.

tcl_sql.h	Common definitions for the package.  This is local to the
		SQL package, and is not used outside of this source directory.

tclAppInit.c	AppInit procedure for tcl_sql (Tcl + SQL).

sql.tcl		Example script that describes the tables in a database.

sql.n		Manual page.


Files Specific to Each Database System
--------------------------------------

For each database system supported, the following files are included.
Let SQLDB be the name of the database system...

sql_SQLDB.build	Shell script that processes tcl_sql.sc.in to produce
		tcl_sql.sc (or tcl_sql.ec, for Informix).

sql_SQLDB.sc	Embedded SQL source file that contains database-specific
		code for accessing some features.  (.ec for Informix)

sql_SQLDB.h	Header file to hide some syntactic differences between the
		database systems.

test_SQLDB.tcl	Test script for the database system.


Files generated by the configuration script
-------------------------------------------

Makefile	Makefile, customized for the database system

config.status	Result of running "configure"; generates Makefile from
		Makefile.in.


Files generated by the build procedure
--------------------------------------

tcl_sql.sc	Results of database-specific substitutions on tcl_sql.sc.in.
or .ec		Don't modify this file, modify tcl_sql.sc.in instead.

tcl_sql.c	Output of the Embedded SQL preprocessor.  Don't modify this
		file, modify tcl_sql.sc.in instead.

libtcl_sql_SQLDB.a
		Library for the SQL extension for Tcl, for the specific
		database system.

tcl_sql_SQLDB	tclsh + SQL interface demo program.



Configuring, Compiling and Installing
-------------------------------------

This release should compile and run with little or no effort on any
UNIX-like system that approximates POSIX, BSD, or System V and supports SQL
and Embedded SQL.  It has only been tested with Ingres.

    (a) Make sure that this directory and the corresponding release of
        Tcl are both subdirectories of the same directory.

    (b) Run "configure" in this directory, giving the name of the database
	to configure it for.  This runs a configuration script created by
	GNU autoconf, which configures tcl_sql for your system and creates a
	Makefile.  The configure script allows you to customize the
	configuration for your site;  for details on how you can do this,
	see the file "configure.info" that came with Tcl.
		./configure -with-DB=XXX
	where XXX is one of INGRES, RDB, or INFORMIX.

	The configure script will attempt to find all of the resources
	needed to build the library and test programs.  If it doesn't find
	what it needs, it will exit with an error message.  Most database
	systems require the following:
	  *  You must install the software development environment for
	     "Embedded SQL".  Some systems require a key that authorizes the
	     use of the development software.
	  *  Some systems require that one or more environment variables be
	     set, so that they can find libraries, etc.
	  *  $PATH must include the directory that contains the ESQL
	     preprocessor.
	The instructions for the database system should include a
	description of these requirements.  Good luck finding them.

    (c) Type "make".  This will create a library archive called
	"libtcl_sql_XXX.a" and an interpreter application called
	"tcl_sql_XXX" that allows you to type Tcl and SQL commands
	interactively or execute script files.  XXX is the name of the
	database system.

    (d)	To test the library, a demonstration script (test_XXX.tcl) is
	included.  Type "make test" to exercise it.  The SQL database server
	must be running, and you must have a database to use.  The
	demonstration generates a list of all of the tables in the database.

    (e) If the make fails then you'll have to personalize Makefile.in
        for your site or possibly modify the distribution in other ways.
	After modifying Makefile.in, you can regenerate the Makefile by
	running the script "./conf.status", which contains the configuration
	information gleaned by configure.
	
    (f) Type "make install" to install the binary and library file in
        standard places.  In the default configuration, it will be installed
	in the same tree that the "tclsh" program is installed in.
	You'll need write permission on this directory.

    (g) At this point you can play with Tcl/SQL by invoking the
	"tcl_sql_XXX" program and typing Tcl commands.


Incorporating tcl_sql into other Tcl interpreters
-------------------------------------------------

The SQL files should be installed in the same locations as the Tcl binaries,
libraries, and manual pages.  The configure script should set up the
Makefile appropriately.

To incorporate the SQL module into your program, add a call to
	Sql_Init(interp);
to your AppInit() procedure.  Link your program with the option
	-ltcl_sql_XXX
You must also include all of the libraries required for your database
system.  The link options that were used when building tcl_sql_XXX should
reveal everything you need.

Make sure that these options come before "-ltk", if you are using Tk.
