Windows CGI for TCL

CGIRead filename

Process the WinCGI ini file, setting up all submitted variables. When the TCL script is started, the first argument is the WinCGI ini file.

CGIValue key

Return the value of a submitted data item. Key is the submitted data name.

CGICookie key

Return the value of a submitted cookie item. Key is the submitted cookie name.

CGIAccept key

Return yes/no settings for what the client can support. Key is the MIME type.

CGISystem key

Return system information such as client browser identifier etc. Key is the argument name

CGIExist Section Key

Return 1 if the CGI Submission included an element named Key in the specified Section. Section can be one of System, Value or Cookie.

CGIDebug option local | remote

A mechanism to display all of the submitted information.

CGIDebug local

display to the standard out of TCL

GCIDebug remote

display back to the client browser. No HTML tags are present in this display, so the programmer must ensure correct HTML wrappers are included.

CGIWrite ?-nonewline? string

Place the string into the data stream going back to the client browser.

CGINames ?pattern?

Return the list of submitted variable names that match the glob style pattern. These variable names come from the CGIValue group.

WinCGI Package specification

1. SYSTEM - all settings for the current server/client/script interaction.
2. ACCEPT - all of the MIME types that the client will accept.
3. COOKIE - all of the values submitted by cookies.
4. VALUES - all of the variables and values that were submitted by the client. This includes the "Form Literal", "Form External" and "Query String" from the Windows CGI Specification.

Section SYSTEM

Request Protocol

The name and revision of the information protocol this request came in with.

Format: protocol/revision.
Example: "HTTP/1.0".

Request Method

The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc.

Executable Path

The logical path to the CGI program executable, as needed for self-referencing URLs. This may vary if the server supports multi-homing with separate logical path spaces. The server must provide the physical path equivalent using the logical to physical mapping for the identity on which the current request was received.

Document Root

The physical path to the logical root "/". This may vary if the server supports multi-homing with separate logical path spaces. The server must provide the physical path to the logical root for the identity on which the current request was received.

Logical Path

A request may specify a path to a resource needed to complete that request. This path may be in a logical pathname space. This item contains the pathname exactly as received by the server, without logical-to-physical translation.

Physical Path

If the request contained logical path information, the server provides the path in physical form, in the native object (e.g., file) access syntax of the operating system. This may vary if the server supports multi-homing with separate logical path spaces. The server must provide the physical path equivalent using the logical to physical mapping for the identity on which the current request was received.

Query String

The information which follows the ? in the URL that generated the request is the "query" information. The server furnishes this to the back end whenever it is present on the request URL, without any decoding or translation, and the WinCGI package performs the URL decoding on this string. This string is fully URL Decoded when returned from the WinCGI Package.

Request Range

Byte-range specification received with request (if any). See the current Internet Draft (or RFC) describing the byte-range extension to HTTP for more information. The server must support CGI program participation in byte-ranging to be compliant with this Specification.

Referrer

The URL of the document that contained the link pointing to this CGI program. Note that in some browsers the implementation of this is broken, and cannot be relied-on.

From

The e-mail address of the browser user. Note that this is in the HTTP specification but is not implemented in some browsers due to privacy concerns.

User Agent

A string description of the client (browser) software. Not generated by all browsers.

Content Type

For requests which have attached data this is the MIME content type of that data. Format: type/subtype.

Content Length

For requests which have attached data, this is the length of the content in bytes.

Content File

For requests which have attached data, the server makes the data available to the CGI program by putting it into this file. The value of this item is the complete pathname of that file.

Server Software

The name and version of the information server software answering the request (and running the CGI program). Format: name/version.

Server Name

The network host name or alias of the server, as needed for self-referencing URLs. This (in combination with the ServerPort) could be used to manufacture a full URL to the server, for URL fixups. This may vary if the server supports multi-homing. The value of this item must be the host name on which the current request was received.

Server Port

The network port number on which the server is listening. This is also needed for self-referencing URLs.

Server Admin

The e-mail address of the server's administrator. This is used in error messages, and might be used to send MAPI mail to the administrator, or to form "mailto:" URLs in generated documents.

CGI Version

The revision of the CGI specification to which this server complies. Format: CGI/revision. For this version, "CGI/1.2 (Win)".

Remote Host

The network host name of the client (requester) system, if available. This item is used for logging.

Remote Address

The network (IP) address of the client (requester) system. This item is used for logging if the host name is not available.

Authentication Method

The protocol-specific authentication method specified in the request. If present, this is normally Basic. The server must provide this whether or not it was used by the server for authentication.

Authentication Realm

The method-specific authentication realm specified in the request. If present in the request, the server must provide this whether or not it was used by the server for authentication.

Authenticated Username

The username (in the indicated realm) that the client used to attempt authentication, as specified in the request. If present in the request, the server must provide this whether or not it was used by the server for authentication.

Authenticated Password

The password that the client used to attempt authentication, as specified in the request. If present in the request, the server must provide this whether or not it was used by the server for authentication.

GMT Offset

The number of seconds to be added to GMT time to reach local time. For pacific Standard time, this number is -28,800. Useful for computing GMT times.

Unique

A file name without an extension or path that is unique within the scope of all outstanding CGI requests.

Output File

The tcl channel ID of the open output file. This channel must not be closed until then end of processing, or automatically by termination of the tcl shell. This is the channel that CGIWrite writes to. If the parent script needs to write to the outgoing channel ID, it should write to this channel ID.

Section ACCEPT

This section contains the client's acceptable data types found in the request header as

Accept: type/subtype {parameters}

If the parameters (e.g., "q=0.100") are present, they are passed as the value of the item. If there are no parameters, the value is "Yes".

Section VALUE

If the request is an HTTP POST or GET from an HTTP form (with content type of application/x-www-form-urlencoded or multipart/form-data), the server will decode the form data and put it into the VALUE section.

Both the variable names and the submitted data are URL Decoded before being placed into this section. All TCL escape sequences are generated so that the TCL operations work with the intended data.

If the form contains any SELECT MULTIPLE elements, there will be multiple occurrences of the same key. In this case, the server generates a normal "key=value" pair for the first occurrence, and it appends a sequence number to subsequent occurrences in the form name_X where X is an integer. The WinCGI Package decodes all of these and generates a TCL list as the value for the variable. It should be noted that if only one selection is made, the submitted field only occurs once, and can not be detected as a SELECT MULTIPLE field. The result is that the value of the field is NOT a TCL List until the second value gets added.

WARNING: If only one selection is made in a SELECT MULTIPLE field, AND the value of the single selection contains spaces, it is impossible to differentiate between this single multi-word selection and a multiple selection of these single words. It is recommended that all SELECT MULTIPLE values do not contain spaces.

The "Query String" from the section SYSTEM is URL decoded and any resulting values are placed in this section as well.

Section COOKIE

The kel=value pairs for all of the cookies that the http client has submitted to the http server.

Both the variable names and the submitted data are URL Decoded before being placed into this section. All TCL escape sequences are generated so that the TCL operations work with the intended data.

Revision History

2.4 Dec 2000.

• Added the parsing of cookie values and created the CGICookie routine.
• Added the CGIExist routine to test for the submission of an element.

2.3 Feb 1999.

• fixed a bug in CGIWrite that didn't accept the -nonewline option like puts.

2.2.1 Sept 1998.

• Due to a bug in WebSite web server 1.1h that does not decode multi value variables correctly, had to process the raw "Content File". The exact error is: If the web client submits multi value variables with other variables inbetween, then WebSite resets the name_x counter and starts replacing variables starting with name, then name_1, then name_2 etc.

2.2 July 11, 1998.

• Fixed a bug that incorectly decoded CGI escape sequences.

2.1

• Overcame a slight problem where multiple select items might be processed out of sequence. Now it does not matter what sequence they are processed in.

2.0

• First release