| iMatix home page | Xitami home page | << | < | > | >> |
Xitami Version 2.5b4 |
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:
A CGI program can get arguments from a number of places, depending on how Xitami is configured and how the HTTP request is made.
http://hostname/cgi-bin/someprog?var1=value1&var2=value2...
http://hostname/cgi-bin/someprog?arg1+arg2+arg3...
The 16-bit Windows version of Xitami does not support CGI.
Under Windows 95 and NT, you can run different types of CGI programs:
#! c:\tools\perlYou 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=4096This reserves memory for DOS applications, and you should make this setting higher if you have plenty of RAM.
.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.
Under UNIX you can run any file that UNIX recognizes as an executable file. This includes linked files, Perl scripts, shell scripts, etc.
Under OS/2, you can run different types of CGI programs:
d:\os2\cmd.exe /c scriptname
Optionally you can specify a different interpreter for the script by using either:
EXTPROC full-path-to-interpreter flagsin 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
/*! 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.
#! c:\tools\perl.exeor
#! c:\tools\perlYou 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.
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.
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.
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.
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.
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.)
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).
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".
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.
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.
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.
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-99 iMatix Corporation |