Supporting FORMS with CGI

Forms Are Neat. In fact, I might even go so far as to say Forms Are Cool. So
how does one go about decoding their output?

First of all, as Eric Bina once put it, "This is NOT rocket science." If you
are unfamiliar with forms or how to write them, we suggest you look at this
guide to fill-out forms.

-------------------------------------------------------------------------------

Where do I get the form data from?

As you now know, there are two methods which can be used to access your forms.
These methods are GET and POST. Depending on which method you used, you will
recieve the encoded results of the form in a different way.

   *  The GET method

     If your form has METHOD="GET" in its FORM tag, your CGI program will
     recieve the encoded form input in the environment variable QUERY_STRING.

   *  The POST method

     If your form has METHOD="POST" in its FORM tag, your CGI program will
     recieve the encoded form input on stdin. The server will NOT send you an
     EOF on the end of the data, instead you should use the environment
     variable CONTENT_LENGTH to determine how much data you should read from
     stdin.

-------------------------------------------------------------------------------

But what does it all mean? How do I decode the form data?

When you write a form, each of your input items has a NAME tag. When the user
places data in these items in the form, that information is encoded into the
form data. The value each of the input items is given by the user is called the
value.

Form data is a stream of name=value pairs separated by the & character. Each
name=value pair is URL encoded, i.e. spaces are changed into plusses and some
characters are encoded into hexadecimal.

Because others have been presented with this problem as well, there are already
a number of programs which will do this decoding for you. The following are
links into the CGI archive, clicking on them will retrieve the software package
being referred to.

   *  The Bourne Shell: The AA archie gateway. Contains calls to sed and awk
     which convert a GET form data string into separate environment variables.

   *  C: The default scripts for NCSA httpd. While I won't win any awards for
     verbosity in documenting my code, there are C routines and example
     programs you can use to translate the query string into a group of
     structures.

   *  PERL: The PERL CGI-lib. This package contains a group of useful PERL
     routines to decode forms.

   *  TCL: TCL argument processor. This is a set of TCL routines to retrieve
     form data and place it into TCL variables.

The basic procedure is to split the data by the ampersands. Then, for each
name=value pair you get for this, you should URL decode the name, and then the
value, and then do what you like with them.

-------------------------------------------------------------------------------
Rob McCool robm@ncsa.uiuc.edu
