


cgi(n)                         Tcl Extensions                          cgi(n)



Name
  cgi - HTTP Common Gateway Interface support for Tcl

Syntax
  ccggii__ggeett__qquueerryy ?--ttiimmeeoouutt _s_e_c_o_n_d_s?
  ccggii__ppaarrssee__qquueerryy ?--ssttrriipp?  ?--lliisstt?  _q_u_e_r_y _a_r_r_a_y ?_l_i_s_t-_v_a_r...?

Description
  CCGGII is an extension for Tcl that implements parts of the HTTP Server Common
  Gateway Interface.  The resulting Tcl shell is useful for executing scripts
  invoked by the http daemon.  HTTP is the transport protocol for the World
  Wide Web (WWW).

  Two commands are implemented, one for getting the query from the server,
  and the other for parsing the query.

  ccggii__ggeett__qquueerryy ?--ttiimmeeoouutt _s_e_c_o_n_d_s?

  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.

  If the query is read from standard input, ccggii__ggeett__qquueerryy will wait 10
  seconds after the last input was received for the entire query to be
  received.  This delay is important for slow network connections, where the
  data may arrive in several widely-spaced TCP segments.  The default timeout
  can be changed by giving the --ttiimmeeoouutt _s_e_c_o_n_d_s option.

  ccggii__ppaarrssee__qquueerryy ?--ssttrriipp? ?--lliisstt? _q_u_e_r_y _a_r_r_a_y ?_l_i_s_t-_v_a_r...?

  Parses a URL-encoded query and assigns each NAME=VALUE pair into the array.
  _i._e., _a_r_r_a_y(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 _l_i_s_t-_v_a_r's, the VALUE is appended as a list element to the
  array element.

  The --lliisstt option causes all VALUEs to be added to _a_r_r_a_y(NAME) as list ele-
  ments.  It is useful when it is not known ahead of time which query ele-
  ments should be treated as lists, such as when the HTML form is
  dynamically-generated.  Note that non-list values must be extracted using
  the Tcl lliinnddeexx command.

  The --ssttrriipp option causes all non-printing, non-whitespace characters to be
  removed from the query values.

Usage
  The expected usage is to create a Tcl interpreter (which I call tcl_cgi),
  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 [cgi_get_query] Q
       set file [open {|/usr/ucb/mail -s "Comments..." smith@bigmax} w]
       puts $file "Comments from $Q(NAME) (at $env(REMOTE_HOST)):0
       puts $file $Q(COMMENTS)
       close $file
       puts {Content-type: text/html

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


Error Messages
  From ccggii__ggeett__qquueerryy:

  Invalid timeout value: XXX
       A non-integer or negative value was given for the --ttiimmeeoouutt option.

  Invalid CONTENT_LENGTH: XXX
       CONTENT_LENGTH contained a non-integer or negative value.

  Usage: cgi_get_query ?-timeout seconds?
       Bad options.

  Can't call cgi_get_query more than once
       You tried to call ccggii__ggeett__qquueerryy a second time.

  XXXX not set
       The environment variable REQUEST_METHOD, QUERY_STRING, or
       CONTENT_LENGTH wasn't set by _h_t_t_p_d.

  malloc failure (XXX bytes)
       Couldn't allocate memory for buffering the incoming query.

  stdin: UNIX ERROR
       A system error occurred during the select or read system calls.  A
       standard Unix error message is appended.

  Couldn't read HTTP query: Expected XXX bytes, but only got YYY bytes
       While reading the query from standard input, no input was received for
       10 seconds, and the query was still incomplete.

  Unsupported REQUEST_METHOD "XXX"
       A REQUEST_METHOD other than GET or POST was encountered.

  From ccggii__ppaarrssee__qquueerryy:

  cgi_parse_query: unknown option "XXX"
       Bad options.

  Usage: cgi_parse_query [-strip] query array [list-names...]
       Bad options.

  Missing "=" in query
       Each NAME=VALUE pair is required to contain the equal sign, even if
       VALUE isn't present.

  Tcl errors may occur when attempting to set elements of the _a_r_r_a_y.




Restrictions
  Some Unix kernels only handle interpreter file names (the "shell" after #!)
  of about 24 bytes in length.  This causes mysterious failures: your Tcl
  script will be executed by sh if the interpreter name is too long.  In par-
  ticular, you will probably exceed this limit if you put the interpreter in
  the conventional httpd location: //uussrr//llooccaall//eettcc//hhttttppdd//ssuuppppoorrtt//ttccll__ccggii.

  It is important to test for and handle errors from these functions, other-
  wise the user may get an incomprehensible error message.































































