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 developers. If you are using another developing 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:

[CGI] [Accept] [System] [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
• From
• 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
• Referer
• 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