Webmaster in a Nutshell

Previous Chapter 14
Windows CGI

14.2 The CGI Data File

The CGI.BAS and CGI32.BAS modules take care of much of the dirty work in CGI processing for Visual Basic programmers. If you are using another programming language or a server other than WebSite, however, you may need to access the external CGI data file manually.

Under WinCGI, the server saves CGI data in an external file to be processed by the CGI program. The CGI data file contains the following sections:

[Extra Headers]
[Form Literal]
[Form External]
[Form File]
[Form Huge]

The CGI Section

The first section of the CGI data file contains most of the CGI data items (accept types, content, and extra headers are defined in separate sections). Each item is provided as a string value. If the value is an empty string, the keyword is omitted. The keywords are listed below:

Authenticated Password

The password that the client used to attempt authentication

Authenticated Username

The username (in the indicated realm) that the client used to attempt authentication

Authentication Method

The protocol-specific authentication method specified in the request

Authentication Realm

The method-specific authentication realm

CGI Version

The revision of the CGI specification to which the server complies

Content File

For requests that have attached data (i.e., in a POST request), 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.

Content Length

For requests that have attached data, the length of the content in bytes

Content Type

For requests that have attached data, the MIME content type of that data

Document Root

The physical path to the logical root "/"

Executable Path

The logical path to the CGI program executable, as needed for self-referencing URLs


The email address of the browser user

Logical Path

The extra path information supplied in the request

Physical Path

If the request contained logical path information, the path in physical (translated) form

Query String

The information that follows the ? in the URL that generated the request is the "query" information


The URL of the document that contained the link pointing to this CGI program

Remote Host

The network host name of the client system, if available

Remote Address

The network (IP) address of the client system

Request Method

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

Request Protocol

The name and revision of the information protocol this request came in with. Format: protocol/revision; Example: "HTTP/1.0"

Request Range

Byte-range specification received with request (if any)

Server Admin

The email address of the server's administrator

Server Name

The network host name or alias of the server, as needed for self-referencing URLs

Server Port

The network port number on which the server is listening, as needed for self-referencing URLs

Server Software

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

User Agent

A string description of the client (browser) software

The Accept Section

The Accept section contains the client's acceptable data types found in the request header as:

Accept: type/subtype [parameters]

The System Section

This section contains items that are specific to the Windows implementation of CGI. The following keys are used:

Content File

The full pathname of the file that contains the content (if any) that came with the request.

Debug Mode

This is No unless the server's script tracing mode is enabled, in which case it is Yes. Useful for providing conditional tracing within the CGI program.

GMT Offset

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

Output File

The full pathname of the file in which the server expects to receive the CGI program's results.

The Extra Headers Section

This section contains the "extra" headers that were included with the request, in key=value form. The server must URL-decode both the key and the value prior to writing them to the CGI data file.

The Form Literal Section

If the request is a POST request from an HTTP form (with content type of application/x-www-form-urlencoded or multipart/form-data), the server decodes the form data and puts it into the Form Literal section.

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.

The Form External Section

If the decoded value string is more than 254 characters long, or if the decoded value string contains any control characters or double-quotes, the server puts the decoded value into an external file and lists the field into the Form External section as:

key=pathname length

where pathname is the path and name of the tempfile containing the decoded value string, and length is the length in bytes of the decoded value string.

The Form Huge Section

If the raw value string is more than 65,535 bytes long, the server does no decoding, but it does get the keyword and mark the location and size of the value in the content file. The server lists the huge field in the Form Huge section as:

key=offset length

where offset is the offset from the beginning of the content file at which the raw value string for this key is located, and length is the length in bytes of the string. You can use the offset to perform a "Seek" to the start of the raw value string, and use the length to know when you have read the entire raw string into your decoder.

The Form File Section

If the request is in the multipart/form-data format, it may contain one or more file uploads. In this case, each file upload is placed into an external temporary file similar to the form external data. Each such file upload is listed in the Form File section as:

key=[pathname] length type xfer [filename]

where pathname is the pathname of the external tempfile containing the uploaded file, length is the length in bytes of the uploaded file, type is the MIME content type of the uploaded file, xfer is the content-transfer encoding of the uploaded file, and filename is the original name of the uploaded file. The square brackets must be included; they are used to delimit the file and pathnames, which may contain spaces.

Example of Form Decoding

In the following sample, the form contains a small field, a SELECT MULTIPLE with 2 small selections, a field with 300 characters in it, one with line breaks (a text area), and a 230KB field:

[Form Literal]
    smallfield=123 Main St. #122
    multiple=first selection
    multiple_1=second selection
[Form External]
    field300chars=C:\TEMP\HS19AF6C.000 300
    fieldwithlinebreaks=C:\TEMP\HS19AF6C.001 43
[Form Huge]
    field230K=C:\TEMP\HS19AF6C.002 276920

Previous Home Next
The Windows CGI Framework for Visual Basic Book Index Results Processing

HTML: The Definitive Guide CGI Programming JavaScript: The Definitive Guide Programming Perl WebMaster in a Nutshell
Hosted by uCoz