OLD Server Script Support

W3C httpd versions 2.15 and newer implement the Common Gateway Interface, CGI. CGI interface should be favoured over this old one.

However, if you are running you server on a VMS machine, a port of CGI/1.0 code does not yet (February 1994) exist for it, so you can only use this one.

Important Note

If you are running httpd 2.15 or newer, old-style script filenames must end with .pp suffix. This allows the server to figure out the correct calling scheme. If you are running older version of httpd where you only have the old-style script interface, scripts should not end in .pp.

The URLs referring to these scripts should never contain the .pp suffix. This makes it easier to later upgrade the script to CGI/1.0 without having to change the documents referring to it.

Upgrading To httpd 2.15

If you have old-style scripts that work fine under 2.13 or 2.14, you only have to rename them to end with .pp suffix. Nothing else needs to be changed -- references to these files are still made with URLs not ending in .pp, so all old links still work.

Invoking A Script

Scripts are called by the server when the URL begins with the string /htbin/. The next pathname component is taken to be the script name. Rest of the URL is passed to the script as the first parameter.

Physical Location of the Scripts

Scripts are placed in a single directory, the absolute path of which is given in the configuration file using HTBin directive:

        HTBin  /directory

Note: The Exec rule in version 2.15 obsolites the HTBin directive.

Script Call by Server

Server script gets:

the rest of the URL after script name as its first parameter (the first parameter is empty if there is just a script name), and
the keywords as the rest of its command line parameters (search script), or
alternately form field names appended with equal sign (even positions) and corresponding values (odd positions).

Keywords, field names and values are already unescaped (from HTTP URL escaping format) and escaped agaist Bourne shell translations so that what the script sees in its command line is exactly what they mean, and no further translations need to be made by the scripts.

Form Requests

Form requests are parsed so that every other parameter is field name ended by an equal sign, and the others are corresponding values. If there is something appended after the script name that is passed to the script as the first parameter. Otherwise first parameter is empty.

Examples:

        /htbin/foo/x/y/z?name1=value1&name2=value2

is calles as:

        /.../foo /x/y/z name1= value1 name2= value2

        /htbin/foo?name1=value1&name2=value2

is calles as:

        /.../foo '' name1= value1 name2= value2

Notice empty first parameter!

Even if values contain blanks they are passed as a single parameter:

        /htbin/favorite/music?band=Vaya+Con+Dios&song=Time+Flies

is called as:

        /htbin/favorite /music band= 'Vaya Con Dios' song= 'Time Flies'

(Actually every parameter is always quoted, but the script programmer never sees this because the shell has already stripped them away, and I didn't have enough energy to write them everywhere.)

How to Make a Server Script

The script writes the document to its standard output. The first line has to be Content-Type: field, and after that there must be an empty line indicating the end of the header section. After that the actual document is output (in the corresponding format).

Example:

        Content-Type: text/html

        <HEAD><TITLE>Example page</TITLE></HEAD>
        <BODY>
        ...
        </BODY>

Redirection

If the script wants to redirect the request it can output the Location: field with the actual URL:

        Location: http://.../...

In this case everything else output by the script is ignored.

Redirection on Fly in Version 2.14

If the given URL is not a full URL, but just a pathname part of it (starting with a slash), it is handled by the server as if it was the original request. That means it is again passed through the rule system, access authorization, and finally served normally.

Note: As the #label part of the URL is exclusively meant to be used by the client, there is no way the server could handle it. Therefore, if you need to specify #label after the URL, you must use full URLs in Location: field, not the redirection-on-fly feature.

httpd@w3.org, July 1995