SCCS ID		@(#)README	1.1	3/11/94

This directory contains the source for the Tcl extension, "CGI", which
implements parts of the HTTP Server Common Gateway Interface.  The resulting
Tcl shell is useful for executing scripts invoked by the http daemon.

Two commands are added:

cgi_get_query
	Reads the query, either from standard input (for a POST query) or
	from $QUERY_STRING (for a GET query).  It examines $REQUEST_METHOD
	to determine which type is in use.  The resulting string is still
	URL-encoded.

	Because cgi_get_query may read standard input, it must not be called
	more than once.

cgi_parse_query [-strip] query array [list-var...]
	Parses a URL-encoded query and assigns each NAME=VALUE pair into the
	array.  i.e. array(NAME) <= VALUE.  If a NAME may occur more than
	once in the query (script writers should know this, based upon the
	form layout), the last value will overwrite all others.

	However, if NAME is given as one of the optional list-var's, the
	VALUE is appended as a list element to the array element.

	The -strip option causes non-printing characters to be removed from
	all values.

Usage
-----

The expected usage is to create a Tcl interpreter (which I call tcl_cgi),
and put it someplace accessable, and write scripts which use it.  So, a
typical script might look like the following.  Assuming that the form
defines two names "NAME" and "COMMENTS":

	#! /usr/local/bin/tcl_cgi

	cgi_parse_query -strip [cgi_get_query] Q
	
	set file [open {|/usr/ucb/mail -s "Comments from a user" smith@bigmax} w]
	puts $file "Comments from $Q(NAME) (at $env(REMOTE_HOST)):\n"
	puts $file $Q(COMMENTS)
	close $file

	puts {Content-type: text/html

	<TITLE>Thank You</TITLE>
	<H1>Thank You</H1>
	Your comments have been submitted.
	}

IMPORTANT SAFETY TIP:

The Ultrix kernel, at least, only handles interpreter file names (the
"shell" after #!) of about 24 bytes in length.  This causes mysterious
failures: your Tcl script will be executed by sh!


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_cgi.c	Tcl routines to deal with CGI stuff.

tclAppInit.c	AppInit procedure for tcl_cgi (Tcl + CGI).

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

cgi.n		Manual page.


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

libtcl_cgi.a	object library for adding to Tcl.

tcl_cgi		tclsh + SQL interface demo program.

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


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

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

    (b) Type "./configure" in this directory.  This runs a configuration
	script created by GNU autoconf, which configures tcl_cgi 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.

    (c) Type "make".  This will create a library archive called "libtcl_cgi.a"
	and an interpreter application called "tcl_cgi" that allows you to type
	Tcl commands interactively or execute script files.

    (d)	To test the library, a demonstration script (cgi.tcl) is included.
	Type "make test" to exercise it.

    (e) If the make fails then you'll have to personalize Makefile.in
        for your site or possibly modify the distribution in other ways.
	
    (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.


Incorporating tcl_cgi into other Tcl interpreters
-------------------------------------------------

The CGI 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 cgi module into your program, add a call to
	Cgi_Init(interp);
to your AppInit() procedure.  Link your program with the option
	-ltcl_cgi



Testing Tcl/CGI Scripts
-----------------------

It is difficult to test Tcl/CGI scripts in-place, because most error
messages won't be made visible by Mosaic.  The easiest way to test these
scripts is to create environment variables to mimic the environment set up
by httpd, as if the user had executed a "GET" method:
	setenv REQUEST_METHOD GET
	setenv QUERY_STRING 'name1=value&name2=a+longer+value'


