#set TITLE = "Operating in CGI mode"
#include top


.SH INVOKING PL AS A CGI PROGRAM
As of version 2.00, 
#set FILE = "pl.1.html"
#set TAG = pl 
#include link
may be invoked directly as a CGI program, to dynamically
create plots without having to write images to temp files.  
CGI mode is not available for 
#set FILE = "pltab.1.html"
#set TAG = pltab 
#include link
\0.
.LP
To set this up, copy your pl executable to your cgi-bin (or make 
a link), and create a ploticus config file (see below).
The specifics of local CGI bin and file naming conventions vary;
see your local admin if having difficulty.
Then, use a construct such as this in your HTML page:
.IP
\fC<img src="http://abc.org/cgi-bin/pl?cgi=1&scat1.pl&-png&-scale&0.8&
TITLE=Trailer%20Tongue%20Technologies">\fR
.LP
This is equivalent to command line usage:
.IP
\fCpl scat1.pl  -png  -scale 0.8  TITLE="Trailer Tongue Technologies"\fR
.LP
\fCcgi=1\fR should be the first parameter in your URL construct, as shown 
in the above example.
.LP
After that, the regular 
#set FILE = "pl.1.html#options"
#set TAG = "pl command line options and arguments"
#include link
, including those for
#set FILE = "prefabs.html"
#set TAG = "prefabs"
#include link
,
may be given in the usual order.  However, to 
conform to URL syntax, a question mark (?) must separate the program name 
from the first argument, and ampersand (&) must be used to separate subsequent 
arguments.  Also, arguments should not be enclosed in quotes.  Use %20 to represent 
an embedded space, %26 for an embedded ampersand, etc (%XX may be used to represent 
any problematic character, where XX is its hex ascii value).  Arguments are limited 
to a length of 250 chars each and may not contain embedded newlines.  

#include space

.SH CGI MODE BEHAVIOR
pl automatically goes into CGI mode if it detects the environment variable 
REQUEST_URI (set by your web server), and there are no conventional command
line arguments given.  pl behaves this way when in CGI mode:

.IP \(bu
a 
#set FILE = "config.html"
#set TAG = "ploticus config file"
#include link
is required, and the config file must contain a
\fCprojectroot\fR setting; other settings are optional.  Here is an example
of such a config file:
.RS
.IP
.nf
projectroot: /home/steve/proj1
.fi
.RE
.IP
The config file
must have the same name as your pl executable, plus a \fC.cnf\fR extension
(if your pl executable name ends in \fC.cgi\fR the \fC.cgi\fR is ignored).  
If pl must be used in several different contexts within the same cgi-bin, 
you can make soft links to pl, using other names for the links, and have 
a separate config file corresponding with each one.  Examples:
.nf
        pl executable name		config file name
    ---------------------------     ---------------------------
	/data/cgi-bin/pl		/data/cgi-bin/pl.cnf 
	/data/cgi-bin/plproj1		/data/cgi-bin/plproj1.cnf 
	/data/cgi-bin/pl.cgi		/data/cgi-bin/pl.cnf 
.fi
.LP
.IP \(bu
pl will operate from the \fCprojectroot\fR directory.  All filenames should
be expressed relative to \fCprojectroot\fR.  The script file must be
below projectroot.  Script file names beginning with slash (/) or 
dot (.), or containing double-dot (..) are prohibited.  This
restriction does not apply to other files (eg data files).
.LP
.IP \(bu
command arguments are extracted from REQUEST_URI (HTML POST method is not supported).
SCRIPT_FILENAME is used to build the config filename.
These are environment variables that are set by your web server before
it invokes CGI programs.
If either of these are not available, pl will exit.
.LP
.IP \(bu
default output format is GIF, JPEG, or PNG depending on the pl build;
this can also be controlled via the arguments list.
.LP
.IP \(bu
an appropriate Content-type header is generated based on output format 
type.  This header as well as image content are written to standard output.
.LP
.IP \(bu
output is limited to one image or "page".  To do multiple images, temp
files will need to be used.

#include space

.SH DEVELOPMENT HINTS
When using pl in CGI mode, debugging is difficult because 
diagnostics cannot be viewed, and the image content is being
streamed to standard output.  If you are having trouble getting pl to work
in CGI mode, try the following:
cd to your cgi bin, deploy a new term window, and in the new window
manually set the REQUEST_URI and SCRIPT_FILENAME environment variables,
eg:
.IP
\fCexport REQUEST_URI="/data/cgi-bin/pl?scat1.pl&-scale&0.8"\fR
.IP
\fCexport SCRIPT_FILENAME="/data/cgi-bin/pl"
.LP
Then, in the new window, invoke pl by hand, with no command line arguments:
.IP
\fCpl > out.gif\fR
.LP
Any error messages should be visible on screen.  

#include space

.SH CGI SECURITY 
You should be fully familiar with CGI security issues and how
they relate to your platform and project,
before putting pl into
service as a CGI program.  Some thoughts:
.IP \(bu
Anyone can easily view your HTML, including your invocation of CGI programs.
It is also very easy for users to submit modified CGI invocations (especially altered
arguments).
.IP \(bu
If you pass a data file name (or other filename) to pl via a varvalue argument, 
use the following within your pl script to guard against hacks on the file name:
.RS
.IP
.nf
\0 #if @DATAFILE inlike /*,.*,*..*
\0   #exit
\0 #endif
.fi
.RE
.IP \(bu
If you build a shell command from anything passed via a varvalue argument, 
remove shell metacharacters from the variables using the 
#set FILE = shell.html
#set TAG =  "$shellstripchars function"
#include link
\0.
.IP \(bu
CGI security worries can be avoided by invoking ploticus via the shell (ie. the old way),
capturing the results into a temp file, then using <img> to access the temp file.
The tradeoff is that this is less efficient due the temp file i/o.
.LP

#include bottom
