CGI & WinCGI Scripts

The Sambar Server CGI implementation is based on the CGI/1.1 specification. CGI enables HTTP server to be extended via server-side applications. Stdin, stdout and environment variables are used to communicate between the HTTP Server and the CGI application.

The Sambar Server only returns the results of the CGI script to the client when the CGI script has completed execution. All output from the CGI script being executed are buffered and returned to the client when the script exits. Future releases may support non-blocking script execution.

CGI & WinCGI Directories

All scripts found in the CGI and WinCGI directories must be executable applications. Using the CGI Extensions and WinCGI Extensions, CGI and WinCGI scripts can be executed from anywhere in the Documents Directory.

CGI applications with the extension .bat, .exe and .pl are recognized and properly executed by the Sambar Server. Files with other extensions require file system association with the appropriate executable (see Using tcl, sh etc. below).

Note: WinCGI is primarily used for Visual Basic applications. The sample provided with this server is a Visual Basic executable. You must have the runtime Visual Basic libraries installed on your system to run this sample.

Important: The installation directory of the Sambar Server may contain spaces (i.e. c:\program files\sambar). May CGI/WinCGI applications especially 16-bit applications or Perl applications that perform file i/o based on the installation directory will not run if there are spaces in the directory path. To execute properly, the Sambar Server must be moved to a directory that has not spaces. This is particularly important for WinCGI Visual Basic applications because the Sambar Server automatically puts quotes around input parameters if the parameters have spaces; Visual Basic improperly interprets these file name parameters.

CGI Directory Location

By default the CGI and WinCGI directories are set to the installation directory of the Sambar Server (cgi-bin and cgi-win respectively). Some sample applications, such as Selana Sol's samples, require that the cgi-bin directory be "in" the documents directory because they modify files relative to docs. To accomodate these applications, the CGI directory can be modified by editing the config.ini file and setting the variable: CGI Directory = /docs/cgi-bin/

CGI Command line options

The command line is used in the case of an ISINDEX query. If the QUERY_STRING environment variable contains only a single parameter with no = character, the parameter is passed to the CGI command on the command line. For example, the following URL /cgi-bin/finger?httpd will execute "finger httpd" on the command line and output the results.

Using Perl

When the Sambar Server executes a Perl CGI application (*.pl files found in the CGI directory), the perl.exe executable found in the perl subdirectory of the Sambar Server installation is used. This perl executable is standard PERL 5.004_02.

For a comprehensive listing of Perl executables and more recent releases the Comprehensive Perl Archive Network is the best source. The CPAN contains the collected wisdom of the Perl community.

To use a newer version or perl, simple copy the perl.exe and associated DLLs to the perl subdirectory of the Sambar Server Installtion.

Note: Many Perl scripts written for UNIX do not run properly with the Sambar Server. Typically, one or more of the following is the issue:

The #!/usr/local/perl/perl notation at the top of the *.cgi file does not map to a valid Perl executable. The notation should be changed to to location of the Perl executable (i.e. #!c:\Program Files\sambar\perl\perl.exe)
The Perl commands used by the script are not supported by the Perl executable (i.e. system() is not supported by all Perl executables).
The Perl package used by the script is not installed (i.e. Graph.pm).
The paths used by the script are not valid or do not exist (i.e. /tmp).

Using tcl, sh etc.

When the Sambar Server executes a CGI application, it uses the DOS shell's OpenProcess() function. To have the Sambar Server recognize file types such as tcl scripts, you must create an open action for the file type (extension). This can be done from the Win95/NT shell, by double clicking on "My Computer" and then selecting View->Options from the menu. A window will appear with a "File Types" tab from which you can add, remove or edit file types. To work with the Sambar Server, you must be able to run the program by double clicking it from the shell.

#! directive

If the file extension is not recognized and there is no interpreter "associated" with the file extension, the Sambar Server will open the file and look for the #! interpreter directive. If found, this directive is used to execute the CGI request. The following is an example of how this directive is used (typically on UNIX systems):

        #!/sambar/distrib/perl/perl

        print "SERVER_PORT: ", $ENV{'SERVER_PORT'};
        print "REMOTE_HOST: ", $ENV{'REMOTE_HOST'};

CGI Interpreter Selection

The Sambar Server attempts to discover the interpreter for the CGI using the following search path (in order):

.pl, .bat and .exe file extensions are associated with by the Sambar Server using their pre-defined interpreters.
Look for a File Association with the extension
Look for an interpreter on the first line of the file (#! syntax)

So, a file association will over-ride any interpreter specified on the first line of the application.

File Associations

As mentioned in the previous section, File Associations are favored for determining the interpreter to associate with CGI-BIN files (with the exception of .exe, .bat and .pl extensions). An easy way to setup file associations is to highlight a file with the extension you want to associate and hold down the Shift key while right-clicking on the file. A new menu item should appear: Open With... Select this menu item and when Windows asks which program to open, select from the list or browse to the correct interpreter, making sure to check always use this program to open this type of file. CGI

Stdout

Stdout is sent to the browser from the execution of the script. Should the script run longer than the maximum configured time (CGI Timeout), no output from the CGI script is returned to the client; a timeout error is returned.

Environment Variables

Environment Variable	Description
SERVER_SOFTWARE	is the name and version of the Sambar Server answering the request.
SERVER_NAME	is the server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.
GATEWAY_INTERFACE	is the revision of the CGI sepcification to which the server complies.
SERVER_PROTOCOL	is the name and revision of the protocol this request came in with.
SERVER_PORT	specifies port to which the request was sent.
REQUEST_METHOD	is the method with which the request was made: "GET", "POST" etc.
QUERY_STRING	is defined as anything following the first '?' in the URL. Typically this data is the encoded results from your GET form. The string is encoded in the standard URL format changing spaces to +, and encoding special characters with %xx hexadecimal encoding.
PATH_INFO	The extra path information, as given by the client.
PATH_TRANSLATED	The server provides a translated version of PATH_INFO, which takes the path and does a virtual-to-physical maping to it.
SCRIPT_NAME	is a virtual path to the script being executed.
REMOTE_HOST	is the host name making the request. If DNS lookup is turned off, the REMOTE_ADDR is set and this variable is unset.
REMOTE_ADDR	is IP address of the remote host making the request.
CONTENT_LENGTH	is length of any attached information from an HTTP POST.
CONTENT_TYPE	is the media type of the posted data (usually application/x-www-form-urlencoded).

Returning Data

CGI programs can return content in many different document types (i.e. text, images, audio). They can also return references to other documents. To tell the server what kind of document you are sending back, CGI requires you to place a short header on your output. This header is ASCII text, consisting of lines separated by either linefeeds or carriage returns (or both) followed by a single blank line. The output body then follows in whatever native format.

If you begin your script output with either "HTTP/" then the Sambar Server will send all output exactly as the script has written it to the client. Otherwise, the Sambar Server will send a default header back (text/html file type) with any data returned from the script. Important: If you do not choose to write the entire HTTP header, you should not provide any special headers, as they will appear as part of the body after Sambar Server processing.

If you begin your script with any of the following:

Content-type:
Location:
Transfer-Encoding:
Last-Modified:
Set-Cookie:

the Sambar Server will append the appropriate HTTP response status (200 or 302) followed by the headers and content of your script exactly as received.

For example, to send back HTML to the client, your output should read:

        Content-type: text/html

        <HTML><HEAD>
        <TITLE>output of HTML from CGI script</TITLE>
        </HEAD><BODY>
        <H1>Sample output</H1>
        Blah, blah, blah.
        </BODY></HTML>

In the above example, the response prepended is: HTTP/1.0 200 OK
To reference a file on another HTTP server, you would output something like this:

        Location: http://www.sambar.com/
        Content-type: text/html

        <HTML><HEAD>
        <TITLE>Whoops...it moved</TITLE>
        </HEAD><BODY>
        <H1>Content Moved!</H1>
        </BODY></HTML>

In the above example, the response prepended is: HTTP/1.0 302 MOVED Important: The Location: directive comes prior to the Content-type: directive.

CGI Status & Stderr

By default, the Sambar Server tests the return status of CGI programs and displays to the client the stderr output from the CGI program if the exit status is not 0. Important: If your CGI application returns a nonzero error code, and does not print an error message to stderr, you will get the following:

	CGI Failure...

	CGI command: C:\Program Files\sambar/cgi-bin/dmailweb.exe
	Failure status: 7858720

	No output was written to stderr...

The CGI exit test is configurable using the configuration parameter CGI Exit Test = true. You can set this to false if your CGI programs do not return an exit status of zero (0) on success.

WinCGI Limitations

The [Form File] Section specified in the WinCGI specification for multipart/form-data is not presently supported. In addition, the [Form Huge] Section for strings more than 65,535 bytes is not presently supported.