Home

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.

Unbuffered CGI

By default, the Sambar Server returns the results of the CGI script to the client as the CGI returns the data. Operating system pipes are used to stream data between the CGI process and server without requiring intermediate buffering. To stream unbuffered output to the client in real-time, Perl scripts must include the following line:

$| = 1;

CGI & WinCGI Directories

All scripts found in the CGI and WinCGI directories must be executable applications with the exception of documents of type: .txt .htm or .html. These document types are recognized as text and are not executed, however, all other document types should be served out of the Documents Directory.

The Sambar Server allows CGI and WinCGI scripts to be executed from anywhere in the Documents Directory by using the CGI Extensions and WinCGI Extensions. CGI's are typically restricted to the cgi-bin or cgi-win directories because UNIX machines tend not to use the document's MIME type to identify executable scripts. The CGI directory provides the "hint" needed by the server. The other reason for restricting CGIs to a particular directory is for security reasons (i.e. only "trusted" users are allowed to post CGIs, but anyone can post content). If neither of these apply to your environment, CGI's can be executed 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 either a interpreter indicator at the top of the file (#!) or a file system association with the appropriate executable (see Using tcl, sh etc. below).

The cgi-bin and cgi-win directories are designed specifically for CGI applications. HTML and text documents must be placed in the docs directory.

Note: WinCGI is primarily used for Visual Basic and Delphi 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. Many thanks to IndigoSTAR Software for permission to redistribute their Perl binaries.

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. Optionally, you can modify the Perl Executable parameter in the config.ini file to point to the location where you have installed the perl.exe. Many Perl installations (ActiveState and CPAN) install perl in /perl/bin by default, so the appropriate modification would be to set:

Perl Executable = c:\perl\bin\perl.exe

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:

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

Prior to using the file extension to find the 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. If an interpreter directive is not found, the FindExecutable() windows API is used to find the file association. The following is an example of how this directive is used (typically on UNIX systems):

#!/sambar/distrib/perl/perl.exe

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):

File Associations

File Associations are used as a last-resort for determining the interpreter to associate with CGI-BIN files. This was modified from earlier releases when the file association method was the preferred mechanism because many users inadvertently associate their file editors with a given file extension. 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 output 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.

Stderr

By default, stderr output is not returned to the browser from the execution of the script. The server can return stderr output in addition to stdout output by editing the config/config.ini file and and setting the CGI stderr parameter to true.

Environment Variables

Environment VariableDescription
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).
DOCUMENT_NAME is the current file name.
DOCUMENT_ROOT is the directory relative to the current virtual host where documents are stored.
DOCUMENT_URI is the virtual path of the current document.
GATEWAY_INTERFACE is the revision of the CGI specification to which the server complies.
HTTP_REFERER is the URL from which the request was made.
HTTP_USER_AGENT is the name of the client browser making the request.
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. Important! Several packages (notably, PHP) have chosen to interpret PATH_TRANSLATED as the physical translated path of the request. To accomodate these applications, PATH_TRANSLATED is mapped to this interpretation if no PATH_INFO is provided.
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.
REMOTE_ADDR is IP address of the remote host making the request.
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.
REQUEST_METHOD is the method with which the request was made: "GET", "POST" etc.
SCRIPT_NAME is a virtual path to the script being executed.
SCRIPT_FILENAME is a physical path to the script being executed.
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.
SERVER_PORT specifies port to which the request was sent.
SERVER_PROTOCOL is the name and revision of the protocol this request came in with.

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:

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.

Maximum Concurrent CGIs

The server can limit consecutive CGI execution to prevent a the system from becoming overloaded by too many CGIs executing (whether malicious or intentional). By default, the maximum number of concurrent CGIs (WinCGI, CGI or WinCMD) is set to 200.

© 1998-2003  Sambar Technologies. All rights reserved. Terms of Use.