Google Git
Sign in
apache / tcl-site / 90960537c45f1861dadf29288ec4bce3d5383d95 / . / websh / quickref / context_handling.html
blob: a6b5809614bab8b9b7f6142e4a8131491e8a1960 [file] [log] [blame]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Context handling</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="logging.html" title="Logging"><link rel="next" href="file_handling_and_file_IO.html" title="File handling and file I/O"></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">Context handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="logging.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="file_handling_and_file_IO.html">Next</a></td></tr></table><hr></div><div class="section" title="Context handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="context_handling"></a>Context handling</h2></div></div></div><div class="section" title="web::context"><div class="titlepage"><div><div><h3 class="title"><a name="web::context"></a><span style="font-family:monospace"><span class="command"><strong>web::context</strong></span></span></h3></div></div></div><p style="width:90%">
Creation
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::context</code></span> <em class="replaceable"><code>name</code></em></span></div><p style="width:90%">
Creates a namespace <tt>name</tt> with the following
commands:
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command"><em class="replaceable"><code>name</code></em>::subcommand</code></span> <em class="replaceable"><code>args</code></em></span></div><p style="width:90%">
Subcommands are: <tt>cset</tt>,
<tt>cappend</tt>, <tt>clappend</tt>,
<tt>cget</tt>, <tt>cexists</tt>,
<tt>cunset</tt>, <tt>carray</tt>,
<tt>cnames</tt>, <tt>delete</tt>,
and <tt>dump</tt>.
Manages data of the context. The subcommands behave like the
Tcl commands with similar names.
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cset</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Set <tt>key</tt> to <tt>value</tt>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cappend</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt>
?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>?
?<span class="optional"><tt><em class="replaceable"><code>...</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">
Appends <tt>value</tt> to existing value for
<tt>key</tt>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::clappend</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt>
?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>?
?<span class="optional"><tt><em class="replaceable"><code>...</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">
Appends <tt>value</tt> to existing list of
values for <tt>key</tt>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cget</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt>
?<span class="optional"><tt><em class="replaceable"><code>default</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">
Accesses the value for key <tt>key</tt>, or
returns <tt>default</tt> if
<tt>key</tt> does not exist in the context. If
<tt>default</tt> is omitted, an empty string
is returned if <tt>key</tt> is unknown.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cexists</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Returns true (1) if <tt>key</tt> exists in
context, false (0) otherwise.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cunset</strong></span></span>
<tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Removes <tt>key</tt> from context.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::carray</strong></span></span>
<tt><em class="replaceable"><code>option</code></em></tt> <tt><em class="replaceable"><code>key</code></em></tt>
<tt><em class="replaceable"><code>arg</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Array manipulation as known from the Tcl command
<span class="emphasis"><em>array</em></span>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::cnames</strong></span></span>
?<span class="optional"><tt><em class="replaceable"><code>pattern</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">
Lists existing keys of context matching
<tt>pattern</tt>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::delete</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Deletes the context (same as <span style="font-family:monospace"><span class="command"><strong>namespace delete
<em class="replaceable"><code>name</code></em></strong></span></span>)
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::dump</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Serializes context in a "source"-able format.
</div></div></dd></dl></div><p style="width:90%">
</p><div class="example"><a name="id2739577"></a><p class="title"><b>Example 12. <span style="font-family:monospace"><span class="command">web::context</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting">
% web::context sc
% sc::cset lang FR
FR
% # ... some code ...
% set lang [sc::cget lang EN]
FR
% </pre></div></div><p style="width:90%"><br class="example-break">
</p></div><div class="section" title="web::filecontext"><div class="titlepage"><div><div><h3 class="title"><a name="web::filecontext"></a><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span></h3></div></div></div><p style="width:90%">
Creation:
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::filecontext</code></span> <em class="replaceable"><code>name</code></em> ?<em class="replaceable"><code>options</code></em>?</span></div><p style="width:90%">
Options are: <tt>-perm</tt>, <tt>-path</tt>,
<tt>-crypt</tt>, <tt>-idgen</tt>, and
<tt>-attachto</tt>.
Creates a namespace <tt>name</tt> to manage file-based
context data:
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command"><em class="replaceable"><code>name</code></em>::subcommand</code></span> <em class="replaceable"><code>args</code></em></span></div><p style="width:90%">
Subcommands are: <tt>cset</tt>,
<tt>cappend</tt>, <tt>clappend</tt>,
<tt>cget</tt>, <tt>cexists</tt>,
<tt>cunset</tt>, <tt>carray</tt>,
<tt>cnames</tt>, <tt>init</tt>,
<tt>new</tt>, <tt>commit</tt>,
<tt>invalidate</tt>, and <tt>id</tt>.
Manages file-based context data. The subcommands have their
familiar behaviour of the Tcl commands with similar
names. Please refer to the section <a class="link" href="context_handling.html" title="Context handling">context management</a> for a
description of the commands <tt>cset</tt>,
<tt>cappend</tt>, <tt>clappend</tt>,
<tt>cget</tt>, <tt>cexists</tt>,
<tt>cunset</tt>, <tt>carray</tt>, and
<tt>cnames</tt>.
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term">
<span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span>
?<span class="optional"><tt><em class="replaceable"><code>id</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">
Loads an existing session context with id
<tt>id</tt>, or creates a new one, if
possible. Automation depends on the settings of the
actual context manager settings, see
below.</div><div style="margin-bottom:6"> If you specify an
<tt>id</tt>, you must decide when to create a
new file and when to use the old one, if any, by
yourself.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::new</strong></span></span>
?<span class="optional"><tt><em class="replaceable"><code>id</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">
Creates a new session context. Automation depends on
the settings of the actual context manager settings,
see below.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::commit</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Makes session context persistent.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::id</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 id of session.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::invalidate</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Deletes session in memory and on file system.
</div></div></dd></dl></div><p style="width:90%">
Options:
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::filecontext</code></span> <em class="replaceable"><code>name</code></em> -perm <em class="replaceable"><code>perm</code></em></span></div><p style="width:90%">
Sets the file permissions of the session context files
<tt>perm</tt> is an unix-like octal value like 0644.
If not specified, files are created with the permissions defined
in <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>,
which again defaults to 0644.
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-path</tt>
<tt><em class="replaceable"><code>path</code></em></tt>
</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Specifies where to store session context files and how
to name them. Suppose that the session id is 99.
<span class="emphasis"><em>-path [file join .. data s%d.dat]</em></span>
would then cause filecontext to save the session
context as <code class="literal">../data/s99.dat</code>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-crypt</tt>
<tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets crypting of session context on or off.
Default: on.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-idgen</tt>
<tt><em class="replaceable"><code>idgen</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets command <tt>idgen</tt> to find a new
session id. See doc of
<span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span> below for an
implementation provided by Websh.
</div><div style="margin-bottom:6">
<tt>idgen</tt> is used in case that no
<tt>id</tt> argument has been passed to
<tt>init</tt> or <tt>new</tt>.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::filecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-attachto</tt>
<tt><em class="replaceable"><code>idparam</code></em></tt>
</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Causes <span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span>
to initialize with the id given in the querystring parameter
<tt>idparam</tt>. (This is one important reason why
the querystring should be encrypted). After
<span style="font-family:monospace"><span class="command"><strong>web::dispatch</strong></span></span> has
parsed the querystring, <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span>
will report the current session id in
<tt>idparam</tt>, if any. <span class="emphasis"><em>Note</em></span>
that you can maintain several sessions in parallel,
and attach every session to its own
<tt>idparam</tt>.
</div><div style="margin-bottom:6">
Using
<span class="emphasis"><em><span style="font-family:monospace"><span class="command"><strong>web::dispatch -track</strong></span></span></em></span>
further automates the passing of session ids from
request to request.
</div></div></dd></dl></div><p style="width:90%">
<span class="emphasis"><em>Note:</em></span> Whenever you create a new
file-based context, the context is initialized and you loose
whatever information that you might have stored in the context
before you initialized it as a file-based session context.
</p></div><div class="section" title="web::cookiecontext"><div class="titlepage"><div><div><h3 class="title"><a name="web::cookiecontext"></a><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span></h3></div></div></div><p style="width:90%">
Creation:
</p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::cookiecontext</code></span> <em class="replaceable"><code>name</code></em> ?<em class="replaceable"><code>options</code></em>?</span></div><p style="width:90%">
Options are: <tt>-expires</tt>,
<tt>-path</tt>, <tt>-domain</tt>,
<tt>-secure</tt>, <tt>-crypt</tt>, and
<tt>-channel</tt>.
Creates a namespace <tt>name</tt> to manage
cookie-based context data:
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::subcommand</strong></span></span>
<tt><em class="replaceable"><code>args</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Subcommands are: <tt>cset</tt>,
<tt>cappend</tt>, <tt>clappend</tt>,
<tt>cget</tt>, <tt>cexists</tt>,
<tt>cunset</tt>, <tt>carray</tt>,
<tt>cnames</tt>, <tt>init</tt>,
<tt>new</tt>, <tt>commit</tt>,
<tt>invalidate</tt>, and <tt>id</tt>.
</div></div></dd></dl></div><p style="width:90%">
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::init</strong></span></span>
?<span class="optional"><tt><em class="replaceable"><code>id</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">
Loads an existing session context (cookie must have
been sent by the client).
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::new</strong></span></span>
?<span class="optional"><tt><em class="replaceable"><code>id</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">
Creates a new session context.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::commit</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sends a cookie (if no output to the page has been sent yet).
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::id</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 id of session.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong><em class="replaceable"><code>name</code></em>::invalidate</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Deletes session in memory and on client side.
</div></div></dd></dl></div><p style="width:90%">
Options:
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-expires</tt>
<tt><em class="replaceable"><code>time</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the expiration date of the cookie. Possible values
for <tt>time</tt> are
<span class="emphasis"><em>seconds</em></span> (time in seconds since
1970-01-01) or <span class="emphasis"><em>date-string</em></span> (any
time string that Tcl can scan. Note that therefore many
relative times, such as <span class="emphasis"><em>24 hours</em></span>,
<span class="emphasis"><em>week</em></span>, <span class="emphasis"><em>2 weeks</em></span>,
<span class="emphasis"><em>tomorrow</em></span>, etc.
are possible. Default is <span class="emphasis"><em>now + 24 hours</em></span>
(i.e. cookie expires in 24 hours. (Please note that the
behavior of some of these relative time specifiers changed
from Tcl8.4 to Tcl8.5.) Use
<span class="emphasis"><em>-expires ""</em></span> to
send a cookie without an expires parameter.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-path</tt>
<tt><em class="replaceable"><code>path</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the <tt>path</tt> property of the cookie.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-domain</tt>
<tt><em class="replaceable"><code>domain</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the <tt>domain</tt> property of the cookie.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt>
<tt>-secure</tt> <tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the <tt>secure</tt> property of the cookie.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-crypt</tt>
<tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets crypting of cookie context on or off.
Default: on.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::cookiecontext</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-channel</tt>
<tt><em class="replaceable"><code>channelName</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the response object to send the cookie to (see also
<span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span>).
</div></div></dd></dl></div><p style="width:90%">
Because cookies are client-based, in principle no id is
needed. Websh uses <tt>id</tt> to name the cookie,
however, and the <span style="font-family:monospace"><span class="command"><strong>new</strong></span></span>,
<span style="font-family:monospace"><span class="command"><strong>init</strong></span></span>, and <span style="font-family:monospace"><span class="command"><strong>load</strong></span></span> commands
still require the <tt>id</tt> argument. (fixme: any
changes?) Please note that property settings of a cookie
context can only be changed <span class="emphasis"><em>before</em></span>
anything is output on the respective channel.
</p></div><div class="section" title="web::filecounter"><div class="titlepage"><div><div><h3 class="title"><a name="web::filecounter"></a><span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span></h3></div></div></div><p style="width:90%">
This is a numeric sequence-number generator which stores its
state in a file. Basic usage:
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term">Creation:</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
<span style="font-family:monospace"><span class="command"><strong>web::filecounter</strong></span></span>
<tt><em class="replaceable"><code>name</code></em></tt> <tt>-filename</tt>
<tt><em class="replaceable"><code>fname</code></em></tt>
?<span class="optional"><tt><em class="replaceable"><code>options</code></em></tt></span>?
</div><div style="margin-bottom:6">
Options are: <tt>-min</tt>,
<tt>-max</tt>, <tt>-seed</tt>,
<tt>-incr</tt>, <tt>-mask</tt>,
<tt>-wrap</tt>
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-filename</tt>
<tt><em class="replaceable"><code>filename</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Uses <tt>filename</tt> to store the current
value (no default).
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-min</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Uses this value as a minimum at start and after wrap,
if wrap is true. Default: 0.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-max</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Uses this value as a maximum, if wrap is true. Default: 2147483647.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-seed</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Usea this value as a starting point if persistent file does
not exist yet. Default: 0.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-incr</tt> <tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Uses this value as an increment for each 'nextval'.
Default: 1.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-perms</tt>
<tt><em class="replaceable"><code>value</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Sets the permissions on the newly created files.
Default is configured in <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>, which defaults to 0644.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt>-wrap</tt>
<tt>boolean</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Indicates whether this counter should wrap around its
values (back to min from max). Default: false.
</div></div></dd></dl></div><p style="width:90%">
After creation, a new command <tt>name</tt> is
registered with the following subcommands:
</p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> config</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Returns a flat list of key value pairs with the
filecounter's configuration.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> nextval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Returns the next value.
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> curval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Returns the current value, that is, the value that the
last call to "nextval" or "getval"
reported (as opposed to the current value in the file).
</div></div></dd><dt><span style="background:#bbbbff"><span class="term"><tt><em class="replaceable"><code>name</code></em></tt> getval</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6">
Returns the current value in the file. (Does not increment
file as in "nextval".)
</div></div></dd></dl></div><p style="width:90%">
</p><div class="example"><a name="id2741137"></a><p class="title"><b>Example 13. <span style="font-family:monospace"><span class="command">web::filecounter</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting">
% web::filecounter fc1 -filename test.dat
fc1
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr {not valid}
% fc1 curval
web::filecounter: no current value available
% fc1 nextval
0
% fc1 config
file test.dat handle fc1 seed 0 min 0 max 2147483647 incr 1 perms 0644 wrap false curr 0
% fc1 nextval
1
% web::filecounter fc2 -filename test.dat
fc2
% fc2 curval
web::filecounter: no current value available
% fc2 getval
1
% fc2 nextval
2
% fc2 curval
2
% fc1 curval
1
% fc1 nextval
3
% fc2 getval
3
% web::filecounter fc3 -filename othertest.dat -min 1 -max 10 -seed 1 -incr 2 -wrap 1
fc3
% fc3 config
file othertest.dat handle fc3 seed 1 min 1 max 10 incr 2 perms 0644 wrap true curr {not valid}
% fc3 nextval
1
% fc3 nextval
3
% </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logging.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="file_handling_and_file_IO.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Logging </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> File handling and file I/O</td></tr></table></div></body></html>