<!DOCTYPE html>
<html>
<head>
<title>PHP: Hypertext Processor: WASD</title>
<style type="text/css">
body { margin:1em; font-family:arial,helvetica,sans-serif; }
h1 {
font-size:150%; font-weight:bold; text-decoration:underline;
}
h2 {
font-size:130%; font-weight:bold; text-decoration:underline;
letter-spacing:1px;
padding-top:1.2em;
}
h3 {
font-size:120%; font-weight:bold;
padding-top:0.8em;
}
blockquote { font-size:100%; }
tt { font-family:courier,monospace; padding:0 4px 0 4px; }
hr { color:#888888; background-color:#888888; height:1px; border:0; }
.code {
font-family:courier,monospace;
border-style:solid; border-color:#888888; border-left-width:1px;
border-top-width:0; border-right-width:0; border-bottom-width:0;
background-color:#eeeeee;
margin-left:2em;
margin-right:5em;
padding:0.3em;
padding-left:1em;
}
pre {
margin-left:2em;
margin-right:5em;
padding:0.3em;
padding-left:1em;
}
.quote {
border-style:dotted; border-color:#888888; border-width:1px;
font-size:90%;
background-color:#eeeeee;
margin-left:2em;
margin-right:5em;
padding:0.3em;
padding-left:1em;
}
.refer {
font-size:90%; width:90%; text-align:right;
}
.refer {
font-size:90%; width:90%; text-align:right;
}
.which table, .which th, .which td {
border-collapse:collapse;
border-style:solid;
border-width:1px;
border-color:#888888;
background-color:#eeeeee;
padding:5px; margin:0;
font-size:90%;
vertical-align:top;
}
.which th {
font-weight: bold;
}
</style>
</head>
<body bgcolor="#ffffff" text="#000000" link="#0000cc" vlink="#0000cc">
<center>
<h1>PHP: Run-Time Environment for WASD</h1>
<h3>Version 1.4.5, 2nd February 2014
<br><span style="font-size:70%">~ Mark Berryman Port Release ~</span></h3>
<p><b>Copyright © 2002-2014 Mark G. Daniel</b>
<br>This program, comes with ABSOLUTELY NO WARRANTY.
<br>This is free software, and you are welcome to redistribute it under the
<br>conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version.
<br><a href="http://www.gnu.org/licenses/gpl.txt">http://www.gnu.org/licenses/gpl.txt</a>
</center>
<h2 style="margin-left:1.5em;">Contents</h2>
<ul>
<li><a href="#Berryman">Mark Berryman PHP Port</a></li>
<li><a href="#PHPWASD">PHPWASD</a> </li>
<li><a href="#Installation">Installation</a> </li>
<li><a href="#UpdateP">Update PHP</a> </li>
<li><a href="#Configure_WASD">Configure WASD</a> </li>
<li><a href="#Configure_PHP">Configure PHP</a> </li>
<li><a href="#Example_Scripts">Example Scripts</a> </li>
<li><a href="#Performance">Performance</a> </li>
<li><a href="#Command-line_PHP">Command-line PHP</a> </li>
<li><a href="#DCLsymbol">DCLsymbol Extension</a> </li>
<li><a href="#Problems">Problems?</a> </li>
<li><a href="#Releases">Releases</a> </li>
<li><a href="#Acknowlegements">Acknowlegements</a> </li>
</ul>
<br><hr align="left" size="1" noshade><br>
<p> This is an interface to a PHP interpreter engine and environment for the
WASD OpenVMS Web server. It is designed to be able to be used in standard
CGI and CGIplus/RTE persistent scripting modes. The persistent modes
provide a ~20x (yes, an approximate <a href="#Performance">twenty times</a>)
improvement in script activation times and reduced load on server and system.
PHPWASD cannot be used interactively or at the command line, it is only for
scripting use. Note that this package does not contain the PHP engine,
that has to be obtained separately from Mark Berryman.
<a name="Berryman">
<h2>Mark Berryman PHP Port</h2>
</a>
<p> This port is more complete and up-to-date than any provided by HP, and
seems always in-development. <b>Thank you Mark Berryman</b>.
<p> The preceding decade of WASD PHP kits relied on elements of the CPQ/HP CSWS
PHP releases. This and any subsequent release will rely on the Berryman kits.
The PHP engine element can be updated independently to the WASD infrastructure
supporting it.
<blockquote>
<a target="_blank" href="http://www.theberrymans.com/php_kits/">http://www.theberrymans.com/php_kits/</a>
</blockquote>
<p> These kits are provided as a ZIP archive <tt>PHP_<i>xxx_n_n_n</i>.ZIP</tt>
where <i>xxx</i> is the platform (AXP or I64) and <i>n_n_n</i> is the major,
minor and patch level release numbers of the contained PHP (e.g. 5_3_28 being
5.3.28). The PHP ZIP archive is supplied as a parameter to the INSTALL.COM
procedure.
<a name="PHPWASD">
<h2>PHPWASD</h2>
</a>
<p> This document and the kit requires WASD v10.0 or later. If not there yet
it's worthwhile considering upgrading!
<p> Where PHPWASD versions earlier than v1.4.4 have been installed it is
<i>strongly</i> suggested the existing PHPWASD kit be renamed out of the way
(as described in step 3 below) before installing this kit so there can be no
interactions between kit contents. After successful installation and testing
the previous directory trees may be deleted.
<p> The WASD kit supplies the RTE source code, DCL installation and startup
procedures, some elementary scripts, and this document — the WASD
<i>infrastructure</i> — the Berryman kit provides the PHP environment,
all executables including the PHPWASD interface — the PHP <i>engine</i>.
With earlier kits local object code was used to build the required WASD RTE.
All executables are now derived from the Mark Berryman kit. In fact it's
not possible to build PHPWASD.EXE locally without the corresponding PHP header
files which are not supplied with the Mark Berryman kit. However if you have
the headers then the <a target="_blank" href="phpwasd.c">PHPWASD.C</a> source
file should compile and interoperate with any PHP 5 to date — 5.2 or
earlier, 5.3 and 5.4 versions.
<a name="Installation">
<h2>Installation</h2>
</a>
<ol>
<p><li> Obtain the PHPWASD kit from
<blockquote>
<a target="_blank" href="http://wasd.vsm.com.au/wasd/">http://wasd.vsm.com.au/wasd/</a>
</blockquote>
<p><li> Obtain the (most recent) platform-specific Mark Berryman kit from
<blockquote>
<a target="_blank" href="http://www.theberrymans.com/php_kits/">http://www.theberrymans.com/php_kits/</a>
</blockquote>
<li> It is suggested that any existing PHPWASD kit be renamed out of the way
before installing this kit so there can be no interactions between kit
contents. After successful installation the previous directories may be
deleted.
<pre class="code">
$ RENAME WASD_ROOT:[000000]PHP.DIR WASD_ROOT:[000000]PHP_<i>nnn</i>.DIR
$ RENAME WASD_ROOT:[SRC]PHP.DIR WASD_ROOT:[SRC]PHP_<i>nnn</i>.DIR
</pre>
<p><li> UNZIP the PHPWASD archive
<pre class="code">
$ SET DEFAULT WASD_ROOT:[000000]
$ UNZIP <i>location:</i>PHPWASD144.ZIP
</pre>
<p><li> Install the WASD infrastructure and PHP engine
<pre class="code">
$ SET DEFAULT WASD_ROOT:[SRC.PHP]
$ @WASD_ROOT:[SRC.PHP]INSTALL <i>location</i>:PHP_<i>xxx_n_n_n</i>.ZIP
</pre>
<p><li> Check release notes in the respective directory of
<a target="_blank" href="/wasd_root/php/*.*">WASD_ROOT:[PHP.<i>xxx</i>]</a>
for any recommendations against the release.
<p><li>
<a href="#Configure_WASD">Configure</a> the Web server
<p><li>
<a href="#Configure_PHP">Configure</a> the PHP environment
<p><li> Start scripting :^)
Try the <a href="#example_scripts">example scripts</a>. </p>
<p> With the default configuration PHP script files are placed into
[CGI-BIN] by the INSTALL.COM procedure (examples from
WASD_ROOT:[SRC.PHP.SCRIPTS]).
<p><li> When you're satisfied you want to keep it add
<pre class="code">$ @WASD_ROOT:[SRC.PHP]<a target="_blank" href="php_startup.com">PHP_STARTUP.COM</a></pre>
(or the equivalent) to your system/Web startup procedures
</ol>
<p><br> The content of the Mark Berryman kit as restored to the
<a target="_blank" href="/wasd_root/php/*.*">WASD_ROOT:[PHP.<i>xxx</i>]</a>
directory (as of PHP 5.3.28 kit).
<p><table class="which" style="margin-left:2em;border-collapse:collapse">
<tbody>
<tr>
<th>File Name</th>
<th>Purpose</th>
<th>Used with WASD</th>
</tr>
<tr>
<td>AAA_README.TXT</td>
<td>release notes for this kit</td>
<td>relevant to read</td>
</tr>
<tr>
<td>MOD_PHP_APACHE-2_0.EXE</td>
<td>drop-in replacement for CSWS</td>
<td>no</td>
</tr>
<tr>
<td>PHP.EXE</td>
<td>command-line PHP.EXE image</td>
<td>optional</td>
</tr>
<tr>
<td>php.ini-development</td>
<td>example PHP.INI for a development environment</td>
<td>can be</td>
</tr>
<tr>
<td>php.ini-production</td>
<td>example PHP.INI for a production environment</td>
<td>can be</td>
</tr>
<tr>
<td>PHPSHR.EXE</td>
<td>PHP engine shareable image and in-built extensions</td>
<td>yes</td>
</tr>
<tr>
<td>PHPWASD.EXE</td>
<td>WASD PHP RTE executable</td>
<td>yes</td>
</tr>
<tr>
<td>PHP_CGI.EXE</td>
<td>CGI environment PHP executable</td>
<td>no - could be</td>
</tr>
<tr>
<td>PHP_OPENVMS.PHP</td>
<td>example script for <i>openvms</i> extension</td>
<td>as example script</td>
</tr>
</tbody>
</table>
<a name="Update">
<h2>Update PHP</h2>
</a>
<p> The PHP release may be updated independent of the WASD infrastructure.
<ol>
<p><li> Obtain the (most recent) platform-specific Mark Berryman kit from
<blockquote>
<a target="_blank" href="http://www.theberrymans.com/php_kits/">http://www.theberrymans.com/php_kits/</a>
</blockquote>
<li> It is suggested that any existing PHP directory be renamed out of
the way before installing this kit so there can be no interactions between kit
contents. After successful installation the previous directory may be deleted.
<pre class="code">
$ RENAME WASD_ROOT:[000000]PHP.DIR WASD_ROOT:[000000]PHP_<i>nnn</i>.DIR
</pre>
<b>In any case, ensure you can access and if required continue to use the
in-production PHP.INI configuration file!</b>
<p><li> Install the PHP engine and other elements
<pre class="code">
$ SET DEFAULT WASD_ROOT:[SRC.PHP]
$ @INSTALL PHP <i>location</i>:PHP_<i>xxx_n_n_n</i>.ZIP
</pre>
<p><li> Check release notes in the respective directory of
<a target="_blank" href="/wasd_root/php/*.*">WASD_ROOT:[PHP]</a>
and make any configuration adjustments that might be recommended for the
release.
</ol>
<a name="Configure_WASD">
<h2>Configure WASD</h2>
</a>
<p> There are various ways to employ the WASD PHP interpreter. It can be
used in vanilla CGI mode (not recommended), or in persistent CGIplus/RTE mode.
Benchmarking indicates the CGIplus/RTE use reduces activation time to 5% of
CGI (yes, that's correct, by more than an order of magnitude). There are subtle
differences in the way CGIplus and RTE parse and provide the PATH_INFO data.
See the "WASD Scripting" document for more detail.
<h3>Configuration and Mapping</h3>
<p> One or more of the following approaches can be implemented.
<ul>
<li> Server global configuration (WASD_CONFIG_GLOBAL) can be used to indicate
to directory listings and file access the role of the file and its
content-type.
<pre class="code">
# WASD_CONFIG_GLOBAL
[AddType]
.INI text/plain initialization file
.PHP text/plain PHP source
.PHPS text/plain PHP source
.PHTML text/plain PHP source
</pre>
<p> Server global configuration may also be used to activate the CGI PHP
engine (not recommended).
<br><b>Do not mix CGI and RTE configurations (below). Choose one or the
other.</b>
<pre class="code">
# WASD_CONFIG_GLOBAL
[DclScriptRunTime]
.PHP $PHP_ROOT:[000000]PHP_CGI.EXE
</pre>
<p><li> The following rule requires the PHP script files to be located in
the site administrator controlled /cgi-bin/ path. This may be changed
using appropriate rules.
<pre class="code">
# WASD_CONFIG_MAP
exec /cgi-bin/*.php* ($cgi-bin:[000000]phpwasd.exe)/cgi-bin/*.php* \
script=query=relaxed
</pre>
<p><li> The following rule would allow <tt>.php</tt> type files anywhere in the
mapped directory structure to be executed. Deploy with caution as this allows
<b>any</b> PHP script in the tree to be activated. PHP <i>applications</i>
often require this approach to mapping. See <a href="#PHP_Applications">PHP
Applications</a> for further comment. The <i>script=as=</i> is optional but it
is often recommended to run applications in a dedicated account separate to the
rest of the server environment. Note immediately following the <i>exec</i>
rule is a <i>pass</i> rule providing access to all the non-PHP resources (style
sheets, icons, images, etc.) often associated with an application.
<pre class="code">
# WASD_CONFIG_MAP
exec /app/**.php* (cgi-bin:[000000]phpwasd.exe)/app_root/*.php* \
script=query=relaxed map=once ods=5 script=as=APP_ACCOUNT
pass /app/* /app_root/*
</pre>
</ul>
<h3><a name="PHP_Applications"></a>PHP Applications</h3>
<p> A PHP <i>application</i> is a package of PHP scripts and associated
resources such as style-sheets, icons and other non-script files, in a single
directory tree, often with various elements collected together, such as icons
and scripts, but sometimes with multiple instances of these or with them
interspersed amongst each other. That is, as a complex mix of file purposes.
<p> The following rule allows <tt>.php</tt> type files anywhere in the
application tree to be executed. Deploy exercising due diligence. The
<i>script=as=</i> is optional but the recommended approach for the
reasons provided above. Note immediately following the <i>exec</i> rule is a
<i>pass</i> rule providing access to all the non-script resources associated
with the application.
<pre class="code">
# WASD_CONFIG_MAP
exec /app/**.php* (cgi-bin:[000000]phpwasd.exe)/app_root/*.php* \
script=query=relaxed map=once ods=5 script=as=APP_ACCOUNT
pass /app/* /app_root/*
</pre>
<p> The WASD serving model uses two independent accounts, one for more
static resources and the other for overtly dynamic content, that is scripts,
and is considered the minimum best practise from a security perspective. A
breach in the scripting environment has less chance to compromise or damage the
server core, and vice versa. Better practise is an account for every major
processing system (web-based application) handled by the server. In either
case the multiple accounts needing to access the application tree potentially
complicates the file protection requirements.
<p> With an interpreter such as PHP, the scripting engine, and therefore the
scripting account, requires only <i>read</i> access to the source files and
directories. If the application additionally needs to write into some portion
of the file-system then of course this needs to be carefully considered and
implemented. At the very least the server account requires read access to the
directories so that the script may be located before activating the scripting
engine. If the application tree contains non-script resources to be served
then they also require read access for the server account.
<p> There are three basic approaches. The examples are illustrative only.
<ol>
<li> Other considerations ignored, the simplest is to make the directory tree
WORLD READ (with or without propagation ACL).
<pre class="code">
APP.DIR;1 0.50KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,R,R)
(DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:R,WORLD:R)
</pre>
<pre class="code">
EXAMPLE.PHP;1 1KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,R,R)
</pre>
<li> The second involves an ACL that provides access to the specific accounts
involved in serving up the application (this is the WASD model).
<pre class="code">
APP.DIR;1 0.50KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,,)
(IDENTIFIER=WASD_HTTP_SERVER,ACCESS=READ)
(IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=READ)
(IDENTIFIER=*,ACCESS=NONE)
(IDENTIFIER=WASD_HTTP_NOBODY,OPTIONS=DEFAULT,ACCESS=READ)
(IDENTIFIER=*,OPTIONS=DEFAULT,ACCESS=NONE)
(DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)
</pre>
<pre class="code">
EXAMPLE.PHP;1 1KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,,)
(IDENTIFIER=WASD_HTTP_SERVER,ACCESS=READ)
(IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=READ)
</pre>
<li> The third involves creating a rights identifier, granting that to both the
server and scripting(/application) accounts, and then applying an ACL to the
directory tree providing READ access to that rights identifier.
<pre class="code">
APP.DIR;1 0.50KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,,)
(IDENTIFIER=APP_ACCESS,ACCESS=READ)
(IDENTIFIER=*,ACCESS=NONE)
(IDENTIFIER=APP_ACCESS,OPTIONS=DEFAULT,ACCESS=READ)
(IDENTIFIER=*,OPTIONS=DEFAULT,ACCESS=NONE)
(DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)
</pre>
<pre class="code">
EXAMPLE.PHP;1 1KB 1-FEB-2014 05:16 [SYSTEM]
(RWED,RWED,,)
(IDENTIFIER=APP_ACCESS,ACCESS=READ)
(IDENTIFIER=*,ACCESS=NONE)
</pre>
</ol>
<h3><a name="logos"></a>No PHP or Zend Logos?</h3>
<p> By default WASD validates query strings in its own inimitable fashion
(correctly in the author's HO). This validation interferes with the requesting
of the internally generated PHP and Zend logos (as are included by the
<tt>php_info.php</tt> script) and may similarly for other PHP scripts. To
disable query string validation by WASD include the following WASD_CONFIG_MAP
rule at an appropriate location before or at mapping of PHP scripts.
<pre class="code">
set /**.php* script=query=relaxed
</pre>
<h3><a name="script_syntax_unix"></a>PHP on ODS-5 Volumes</h3>
<p> For scripts requiring <i>extended file specification</i> (EFS, located on
ODS-5 volumes) the script path needs to be mapped as ODS-5.
<pre class="code">
set /**.php* script=query=relaxed ods=5
</pre>
<p> When a script environment is mapped as residing on an ODS-5 volume, any
VMS-syntax file specifications contained in PATH_TRANSLATED and SCRIPT_NAME are
automatically translated to Unix-style syntax. This has been demonstrated
to better support PHP applications derived from such environments, in
particular allowing relative directory references. This occurs whether or
not the path is SET using <i>script=syntax=unix</i>.
<p>For example; by default a request's underlying CGI variables might be:
<p><table class="which" style="margin-left:2em;border-collapse:collapse">
<tbody>
<tr>
<td>REQUEST_URI</td>
<td>/php-bin/php_info.php/wasd_root/src/php/</td>
</tr>
<tr>
<td>PATH_INFO</td>
<td>/wasd_root/src/php/</td>
</tr>
<tr>
<td>PATH_TRANSLATED</td>
<td>WASD_ROOT:[SRC.PHP]</td>
</tr>
<tr>
<td>SCRIPT_NAME</td>
<td>/php-bin/php_info.php</td>
</tr>
<tr>
<td>SCRIPT_FILENAME</td>
<td>PHP-BIN:[000000]PHP_INFO.PHP</td>
</tr>
</tbody>
</table>
<p> After mapping being on ODS-5 and subsequent translation they are presented
as:
<p><table class="which" style="margin-left:2em;border-collapse:collapse">
<tbody>
<tr>
<td>_SERVER["REQUEST_URI"]</td>
<td>/php-bin/php_info.php/wasd_root/src/php/</td>
</tr>
<tr>
<td>_SERVER["PATH_INFO"]</td>
<td>/wasd_root/src/php/</td>
</tr>
<tr>
<td>_SERVER["PATH_TRANSLATED"]</td>
<td>/WASD_ROOT/SRC/PHP/</td>
</tr>
<tr>
<td>_SERVER["SCRIPT_NAME"]</td>
<td>/php-bin/php_info.php</td>
</tr>
<tr>
<td>_SERVER["SCRIPT_FILENAME"]</td>
<td>/PHP-BIN/000000/PHP_INFO.PHP</td>
</tr>
</tbody>
</table>
<h3>Script Default or Home Directory</h3>
<p> The PHPWASD engine will by default <i>chdir()</i> to the Unix-style syntax
equivalent of the directory containing the PHP script file. It also does
a <i>setenv()</i> against the environment variable PATH to this same string.
This location may be explicitly provided using the value of CGI variable
SCRIPT_DEFAULT and set on a per-script or general basis using the mapping rule
<i>Set script=default=<string></i>. It will accept either VMS and
Unix specifications depending on the requirements of the script itself.
<pre class="code">
set /php-bin/mumble.php* script=default="/mumble_device/000000"
set /php-bin/mumble.php* script=default="mumble_device:[000000]"
</pre>
<h3>"Watch" Mode</h3>
<p> This is a basic facility to assist in debugging the interactions
between the WASD server, PHPWASD scripting engine, script activation and
input/output. It does not provide for debugging of the script itself but
may be of some elementary assistance when investigating the environment the
script is activating under. There are a number of methods for activating
"watch" mode.
<ul>
<li>Defining the logical name <tt>PHPWASD$WATCH_SCRIPT_NAME</tt>
to contain a (case-sensitive) string from the SCRIPT_NAME variable.
<pre class="code">
$ define /system phpwasd$watch_script_name "php_info"
</pre>
<p><li> Defining the logical name <tt>PHPWASD$WATCH_REMOTE_ADDR</tt>
to contain the IP address of the "watching" browser.
<pre class="code">
$ define /system phpwasd$watch_remote_addr "192.168.0.2"
</pre>
<p><li> Adding the string "#watch" to the first line of the PHP script.<br>
<pre class="code">
<?php #watch
echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
phpinfo (INFO_ALL);<br>?>
</pre>
</li>
<li>
<p>Having a string "#watch:remote_addr=..." in the first line of
the PHP script, specifying the IP address of the "watching" browser.<br>
</p>
<pre class="code">
<?php #watch:remote_addr=192.168.0.2
echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
phpinfo (INFO_ALL);<br>?>
</pre>
</ul>
<p> When either of the logical names is defined without the other each
operates to enable "watch" completely independently. When defined
concurrently both must match for "watch" to be enabled. For example; when
<tt>PHPWASD$WATCH_SCRIPT_NAME</tt> is defined only that script is "watch"ed;
when <tt>PHPWASD$WATCH_REMOTE_ADDR</tt> is defined, all scripts activated by
the specified host are "watch"ed; when both are defined only the specified
script can be "watch"ed by the specified host. Similar (but different :-)
constraints apply to the script-embedded string.
<p> A WATCH statement contains a statement number, timestamp, and then some
free-form text (that hopefully is self-explanatory). WATCH output
can also comprise a hex-dump of a block of data.
<h2><a name="Configure_PHP"></a>Configure PHP</h2>
<p> The author of PHPWASD is only a PHP novice, so anything in this section
should be taken with a large pinch of salt. Any scripting environment
should be approached with due caution and diligence. Please ensure you
are familiar with PHP and its security requirements in particular before
betting the company on anything in this section.
<p> PHP configuration is accomplished using the <tt>PHP.INI</tt> file, by
default located in the <tt>PHP_ROOT:[000000]</tt> directory. The Mark Berryman
kit provides suggested <i>development</i> and <i>production</i> examples in
<a target="_blank" href="/wasd_root/php/php.ini*">WASD_ROOT:[PHP]PHP.INI*</a>
which may be copied to the above location and modified as required.
<p> Mapping rules configure on a per-request basis. Logical names and
configuration file content are loaded once at persistent PHPWASD engine
startup. Changes to configuration need to be loaded into any instantiated PHP
engine(s) using <tt>$HTTPD/DO=DCL=PURGE</tt>.
<h3>PHPWASD$INI</h3>
<p> The PHP engine has a set of default configuration parameters and so can be
used without specific configuration. This not a tutorial on which
changes should be made for any give circumstance, just how to pass those
changes into the PHPWASD scripting engine. To change the defaults a
configuration file PHP.INI should be provided. The default location of
this for VMS PHP and WASD is <tt>PHP_ROOT:[000000]PHP.INI</tt>.
To use a PHP.INI from a location other than the VMS PHP default
define the logical name <tt>PHPWASD$INI</tt> to locate the file. This
logical name can be in any table the scripting process can access (e.g.
process, job, system).
<h3>PHPWASD$INI2</h3>
<p> PHPWASD also has a secondary PHP.INI which contains directives that
override those from the primary PHP.INI. This can be useful when
maintaining the site-wide PHP configuration in the primary PHP.INI while
placing only those directives required to be added or modified for the
particular application. To have the PHPWASD engine process this file
define the logical name <tt>PHPWASD$INI2</tt> to contain the location of the
file. This can be defined in any table the scripting process can access
(e.g. process, job, system). To suppress use of the primary PHP.INI file
and rely entirely on the secondary for configuration define the primary logical
name to the NL: device.
<pre class="code">
$ DEFINE PHPWASD$INI NL:
</pre>
<h3>PHPWASD$INIS</h3>
<p> To specify PHP.INI directives directly (and avoid the overhead of file
processing) the logical name <tt>PHPWASD$INIS</tt> can be
defined. The format for this string is <span
style="font-style: italic;">name="value"[;name="value"]</span>, where
a semicolon is used<span style="font-style: italic;"></span> to
separate directives. Any directive used in this logical overrides
the same directive in the primary and secondary PHP.INI. This is
an example of such a logical value string and its definition
(continued for printed page clarity).
<pre class="code">
short_open_tag=1 ; expose_php=0 ; include_path="/php/application3/include"
$ DEFINE PHPWASD$INIS "short_open_tag=1 ; expose_php=0 ; include_path=""/php/application3/include"""
</pre>
<a name="Mapping_Rules">
<h3>Mapping Rules</h3>
</a>
<p> It is possible to pass parameters to PHP scripts and applications using
the <i>script=param=(name=value)</i> mapping rule. The PHPWASD scripting
engine checks for a number of reserved identifiers and will use the contents of
those present to perform the indicated function. The primary PHP.INI
cannot be supplied via mapping rule due to PHP module startup requirements.
<p><table class="which" style="margin-left:2em;border-collapse:collapse">
<tbody>
<tr>
<th><nobr>Parameter Name</nobr></th>
<th>Purpose</th>
</tr>
<tr>
<td>PHP_INI</td>
<td>Provides the location for the primary PHP.INI configuration file.</td>
</tr>
<tr>
<td>PHP_INI2</td>
<td>Provides the location for the secondary PHP.INI configuration file.</td>
</tr>
<tr>
<td>PHP_INIS</td>
<td>Allows the specification of a value for any of the configuration directives
allowed in PHP.INI. The format for these parameters is
name="value"[;name="value"], where a semi-colon is used to separate directives.
See examples below.
</td>
</tr>
</tbody>
</table>
<p> The first example shows the specification of a primary PHP.INI file,
the second of a secondary PHP.INI file,
and the third the use of a configuration directive string.<br>
<pre class="code">
set /php/application_a/* script=param=(PHP_INI="php:[application_a]php.ini")
set /php/application_b/* script=param=(PHP_INI2="php:[application_b]php.ini")
# continuation lines used for printed page clarity
set /php/application_c* script=param=(PHP_INIS=\
'short_open_tag=1 ; expose_php=0 ; include_path="/php/application_c/include"')
</pre>
<a name="Example_Scripts">
<h2>Example Scripts</h2>
</a>
<p> After configuration the following scripts may be used to confirm the
environment is functioning.
<ul>
<li> <a target="_blank" href="/cgi-bin/php_rules.php">/cgi-bin/php_rules.php</a>
<li> <a target="_blank" href="/cgi-bin/php_info.php">/cgi-bin/php_info.php</a>
(no PHP or Zend <a href="#logos">logos</a>?)
<li> <a target="_blank" href="/cgi-bin/php_openvms.php">/cgi-bin/php_openvms.php</a>
</ul>
<p>Script sources:
<a target="_blank" href="/wasd_root/src/php/scripts/*.*">WASD_ROOT:[SRC.PHP.SCRIPTS]</a>
<a name="Performance">
<h2>Performance</h2>
</a>
<p> The performance of PHPWASD is quite respectable.
<br> This test bench was a Digital Personal WorkStation with 1 CPU and 1536MB
running VMS V8.3, HP TCP/IP Services 5.7, and
<ul>
<li> WASD 10.3, PHPWASD v1.4.4 and PHP 5.3.28
<li> CSWS 2.2 and CSWS_PHP-V0502-17-1 (PHP 5.2.17)
<li> CSWS 2.2 and PHP 5.3.28 modifications<sup>**</sup>
</ul>
with results generated using the
<a target="_blank" href="/wasd_root/src/utils/ab.c">ApacheBench</a> tool.
<p><table class="which" style="margin-left:2em;border-collapse:collapse">
<tbody>
<tr>
<th>Environment</th>
<th>Path</th>
<th>Req/Sec</th>
</tr>
<tr>
<td><b>WASD CGI<b><sup>*</sup></td>
<td>/cgi-bin/php_info.php<br>/cgi-bin/php_rules.php</td>
<td align="right">0.9<br>1<br>
</td>
</tr>
<tr>
<td><b>WASD RTE</b></td>
<td>/php-bin/php_info.php<br>/php-bin/php_rules.php</td>
<td align="right">19<br>72<br>
</td>
</tr>
<tr>
<td><b>CSWS 5.2.17</b><sup>**</sup></td>
<td>/php/php_info.php<br>/php/php_rules.php</td>
<td align="right">20<br>26<br>
</td>
</tr>
<tr>
<td><b>CSWS 5.3.28</b><sup>**</sup></td>
<td>/php/php_info.php<br>/php/php_rules.php</td>
<td align="right">13<br>22<br>
</td>
</tr>
</tbody>
</table>
<blockquote>
<sup>*</sup> The (for interest) CGI comparison was enabled using the following
configuration:
<pre class="code">
# WASD_CONFIG_GLOBAL
[DclScriptRunTime]
.PHP $PHP_ROOT:[000000]PHP_CGI.EXE
</pre>
<pre class="code">
# WASD_CONFIG_MAP
set /cgi-bin/*.php* script=query=none script=syntax=unix ods=5
</pre>
</blockquote>
<blockquote>
<sup>**</sup> The CSWS comparisons were between the <i>out-of-the-box</I>
HP-AXPVMS-CSWS_PHP-V0502-17-1.PCSI installation (PHP 5.2.17), and with images
and extensions updated in accordance to the Mark Berryman kit instructions
and using the <i>production</i> PHP.INI.
</blockquote>
<a name="Command-line_PHP">
<h2>Command-line PHP</h2>
</a>
<p> The PHPWASD.EXE engine interface is only suitable for scripting use.
It cannot be used outside of the CGI environment and certainly not from the
command line. It is often useful to have a PHP tool that can be used in
such a manner and the PHP kit provides one. To access this image assign
a symbol (foreign command) in the (SY)LOGIN.COM procedure (assumes WASD_TABLE
in process search list).
<pre class="code">
$ PHP = "$PHP_ROOT:[000000]PHP.EXE"
</pre>
<a name="DCLsymbol">
<h2>DCLsymbol Extension</h2>
</a>
<p> A practical solution to a WASD site requiring data passback from a PHP
script to a wrapping DCL procedure. This extension allows DCL local and global
symbols to be assigned, deleted, and values accessed from within PHP.
<p> This extension is supplied in-built with the Mark Berryman PHP engine.
<p> Further information is available in the source code of
<a target="_blank" href="dclsymbol.c">DCLSYMBOL.C</a>
<a name="Problems">
<h2>Problems?</h2>
</a>
<ul>
<li> With the PHPWASD script ...
<a href="mailto:Mark.Daniel@wasd.vsm.com.au">mark.daniel@wasd.vsm.com.au</a>
<li> The info-WASD mailing list
<li> Perhaps <a href="news:comp.os.vms">comp.os.vms</a>
</ul>
<p> Unfortunately the author of the PHPWASD interface is such a PHP novice he
is not in any position to answer queries about PHP "programming" or
usage. If there's an obvious behavioural problem with PHPWASD
(preferably diagnosed by someone with PHP experience) then he's it though.
<a name="Releases">
<h2>Releases</h2>
</a>
<dl>
<dt>v1.4.5 02-FEB-2014</dt>
<dd>• tweak for PHP 5.4.<i>n</I> (future release at this date)
<dt>v1.4.4 01-FEB-2014</dt>
<dd>• employ Mark Berryman PHP kit (eliminate use of CSWS kit)
<dd>• intial development against 5.3.28
<dt>v1.4.3 10-FEB-2011</dt>
<dd>• extend PHPWASD$ABSORB_PRE_WRITESAPI to <stderr>
<dt>v1.4.2 17-JUL-2010</dt>
<dd>• WASD v10.1 ProctorDetect()
<dd>• bugfix; initialise SG(request_info), SG(sapi_headers)
<dd>• bugfix; ImageIdent() for __ia64
<dt>v1.4.1 02-JUN-2009</dt>
<dd>• The CSWS PHP v2.0 kit (May 2009) session management extension
outputs spurious debug(?) data <br> which as an interim
measure has been suppressed using the PHPWASD$ABSORB_PRE_WRITESAPI logical name
<dt>v1.4.0 20-MAY-2009</dt>
<dd>• CPQ AXPVMS CSWS_PHP V2.0 (based on PHP v5.2.6)
<dt>v1.3.0 29-JAN-2005</dt>
<dd>• PHPWASD$WATCH_... logical names and script-embedded
"<?php #watch" to activate PHPWASD 'watch' mode
<dd>• SetCrtlFeature ("DECC$FILE_SHARING"),
<dd>• PHPWASD$INI2, PHPWASD$INIS, PHPWASD$NO_TRANSLATE,
PHP_INI2, PHP_INIS, PHP_NO_TRANSLATE,
<dt>v1.2.0 14-FEB-2004</dt>
<dd>• CSWS PHP 1.2 (PHP 4.3.2)
<dd>• minor conditional mods to support IA64
<dt>v1.1.0 26-DEC-2002</dt>
<dd>• CSWS PHP v1.1
<dt>v1.0.0 16-JAN-2002</dt>
<dd>• initial
</dl>
<a name="Acknowlegements">
<h2>Acknowlegements</h2>
</a>
<p> Many thanks to Mark Berryman for his significant efforts in keeping VMS PHP
current.
<p> Of course, thanks to the PHP development team!
<p><hr align="left" size="1" noshade><p>
</body>
</html>