Updated 2015-02-01 04:50:27 by SEH

Purpose: Discuss the various options for writing Tcl Common Gateway Interface CGI compliant applications.

It's really easy, even if you don't use one of the helper libraries out there. There are two parts of running as a CGI script. The first part is understanding the incoming request, which is just a matter of looking at the right environment variables and, possibly, reading some data from stdin. The second part is producing the output to go back to the client (via the webserver), which is really just producing (on stdout) HTML with a little header magic.

The things to watch out for are testing and error handling. If an error occurs, the chance is it will just end up in the server log and you won't find out what happened for ages. And constructing a test harness can be a pain as well (there are many environment variables to set to emulate a CGI environment!)

One trick I use is to generate the output to a string and only output that string at the last moment. I then have a wrapper round my whole script that detects (with the help of catch of course) whether an error occurred and, if so, produces a nice error page instead of output which is still in the string. Careful overriding of the puts command can make this easier still:
 rename puts orig_puts
 proc puts {args} {
    set newline 1
    if {[lindex $args 0] eq "-nonewline"} {
       set newline 0
       set args [lassign $args dummy]
    if {[llength $args] == 1} {
       global accumulator
       append accumulator [lindex $args 0]
       if {$newline} {
          append accumulator \n
    } elseif {[llength $args] == 2} {
       if {$newline} {
          orig_puts {*}$args
       } else {
          orig_puts -nonewline {*}$args
    } else {
       error "wrong # args: should be \"puts ?-nonewline? ?channel? string\""

See Writing simple CGI applications using vanilla Tcl.

FAQ Entries
 What: cgi.tcl
 Where: http://expect.cvs.sourceforge.net/viewvc/expect/cgitcl/
 Description: Procedures for writing CGI scripts or HTML pages using Tcl7.4 to 8.2.
        Support for forms, tables, cookies, Netscape extensions, file upload,
        plug-ins, etc.  The PostScript file is the paper published describing
        the procedures.  The cgi-bin URL is a collection of CGI examples.
        The examples.cgi directory is a series of live cgi examples which
        allow you to see how various features work.  Latest version is now
        version 1.8.0.
 Updated: 09/2013
 Contact: mailto:libes@nist.gov (Don Libes)

 What: cgibitch
 Where: http://neutron.resnet.gatech.edu:8000/index.adp
 Description: Tcl extension to unescape and separate CGI query arguments
        and handles GET and POST requests transparently.
        It is currently at v1.0.4.
 Updated: 02/2000
 Contact: mailto:reeves@earthling.net

 What: email-www
 Where: ftp://ce-toolkit.crd.ge.com/tcl/email-www.tar.gz
 Description: A Tcl support library that works with dtclsh and tcl-www
        and provides support for mailto-like functionality using HTML
        forms. email-www comes with CGI scripts for simple, demonstration mail forms, but it is designed to be used as a library.  It includes basic support for email to FAX gateways and role mapping (aliases) in addition to plain electronic mail support.
 Contact: Unknown

 What: FastCGI for Tcl
 Where: http://sourceforge.net/projects/tcl-fastcgi/
 Description: Extension of CGI that eliminates drawbacks and provides high performance, which remaining highly compatible with existing CGI applications.  Original only supports Tcl 7.4, see idle site for pointers to Tom Pointdexter's version for newer support, as well as other language support. To use some features you need tclX, at least 8.0.2 installed. You must have the fcgi development kit 2.0b2.1 or newer to  use Fcgi.
        FastCGI is supported by at least these servers:
        Apache 1.2.x (with mod_fastcgi 2.0.9), NCSA 1.5 w/FastCGI support, Netscape server w/FastCGI support, Open Market, Stronghold,
        Bluestone Sapphire web servers.
        Some problems appear to exist with this code and recent Tcls, resulting in core dumps on Unix.  Contact Tom Poindexter for details.
 Updated: 11/2000
 Contact: mailto:fastcgi-developers-request@openmarket.com
        mailto:tpoindex@nyx.net (Tom Poindexter)

 What: filebrowse
 Where: ftp://ce-toolkit.crd.ge.com/pub/tcl/filebrowse.tar.gz
 Description: Allows a CGI program to generate forms that include a directory browser that resembles PC based applications.  Can specify virtual root directory and working directory, URL where directories are to be linked, and URL where files are to be linked.
 Updated: 08/1998
 Contact: Unknown

 What: NeoSoft Tcl
 Where: ftp://ftp.procplace.com/pub/tcl/neosoft/neotcl/
 Description: Tcl 7.6 and 8.0 set of commands and libraries providing
        interfaces to disk-based btree and hashtables,  TCP/IP server-client objects,  along with examples of an IRC robot object, RFC931 authentication  object, support for WWW CGI scripts, WWW log file parsing. Also, this includes file requestors, dialog boxes, pull-down menus, class libraries for databases, listboxes, a Tk notepad, progress
        notifiers, UDP-based object sharing, and more.  Package includes
        Tcl, Tk, itcl, Tcl-DP, tclX, color pixmap and GIF support,
        and Expect.
 Updated: 10/1998
 Contact: mailto:tcl-project@neosoft.com (Neosoft support)

 What: ProcCGIInput
 Where: http://www.uni-frankfurt.de/%7Efp/Tcl/ProcCGIInput.tcl.txt
 Description: Tcl 7.6 script that finds all form variables in the
        $form() array.
 Updated: 07/1997
 Contact: mailto:fp@informatik.uni-frankfurt.de (Frank Pilhofer)

 What: SNTL
 Where: http://www.csua.berkeley.edu/%7Esls/woa/distrib/
 Description: A general Tcl library of procedures.  Contains code to
        produce man pages from Tcl source, conversions from Tcl to C,
        HTML rendering, generating HTML, handling CGI forms, command line
        argument processing, a debugging message system, an object system,
        and various Tk widgets built with the object system.
 Updated: 10/1998
 Contact: mailto:slshen@lbl.gov (Sam Shen)
        mailto:sls@aero.org (Sam Shen)

 What: tcl-cgi
 Where: http://ruulst.let.ruu.nl:2000/tcl-cgi.html
 Description: Small extension allowing Tcl programmers to write CGI programs
        which can handle the POST method of data.  Enables a secure WWW
        interface to Tcl applications.
 Updated: 10/1998
 Contact: mailto:Wessel.Kraaij@let.ruu.nl (Wessel Kraaij)

 What: tclsap
 Where: http://www.mcs.net/%7Egarth/SAP/TCLSAP/
 Description: Extensions to Tcl 7.4/Tk 4.0 to allow interactive or script  based access to a SAP R/3 system through RFC calls.
        Allows one to develop CGI-BIN access through which SAP can be
 Contact: mailto:garth@mcs.net (Garth Kennedy)

 What: uncgi
 Where: From the contact
 Description: Tcl procedure to parse the CGI form data.
 Contact: mailto:L@demailly.com (Laurent Demailly)

 What: Blitz.tcl
 Where: http://www.nsoftware.com/
 Description: Beta release of a CGI script accelerator for ISAPI enbabled
        HTTP servers.  No changes to CGI scripts are needed.  Initial
        version is tuned for Tcl 8.x and Windows NT.  A Windows 95/98
        version is available for testing.  Future versions will become
        commercially available after development completes.
 Updated: 04/1999
 Contact: mailto:info@nsoftware.com

 What: cal.tcl
 Where: ftp://ftp.net-quest.com/users/ivler/tcl/cal.cgi
 Description: CGI script to provide a WWW-based, dynamic, calendar.
        Requires uncgi.  See a demo at
 Contact: mailto:ivler@i-xpress.com (J.M. Ivler)

 What: CGI Forms based mailing (Ivler)
 Where: ftp://ftp.net-quest.com/users/ivler/tcl/email.tcl
 Description: A Tcl script to do CGI processing of 'email the form data'
        for the programmer.  Requires uncgi.
        See http://www.net-quest.com/%7Eivler/ for explanation
        of the script.
 Contact: mailto:ivler@i-xpress.com (J.M. Ivler)

 What: CGI Forms based mailing (Knight)
 Where: From the contact
 Description: A Tcl script to allow Common Gateway Interface forms-based
        mailing to a specific user.
 Contact: mailto:J.P.Knight@lut.ac.uk (Jon P. Knight)

 What: CGI Forms data formating
 Where: http://www.winehq.com/apps.cgi
 Description: Tcl based CGI script which allows data to be entered and
        the results formatted into a nice table.
 Updated: 02/1998
 Contact: mailto:ridgway@taiga.gmcl.com (Douglas Ridgway)

 What: CGI Tcl commands
 Where: http://camnet.ge.com/tcl/
 Description: C code implementing Tcl commands for query-string parsing and
        other interesting things for CGI programmers.
 Contact: mailto:kennykb@crd.ge.com (Kevin B. Kenny)

 What: CGI to Tcl and/or Tk
 Where: From the contact
 Description: Simple Common Gateway Interface scripts for invoking
        Tcl scripts or Tk scripts.
 Contact: mailto:sgutfreund@gte.com (Yechezkal-Shimon Gutfreund)

 What: CGI upload script
 Where: http://www.winehq.com/patches.cgi
 Description: cgi.tcl based script to allow people to upload their own
 Updated: 06/1998
 Contact: mailto:ridgway@winehq.com (Doug

 What: Data entry via CGI
 Where: http://www.winehq.com/apps.cgi
 Description: Tcl based CGI script that allows people to enter data and
        then formats it into a table.  Data can contain HTML, which then
        will be included so that links can be put in.
 Updated: 01/1998
 Contact: mailto:ridgway@winehq.com (Douglas Ridgway)

 What: Email CGI form script
 Where: From the contact
 Description: A tcl script that generates the HTML for an email entry
 Contact: mailto:hhalkin@ucsd.edu (Hubert Halkin)

 What: Got It
 Where: http://www.goahead.com/gotit/
 Description: Commercial product which attempts to improve web response time
        by predicting, retrieving, and filtering pages for you,
        in the background.  Prioritizes retrieved data and caches the data
        on your hard drive.  Works transparently with your web
        browser.  Consists of a page fetcher, a pruner, and maintainer of
        a news page listing what pages have been downloaded for the user.
        Runs as a proxy HTTP server.  Supports CGI scripting and
        safe Tcl CGI scripting.  Works on Windows 95/Windows NT and Netscape or
        Microsoft Internet Explorer.  See above page for a 14 day
        evaluation copy.
 Updated: 02/1997
 Contact: mailto:bryan@goahead.com (Bryan Klisch)

 What: HTTP CGI example of calling Tcl
 Where: ftp://ftp.ncsa.uiuc.edu/Web/ncsa_httpd/cgi/tcl-proc-args.tar.Z
 Description: The NCSA's httpd can invoke tcl scripts.  It appears
        there is a test example called test-cgi.tcl that comes with
        the httpd source.  At least one bug fix was reported
        relating to the content length field.  Contact
        mailto:etxmesa@eos.ericsson.se (Michael Salmon) for details.
 Contact: mailto:robert.bagwill@nist.gov

 What: Illustra ORDBMS to WWW CGI gateway
 Where: http://lenti.med.umn.edu/%7Ethanson/sqlform.html
 Description: A Tcl CGI gateway for WWW access to Illustra ORDBMS files.
 Contact: mailto:thanson@acl.lanl.gov (Troy Hanson)

 What: Jungle
 Where: ftp://catless.ncl.ac.uk/pub/jungle.tar.gz
 Description: The contact is developing a "WWW server" (sic) (really HTTP?)
        using Tcl/Tk/tclX/Tcl-DP.  Alpha version currently supports simple
        GET, HEAD, POST directives and CGI-Scripts and can server plaintext,
        HTML, GIF, JPG, and AU file formats.  Configure it similar to CERN.
        Provides no authentication or access controls, or
        cgi program execution for POST or searching.
 Contact: mailto:jungle@catless.ncl.ac.uk

 What: mmm
 Where: ftp://ftp.inria.fr/INRIA/Projects/cristal/Francois.Rouaix/mmm/
 Description: A WWW client demonstrating the capabilities of the Caml
        Special Light programming language.
        Supports most of HTML 3.2, as well as Caml Special Light applets.
        Supports CGI calling, english, french and japanese,
        V0.41 requires Tcl 7.5/Tk 4.1 or Tcl 7.6/Tk 4.2,
        metamail, djpeg, gzcat, and Caml v1.06 or newer.
 Updated: 01/1998
 Contact: mailto:Francois.Rouaix@inria.fr

 What: Mod_dtcl
 Where: http://tcl.apache.org/
 Description: Apache module to enable server parsed web pages using Tcl
        as the scripting language.  It is simlar in functionality to PHP,
        fast, easy to use, tightly integrated with HTML, and extensible.
        It is currently available in an alpha release.  Includes
        dtcl-mode.el, which lets you switch between Tcl and HTML modes,
        dtcl.tcl, a port of Don Libes' cgi.tcl.  Supports TTML pages.
        Latest version is v0.7.3.
 Updated: 02/2000
 Contact: mailto:davidw@apache.org (David N. Welton)

 What: Myrmeco
 Where: http://www.neatware.com/myrmecox/
 Description: Trial version of a commercial Tcl/Tk IDE for Windows 95/98/2000/NT.
        Supports Multithreads, Unicode, and the Tcl Stubs interface.
        Includes project, command and console view, smart MDI editor with
        color coding of command keywords and comments,
        command keyword editor, Tcl/Tk 8.2 core, and a debugger.  Also
        includes a web builder (MyrmecoWeb),
        MyrmecoWiz, a wizard for generating c/c++ code templates for Tcl
        extensions, MyrmecoTk, a component based framework for GUI applications,
        Salan, a Tcl extension for HTML, CGI, and XML.
        Platform: Windows 95/98/2000/NT 4.0
        Current version is 2.3.
 Updated: 11/1998
 Contact: mailto:support@neatware.com

 What: Namazu
 Where: http://saturn.aichi-u.ac.jp/%7Eccsatoru/Namazu/
 Description: Namazu (catfish, in English) is search engine software intended
        for easy use.
        Not only does it work as a CGI interface for small to medium scale
        WWW search engines, but is also appropriate for personal search
        databases.  Search clients are available in Mule and Tcl/Tk,
        Java, Perl.  It has been ported to OS/2, Unix, and Win32.
        tknamazu is the Tcl/Tk search client.
 Updated: 10/1998
 Contact: mailto:ccsatoru@vega.aichi-u.ac.jp (Satoru Takabayashi)
        mailto:kenzo-@tama.or.jp (Ken-ichi Hirose)

 What: rfc
 Where: http://www.uni-frankfurt.de/%7Efp/Tcl/rfc.tcl.txt
 Description: Tcl 7.5 CGI script to interface with glimpse to browse
        internet Request For Comment (RFC) documents.
 Updated: 07/1997
 Contact: mailto:fp@informatik.uni-frankfurt.de (Frank Pilhofer)

 What: Simple Order Form generator
 Where: ftp://ce-toolkit.crd.ge.com/tcl/simpleforms.tar.gz
 Description: A simple order form generator and processor package.
        It consists of a Tcl support library and CGI scripts that
        read forms from template files and use the email-www package
        to transport the results.
 Contact: Unknown

SnamlScript is a language to generate HTML5 for Web applications. It adds block command and inline command to integrate the Tcl with HTML5 for Web programming. Example:
# Use SnamlScript HTML5 package
package require HTML5

# output to a file. If no output or its first parameter is null, default output is to stdout.
output hello.html

# declare document type as html
__doctype html

# html header. quote command render the string.
_html "lang='en'"
  _title; quote Hello; title_

# html body
  __img "src='hello.gif' alt='hello'" 
  quote "Hello World!"

 What: Tcl-Httpd
 Where: http://www.tcl.tk/software/tclhttpd/
 Description: An HTTP daemon written in Tcl.  Uses event-driven I/O,
        and caches URL to file name lookups.  Provides CGI interface,
        built in image map hit detection, uses SafeTcl as an
        additional way to process a page, supports server side
        includes, and provides a GUI to monitor the server's activity.
        Should run on all platforms.  A mailing list is available.
        Currently this is at version 3.0.2.
 Updated: 06/2000
 Contact: mailto:welch@acm.org (Brent Welch)

 What: tcl2html
 Where: http://www.purl.org/net/hobbs/tcl/script/
 Description: Tcl script which creates an HTML presentation of a Tcl program.
        Preserves spacing, emphasizes comments, bolds Tcl keywords for
        presentation on the WWW.  Works as either a CGI script or stand-alone
        script.  Written in Tcl 7.6.
 Updated: 11/1998
 Contact: mailto:jeff.hobbs@acm.org (Jeffrey Hobbs)

 What: uncgi (Koreth)
 Where: http://www.hyperion.com/%7Ekoreth/uncgi.html
 Description: A frontend for processing queries and forms from WWW on
        Unix systems.
 Contact: mailto:koreth@hyperion.com

 What: Velocity Engine
 Where: http://www.binevolve.com/
 Description: A commercial Netscape Server API plugin that allows you to
        program the Netcape HTTP server using Tcl.  Speeds up developer
        time on WWW site developement by replacing CGI by allowing one
        to embed Tcl into pages.  Also known as Velocigen.  Currently
        at version v1.1.3.
 Updated: 05/1999
 Contact: mailto:info@binevolve.com

 What: WebHand
 Where: http://members.xoom.com/xwebhand/
 Description: HTML editor, beautifier, template manager, with the idea
        to make editing JavaScript, CGIs, etc. easier.
 Updated: 02/2000
 Contact: mailto:igors@angara.ru

 What: Wikit
 Where: http://www.equi4.com/tclkit/wikit.html
 Description: A "wiki wiki web" application written in Tcl.  It allows anyone
        with a web browser to edit pages of the application remotely.  Allows
        a loosely organized web forum.
        The application provides hypertext between its pages.  Application
        can be used both as a stand alone Tk application and as a CGI
        application.  Requires Tclkit or Tcl 8.0.x and mk4tcl.
        The mini net site is an up to date snapshot of the entire Wiki.
 Updated: 10/2000
 Contact: mailto:jcw@equi4.com (Jean-Claude Wippler)

 What: wwwtools
 Where: http://www.demailly.com/~dl/wwwtools.html
 Description: Source for geturl, geturl2, uncgi, test-cgi, guest book,
        as well as other WWW related Tcl tools.
        Note that a HTTP server written in
        Tcl, tclX, Tcl-DP, and GD Tcl is also described here.
 Contact: mailto:L@demailly.com (Laurent Demailly)

 What: Yakdot
 Where: http://www.smith-house.org:8000/open.html
 Description: Simple Tcl application to provide a slashdot-like web forum
        manager.  Runs as a CGI.
        Currently at version 1.0
 Updated: 09/2000
 Contact: mailto:larry@smith-house.org (Larry Smith)