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 developing 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 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 developers 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 developing.
The Windows CGI Framework for Visual Basic
The WebSite server is distributed with CGI.BAS and CGI32.BAS modules, to facilitate CGI developing 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 developing 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 developing, 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 |