websh/quickref/apache_module_specific

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache module specific commands</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Websh Reference 3.6.0b5"><link rel="up" href="index.html" title="Websh Reference 3.6.0b5"><link rel="prev" href="inter-process_and_-system_communication.html" title="Inter-process/-system communication"><link rel="next" href="misc_commands.html" title="Miscellaneous commands"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Apache module specific commands</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="inter-process_and_-system_communication.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="misc_commands.html">Next</a></td></tr></table><hr></div><div class="section" title="Apache module specific commands"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apache_module_specific_commands"></a>Apache module specific commands</h2></div></div></div><p style="width:90%"> Note that these commands are implemented as dummies in the CGI version of Websh only. They don't do anything except for <span style="font-family:monospace"><span class="command"><strong>web::initializer</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>web::finalizer</strong></span></span>, which just evaluate the code provided in the argument. </p><div class="section" title="web::initializer"><div class="titlepage"><div><div><h3 class="title"><a name="web::initializer"></a><span style="font-family:monospace"><span class="command"><strong>web::initializer</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::initializer</code></span> <em class="replaceable"><code>code</code></em></span></div><p style="width:90%"> This code is executed only when a new interpreter is created. Note that the "main" Websh script can <span style="font-family:monospace"><span class="command"><strong>source</strong></span></span> several modules which each call their initialization code. Also note that this code eval'd when it is first requested and read in its normal script sequence, and not prior to any other code in the script. </p><p style="width:90%"> Calling <span style="font-family:monospace"><span class="command"><strong>web::loglevel</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>web::logdest</strong></span></span> in any <span style="font-family:monospace"><span class="command"><strong>web::initializer</strong></span></span> will tag these log levels and destinations as not to be deleted, after the request ends. This log condifguration will therefore also be available in the finalizer code, which is only eval'd after the last request in the interpreter has been cleaned up. </p><div class="example"><a name="id2742560"></a><p class="title"><b>Example�17.�logging in <span style="font-family:monospace"><span class="command">web::initializer</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> > cat test.ws3 web::initializer { web::logdest add user.-debug file -unbuffered /tmp/test.log web::logfilter add *.-debug web::log info "initializing interp" } web::command default { web::log info "command default call number [web::interpcfg numreq]" web::putxfile /tmp/dummypage.html } web::finalizer { web::log info "shutting down interp" } web::dispatch > # requesting test.ws3 three times over mod_websh: > more /tmp/test.log 10/28/05 14:13:45 [20639] user.info: initializing interp 10/28/05 14:13:45 [20639] user.info: command default call number 0 10/28/05 14:13:46 [20639] user.info: command default call number 1 10/28/05 14:13:47 [20639] user.info: command default call number 2 10/28/05 14:13:47 [20639] user.info: shutting down interp</pre></div></div><br class="example-break"><p style="width:90%"> Note that in the above example the lifetime of the interpreter class is set to 3 requests. (See command <span style="font-family:monospace"><span class="command"><strong>web::interpclasscfg</strong></span></span>.) </p></div><div class="section" title="web::finalizer"><div class="titlepage"><div><div><h3 class="title"><a name="web::finalizer"></a><span style="font-family:monospace"><span class="command"><strong>web::finalizer</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::finalizer</code></span> <em class="replaceable"><code>code</code></em></span></div><p style="width:90%"> Registers code to be exectuted when the interpreter for this Websh script is deleted. <span style="font-family:monospace"><span class="command"><strong>web::finalize</strong></span></span> will then call each <tt>code</tt> block that has been registered, starting with the most recently added <tt>code</tt>. </p></div><div class="section" title="web::finalize"><div class="titlepage"><div><div><h3 class="title"><a name="web::finalize"></a><span style="font-family:monospace"><span class="command"><strong>web::finalize</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::finalize</code></span> </span></div><p style="width:90%"> Executes finalizer code that has been registered using <span style="font-family:monospace"><span class="command"><strong>web::finalizer</strong></span></span>, starting with the most recently added <tt>code</tt>. Note that this command is executed automatically and does not have to be called manually. However, it can be used as a hook, when the interpreter is deleted: </p><div class="example"><a name="id2742696"></a><p class="title"><b>Example�18.�<span style="font-family:monospace"><span class="command">web::finalize</span></span> hook</b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> rename web::finalize web::finalize.orig proc web::myFinalize {} { # code to eval before finalize.orig finalize.orig # code to eval after finalize.orig } </pre></div></div><p style="width:90%"><br class="example-break"> </p></div><div class="section" title="web::maineval"><div class="titlepage"><div><div><h3 class="title"><a name="web::maineval"></a><span style="font-family:monospace"><span class="command"><strong>web::maineval</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::maineval</code></span> <em class="replaceable"><code>code</code></em></span></div><p style="width:90%"> Executes code in the "main" interpreter of mod_websh. (Note that this is synchronized, i.e. the main interpreter is locked for exclusive access by the current thread within the process. However, running Apache in a prefork setting sets up a main interpreter per child, so the exclusive access does not refer to server wide exclusivity, but only to child process wide exclusiveity.) </p></div><div class="section" title="web::interpclasscfg"><div class="titlepage"><div><div><h3 class="title"><a name="web::interpclasscfg"></a><span style="font-family:monospace"><span class="command"><strong>web::interpclasscfg</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::interpclasscfg</code></span> <em class="replaceable"><code>classid</code></em> <em class="replaceable"><code>property</code></em> ?<em class="replaceable"><code>value</code></em>?</span></div><p style="width:90%"> Properties are: <tt>maxrequests</tt>, <tt>maxttl</tt>, <tt>maxidletime</tt> Sets or accesses properties of the interpreter class <tt>classid</tt>. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"> <span style="font-family:monospace"><span class="command"><strong>web::interpclasscfg</strong></span></span> <tt><em class="replaceable"><code>classid</code></em></tt> <tt>maxrequests</tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the maximum number of requests interpreters of this class should handle. If <tt>value</tt> is 0, handle an unlimited number of requests. Default: 1. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpclasscfg</strong></span></span> <tt><em class="replaceable"><code>classid</code></em></tt> <tt>maxttl</tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the maximum number of seconds interpreters of this class should live. If <tt>value</tt> is 0, it lives forever. Default: 0. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpclasscfg</strong></span></span> <tt><em class="replaceable"><code>classid</code></em></tt> <tt>maxidletime</tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the maximum number of seconds interpreters of this class should live beeing idle. If <tt>value</tt> is 0, no idle timeout is assumed. Default: 0. </div></div></dd></dl></div><p style="width:90%"> </p></div><div class="section" title="web::interpcfg"><div class="titlepage"><div><div><h3 class="title"><a name="web::interpcfg"></a><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::interpcfg</code></span> ?<em class="replaceable"><code>property</code></em>? ?<em class="replaceable"><code>value</code></em>?</span></div><p style="width:90%"> Properties are: <tt>numreq</tt>, <tt>retire</tt>, <tt>starttime</tt>, <tt>lastusedtime</tt> Sets or accesses properties of the current interpreter. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns <tt>classid</tt> of current interpreter. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span> <tt>numreq</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the number of requests handled by this interpreter. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span> <tt>retire</tt> ?<span class="optional"><tt>boolean</tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the flag indicating this interpreter should be removed after handling the current request. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span> <tt>starttime</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the time in seconds since the epoch, this interpreter was started. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::interpcfg</strong></span></span> <tt>lastusedtime</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the time in seconds since the epoch, this interpreter was last used (starttime in case of first request). </div></div></dd></dl></div><p style="width:90%"> </p></div><div class="section" title="web::interpmap"><div class="titlepage"><div><div><h3 class="title"><a name="web::interpmap"></a><span style="font-family:monospace"><span class="command"><strong>web::interpmap</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::interpmap</code></span> <em class="replaceable"><code>filename</code></em></span></div><p style="width:90%"> Hook to define interpreter classes depending on the requested file. Note that this hook must be defined in the Websh configuration file (WebshConfig directive of mod_websh). </p><p style="width:90%"> When a request is directed to mod_websh, Websh needs to determine the interpreter class for that reqest. It does that by calling <span style="font-family:monospace"><span class="command"><strong>web::interpmap</strong></span></span> with the requested file as argument. The return value of that command is the name of the interpreter class and at the same time the filename of the script for this interpreter class. </p><div class="example"><a name="id2743188"></a><p class="title"><b>Example�19.�<span style="font-family:monospace"><span class="command">web::interpmap</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> proc web::interpmap {filename} { if {[string match "/path/to/myApp" $filename]} { # this is my special app return /real/path/to/myApp } if {[string match "*.ws3"]} { # scripts have their own interp class return $filename } # default: all templates are handled by my handler return /my/special/template/handler } </pre></div></div><p style="width:90%"><br class="example-break"> The default implementation of <span style="font-family:monospace"><span class="command"><strong>web::interpmap</strong></span></span> is </p><pre style="background:#bbffbb ; width:75%" class="programlisting">proc web::interpmap {filename} {return $filename}</pre><p style="width:90%"> This sets up a separate interpreter class for every requested URL and takes the file itself as script. </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="inter-process_and_-system_communication.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="misc_commands.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Inter-process/-system communication�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Miscellaneous commands</td></tr></table></div></body></html>

websh/quickref/apache_module_specific_commands.html (167 lines of code) (raw):