NAME

       ::ncgi - Procedures to manipulate CGI values.


SYNOPSIS

_________________________________________________________________

       ncgi::cookie cookie

       ncgi::decode str

       ncgi::empty name

       ncgi::encode string

       ncgi::header {type text/html} args

       ncgi::import cginame {tclname {}}

       ncgi::importAll args

       ncgi::input {fakeinput {}} {fakecookie {}}

       ncgi::multipart type query

       ncgi::nvlist

       ncgi::parse

       ncgi::parseMimeValue value

       ncgi::query

       ncgi::redirect url

       ncgi::reset args

       ncgi::setCookie args

       ncgi::setDefaultValue key defvalue

       ncgi::setDefaultValueList key defvaluelist

       ncgi::setValue key value

       ncgi::setValueList key valuelist

       ncgi::type

       ncgi::urlStub {url {}}

       ncgi::value key {default {}}

_________________________________________________________________


DESCRIPTION

       The  ::ncgi  package provides commands that manipulate CGI
       values.  These are values that come from Web forms and are
       processed either by CGI scripts or web pages with embedded
       Tcl code.  Use the ::ncgi package to query  these  values,
       set and get cookies, and encode and decode www-url-encoded
       values.

       In the simplest case, a CGI script first calls ncgi::parse
       and  then  calls ncgi::value to get different form values.
       If a CGI value is repeated, you should use ncgi::valueList
       to get back the complete list of values.

       An  alternative  to  ncgi::parse is ncgi::input, which has
       semantics  similar  to  Don  Libes'  cgi_input  procedure.
       ncgi::input  restricts  repeated  CGI values to have names
       that end with "List".   In  this  case,  ncgi::value  will
       return  the  complete list of values, and ncgi::input will
       raise errors if it find repeated form elements without the
       right name.

       The  ncgi::reset  procedure can be used in test suites and
       Web servers to initialize the source of  the  CGI  values.
       Otherwise the values are read in from the CGI environment.

       The complete set of procedures is described below.

       ncgi::cookie cookie
              Return a list of values for cookie, if any.  It  is
              possible  that  more  than one cookie with the same
              name can be present, so this  procedure  returns  a
              list.

       ncgi::decode str
              Decode  strings  in  www-url-encoding, which repre­
              sents special characters with a %xx sequence, where
              xx is the character code in hex.

       ncgi::empty name
              Returns  1  if the CGI variable name is not present
              or has the empty string as its value.

              Encode string into www-url-encoded format.

       ncgi::header {type text/html} args
              Output the CGI header  to  standard  output.   This
              emits a Content-Type: header and additional headers
              based on args, which is a list of header names  and
              header values.

       ncgi::import cginame {tclname {}}
              This  creates  a variable in the current scope with
              the value of the CGI variable cginame.  The name of
              the  variable  is tclname, or cginame if tclname is
              empty.

       ncgi::importAll args
              This imports several CGI  variables  as  Tcl  vari­
              ables.   If  args  is empty, then every CGI vale is
              imported.  Otherwise each CGI  variable  listed  in
              args is imported.

       ncgi::input {fakeinput {}} {fakecookie {}}
              This  reads  and  decodes  the  CGI values from the
              environment.  It restricts repeated form values  to
              have a trailing "List" in their name.  The CGI val­
              ues are obtained later with the ncgi::value  proce­
              dure.

       ncgi::multipart type query
              This  procedure parses a multipart/form-data query.
              This is  used  by  ncgi::nvlist  and  not  normally
              called directly.  It returns an alternating list of
              names and structured values.  Each structure  value
              is  in turn a list of two elements.  The first ele­
              ment  is  meta-data  from  the  multipart/form-data
              structure.   The  second element is the form value.
              If you use ncgi::value you just get the form value.
              If  you  use ncgi::valueList you get the structured
              value with meta data and the value.

              The type is the whole Content-Type,  including  the
              parameters  like  boundary.  This returns a list of
              names and values that describe the multipart  data.
              The  values  are  a  nested list structure that has
              some descriptive information first, and the  actual
              form  value second.  The descriptive information is
              list of header names and values that  describe  the
              content.

              This  returns  all  the query data as a name, value
              list.  In the case of multipart/form-data, the val­
              ues are structured as described in ncgi::multipart.

       ncgi::parse
              This reads and decodes  the  CGI  values  from  the
              environment.   The  CGI  values  are obtained later
              with the ncgi::value procedure.  IF a CGI value  is
              repeated,  then  you  should use ncgi::valueList to
              get the complete list of values.

       ncgi::parseMimeValue value
              This decodes the Content-Type and other MIME  head­
              ers   that   have   the  form  of  "primary  value;
              param=val; p2=v2" It  returns  a  list,  where  the
              first  element is the primary value, and the second
              element is a list of parameter names and values.

       ncgi::query
              This returns the raw query data.

       ncgi::redirect url
              Generate a response that causes a 302  redirect  by
              the Web server.  The url is the new URL that is the
              target of the redirect.  The URL will be  qualified
              with  the  current server and current directory, if
              necessary, to convert it into a full URL.

       ncgi::reset query type
              Set the query data and Content-Type for the current
              CGI session.  This is used by the test suite and by
              Web servers to initialize the  ncgi  module  so  it
              does not try to read standard input or use environ­
              ment variables to get its data.  If  neither  query
              or  type  are  specified, then the ncgi module will
              look in the standard CGI environment for its  data.

       ncgi::setCookie args
              Set a cookie value that will be returned as part of
              the reply.  This must be done  before  ncgi::header
              or ncgi::redirect is called in order for the cookie
              to be returned properly.  The args  are  a  set  of
              flags and values:

              -name name
              -value value

              -path path restriction
              -domain domain restriction

       ncgi::setDefaultValue key defvalue
              Set  a  CGI  value  if  it does not already exists.
              This affects future calls to ncgi::value  (but  not
              future  calls  to  ncgi::nvlist).  If the CGI value
              already is present, then this procedure has no side
              effects.

       ncgi::setDefaultValueList key defvaluelist
              Like  ncgi::setDefaultValue  except  that the value
              already has list structure  to  represent  multiple
              checkboxes or a multi-selection.

       ncgi::setValue key value
              Set a CGI value, overriding whatever was present in
              the CGI environment already.  This  affects  future
              calls  to  ncgi::value  (but  not  future  calls to
              ncgi::nvlist).

       ncgi::setValueList key valuelist
              Like ncgi::setValue except that the  value  already
              has list structure to represent multiple checkboxes
              or a multi-selection.

       ncgi::type
              Returns the Content-Type of the current CGI values.

       ncgi::urlStub {url {}}
              Returns  the current URL, but without the protocol,
              server, and port.  If url  is  specified,  then  it
              defines  the  URL  for  the  current session.  That
              value  will  be  returned  by   future   calls   to
              ncgi::urlStub

       ncgi::value key {default {}}
              Return the CGI value identified by key.  If the CGI
              value is not present, then  the  default  value  is
              returned   instead.   If  the  form  value  key  is
              repeated, then there are two cases:  if ncgi::parse
              was called, then ncgi::value only returns the first
              value associated  with  key.   If  ncgi::input  was
              called,  then  ncgi::value returns a Tcl list value
              and key must end in "List" (e.g.,  "skuList").   In
              the  case  of  multipart/form-data,  this procedure
              just returns the value of the form element.  If you
              want the meta-data associated with each form value,


       ncgi::valueList key {default {}}
              Like ncgi::value, but this always returns a list of
              values  (even  if there is only one value).  In the
              case of multipart/form-data, this procedure returns
              a list of two elements.  The first element is meta-
              data in the form of a parameter, value  list.   The
              second element is the form value.


SEE ALSO

       html


KEYWORDS

       CGI, form, html, cookie


Man(1) output converted with man2html