Webmaster in a Nutshell

Previous Chapter 14 Next
 

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


Previous Home Next
Configurable Time Formats for SSI Output Book Index The CGI Data File

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