Xitami 1.3c

| iMatix home page | Xitami home page | << | < | > | >>

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

http://localhost/cgi-bin/myprog
http://localhost/cgi-bin/myprog.pl
http://localhost/products/install/cgi-bin/myprog

Xitami defines these CGI environment variables:

• For each HTTP header field, inserts a symbol called HTTP_xxxx where xxxx is the header field name. The field names are put into uppercase, and hyphens replaced by underlines.
• For each variable in the query string, inserts a symbol called FORM_xxxx where xxxx is the variable name.
• SERVER_SOFTWARE is the name of the web server.
• SERVER_NAME is the current host name.
• SERVER_PORT is the port on which the web server is running.
• SERVER_PROTOCOL is the HTTP version in use (e.g. "HTTP/1.0").
• GATEWAY_INTERFACE is the CGI version in use (e.g. "CGI/1.1").
• REQUEST_METHOD is the HTTP method used, "GET" or "POST".
• CONTENT_TYPE is the Content-Type: HTTP field.
• CONTENT_LENGTH is the Content-Length: HTTP field.
• REMOTE_USER is the authorised username, if any, else "-"; this will only be set if the user has accessed a protected URL.
• REMOTE_ADDR is the address of the remote host, "x.x.x.x".
• REMOTE_HOST is the same as REMOTE_ADDR. Xitami does not translate host addresses into names.
• SCRIPT_PATH is the path of the script being executed.
• SCRIPT_NAME is the path and name of the script being executed.
• QUERY_STRING is the GET query string, or POST data.
• PATH_INFO is any path data following the CGI URL.
• CGI_STDIN is the CGI standard input filename.
• CGI_STDOUT is the CGI standard output filename.
• CGI_STDERR is the CGI standard error filename, if any.

A CGI program can read its arguments from the stdin file stream; this data is equivalent to the QUERY_STRING variable. Note that in large forms, the QUERY_STRING may not be supplied; we recommend that you use the stdin file stream for such cases. Xitami provides the same data whether you use a GET or a POST method; if you use forms, you must use a POST method.

CGI Programs Under 16-bit Windows

The 16-bit Windows version of Xitami does not support CGI. We expect to be able to provide this in a later release.

CGI Programs Under 32-bit Windows

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

• 16-bit executable .exe files. You do not need to specify the .exe file extension; Windows will correctly locate an .exe file. A bug in Windows 95 (we think) prevents 16-bit CGI programs from working when the Xitami server is installed in a directory containing a long filename.
• 32-bit executable .exe files. The files do not actually need an .exe. extension; Xitami will execute a file with any name so long as it is in the CGI directory and 'looks' like an executable file (precisely: it must start with the letters "MZ").
• Perl programs. The first line of the program must start with the characters "#!" followed by a space and the perl filename. The '.exe' extension is optional. Perl must be installed on your system. For example, if your Perl interpreter is located in c:\tools\perl you could start your Perl program like this:

  #! c:\tools\perl

  You can use '\' or '/' in the path name. The Perl script should be fully specified; Xitami does not assume any kind of extension. Perl programs sometimes end in '.pl'; we recommend you use no extension. To provide compatibility with Perl scripts coming from Unix, Xitami will handle a path like '/usr/bin/perl' by removing '/usr/bin/' and looking for PERL.EXE on the PATH, if /usr/bin/perl does not actually exist as a file.
• Awk scripts, and scripts in other UNIX-type languages that accept comments starting with '#'. Start the script with '#! ' as for Perl.
• Visual Basic programs. Use the CGI_STDIN and CGI_STDOUT environment variables to read the HTTP form data, and write the HTML output. You may want to set cgi:form_fields to 0, since you can pick-up the HTTP form data from the stdin file instead of the environment. Set cgi:form_query to 1 so that you have access to the URL arguments if any.
• Rexx programs. The first line of the program must start with the characters "/*!" followed by a space and the full filename for Rexx. The '.exe' extension is optional. You can close the comment on the same line, but the '*/' must be the last text on the line.
• Batch files, although their usefulness is limited, since MS-DOS has trouble with the HTML characters '<' and '>'.

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

• 16-bit executable .exe files. You do not need to specify the .exe file extension; OS/2 will correctly locate an .exe file.
• 32-bit executable .exe files built using EMX or some similar extender.
• Perl programs. The first line of the program must start with the characters "#!" followed by a space and the full filename for Perl. The '.exe' extension is optional. Perl must be installed on your system. For example, if your Perl interpreter is located in c:\tools\perl you should start your Perl program like this:

  #! c:\tools\perl

  You can use '\' or '/' in the path name. The Perl script should be fully specified; Xitami does not assume any kind of extension. Perl programs sometimes end in '.pl'; we recommend you use no extension. To provide compatibility with Perl scripts coming from Unix, Xitami will handle a path like '/usr/bin/perl' by removing '/usr/bin/' and looking for PERL.EXE on the PATH, if /usr/bin/perl does not actually exist as a file.
• Awk scripts, and scripts in other UNIX-type languages that accept comments starting with '#'. Begin the script with '#! ' as for Perl.
• Shell scripts, starting with the '#!' indicator.
• Rexx programs. The first line of the program must start with the characters "/*!" followed by a space and the full filename for Rexx. The '.exe' extension is optional. You can close the comment on the same line, but the '*/' must be the last text on the line.
• Batch files, although their usefulness is limited, since MS-DOS has trouble with the HTML characters '<' and '>'. To run a batch file you must specify the .bat extension.

We do not know if .com programs will run under OS/2.  

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:

• If the URL starts with '/cgi-bin' this text is removed, and the remainder of the path is attached to the 'cgi-bin' option to give a full path name.
• If the URL does not start with '/cgi-bin', the complete URL path is attached to the 'webpages' directory to give a file path.

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 webserver, 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.

Undetermined error

Something else happened. Cure: tell us about it.

| << | < | > | >>
| Contents | Installation | Administration | Configuration | Using CGI | Image Maps | Virtual Hosting | A Beginner's Guide | FAQ | Technical Implementation | Getting Support | Release History | License Agreement

Designed by Pieter Hintjens © 1997 iMatix