| iMatix home page
| Xitami home page
| << | < | > | >>
Xitami Xitami
Version 2.5b6

Using The Common Gateway Interface (CGI)

Xitami supports CGI programs in Perl, C, or any other language that your system supports. In general, CGI program written for web servers such as Apache and NCSA httpd will run unchanged with Xitami.

A 'CGI' program is considered to be any URL with '/cgi-bin' somewhere in the path name. These are all examples of valid CGI program URLs:


Xitami defines these CGI environment variables:

A CGI program can get arguments from a number of places, depending on how Xitami is configured and how the HTTP request is made.

CGI Programs Under 16-bit Windows

The 16-bit Windows version of Xitami does not support CGI.

CGI Programs Under 32-bit Windows

Under Windows 95 and NT, you can run different types of CGI programs:

.com files should run correctly under 32-bit Windows. We recommend that you use 32-bit executable programs, also called 'console programs'. The Windows 32-bit interface is more robust and controlled than the 16-bit interface. One example: if a CGI program loops, Xitami will kill it after a timeout. But: a 16-bit DOS program will not respond to a kill request, and will eventually bring the system down.

CGI Programs Under UNIX

Under UNIX you can run any file that UNIX recognizes as an executable file. This includes linked files, Perl scripts, shell scripts, etc.

CGI Programs Under OS/2

Under OS/2, you can run different types of CGI programs:

When searching for a CGI program to run, if the program specified has no extension Xitami for OS/2 first tries adding a ".exe" extension, then if that fails it tries adding a ".cmd;" extension. If both of those fail, or the program name already has an extension, the name is tried as is; it will be considered executable if it has a ".exe" extension, a ".cmd" extension or the file starts with a "#!" comment line. (REXX scripts and CMD scripts must be stored in files with a ".cmd" extension because that is all the command interpter (CMD.EXE) will accept.)

It is not possible to run DOS executables (".exe" or ".com") or DOS batch files (".bat") under Xitami for OS/2. Nor is it possible to run PM-based programs as CGI programs.  

CGI Directories

You can specify an alternate CGI directory. By default, Xitami will search a subdirectory called 'cgi-bin'. This is how Xitami translates a URL into an absolute file path, when looking for the CGI program:
'cgi-bin' option: URL: Final pathname:
Default /cgi-bin/myprog ./cgi-bin/myprog
Default /cgi-bin/products/myprog ./cgi-bin/products/myprog
Default /products/cgi-bin/myprog ./webpages/products/cgi-bin/myprog
/web/cgibin /cgi-bin/myprog /web/cgibin/myprog
/web/cgibin /cgi-bin/products/myprog /web/cgibin/products/myprog
/web/cgibin /products/cgi-bin/myprog ./webpages/products/cgi-bin/myprog
. /cgi-bin/myprog ./myprog
. /cgi-bin/products/myprog ./products/myprog
. /products/cgi-bin/myprog ./webpages/products/cgi-bin/myprog

This translation works as follows:

Only one of these translations can be done. By consequence, any value you specify for the 'cgi-bin' option is ignored if you place the '/cgi-bin' directory at some deeper level in the URL. This is useful if you intend to mix CGI programs with your HTML files, as complete directories.

CGI Error Messages

Xitami tries to explain why a CGI program fails; these are the different messages you may see for a 500 error, with an explanation for each.

Insufficient resources to run this CGI program

There is not enough memory available. This is a bad sign; it means that the virtual memory available to Xitami is all full. Stop the web server, modify your systems' virtual memory settings, and start it up again. This problem is very rare, really, especially since Xitami is a tiny piece of software.

CGI arguments are too long - request was refused

The CGI URL argument (text following a '?' after the URL) was too long. Whatever you are trying to do, stop it. (Actually, since release 1.2a, Xitami allocates such buffers dynamically, so this error will not occur, and it is now rather difficult to hack Xitami by using buffer overruns.)

Cannot create stdin stream for CGI

Xitami communicates with CGI processes using simple text files; if the file it wants to use already exists and is unavailable to Xitami, it will not be able to run the CGI process. Cure: make sure that you only run one instance of Xitami from one directory. Delete any files called 'tmp...'. Make sure no CGI process is still hanging around, looping but unkillable (typically under Windows 95 or NT with 16-bit CGIs).

Cannot create CGI process - program not found

The CGI program exists (otherwise you get a 402 Not Found), but could not be started correctly. The most common cause of this error is a Perl script which has a misformed magic header line. Make sure that the Perl script starts with "#! perlpath" where perlpath is the full path name of the Perl executable, e.g. "C:\Perl\Perl.exe".

CGI process ended with an error status

The CGI program ran, but returned an error code. Most servers ignore this, but Xitami treats this as an error. Cure: make sure your CGI programs end correctly with a 'return (0)' or equivalent. If you cannot do this, set the configuration option cgi:exit-ok to 0.

CGI process was interrupted before ending

Someone or something interrupted the CGI process before it ended. This can happen when a CGI process takes too long to run, and the system administrator decides that enough is enough, and kills it. Cure: ask your sysadmin to be nice, or write faster CGIs.

Internal server error while running CGI

Something unexpected happened inside Xitami's guts when it tried to run your CGI. Aaaagh! What did you do?! If this happens, let us know how to reproduce it.

Undetermined error

Something else happened. Cure: tell us about it.

| << | < | > | >>
| Welcome To Xitami | Table Of Contents | Installing Xitami | Administration | Configuration | Using The Common Gateway Interface (CGI) | Server-Side Includes (SSI) | Using Filters | Server-Side XML Processing | Server-Side GSL Scripting | Image Maps | Virtual Hosts | The FTP Service | The Dynamic DNS Feature | Throttle Pipes | A Beginner's Guide | Writing Web Server Extension (WSX) Agents | Extending Xitami with External Peer Processes | FAQ | Getting Support | Credits | Release History | License Agreement
Copyright © 1996-2002 iMatix Corporation