[Chapter 14] Windows CGI

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