| <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> |
