diff --git a/src/python/readmore.html b/src/python/readmore.html new file mode 100755 index 0000000000000000000000000000000000000000..6f19c18fd6d49267cb1b4b8501c5102c7e661526_c3JjL3B5dGhvbi9yZWFkbW9yZS5odG1s --- /dev/null +++ b/src/python/readmore.html @@ -0,0 +1,321 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>Python RTE for WASD</title> + <meta content="Mark Daniel" name="author"> + <meta content="PyRTE installation and configuration" + name="description"> + <meta content="Mozilla Edit sucks big-time!" name="comment"> +</head> +<body style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);" + link="#0000cc" vlink="#000099"> +<h2 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;">Python +Run-Time Environment<br> +</h2> +<span style="font-family: helvetica,arial,sans-serif;"></span><span + style="font-weight: bold; text-decoration: underline; font-family: helvetica,arial,sans-serif;">PyRTE +v1.0.0, 10th May 2007</span> +<ul style="font-family: helvetica,arial,sans-serif;"> + <li><a href="#Installation">Installation</a> </li> + <li><a href="#Configure_WASD">Configure WASD</a> </li> + <li><a href="#Example_Scripts">Example Scripts</a></li> + <li><a href="#Leveraging_PyRTE">Leveraging PyRTE</a></li> + <li><a href="#Problems">Problems?</a></li> + <li><a href="#Acknowlegements">Acknowlegements</a> </li> +</ul> +<hr style="font-family: helvetica,arial,sans-serif;" align="left" + noshade="noshade" size="1" width="65%"> +<p style="font-family: helvetica,arial,sans-serif;">PyRTE is an +interface to a <a href="http://www.python.org/">Python</a> interpreter +engine and environment +for the WASD VMS Web server. It is designed to be able to be +used +in standard CGI and CGIplus/RTE persistent scripting modes. The +persistent modes (default) provide a ~35x (yes, an approximate <a + href="#Performance">thirty-five times</a>) +improvement in +script activation times (compared to CGI/command-line) and comparably +reduced load on both server and system. Note that this package does not +contain the Python interpreter or kit, +that has to be +obtained and installed separately (a simple matter as it is provided +via a PCSI package). +</p> +<p style="font-family: helvetica,arial,sans-serif;"> PyRTE is linked +against the Python interpreter +shareable image and so shares a set of Python capabilities in common +with +command-line OpenVMS Python. Alpha (AXP) and Itanium object +modules are provided for the VMS platforms available for Python.<br> +</p> +<span style="text-decoration: underline;"></span>PyRTE has been +developed and tested on VMS V8.3 using the WASD v9.2.0 and VMS Python +kit <span style="font-family: monospace;">JFP AXPVMS PYTHON251</span> +available from <a href="http://pi-net.dyndns.org">http://pi-net.dyndns.org</a>/ +and documented at <a href="http://vmspython.dyndns.org">http://vmspython.dyndns.org</a>/. +JFP's Python kits are kept very up-to-date as Python updates or +implmentation problems arise.<br> +<br> +<span style="font-weight: bold;"></span> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;">Installation</h3> +<ol style="font-family: helvetica,arial,sans-serif;"> +</ol> +<ol style="font-family: helvetica,arial,sans-serif;"> + <li>If Python for OpenVMS is not currently installed, or if the +version is not up-to-date, obtain the latest kit from<br> + <div style="margin-left: 40px;"> + <pre><a href="http://pi-net.dyndns.org">http://pi-net.dyndns.org</a>/</pre> + </div> +and install according +to the instructions available.<br> + <br> + </li> + <li>When updating it is suggested that any exisiting PyRTE kit be +renamed out of the way before installing this kit. After successful +installation and testing the old kit may be deleted. <br> + <pre style="margin-left: 40px;">$ RENAME HT_ROOT:[SRC]PYTHON.DIR HT_ROOT:[SRC]PYTHON_nnn.DIR<br></pre> + </li> + <li> + <p> Obtain the PyRTE kit from (or one of the mirror sites) </p> + <pre style="margin-left: 40px;"><a + href="http://wasd.vsm.com.au/wasd/">http://wasd.vsm.com.au/wasd/</a></pre> + </li> + <li>UNZIP the kit<br> + <pre style="margin-left: 40px;">$ SET DEFAULT HT_ROOT:[000000]<br>$ UNZIP "-V" location:PYRTEnnn.ZIP</pre> + </li> + <li>Note that this performs a link-only build against the supplied +object modules. Compilation is also available.<br> + <pre style="margin-left: 40px;">$ SET DEFAULT HT_ROOT:[SRC.PYTHON]<span + style="font-family: helvetica,arial,sans-serif;"></span><br><span + style="font-family: helvetica,arial,sans-serif;"></span>$ @BUILD_PYRTE LINK<br></pre> + </li> + <li>Copy the PyRTE engine to the script executable location.<br> + <pre style="margin-left: 40px;">$ COPY HT_EXE:PYRTE.EXE CGI_EXE:</pre> + </li> + <li><a href="#configure_wasd">Configure</a> the Web server<br> + <br> + </li> + <li>S<span style="font-family: helvetica,arial,sans-serif;"></span>tart +scripting :^)<br> +Try the <a href="#Example_Scripts">example scripts</a>.<br> + <br> + </li> +</ol> +<ol style="font-family: helvetica,arial,sans-serif;"> +</ol> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;"><a + name="Configure_WASD"></a>Configure +WASD </h3> +Although there are experimentation modes built into PyRTE basically it +will be used as a WASD Run-Time Environment providing persisten Python +interpreter(s) and environment(s) for Python scripts and +applications. Benchmarking indicates the CGIplus/RTE use reduces +activation time to 3% of CGI (yes, that's correct, by a factor 35 - a +python interpreter is quite expensive to instantiate). There are +subtle +differences in the way CGIplus and RTE parse and provide the PATH_INFO +data (see the "WASD Scripting Overview" for detail).<span + style="font-family: helvetica,arial,sans-serif;"></span><br> +<span style="font-family: helvetica,arial,sans-serif;"></span> +<h4>Configuration and Mapping</h4> +One or more of the following approaches can be implemented. +Remember to<br> +<pre style="margin-left: 40px;">$ HTTPD /DO=MAP</pre> +after changing mapping rules.<br> +<ul> + <li>Server global +configuration (HTTPD$CONFIG) can be used to indicate +which file types should activate the Python engine and how perform +non-script access. </li> +</ul> +<pre style="font-family: helvetica,arial,sans-serif; margin-left: 80px;"><span + style="font-family: monospace;"># HTTPD$CONFIG</span><br + style="font-family: monospace;"><span style="font-family: monospace;">[DclScriptRunTime]</span><br + style="font-family: monospace;"><span style="font-family: monospace;">.PY $CGI-BIN:[000000]PYRTE<br + style="font-family: monospace;"></span><span + style="font-family: monospace;">[AddType]</span><span + style="font-family: monospace;"></span><br + style="font-family: monospace;"><span style="font-family: monospace;">.PY text/plain Python source</span><br + style="font-family: monospace;"><span style="font-family: monospace;"></span><span + style="font-family: monospace;">.PYC application/octet-stream Python byte-code<br>.PYO application/octet-stream Python optimised byte-code<br></span></pre> +<ul> + <li>The following rules require the Python script files to be located +in +the site +administrator controlled /cgi-bin/ path.<span + style="font-family: monospace;"><br> + </span> + <pre style="margin-left: 40px;"># HTTPD$MAP<br>exec /py-bin/* (cgi_exe:pyrte)/cgi-bin/* \<br> script=syntax=unix script=query=none map=once ods=5</pre> + </li> + <li>Alternatively, to +automatically map scripts ending in <span + style="font-family: monospace;">.py</span> to the RTE +engine. </li> +</ul> +<pre style="font-family: helvetica,arial,sans-serif; margin-left: 80px;"><span + style="font-family: monospace;"># HTTPD$MAP for automatic RTE usage</span><br + style="font-family: monospace;"><span style="font-family: monospace;">map /cgi-bin/*.py* /py-bin/*.py*</span><span + style="font-family: monospace;"><br>exec /py-bin/* </span>(cgi_exe:pyrte)/cgi-bin/* \<br> script=syntax=unix script=query=none map=once ods=5<span + style="font-family: monospace;"></span><span + style="font-family: monospace;"></span></pre> +<ul> + <li>The following +rule would allow <span style="font-family: monospace;">.py</span> +type +files anywhere in the mapped +directory +structure to be executed. This may be what is desired but might be +dangerous in some circumstances.<span style="font-family: monospace;"></span><br> + <pre style="margin-left: 40px;"># HTTPD$MAP<span + style="font-family: monospace;"><br>exec /web/**.py* /web/*.py*</span> \<br> script=syntax=unix script=query=none map=once ods=5<span + style="font-family: monospace;"></span></pre> + </li> + <li>It is a general principal that Web applications requiring write +access to parts of the file-system +be run in a unique account with those file-system areas being owned by +and having protections associated with that account. WASD +provides this using its PERSONA facility (see the "WASD +Scripting Overview" for detail).<br> + <pre style="margin-left: 40px;"># HTTPD$MAP<span + style="font-family: monospace;"><br>exec /appx/**.py* /appx_root/*.py*</span> \<br> script=syntax=unix script=query=none map=once ods=5 \<br> script=as=USERX<span + style="font-family: sans-serif;"></span></pre> + </li> + <li><span style="font-family: sans-serif;">To provide in-situ +activation of the example scripts below use the following configuration.<br> + </span> + <pre style="margin-left: 40px;"># HTTPD$MAP<br>exec /py-bin/* (cgi_exe:pyrte)/ht_root/src/python/* \<br> script=syntax=unix script=query=none map=once ods=5<br><br><span + style="font-family: sans-serif;"></span></pre> + </li> +</ul> +<p style="font-family: helvetica,arial,sans-serif;"> </p> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;"><a + name="Example_Scripts"></a>Example +Scripts</h3> +<p style="font-family: helvetica,arial,sans-serif;"> +</p> +<p style="font-family: helvetica,arial,sans-serif;"> After +configuration the following scripts may be used to confirm +the +environment is functioning. +</p> +<ul style="font-family: helvetica,arial,sans-serif;"> + <li> <a href="/py-bin/pyrte_test1.py">/py-bin/pyrte_test1.py</a> + <br> + </li> + <li> <a href="/py-bin/pyrte_test2.py">/py-bin/pyrte_test2.py</a> </li> + <li> <a href="/py-bin/pyrte_test3.py">/py-bin/pyrte_test3.py</a> </li> + <li> <a href="/py-bin/pyrte_test4.py">/py-bin/pyrte_test4.py</a> </li> + <li> <a href="/py-bin/pyrte_chart_pie.py">/py-bin/pyrte_chart_pie.py</a></li> +</ul> +Some of these examples also support CGIplus mode for comparison +purposes.<br> +<br> +Of course the Python code in the script may be inspected from the source +directory:<br> +<br> +<div style="margin-left: 40px;"><a href="/ht_root/src/python/">/ht_root/src/python/</a><br> +</div> +<br> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;"><a + name="Leveraging_PyRTE"></a>Leveraging PyRTE</h3> +Python scripts activated using the default persistent engine generally +have low-latency, low-system-impact characteristics and seem to perform +reliably and efficiently. The PyRTE generally handles all the +WASD server interaction requirements. However there may be +occasions where the application itself benefits from being persistent +(many Python Web application are written with this in mind) or where +more control needs to be exercised by the application designer. +The WASD PyRTE provides a WASD Python module that provides an API for +some of these aspects. Rather than clutter this document with +such arcane detail the description may be found in the prologue to the +PyRTE source code:<br> +<br> +<div style="margin-left: 40px;"><a href="/ht_root/src/python/pyrte.c">/ht_root/src/python/pyrte.c</a><br> +</div> +<br> +An example of where an application benefits from an explicitly CGIplus +activation is MoinMoin:<br> +<br> +<div style="margin-left: 40px;"><a + href="http://moinmoin.wikiwikiweb.de/">http://moinmoin.wikiwikiweb.de/</a><br> +<a href="http://vmspython.dyndns.org/MoinMoin">http://vmspython.dyndns.org/MoinMoin</a><br> +<a href="http://vmspython.dyndns.org/DownloadAndInstallationMoinMoin">http://vmspython.dyndns.org/DownloadAndInstallationMoinMoin</a><br> +</div> +<br> +MoinMoin is generally run independently to a system's primary Web server +using the embedded Web server available for Python. Reverse proxy +is often then use to provide and control access through to the persistent +MoinMoin server.<br> +<br> +Using the same principle of keeping MoinMoin persistent (for the +obvious latency and efficiency benefits) it can be run and controlled +directly by the WASD Web server using a CGIplus <span + style="font-style: italic;">wrapper</span> DCL procedure and a little +Python <span style="font-style: italic;">glue</span> (directly derived +from persistence code already present in the MoinMoin package). <br> +<br> +<div style="margin-left: 40px;"><a + href="/ht_root/src/python/moincgiplus.com">/ht_root/src/python/moincgiplus.com</a></div> +<br> +The same principles may be applied to any application environment +(third-party or in-house) with similar characteristics. +Python applications running as CGIplus scripts using the PyRTE <b>must</b> be +activated via DCL wrappers as illustrated above (in part due to mapping +requirements).<br><br> +With CGIplus persistent applications configuration or code changes will +in all probability require a 'restart' of the application using one or +other of:<br> +<div style="margin-left: 40px;"> +<pre>$ HTTPD/DO=PURGE<br>$ HTTPD/DO=DELETE<br></pre> +</div> +<br> +<span style="font-family: helvetica,arial,sans-serif;"></span> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;"><a + name="Problems"></a>Problems?</h3> +<ul style="font-family: helvetica,arial,sans-serif;"> + <li> With the PyRTE kit ... <a + href="mailto:Mark.Daniel@wasd.vsm.com.au">Mark.Daniel@wasd.vsm.com.au</a> + </li> + <li> With the VMS Python kit ... <a + href="mailto:jf.pieronne@laposte.net">jf.pieronne@laposte.net</a><br> + </li> + <li> The info-WASD mailing list <br> + </li> +</ul> +<p style="font-family: helvetica,arial,sans-serif;"> Unfortunately the +author of the PyRTE interface is such a Python +novice he is not in any position to answer queries about Python +"programming" or +usage. There is the VMS Python Wiki<br> +</p> +<p style="font-family: helvetica,arial,sans-serif; margin-left: 40px;"><a + href="http://vmspython.dyndns.org/">http://vmspython.dyndns.org/</a><br> +</p> +<p style="font-family: helvetica,arial,sans-serif;">and support forum<br> +</p> +<p style="font-family: helvetica,arial,sans-serif; margin-left: 40px;"><a + href="http://www.pi-net.dyndns.org/piforum/index.php">http://www.pi-net.dyndns.org/piforum/index.py</a><br> +</p> +<p style="font-family: helvetica,arial,sans-serif;">for VMS Python +issues. If there's an obvious behavioural problem with PyRTE then +contact the author or use the info-WASD mailing list.<br> +<br> +</p> +<h3 + style="text-decoration: underline; font-family: helvetica,arial,sans-serif;"><a + name="Acknowlegements"></a>Acknowlegements</h3> +<p style="font-family: helvetica,arial,sans-serif;"> Many thanks to +Jean-François Piéronne for his initial port of Python to +VMS and his energetic, ongoing maintenance of the product.<br> +<br> +</p> +<hr style="font-family: helvetica,arial,sans-serif;" align="left" + noshade="noshade" size="1" width="65%"> +</body> +</html>