Manual Pages for UNIX Darwin command on man ncgi

ncgi(n) CGI Support ncgi(n)

NAME

ncgi - Procedures to manipulate CGI values.

SYNOPSIS

package require TTccll 88..22 package require nnccggii ??11..22..33?? ::::nnccggii::::ccooookkiiee cookie ::::nnccggii::::ddeeccooddee str ::::nnccggii::::eemmppttyy name ::::nnccggii::::eennccooddee string ::::nnccggii::::hheeaaddeerr ?type? args ::::nnccggii::::iimmppoorrtt cginame ?tclname? ::::nnccggii::::iimmppoorrttAAllll args ::::nnccggii::::iimmppoorrttFFiillee cmd cginame ?filename? ::::nnccggii::::iinnppuutt ?fakeinput? ?fakecookie? ::::nnccggii::::mmuullttiippaarrtt type query ::::nnccggii::::nnvvlliisstt ::::nnccggii::::ppaarrssee ::::nnccggii::::ppaarrsseeMMiimmeeVVaalluuee value ::::nnccggii::::qquueerryy ::::nnccggii::::rreeddiirreecctt url ::::nnccggii::::rreesseett query type ::::nnccggii::::sseettCCooookkiiee args ::::nnccggii::::sseettDDeeffaauullttVVaalluuee key defvalue ::::nnccggii::::sseettDDeeffaauullttVVaalluueeLLiisstt key defvaluelist ::::nnccggii::::sseettVVaalluuee key value ::::nnccggii::::sseettVVaalluueeLLiisstt key valuelist ::::nnccggii::::ttyyppee ::::nnccggii::::uurrllSSttuubb ?url? ::::nnccggii::::vvaalluuee key ?default? ::::nnccggii::::vvaalluueeLLiisstt key ?default?

DESCRIPTION

The nnccggii 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 nnccggii 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 ::::nnccggii::::ppaarrssee and then calls ::::nnccggii::::vvaalluuee to get different form values. If a CGI value is repeated, you should use ::::nnccggii::::vvaalluueeLLiisstt to get back the complete list of values. An alternative to ::::nnccggii::::ppaarrssee is ::::nnccggii::::iinnppuutt, which has semantics similar to Don Libes' ccggiiiinnppuutt procedure. ::::nnccggii::::iinnppuutt restricts repeated CGI values to have names that end with "List". In this case, ::::nnccggii::::vvaalluuee will return the complete list of values, and

::::nnccggii::::iinnppuutt will raise errors if it find repeated form elements with-

out the right name. The ::::nnccggii::::rreesseett 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. ::::nnccggii::::ccooookkiiee 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. ::::nnccggii::::ddeeccooddee str

Decode strings in www-url-encoding, which represents special

characters with a %xx sequence, where xx is the character code

in hex. ::::nnccggii::::eemmppttyy name Returns 1 if the CGI variable name is not present or has the empty string as its value. ::::nnccggii::::eennccooddee string

Encode string into www-url-encoded format.

::::nnccggii::::hheeaaddeerr ?type? 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. The type defaults to "text/html". ::::nnccggii::::iimmppoorrtt 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 (default). ::::nnccggii::::iimmppoorrttAAllll args This imports several CGI variables as Tcl variables. If args is empty, then every CGI value is imported. Otherwise each CGI variable listed in args is imported. ::::nnccggii::::iimmppoorrttFFiillee cmd cginame ?filename? This provides information about an uploaded file from a form input field of type ffiillee with name cginame. cmd can be one of

-sseerrvveerr -cclliieenntt, -ttyyppee or -ddaattaa.

-cclliieenntt cginame

returns the filename as sent by the client.

-ttyyppee cginame

returns the mime type of the uploaded file.

-ddaattaa cginame

returns the contents of the file.

-sseerrvveerr cginame filename

writes the file contents to a local temporary file (or filename if supplied) and returns the name of the file. The caller is responsible for deleting this file after use. ::::nnccggii::::iinnppuutt ?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 values are obtained later with the ::::nnccggii::::vvaalluuee procedure. ::::nnccggii::::mmuullttiippaarrtt type query

This procedure parses a multipart/form-data query. This is used

by ::::nnccggii::::nnvvlliisstt and not normally called directly. It returns

an alternating list of names and structured values. Each struc-

ture value is in turn a list of two elements. The first element

is meta-data from the multipart/form-data structure. The second

element is the form value. If you use ::::nnccggii::::vvaalluuee you just get the form value. If you use ::::nnccggii::::vvaalluueeLLiisstt 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. ::::nnccggii::::nnvvlliisstt This returns all the query data as a name, value list. In the

case of multipart/form-data, the values are structured as

described in ::::nnccggii::::mmuullttiippaarrtt. ::::nnccggii::::ppaarrssee This reads and decodes the CGI values from the environment. The CGI values are obtained later with the ::::nnccggii::::vvaalluuee procedure.

IF a CGI value is repeated, then you should use ::::nnccggii::::vvaall-

uueeLLiisstt to get the complete list of values. ::::nnccggii::::ppaarrsseeMMiimmeeVVaalluuee value

This decodes the Content-Type and other MIME headers 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. ::::nnccggii::::qquueerryy This returns the raw query data. ::::nnccggii::::rreeddiirreecctt 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 redi-

rect. The URL will be qualified with the current server and current directory, if necessary, to convert it into a full URL. ::::nnccggii::::rreesseett 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

environment variables to get its data. If neither query or type are specified, then the nnccggii module will look in the standard CGI environment for its data. ::::nnccggii::::sseettCCooookkiiee args Set a cookie value that will be returned as part of the reply. This must be done before ::::nnccggii::::hheeaaddeerr or ::::nnccggii::::rreeddiirreecctt is called in order for the cookie to be returned properly. The args are a set of flags and values:

-nnaammee name

-vvaalluuee value

-eexxppiirreess date

-ppaatthh path restriction

-ddoommaaiinn domain restriction

::::nnccggii::::sseettDDeeffaauullttVVaalluuee key defvalue Set a CGI value if it does not already exists. This affects future calls to ::::nnccggii::::vvaalluuee (but not future calls to ::::nnccggii::::nnvvlliisstt). If the CGI value already is present, then this procedure has no side effects. ::::nnccggii::::sseettDDeeffaauullttVVaalluueeLLiisstt key defvaluelist Like ::::nnccggii::::sseettDDeeffaauullttVVaalluuee except that the value already has

list structure to represent multiple checkboxes or a multi-

selection. ::::nnccggii::::sseettVVaalluuee key value Set a CGI value, overriding whatever was present in the CGI environment already. This affects future calls to ::::nnccggii::::vvaalluuee (but not future calls to ::::nnccggii::::nnvvlliisstt). ::::nnccggii::::sseettVVaalluueeLLiisstt key valuelist Like ::::nnccggii::::sseettVVaalluuee except that the value already has list

structure to represent multiple checkboxes or a multi-selection.

::::nnccggii::::ttyyppee

Returns the Content-Type of the current CGI values.

::::nnccggii::::uurrllSSttuubb ?url? Returns the current URL, but without the protocol, server, and

port. If url is specified, then it defines the URL for the cur-

rent session. That value will be returned by future calls to ::::nnccggii::::uurrllSSttuubb ::::nnccggii::::vvaalluuee key ?default? Return the CGI value identified by key. If the CGI value is not present, then the default value is returned instead. This value defaults to the empty string. If the form value key is repeated, then there are two cases: if ::::nnccggii::::ppaarrssee was called, then ::::nnccggii::::vvaalluuee only returns the first value associated with key. If ::::nnccggii::::iinnppuutt was called, then ::::nnccggii::::vvaalluuee 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, then use

::::nnccggii::::vvaalluueeLLiisstt. ::::nnccggii::::vvaalluueeLLiisstt key ?default? Like ::::nnccggii::::vvaalluuee, but this always returns a list of values

(even if there is only one value). In the case of multi-

part/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.