
MOD_Q
=====

This directory contains the Q Apache module which can be used to embed the Q
interpreter in the Apache web server. The current version has been tested with
Apache 1.3 as well as Apache 2.0 (prefork MPM only, the worker MPM surely
needs some work and is not supported right now). To install, edit the Makefile
as necessary (in particular, check the name and path of the apxs executable),
then run `make' and `make install', and set up `q' as a handler for .q script
files in your httpd.conf file as described in the Apache manual.

The module provides essentially the same environment as the Common Gateway
Interface, meaning that existing CGI scripts should work without any further
ado, provided that their output-generating function is named `cgi_main'. The
only fundamental difference is that the interpreter is executed directly
inside the server and thus does not have to be restarted each time a script is
run. Moreover, the module caches the current script name and its modification
time so that the script does not have to be reloaded if the same script is run
multiple times in succession. This speeds up script execution and makes it
possible to maintain state between different invokations.

USAGE
=====

As with CGI scripts, details about the request, such as client information and
the submitted query, are available through a collection of environment
variables, and the request body can be read from standard input. The standard
output of the script is sent back to the client. It should begin with an
appropriate request header (specifying the Content-Type field will do for most
purposes) which ends in two newline characters and is followed by the contents
generated by your script (HTML page, image, audio file, whatever). The
output-generating function of the script should be called `cgi_main', as this
is the function executed by the module if it is present. The `cgi_main'
function may also return an integer which will be passed on as the HTTP result
code of the request to the server. Some useful return codes are 0 = "ok",
404 = "not found" and 500 = "internal server error"; if no integer value is
returned by the function, 0 is assumed.

See the `myreq.q' script for a simple example, which can be run through both
this module and the Common Gateway Interface. It displays the environment and
body of the submitted request as a nicely formatted HTML page, which is quite
useful for debugging purposes, too.


Enjoy! :)

Jan 19 2004
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikwissenschaft.uni-mainz.de/~ag
