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

Xitami Version 2.4d7

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:

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_VERSION is the version of the web server (2.4d7).
• SERVER_NAME is the current host name. This can be overridden by defining a value for server:hostname.
• SERVER_URL holds the full URL to the server.
• 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".
• QUERY_METHOD is same as the REQUEST_METHOD.
• 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_HOST is the same as REMOTE_ADDR. Xitami does not translate host addresses into names.
• REMOTE_ADDR is the address of the remote host, "x.x.x.x".
• SCRIPT_PATH is the path of the script being executed.
• SCRIPT_NAME is the URI of the script being executed.
• QUERY_STRING is the query string following the URL.
• PATH_INFO is any path data following the CGI URL.
• PATH_TRANSLATED is the full translated path with URL arguments.
• CGI_ROOT is the CGI binary directory.
• 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.
• DOCUMENT_ROOT is the main webpages root directory.

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

• For GET requests, it is usual to follow the URL with '?' and some arguments. These are passed to the CGI program in the QUERY_STRING variable. The standard format for passing a number of variables in this way is (e.g.):

  http://hostname/cgi-bin/someprog?var1=value1&var2=value2...
  

• If the arguments do not contain '=', they are broken into separate arguments and passed to the CGI program that way too. Each '+' in the query string is used as a separator. This may be used in a URL like this:

  http://hostname/cgi-bin/someprog?arg1+arg2+arg3...
  

• Larger amounts of data should be passed using the POST method, in which case the CGI program reads the data from its stdin stream. (You can also configure Xitami to pass these in the QUERY_STRING variable if the data is not too large).

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:

• 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. You can increase the speed of Perl CGI programs under Windows 95 by adding this definition to your system.ini file (this may also work under NT; we've not tested it):

  [NonWindowsApp]
      CommandEnvSize=4096
  

  This reserves memory for DOS applications, and you should make this setting higher if you have plenty of RAM.
• 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. Set cgi:stdio to 0 so that your CGI program has full access to the input and output files.
• 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:

• 32-bit (and 16-bit) command-line based executable ".exe" files. You do not need to specify the ".exe" file extension in the URL; Xitami for OS/2 will correctly locate an ".exe" CGI program. Starting PM-based executable files through CGI is not supported.
• REXX (and CMD) scripts. These files must have a ".cmd" extension, but this does not have to be specified in the URL unless there is an executable (".exe") of the same name in the directory (see the details of the search order below). By default the script will be run by running the program specified in the COMSPEC environment variable, followed by "/c scriptname", so if your COMSPEC variable is set to "d:\os2\cmd.exe" then it will be run as:

  d:\os2\cmd.exe /c scriptname

  Optionally you can specify a different interpreter for the script by using either:

  • The OS/2 EXTPROC syntax:

    EXTPROC full-path-to-interpreter flags

    in the first line of the script file (Xitami will accept flags at the end of the EXTPROC line by some other programs may not; test carefully); or
  • A special REXX comment:

    /*! full-path-to-interpreter flags */

    in the first line of the script file. You can use the standard OS/2 command interpreter (CMD.EXE) as the interpreter for REXX, but if you do then you must specify "/c" as one of the flags to ensure the command interpreter exits as soon as the CGI script finishes running.

  Remember the REXX scripts are identified by the "/*" comment in their first line. The full-path-to-interpreter should specify the full filename (drive (if it is not on the same drive as everything else), path, and filename) of the interpreter to use.

• Perl programs. The first line of the program must start with the characters "#!" followed by a space and the full filename for Perl. For example if your perl interpreter is "c:\tools\perl.exe" you should start your Perl program like this:

  #! c:\tools\perl.exe

  or

  #! c:\tools\perl

  You can use '\' or '/' in the path name. The programs are best stored in a file without an extension, or in a file with a ".cmd" extension; if you use another extension you will need to specify the whole filename (including the extension) in the URL. Perl must be installed on your system. Perl 5.004 is recommended. If your perl script uses special features make sure you are running the correct perl executable (check the Perl 5.004 for OS/2 documentation) for the features you require.
• Awk scripts, and scripts in other UNIX-type languages that accept comments starting with '#'. Begin the script with '#! ' as for Perl.

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:

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

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) | Using SSI and Filters | Image Maps | Virtual Hosts | The FTP Service | A Beginner's Guide | Writing Web Server Extension (WSX) Agents | Extending Xitami with External Peer Processes | FAQ | Technical Implementation | Getting Support | Release History | License Agreement

Copyright © 1996-99 iMatix Corporation