[Chapter 14] Windows CGI
Author: Stephen Spainhour and Valerie Quercia
Date: Fri Aug 29 18:11:02 1997

#

| Chapter 14 |

# 14. Windows CGI

Contents:
The Windows CGI Framework for Visual Basic
The CGI Data File
Results Processing

Many Windows-based Web servers use a modified CGI interface that allows users to write CGI programs in native Windows programming environments, such as Visual Basic, Delphi, or Visual C++. While many of the CGI basics still apply, WinCGI has its own implementation, covered in this chapter. See Chapter 9, CGI Overview, for basic CGI information.

Since the UNIX concepts of standard input and environment variables are foreign to Microsoft Windows, WinCGI-compliant servers transfer data to the program using external temporary files. CGI programs can then retrieve CGI information directly from these files, or they can use a framework such as the CGI.BAS module supplied for Visual Basic programmers using the WebSite server.

This chapter covers the generic WinCGI interface as well as the variables and functions defined on the WebSite server for Visual Basic programming.

## 14.1 The Windows CGI Framework for Visual Basic

The WebSite server is distributed with CGI.BAS and CGI32.BAS modules, to facilitate CGI programming under (respectively) Visual Basic Version 3 and Visual Basic Version 4. The framework module defines the `Main()` routine of the program, CGI variables for use by the program, and several functions for simplifying CGI programming and error handling.

### The Main( ) Routine

Projects you create for CGI programs that use the framework should be set to start in `Sub Main()` (rather than in a form). When the CGI program starts, it enters at `Main()` in the framework. The framework extracts all of the variables, special request headers, and form content, if any, and stores them in global variables. It also establishes a global exception handler (`On Error`) so that runtime errors in your CGI program are trapped, preventing the CGI program from exiting without producing a response.

Once the CGI environment has been set up, the framework calls a routine called `CGI_Main()` that you must write. This is where your code starts. Always return from CGI_Main(). Never do an abort or exit within a CGI program using the framework.

If the CGI executable is double-clicked, it will not have the correct information on its command line (no INI file). If this happens, the `Main()` routine calls a routine `Inter_Main()`, which you must also write. For most applications, simply display a message box telling the user that this is a CGI program, then exit.

### CGI Variables

The CGI32.BAS module defines variables for use within the CGI program.

#### Information About the Server

Variable name | Description | Data type
--- | --- | ---
`CGI_ServerSoftware` | The name and version of the server software (e.g., WebSite/1.1) | String
`CGI_ServerAdmin` | The email address of the server's administrator | String
`CGI_Version` | The CGI version to which this server complies (e.g., CGI/1.2) | String
`CGI_GMTOffset` | The number of seconds from GMT | Variant

#### Information About the Browser or User

Variable name | Description | Data type
--- | --- | ---
`CGI_RequestProtocol` | The name and revision of the information protocol (e.g., HTTP/1.0) | String
`CGI_Referer` | The URL that referred to the CGI script | String
`CGI_From` | The email address of the user (rarely supplied by the browser) | String
`CGI_RemoteHost` | The hostname of the remote host running the browser | String
`CGI_RemoteAddr` | The IP address of the remote host running the browser | String
`CGI_AcceptTypes` | The CGI accept types | Tuple
`CGI_NumAcceptTypes` | The number of CGI accept types | Integer

#### Executable, Logical, and Physical Paths

Variable name | Description | Data type
--- | --- | ---
`CGI_ExecutablePath` | The path of the CGI program being executed | String
`CGI_LogicalPath` | The logical path or extra path information | String
`CGI_PhysicalPath` | The physical path (i.e., translated version of the logical path) | String

#### Information About the Request

Variable name | Description | Data type
--- | --- | ---
`CGI_RequestMethod` | The method with which the request was made (GET, POST, or HEAD) | String
`CGI_ServerPort` | The port number associated with the request | Integer
`CGI_ServerName` | The server hostname for this request (varies in multi-homed configuration) | String
`CGI_QueryString` | The encoded portion of the URL after the ?, containing GET data or query string (if any) | String
`CGI_ContentFile` | The full pathname of the file containing any attached data (i.e., POST data) | String
`CGI_ContentType` | The MIME content type of requests with attached data (i.e., POST data) | String
`CGI_ContentLength` | The length of the attached data (content file) in bytes | Long
`CGI_FormTuples` | The name=value pairs supplied in form data, if any | Tuple
`CGI_NumFormTuples` | The number of name=value pairs | Integer
`CGI_HugeTuples` | Large name=value pairs | HugeTuple
`CGI_NumHugeTuples` | The number of huge tuples | Integer

#### Security

Variable name | Description | Data type
--- | --- | ---
`CGI_AuthUser` | The name of the authorized user | String
`CGI_AuthPass` | The password of the authorized user (only if enabled) | String
`CGI_AuthType` | The authorization method | String
`CGI_AuthRealm` | The realm of the authorized user | String

#### Miscellaneous

Variable name | Description | Data type
--- | --- | ---
`CGI_ExtraHeaders` | The "extra" headers supplied by the browser | Tuple
`CGI_NumExtraHeaders` | The number of extra headers | Integer
`CGI_OutputFile` | The full pathname of the file in which the server expects the CGI program's response | String
`CGI_DebugMode` | CGI Tracing flag from server | Integer

### Utility Functions

The CGI32.BAS module defines these functions for facilitating CGI programming, which give information about the server:

Routine names | Descriptions | Returns
--- | --- | ---
ErrorHandler() | Global exception handler | n/a
FieldPresent() | Test for the presence of a named form field | T/F
GetSmallField() | Retrieve the contents of a named form field | String
PlusToSpace() | Remove "+" delimiters from a string, converting to spaces | n/a
Send() | Write a string into the output spool file | n/a
SendNoOp() | Send a complete response causing the browser to do nothing, staying on its current page | n/a
Unescape() | Remove URL-escaping from a string, return modified string | String
WebDate() | Return a Web-compliant date/time string (GMT) | String

Configurable Time Formats for SSI Output |  | The CGI Data File