may be invoked from within an HTML <img> tag as a CGI program to create plots on the fly.
Direct CGI mode can produce PNG, JPEG, and other web browser displayable formats.
This is one of several possible ways to implement
Please be sure you understand the various CGI-related security concerns discussed below that come into play when using ploticus in direct CGI mode.
In particular, note that
are unsafe in direct CGI mode (and in any other situation
where unknown/untrusted users can directly or indirectly set or manipulate prefab parameters).
Briefly, here's what you need to do to use ploticus in direct CGI mode:
1. be sure you understand the CGI-related security concerns
2. copy your pl executable to your cgi-bin (or perhaps create a soft link)
3. using a text editor, create a ploticus config file in your cgi-bin. This allows ploticus to get its bearings and find things (discussed below)
4. check file and directory permissions - be sure that your web server (which typically runs as a UID of nobody) can access your pl executable, config file, data file, and script file
5. place an <IMG> construct into your HTML page that uses an appropriate URL (discussed below)
6. point your web browser to the HTML page.. this will cause pl to be executed and if everything's working you will see the graphic result
7. If you're not getting the desired results, add the -debug option in your invoking URL, like this: /cgi-bin/pl&cgi=1&-debug&-gif .. This causes error messages to be logged to /tmp/plcgi_err and debug output to /tmp/plcgi_diag .
8. See the other
troubleshooting tips below
Config fileBecause CGI programs are invoked in a generic, bare-bones environment, you must provide some basic information so that ploticus can get its bearings and find necessary files. This is done by creating a config file (not the same thing as a script file). It can be created using a text editor. It must be located in your cgi-bin and named similarly to your pl executable.. eg. if your pl executable is named pl or pl.exe your config file must be named pl.cnf.
Here's an example of a minimal config file for ploticus in CGI mode:
projectroot specifies a directory where ploticus will execute and do its work. It must be a directory accessible by your local web server. Data file names and script file names should be expressed relative to projectroot. If you're using your own ploticus script it must reside within the projectroot directory or one of its subdirectories.
Don't set PLOTICUS_PREFABS here! See security concerns, below.
There are many other optional things that can be done as well ...
more about config files.
URLsIn direct CGI mode you invoke ploticus using a URL instead of command line. Fortunately the two methods are similar, varying only in argument delimitation syntax. Here are two examples:
Example command: pl scat1.pl -png TITLE="Usage report" -scale 0.8
Here are the rules for URLs:
1. the first part of the URL locates your cgi-bin, eg. http://abc.com/cgi-bin or just /cgi-bin (relative) and the program to execute (pl) .. of course this part is dependent on local configuration. A question mark (?) must follow the program name. This is all standard CGI practice.
2. The first argument after the question mark should be cgi=1. This helps make it clear to pl that it is operating as a CGI program.
3. Next come all the other pl arguments and parameters. Just about any set of ploticus command line arguments can be used, in the usual order. Each argument is delimited using an ampersand (&). Some command line arguments, such as -scale 0.8 are really two arguments, and must be treated as such for URL purposes (see examples above). Arguments that need to be quoted when used on the command line should not be quoted in URL usage. Standard URL encoding may be used to represent problematic characters such as spaces (%20), ampersands (%26), etc. Arguments are truncated to a length of 250 chars each.
Note: any settings that apply to all your invocations can be conveniently made in your
using the option: or varvalue: directives. This also gets them out of the public eye.
pl senses that it is running as a CGI program automatically if it finds the environment variable QUERY_STRING (set by your web server), and there are no conventional command line arguments present. Command arguments are extracted from QUERY_STRING environment variable. Providing the cgi=1 dummy argument helps in cases where there are no other CGI user arguments.
Default output format will be PNG, JPEG, or GIF depending on the pl build. An appropriate HTTP Content-type header is generated (based on output format type) and written to standard output.
HTTP POST method is not supported.
You can only generate one image per invocation in direct CGI mode.
Clickmaps generally cannot be done in direct CGI mode, since the map and the image content require two separate streams.
Command line options that are inappropriate in direct CGI mode, such as -diagfile, -errfile, -viewer, and -o, are automatically disabled.
TroubleshootingGetting direct CGI mode to work can be tricky... and certain details depend on your local web server configuration. Ploticus direct CGI mode should work on any server that supports the CGI standard (almost all do).
The first thing to try is to use the -debug option in your invoking URL, like this:
This will cause error messages to be logged to /tmp/plcgi_err
and additional diagnostic output to be logged to /tmp/plcgi_diag .
Things to check:
When operating in direct cgi mode and similar situations script writers should be sure that prefabs are disabled. In version 2.32 and later prefabs should be automatically disabled in direct cgi mode. Do not set the PLOTICUS_PREFABS environment variable in the config file. Prefabs may also be disabled by simply renaming the prefabs directory to some other name, or removing it.
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 things to keep in mind:
Using ploticus CGI with ASP/VBSThis is discussed here: ploticus newsgroup message# 1358
data display engine
Copyright Steve Grubb
|Ploticus is hosted at http://ploticus.sourceforge.net|