cgi.tcl FAQ (Frequently Asked Questions)

Go to cgi.tcl home page

This FAQ lists common questions, usually about subjects that either didn't fit well in the man page or can't be found easily. In some cases, I've left the original questions. I suppose I could've stripped off the headers, but it seems more realistic to see actual people who've asked the questions. Thanks to everyone who asked.

The man page and the papers listed in the README file should also be consulted for highly technical or philosophical discussion of the implementation, design, and practical application of cgi.tcl.


Click on the question to see its answer.

    Basic Questions

  1. Why doesn't "package require" work?
  2. Why are certain things printed in the "wrong" order?
  3. Some of the proc names seem really verbose - would you consider shorter names?
  4. Does a program exist to convert from HTML to Tcl?
  5. Is memory usage too high?
  6. ISP with Tcl support
  7. no code tag?
  8. My cookies had problems on Y2K!
  9. Some code in your examples accomplishes nothing?
  10. Is there more complete documentation than ref.txt?

    File Upload

  11. Why does file upload return an empty file when the user leaves it empty?
  12. Is it possible to change the default file upload filter?

Questions and Answers

    Basic Questions

  1. Why doesn't "package require" work?

    It should work. First, make sure that you're running Tcl 7.6p2 (or whatever the latest production release is). Assuming you're running a modern Tcl, the usual reason for failure of the package command is that you've configured Tcl and cgi.tcl to use different directories for the packages. You can see what directory Tcl is configured to use by examining the variable tcl_pkgPath. Now look to see where "make install" puts the cgi.tcl package. If they're not the same, rerun the configure script with the right arguments.

  2. Why are certain things printed in the "wrong" order?
    From: De Clarke 
    >here's a snip of source
    >        cgi_number_list {
    >                cgi_li "[cgi_radio_button match=both checked] Match First or Last Name"
    >                cgi_li "[cgi_radio_button match=first] Match First Name Only"
    >                cgi_li "[cgi_radio_button match=last] Match Last Name Only"
    >                cgi_li "[cgi_radio_button match=title] Match Title"
    >                cgi_li "[cgi_radio_button match=unit] Match Unit"
    >                cgi_li "[cgi_radio_button match=email] Match Email"
    >        }
    >wouldn't you think that would result in
    >	1 [radiobutton 1, checked] Text
    >	2 [radiobutton 2] Text
    >	3 ....
    >and so on?
    >But instead:
    >  [radiobutton 1, checked]
    >  1.Match First or Last Name  [radiobutton 2]
    >  2.Match First Name Only  [radiobutton 3]
    >  3.Match Last Name Only  [radiobutton 4]
    >  4.Match Title  [radiobutton 5]
    >  5.Match Unit   [radiobutton 6]
    >  6.Match Email  [no radiobutton here]
    >is what I get.
    >this doesn't seem right somehow.  am I not understanding something, or
    >have I found a little problem?  I'm still learning the basics, so
    >quite willing to believe this is my stupid mistake.

    It's not a stupid mistake - rather, it's my practical response to the implementation challenge posed by the flexibility of HTML. So here's the scoop:

    Radio buttons (and most other form elements) are rarely embedded in the middle of paragraphs. They're almost always top-level items. Thus, the default behavior is to immediately generate it - that is, they all have implicit calls to "puts". So if you understand the basics of Tcl, it then makes sense that "li [radiobutton...]" generates <input type=radio...> <li>. (Not what you want, but at least it makes sense now ... right?)

    One solution is to use cgi_buffer, which suppresses this behavior. So instead of:

    	cgi_li "[cgi_radio_button match=unit] Match Unit"


    	cgi_li "[cgi_buffer {cgi_radio_button match=unit}] Match Unit"

    As an aside, I wouldn't put radio buttons in a numbered list in the first place. The whole point of the descriptive phrases (to their right) is so that you don't need arbitrary numbers. If the numbers are truly part of the label, I would generate it using a Tcl variable - either

    	cgi_radio_button ...; puts "$num $label[nl]"


    	puts "$num"; cgi_radio_button ...; puts "$label[nl]"
    >the numbered list was sort of a coincidence.  I was 
        >reproducing faithfully an old CGI bin, doing a before/after, 
        >and in the old CGI bin I typed ol instead of ul.  you know how 
        >that goes.  actually I embed form elements, including buttons, 
        >inside other structures all the time -- in lists, tables, etc.  
        >so the buffering behaviour is "OK" but it seems to me the 
        >default is the wrong way round... it ought to act "by default"
        >as if you were writing raw HTML, and unbuffered should
        >be the option ... imho ...

    Yes, you have a point (one of which I'm well aware). My previous response was merely a generalization. I wish your suggestion could have been taken - it's cleaner but it really does lead to clumsier scripts in most cases that I'm familiar with.

  3. Some of the proc names seem really verbose - would you consider shorter names?
    From: De Clarke 
    >I kinda wish you would have used shorter names for some of the cgi_ commands,
    >btw.  cgi_radio would have been fine, and cgi_check.  May I send a list
    >of shorter alternatives to the ones that are beginning to be a pain
    >to type repeatedly?

    Sure go ahead. I must warn you however that some of the long names were intentionally chosen with the idea that users should be making their own procs to call them.

    As an example, I use preformatted text frequently, but I don't use cgi_preformatted frequently. I almost always define my own proc (with a short name like "code") that formats things appropriately and then internally calls cgi_preformatted.

    In other words, the more you find yourself calling some proc of mine, the more you should be writing little procs of your own to automate that call!

    By the way, you can also drop the cgi_ prefix if there are no collisions. For example, "cgi_link" can be written as "link".

    >I still think shorter names for the basic elements like 
    >buttons and so forth would be nice.  many users of CGItcl will 
    >use it, I suspect, exactly as I am now -- as a cleaner, more 
    >aesthetic, way of writing HTML (even for pages that 
    >are not truly "dynamic" and therefore not really 
    >proceduralized).  I've no motivation to wrap all your procs 
    >*except* to shorten their names... in fact, omitting the cgi_ 
    >prefix doesn't appeal to me, whereas having shorter command 
    >names does.  I always use package prefixes where available, to 
    >avoid any future namespace collision (your package collides 
    >with TclX, for example, on at least one proc name).  So 
    >cgi_radio is fine by me, but cgi_radio_button feels like 
    >overkill.  Aw come on, can't I talk you into this?  such
    >a minor change, for a much "friendlier" surface appearance.

    I'm certainly willing to entertain such proposals. I started choosing names when I had little experience doing so. I was worried that I might run into conflicts. HTML is so, uh, stupid in its choice of names that my concerns should be understandable. You just don't know if the next release of HTML will define something called <radio> which would then more logically be cgi_radio.

    I also wanted to avoid confusion. For instance, consider <img> versus <input type=img>. Do you really want cgi_img and cg_image?

    I'm going to think about this some more. I actually reviewed the names before I replied and I see that img/image is really the only awful clash. I really do prefer "cgi_radio" over "cgi_radio_button".

  4. Does a program exist to convert from HTML to Tcl?
    From: Roy Lee 
    Subject: CGI scripts in tcl
    Date: Thu, 11 Dec 1997 14:57:37 +0000
    Does a tcl script exist which will read an existing HTML page and
    covert the tags into the tcl procedures used in cgi.tcl? If the answer
    is no, do you have any interest in developing it? My thoughts are that
    if non technical people can use WYSIWYG editors to create the style
    for a web page, tcl can be used to deliver it more efficiently.

    I have thought about this, too. It's a great idea and I'd love to do it. The missing piece is a robust HTML parser. The best Tcl implementation (Steve Ball's) wasn't robust enough last time I looked. One alternative is to use a C-based parser but I'd rather avoid this if possible. So I've just been waiting.

    If the above tool existed am I right in thinking that it could
    be used as a style sheet and data held in a tcl list or array could be
    presented to a user using it for layout.
    I am not a programmer and whilst the challenge of the above keeps
    nagging at me I am trying to stay focussed on my areas of
    competence. Hence I am looking at ways to use tcl in our product which
    will set it apart from the rest. I know we have a powerful platform
    but we need business focussed applications.
    Roy Lee - WebBox (UK) Ltd
    UK Sales Manager

  5. Is memory usage too high?
    chris meyer  writes:
    >Hello!  I like your cgi.tcl library that you wrote.  Here is a question,
    >and correct me if my assumptions are wrong:
    >Each time a the web server gets a request for a .cgi page, a new tcl
    >process needs to be started to handle the page.  This process takes 2.7mb
    >or ram (that number was provided by a friend who did the experiment). Now,
    >what if the web server gets, say, 100 hits at the same time? Are we out of
    >luck if we our machine doesn't have enough ram? 

    That sounds way too high. This calls for an experiment.

    Ok, I just created 10 simultaneous cgi.tcl processes (virgin tclsh8.0 + cgi.tcl) and it appears that each uses about 575K. This was on my desktop Sun running Solaris. I used vmstat to check memory usage. So to process 100 simultaneous hits, I'd need 57M plus whatever extra is required by my particular CGI scripts. So this isn't much to worry about.

    The time to start the cgi processes is a more realistic concern. I ran another test and on the Linux-Wintel box running our webserver, it took 20msec to run a cgi.tcl script. So it can do 50 cgi.tcl requests a second. If you need faster response for hundreds of processes, consider fcgi.tcl (which lets cgi.tcl use the Fast CGI protocol) and NewWebScript and mod_dtcl (which are embeddings of Tcl directly into the http server).

  6. ISP with Tcl support
    "Jack Shellard"  writes:
    > I am looking for an ISP with cgi-bin and Tcl (8.0)scripting language
    > support.
    > Thanks a lot for any possible advice.

    There are ISPs that provide Tcl but I've found that's an unnecessary restriction. As long as the ISP lets you use your own compiled programs, just load a binary version or compile Tcl and you're good to go.

    In fact, surf over to and click on the "See Tcl script that created this page" links in the examples - you will see #! lines that look like this:


    meaning that they are all driven by a tclsh in my own personal directory.

  7. no code tag?
    Why is there no tag that generates <code></code>?

    <code> is deprecated. I usually do something like this:

    proc code {s} {
        preformatted {put [quote_html $s]}

  8. My cookies had problems on Y2K!

    An early release of cgi.tcl was based on an early release of the cookie specification which only allowed two-digit years. Pretty incredible for a specification written only a few years ago! RFC2109 (dated 2/97) noted the Netscape behavior without comment or improvement.

    Netscape's latest cookie documentation now provides 4-digit years (and makes no mention of RFC2109). So cgi.tcl now uses 4-digit years too. (If you have a cgi.tcl prior to version 1.2.1, you should upgrade.) Of course, if your browser only understands 2 digits, then your browser needs to be upgraded as well.

  9. Some code in your examples accomplishes nothing?
    From: Gerald Bird
    Subject: Suggestion for improvement
    Date: Mon, 07 Aug 2000 21:12:13 -0600
    I have been using your library for a few days now and writing my own cgi
    tcl sripts. One thing that I notice is that this piece of code that you
    use in the creditcard.cgi example (and any other form processing example
    that reads a text input) does not accomplish anything:
    if {[catch {cgi_import expiration}]} {
      user_error "You must enter an expiration."
    It would appear that any text input will import correctly with a value
    of nothing (ie: "") which I am certain is correct and needed. However
    for the above error check, it fails every time. You can of course prove
    this by entering a valid credit card in your example and leaving the
    expiration date blank.
    I have simply changed the code to this and it accomplishes your original
    intention I'm sure:
    if {[catch {cgi_import expiration}] || $expiration == ""} {
      user_error "You must enter an expiration."

    Actually, there's no point in adding the check for a non-empty string since that alone doesn't mean it's a valid expiration. Of course. So why does the code bother to check the import itself? To guard against the script behaving ungracefully (i.e., blowing up) if someone modifies the form so that the expiration isn't sent (or achieves a similar effect with a GET-style URL). Since these are examples, people experiment in just this way - they modify the forms on their site and point them back to the CGI scripts here. I see this all the time. Or at least I used to - when the code would blow up. Due to the built-in error handling, I get email whenever any of these CGI script bombs. So in order to reduce my email, it was in my best interest to make these examples totally bombproof.

  10. Is there more complete documentation than ref.txt?

    A couple of people have told me that were writing books about it (or thinking of writing books about it anyway :-) and Steve Ball covered part of it as part of a much larger book he wrote ("Web Tcl Complete") which I see has very good reviews at Amazon. Last I checked, Steve had the TOC and several chapters of the book on the web so it should be pretty easy for you to evaluate whether it is helpful to you.

    I regret not having time to produce more documentation but it's a huge topic. The current documentation assumes you already know the basics of HTML, CGI, and Tcl. You're right, by itself the ref.txt file is totally inadequate. But then it wasn't meant to be more than a bare reference. It is essential to read and try out the examples. I've tried to make this very easy by making them live and source-viewable and I've put up examples for various tricky things as well as just about everything that people have asked. Please let me know if there are specific examples you would like added.

    PS: I am going to add this question to the FAQ because it's a damn good question. Shucks, maybe it will inspire someone to start (or finish) another book.

    File Upload

  11. Why does file upload return an empty file when the user leaves it empty?

    I agree, it would seem more intuitive not to return anything. File upload always returns something because, well, the browser is returning something although it appears to be useless (i.e., an empty unnamed file). I'm concerned that file upload does this for a reason and that at sometime in the future I'll find out. For example, perhaps it is or will be possible to upload unnamed files, such as from a UNIX pipe. I figure that the file upload implementors had something like this in mind - or at least - giving themselves a little redesign room for the future, so I'm doing the same.

  12. Is it possible to change the default file upload filter?
    To: (John E. Koontz)
    Date: Thu, 6 Mar 1997 18:35:07 -0500
    Incidentally, I noticed also that the browse facility associated
    with the cgi_file_button always seeds the filter with a .../*.html
    pattern.  For us * is probably a better choice, but I don't see any
    way to control that in cgi.tcl.  However, I don't see any way to
    control that in HTML either!

    I noticed this, too. I don't see any way to control it either.

Go to cgi.tcl home page
Names of companies and products, and links to commercial pages are provided in order to adequately specify procedures and equipment used. In no case does such identification imply recommendation or endorsement by the National Institute of Standards and Technology, nor does it imply that the products are necessarily the best available for the purpose.