CGIplus - Perl extension for WASD CGIplus protocol.
Copyright (C) 2000-2008 Mark G.Daniel This program, comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under the conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version. http://www.gnu.org/licenses/gpl.txt
# CGIplusPM_example1.pl
#
# Simple example that just prints the CGI variables, then demonstrates how
# to retrive variable values using the CGIplus module 'var' subroutine.
# May be invoked using either /cgi-bin/cpipluspm_example1 for standard CGI
# environment or using /CGIplus-bin/cpipluspm_example1 for CGIplus environment.
#
use CGIplus qw(:all) ;
# change this to false to retain (any) "WWW_" on CGI variable names
#stripWWW(1);
# change this to true to coerce all CGIplus::var() to have a leading "WWW_"
#usingWWW(0);
# pass the reference of the example function to the CGIplus processor
process(\&exampleScript);
#------------------------------------------------------------------------------
# all the work is done in this function
sub exampleScript
{
printf ("Content-Type: text/plain\
Expires: Fri, 13 Jan 1978 14:00:00 GMT\
");
if (isCGIplus())
{
if ($ENV{'QUERY_STRING'} eq "eoj")
{
printf ("Bye! (after %d requests)\n", CGIplus::usageCount());
exit;
}
}
varPrint();
# show that the $ENV associative array and var() are identical
printf ("\nDemonstrate that the var() function and \$ENV associative array contents are identical ...\n");
printf ("\n\$ENV{'SCRIPT_NAME'} |%s|\n", $ENV{'SCRIPT_NAME'});
printf ("var('SCRIPT_NAME') |%s|\n", var('SCRIPT_NAME'));
printf ("\n\$ENV{'PATH_INFO'} |%s|\n", $ENV{'PATH_INFO'});
printf ("var('PATH_INFO'} |%s|\n", var('PATH_INFO'));
printf ("\n\$ENV{'QUERY_STRING'} |%s|\n", $ENV{'QUERY_STRING'});
printf ("var('QUERY_STRING') |%s|\n\n", var('QUERY_STRING'));
if (!defined($ENV{'SERVER_SOFT'})) {
printf ("SERVER_SOFT does not exist and looks like an empty string ...\n");
}
printf ("SERVER_SOFT |%s|\n\n", $ENV{'SERVER_SOFT'});
if (defined($ENV{'SERVER_SOFTWARE'})) {
printf ("SERVER_SOFTWARE should exist ...\n");
}
printf ("SERVER_SOFTWARE |%s|\n", $ENV{'SERVER_SOFTWARE'});
}
#------------------------------------------------------------------------------
CGIplus provides a persistent CGI environment for a specific CGI running under the WASD web server. CGIplus dedicates a process running a Perl interpreter (for CGIs written in Perl) to the execution of the CGI.
CGIplus.pm makes WASD and general DCL CGI and WASD CGIplus environments transparent to CGI Perl scripts. To make the standard CGI and CGIplus as compatible as possible the CGIplus::process() function takes a reference to a function which contains all of the essential activities of the script. This mechanism should *always* be used to execute the script. Nothing of the environment is then needed to be known by the script itself! Of course, for persistent scripting some care needs to be taken to ensure all storage, etc., is correctly initialized each time the script is started and nothing is left to script exit and rundown to clean up (which of course doesn't happen with persistant scripts).
This version of CGIplus.pm (January 2003) makes CGI environment variables, formally available only via CGIplus::var(), accessable using ENV associative array. The CGIplus.pm variable array has been renamed and relocated to main::CGIplusENV. This allows PERLRTE.C to support CGIplus (in addition to RTE) with CGIplus.pm. The complication arose because both would be attempting to read the CGIPLUSIN stream and synchronise the request processing. Obviously both cannot do this! The compromise has been to allow PERLRTE.C to sync and read the first request's variables, which it places into the main::CGIplusENV associative array used by this module (as well as into main::ENV). After that initial request CGIplus.pm takes over the request syncchronising and variable reading (As far as PERLRTE.C is concerned the first request it initiates never, or seldom, completes ;^)
A script using CGIplus.pm should never be activated using an RTE path (one using the mapping syntax ``exec+ (rte_executable)/path/* /path/*''). When an RTE becomes quiescent the server will give it another script. With the CGIplus.pm CGIplus loop is active an unintended and probably incorrect script will become active. Always activate CGIplus.pm enabled scripts via a CGIplus path. CGIplus.pm will detect this mapping mistake and die!
It also, by default, strips the leading ``WWW_'' from variable names (for greater compatibility with most CGI environments that do not use such). This should not be a problem with scripts designed for the previous version module and using CGIplus::var() with leading ``WWW_'' on variable names as this will be removed automatically by CGIplus::var() before lookup. It may be an issue with non-CGI variables stored in $ENV as the algorithm is fairly heavy handed and will also clobber the names of any non-CGI environment variables in $ENV. It can be turned off before starting any script using CGIplus::stripWWW(0) or on a per-module basis by modifying CGIplus.pm itself to initialize ``$stripWWW = 0;''; A complementary switch that can be set using CGIplys::usingWWW(1) (or modify to ``$usingWWW = 1;'') to retain any leading ``WWW_'' on variable names and to add them to names (if necessary) before lookup using CGIplus::var().
VMS' RMS complicates output streams under Perl. This is a particular issue with CGIplus end-of-file sentinals, which must be output as a single record. CGIplus.pm attempts to provide a simple mechanism for providing binary streams if necessary, while still ensuring it's own records are not interfered with. This uses Charles Bailey's VMS::Stdio extension module built into most versions of VMS Perl.
This module should be suitable for VMS Perl 5.6 and 5.8.
It requires that the following system or process level logical be defined for correct resolution of the standard CGI variables supplied by WASD using DCL symbols (CGIplus variables are not affected by this).
$ DEFINE /SYSTEM PERL_ENV_TABLES CLISYM_GLOBAL,LNM$PROCESS
All functions are exported and may be included into the using packages name space at will.
beginStream()
Open SYS$OUTPUT as a binary stream.
fileStream(fileName,
[content type])
Write the contents of the specified file to SYS$OUTPUT in binary mode. A content-type HTTP header is generated. If the content type is omitted, it defaults to application/octed-stream.
isCGI()
Return true if the CGIplus environment is not active, false otherwise.
isCGIplus()
Returns true if the CGIplus environment is active, false otherwise.
process(function reference)
The specified function is called whenever CGIplus has more work for the function to do.
stripWWW(boolean)
If true, the leading ``WWW_'' will be stripped from all CGI symbols before calling the CGI function passed to process. If false, the CGI symbols are left intact. This can be important for CGIs developed under U*x and ported to OpenVMS/WASD. U*x CGIs do not expect the CGI variables to begin with WWW_ (or any other prefix for that matter).
usageCount()
The number of times this CGI has been executed by CGIplus.
usingWWW(boolean)
If true, environment variables are expected to begin with WWW_. It turns off stripWWW if enabled, but doesn't touch stripWWW if disabled.
$theValue = var(variable name)
Look up the specified variable name in the CGIplus environment (if CGIplus is active) or the CGI environment (if CGIplus is NOT active). If stripWWW is true and the variable name begins with WWW_ then the prefix is stripped before lookup occurs. If usingWWW is true and the variable name does not begin with WWW_ then WWW_ is added.
varPrint()
Print the CGIplus environment variables or the CGI environment variables depending on which environment is active.
writeStream(string, length)
Write the data specified to the SYS$OUTPUT when in binary mode.
None by default.
Mark Daniel, <Mark.Daniel@wasd.vsm.com.au>
Perl language refinements and notes courtesy Richard Munroe <munroe@csworks.com>
perl.