The Common Gateway Interface
                     THE COMMON GATEWAY INTERFACE
                                   
   After reading this document, you should have an overall idea of
   what a CGI program needs to do to function.
   ___________________________________
   
How do I get information from the server?

   Each time a client requests the URL[1] corresponding to your CGI
   program, the server will execute it in real-time. The output of
   your program will go more or less directly to the client.
   
   A common misconception about CGI is that you can send command-line
   options and arguments to your program, such as
   
     command% myprog -qa blorf

   CGI uses the command line for other purposes and thus this is not
   directly possible. Instead, CGI uses environment variables to send
   your program its parameters. The two major environment variables
   you will use for this purpose are:
   
       QUERY_STRING
      
          QUERY_STRING is defined as anything which follows the first
      ? in     the URL. This information could be     added either by
      an ISINDEX document, or by an HTML     form (with the GET
      action)[2]. It could also be manually embedded     in an HTML
      anchor which references your gateway. This string will
      usually be an information query, i.e. what the user wants to
      search for in the archie databases, or perhaps the encoded
      results     of your feedback GET form.
      
          This string is encoded in the standard URL[3]     format of
      changing spaces to +, and encoding special characters     with
      %xx hexadecimal encoding. You will need to decode it in order
       to use it.
      
          If your gateway is not decoding results from a FORM, you
      will also     get the query string decoded for you onto the
      command line. This     means that each word of the query string
      will be in a different     section of ARGV. For example, the
      query string "forms rule" would     be given to your program
      with argv[1]="forms" and     argv[2]="rule". If you choose to
      use this, you do not need to do     any processing on the data
      before using it.
      
       PATH_INFO
      
          CGI allows for extra information to be embedded in the URL
      for     your gateway which can be used to transmit extra
      context-specific     information to the scripts. This
      information is usually made     available as "extra" information
      after the path of your gateway in     the URL. This information
      is not encoded by the server in any     way.
      
          The most useful example of PATH_INFO is transmitting
      file locations to the CGI program.      To illustrate this,
      let's say I have a CGI program on my server     called
      /cgi-bin/foobar that can process files     residing in the
      DocumentRoot of the server.     I need to be able to tell foobar
      which file to process.     By including extra path information
      to the end of the URL, foobar     will know the location of the
      document relative to the DocumentRoot via     the PATH_INFO
      environment variable, or the actual path     to the document via
      the PATH_TRANSLATED environment variable     which the server
      generates for you.
      
      
      
   
   ___________________________________
   
How do I send my document back to the client?

   I have found that the most common error in beginners' CGI programs
   is not properly formatting the output so the server can understand
   it.
   
   CGI programs can return a myriad of document types. They can send
   back an image to the client, and HTML document, a plaintext
   document, or perhaps even an audio clip. They can also return
   references to other documents. The client must know what kind of
   document you're sending it so it can present it accordingly. In
   order for the client to know this, your CGI program must tell the
   server what type of document it is returning.
   
   In order to tell the server what kind of document you are sending
   back, whether it be a full document or a reference to one, CGI
   requires you to place a short header on your output. This header is
   ASCII text, consisting of lines separated by either linefeeds or
   carriage returns (or both) followed by a single blank line.  The
   output body then follows in whatever native format.
   
       A full document with a corresponding MIME type
      
          In this case, you must tell the server what kind of document
      you     will be outputting via a MIME type.  Common     MIME
      types are things such as text/html for HTML, and     text/plain
      for straight ASCII text.
      
          For example, to send back HTML to the client, your output
      should read:
      
        Content-type: text/html

        <HTML><HEAD>
        <TITLE>output of HTML from CGI script</TITLE>
        </HEAD><BODY>
        <H1>Sample output</H1>
        What do you think of <STRONG>this?</STRONG>
        </BODY></HTML>

       A reference to another document
      
          Instead of outputting the document, you can just tell the
      browser     where to get the new one, or have the server
      automatically output     the new one for you.
      
          For example, say you want to reference a file on your Gopher
          server. In this case, you should know the full URL of what
      you     want to reference and output something like:
      
        Content-type: text/html
        Location: gopher://httprules.foobar.org/0

   <HTML><HEAD>
   <TITLE>Sorry...it moved</TITLE>
   </HEAD><BODY>
   <H1>Go to gopher instead</H1>
   Now available at
   <A HREF="gopher://httprules.foobar.org/0">a new location</A>
   on our gopher server.
   </BODY></HTML>

      However, today's browsers are smart enough to automatically
      throw you to the new document, without ever seeing the above
      since.  If you get lazy and don't want to output the above HTML,
          NCSA HTTPd will output a default one for you to support
      older     browsers.
      
          If you want to reference another file (not protected by
      access authentication) on your own server, you     don't have to
      do nearly as much work. Just     output a partial (virtual) URL,
      such as the following:
      
        Location: /dir1/dir2/myfile.html

      The server will act as if the client had not     requested your
      script, but instead requested
      http://yourserver/dir1/dir2/myfile.html. It will take     care
      of most everything, such as looking up the file type     and
      sending the appropriate headers.  Just be sure that you
      output the second blank line.
      
          If you do want to reference a document that is protected
      by access authentication, you will need to have a full URL
      in the Location:, since the client and the server     need to
      re-transact to establish that you access to the referenced
      document.
      
   Advanced usage: If you would like to output headers such as Expires
   or Content-encoding, you can if your server is compatible with
   CGI/1.1. Just output them along with Location or Content-type and
   they will be sent back to the client.
   
   
   ___________________________________
   [Back]Return to the overview[4]
   
   CGI - Common Gateway Interface
   
                                                  cgi@ncsa.uiuc.edu[5]
                                                                      
   

*** References from this document ***
[orig] http://hoohoo.ncsa.uiuc.edu/cgi/primer.html
[1] http://www.ncsa.uiuc.edu/demoweb/url-primer.html
[2]
http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/fill-out-forms/overview.html
[3] http://www.ncsa.uiuc.edu/demoweb/url-primer.html
[4] http://hoohoo.ncsa.uiuc.edu/cgi/overview.html
[5] http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.htm