You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rivet-dev@tcl.apache.org by mx...@apache.org on 2008/11/21 10:54:07 UTC
svn commit: r719552 [2/5] - in /tcl/rivet/trunk: ./ doc/ doc/xml/
Added: tcl/rivet/trunk/doc/rivet-full.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet-full.xml?rev=719552&view=auto
==============================================================================
--- tcl/rivet/trunk/doc/rivet-full.xml (added)
+++ tcl/rivet/trunk/doc/rivet-full.xml Fri Nov 21 01:54:06 2008
@@ -0,0 +1,4675 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/committees/docbook/xml/4.1.2/docbookx.dtd" [
+ <!ENTITY hello.rvt SYSTEM "examples/hello.rvt" >
+ <!ENTITY table.rvt SYSTEM "examples/table.rvt" >
+ <!ENTITY vars.html SYSTEM "examples/vars.html" >
+ <!ENTITY vars.rvt SYSTEM "examples/vars.rvt" >
+ <!ENTITY upload.html SYSTEM "examples/upload.html" >
+ <!ENTITY upload.rvt SYSTEM "examples/upload.rvt" >
+ <!ENTITY download.tcl SYSTEM "examples/download.tcl" >
+ <!ENTITY rivet_web_service.tcl SYSTEM "examples/rivet_web_service.tcl" >
+]>
+
+<!--
+ Copyright 2002-2005 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License"); you
+ may not use this file except in compliance with the License. You
+ may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
+ permissions and limitations under the License.
+-->
+
+<!-- $Id: rivet.xml 718432 2008-11-17 23:14:18Z karl $ -->
+
+<article>
+ <articleinfo>
+ <title>Apache Rivet</title>
+ <copyright>
+ <year>2002</year>
+ <year>2003</year>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2006</year>
+ <year>2007</year>
+ <year>2008</year>
+ <holder>Apache Software Foundation</holder>
+ </copyright>
+ <author>
+ <firstname>The Rivet Team</firstname>
+ <affiliation>
+ <orgname>The Apache Software Foundation</orgname>
+ <address>
+ <email>rivet-dev@tcl.apache.org</email>
+ </address>
+ </affiliation>
+ </author>
+ </articleinfo>
+ <!--para>
+ This document is also available in the following languages: <ulink
+ url="index.it.html">Italian</ulink>, <ulink
+ url="index.ru.html">Russian</ulink>
+ </para-->
+
+ <para>
+ Document revision: $Revision: 718432 $, last modified $Date: 2008-11-18 00:14:18 +0100 (Tue, 18 Nov 2008) $ by $Author: karl $.
+ </para>
+
+ <section id="introduction">
+ <title>Introduction to Apache Rivet</title>
+ <para>
+ Apache Rivet is a system for creating dynamic web content via a
+ programming language integrated with Apache Web Server. It is
+ designed to be fast, powerful and extensible, consume few system
+ resources, be easy to learn, and to provide the user with a
+ platform that can also be used for other programming tasks
+ outside the web (GUI's, system administration tasks, text
+ processing, database manipulation, XML, and so on). In order to
+ meet these goals, we have chosen the Tcl programming language to
+ combine with the Apache Web Server.
+ </para>
+
+ <para>
+ In this manual, we aim to help get you started, and then
+ writing productive code as quickly as possible, as well as
+ giving you ideas on how to best take advantage of Rivet's
+ architecture to create different styles of web site.
+ </para>
+
+ <para>
+ This documentation is a work in progress, and, like everything
+ else about Apache Rivet, it is Free Software. If you see
+ something that needs improving, and have ideas or suggestions,
+ don't hesitate to let us know. If you want to contribute
+ directly, better yet!
+ </para>
+ </section>
+
+
+ <section id="installation">
+ <title>Apache Rivet Installation</title>
+
+ <procedure>
+ <step>
+ <title>Check Dependencies</title>
+ <para>
+ To install Rivet, you will need Tcl 8.4 or greater and
+ Apache 1.3.xx. It is known to run on Linux, FreeBSD,
+ OpenBSD, and Solaris and HPUX. Windows NT is also possible
+ - please see the directions in the distribution. Note that
+ Rivet does not currently work with Apache 2.
+ </para>
+ </step>
+ <step>
+ <title>Get Rivet</title>
+ <para>
+ Download the sources at <ulink
+ url="http://tcl.apache.org/rivet/download"/>. Currently
+ the only way to obtain Rivet. In the future, we hope to
+ have a FreeBSD port, Debian package, RPM's, and windows
+ binaries.
+ </para>
+ </step>
+ <step performance="required">
+ <title>Install Tcl</title>
+ <para>
+ If you don't have Tcl already, you need it! If you already
+ have it, you should just be able to use your system Tcl as
+ long as it is recent. You can tell Rivet where Tcl is via
+ the <option>-with-tclconfig</option> option to
+ <command>configure.tcl</command> (see below).</para>
+ </step>
+ <step performance="optional">
+ <title>Get and Install Apache Sources</title>
+ <para>
+ Rivet needs some Apache include (.h) files in order to
+ build. The easiest way to get them is to download the
+ source code of the Apache web server, although some systems
+ (Debian GNU/Linux for example) make it possible to install
+ only the headers and other development files. If you intend
+ to build Rivet statically (compiled into the Apache web
+ server instead of loaded dynamically), you definitely need
+ the sources. We recommend that you build Rivet as a
+ loadable shared library, for maximum flexibility, meaning
+ that you also build Apache to be able to load modules.
+ Other than that, the default Apache install is fine. We
+ will tell Rivet where it is located via the
+ <option>-with-apxs</option> option to
+ <command>configure.tcl</command> (see below).
+ </para>
+ <para>
+ The source code for the Apache web server may be found by
+ following the links here: <ulink
+ url="http://httpd.apache.org/"/>.
+ </para>
+ </step>
+ <step>
+ <title>Uncompress Sources</title>
+ <para>
+ We will assume that you have Apache installed at this point.
+ You must uncompress the Rivet sources in the directory where you
+ wish to compile them.
+
+ <programlisting>gunzip tcl-rivet-X.X.X.tar.gz
+tar -xvf tcl-rivet-X.X.X.tar.gz</programlisting>
+
+ </para>
+ </step>
+ <step>
+ <title>Building Rivet</title>
+ <substeps>
+ <step>
+ <para>
+ On Linux or Unix systems, Rivet uses the standard
+ ./configure ; make ; make install technique.
+ </para>
+ <para>
+ There are several options to configure that might be useful
+ or necessary:
+ <variablelist>
+ <varlistentry>
+ <term>--with-tcl</term>
+ <listitem>
+ <para>
+ This points to the directory where the
+ <filename>tclConfig.sh</filename> file is located.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--with-tclsh</term>
+ <listitem>
+ <para>This points to the location of the
+ <filename>tclsh</filename> executable.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>--with-apxs</term>
+ <listitem>
+ <para>The location of the <filename>apxs</filename>
+ program that provides information about the
+ configuration and compilation of Apache modules.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <programlisting>cd src/
+./configure --with-tcl=/usr/lib/tcl8.4/ --with-tclsh=/usr/bin/tclsh8.4 \
+ --with-apxs=/usr/bin/apxs
+</programlisting>
+
+ </step>
+ <step>
+ <title>Run make</title>
+ <para>
+ At this point, you are ready to run make, which should
+ run to completion without any errors (a warning or two
+ is ok, generally).
+ </para>
+ </step>
+ <step>
+ <title>Install</title>
+ <para>
+ Now, you are ready to run the <command>make
+ install</command> to install the resulting files.
+ This should copy the shared object (like
+ <filename>mod_rivet.so</filename>, if one was
+ successfully created, into Apache's
+ <filename>libexec</filename> directory, as well as
+ install some support scripts and various code.
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <title>Apache Configuration Files</title>
+ <para>
+ Rivet is relatively easy to configure - we start off by
+ adding the module itself:
+ </para>
+
+ <programlisting>LoadModule rivet_module <replaceable>/usr/lib/apache/1.3/mod_rivet.so</replaceable></programlisting>
+
+ <para>
+ This tells Apache to load the Rivet shared object, wherever
+ it happens to reside on your file system. Now we have to
+ tell Apache what kind of files are "Rivet" files and how to
+ process them:
+ </para>
+
+ <programlisting>AddType application/x-httpd-rivet .rvt
+AddType application/x-rivet-tcl .tcl</programlisting>
+
+ <para>
+ These tell Apache to process files with the
+ <filename>.rvt</filename> and <filename>.tcl</filename>
+ extensions as Rivet files.
+ </para>
+ <para>
+ The characters encoding can be changed using the <command>header type</command> command,
+ but if you want to change the default charset for the whole site or directory hierarchy
+ a new charset can be embedded in a AddType line in a way similar to the html pages encoding.
+ </para>
+ <programlisting>AddType 'application/x-httpd-rivet;charset=utf-8' rvt</programlisting>
+ <para>
+ Pages which this configuration applies to send back to the client
+ a <command>Content-Type:'text/html;charset=utf-8'</command> header.
+ </para>
+ <para>You may also wish to use Rivet files as index files for
+ directories. In that case, you would do the following:</para>
+ <programlisting>DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</programlisting>
+ <para>
+ For other directives that Rivet provides for Apache
+ configuration, please see <xref linkend="directives"/>.
+ </para>
+ </step>
+ </procedure>
+ </section>
+
+ <section id="directives">
+ <title>Rivet Apache Directives</title>
+
+ <para>
+ These directives are used within the Apache httpd server
+ configuration files to modify Apache Rivet's behavior. Their
+ precedence is as follows: <command>RivetDirConf</command>,
+ <command>RivetUserConf</command>,
+ <command>RivetServerConf</command>, meaning that DirConf will
+ override UserConf, which will in turn override ServerConf.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>RivetServerConf</command>
+ <group choice="req">
+ <arg>CacheSize</arg>
+ <arg>GlobalInitScript</arg>
+ <arg>ChildInitScript</arg>
+ <arg>ChildExitScript</arg>
+ <arg>BeforeScript</arg>
+ <arg>AfterScript</arg>
+ <arg>ErrorScript</arg>
+ <arg>UploadDirectory</arg>
+ <arg>UploadMaxSize</arg>
+ <arg>UploadFilesToVar</arg>
+ <arg>SeparateVirtualInterps</arg>
+ <arg>HonorHeaderOnlyRequests</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para><command>RivetServerConf</command> specifies a global
+ option that is valid for the whole server. If you have a
+ virtual host, in some cases, the option specified in the
+ virtualhost takes precedence over the 'global' version.
+ </para>
+ </listitem>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">CacheSize</arg>
+ <arg><replaceable>size</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Sets the size of the internal page cache, where
+ <option><replaceable>size</replaceable></option> is
+ the number of byte-compiled pages to be cached for
+ future use. Default is
+ <command>MaxRequestsPerChild</command> / 5, or 50,
+ if <command>MaxRequestsPerChild</command> is 0.
+ </para>
+ <para>
+ This option is completely global, even when using
+ separate, per-virtual host interpreters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">GlobalInitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Tcl script that is run when each interpreter is
+ initialized. <replaceable><option>script</option></replaceable>
+ is an actual Tcl script, so to run a file, you would
+ do:
+
+ <programlisting>RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"</programlisting>
+ </para>
+ <para>
+ This option is ignored in virtual hosts.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ChildInitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated when each Apache child
+ process is initialized. This is the recommended
+ place to load modules, create global variables, open
+ connections to other facilities (such as databases)
+ and so on.
+ </para>
+ <para>
+ In virtual hosts, this script is run in addition to
+ any global childinitscript.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ChildExitScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated when each Apache child
+ process exits. This is the logical place to clean
+ up resources created in
+ <option>ChildInitScript</option>, if necessary.
+ </para>
+ <para>
+ In virtual hosts, this script is run in addition to
+ any global childexitscript.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">BeforeScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be evaluated before each server parsed
+ (.rvt) page. This can be used to create a standard
+ header, for instance. It could also be used to load
+ code that you need for every page, if you don't want
+ to put it in a <option>GlobalInitScript</option>
+ <option>ChildInitScript</option> when you are first
+ developing a web site.
+ <note>
+ This code is evaluated at the global level, not
+ inside the request namespace where pages are
+ evaluated.
+ </note>
+ </para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">AfterScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Script to be called after each server parsed (.rvt) page.
+ </para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">ErrorScript</arg>
+ <arg><replaceable>script</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ When Rivet encounters an error in a script, it
+ constructs an HTML page with some information about
+ the error, and the script that was being
+ evaluated. If an <option>ErrorScript</option> is
+ specified, it is possible to create custom error
+ pages. This may be useful if you want to make sure
+ that users never view your source code.
+ </para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">UploadDirectory</arg>
+ <arg><replaceable>directory</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>Directory to place uploaded files.</para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">UploadMaxSize</arg>
+ <arg><replaceable>size</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>Maximum size for uploaded files.</para>
+ <para>
+ In virtual hosts, this option takes precedence over
+ the global setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">UploadFilesToVar</arg>
+ <group choice="req"><arg>yes</arg><arg>no</arg></group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ This option controls whether it is possible to
+ upload files to a Tcl variable. If you have a size
+ limit, and don't have to deal with large files, this
+ might be more convenient than sending the data to a
+ file on disk.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">SeparateVirtualInterps</arg>
+ <group choice="req">
+ <arg>yes</arg>
+ <arg>no</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ If on, Rivet will create a separate Tcl interpreter
+ for each Apache virtual host. This is useful in an
+ ISP type situation where it is desirable to separate
+ clients into separate interpreters, so that they
+ don't accidentally interfere with one another.
+ </para>
+ <para>This option is, by nature, only available at the
+ global level.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">HonorHeaderOnlyRequests</arg>
+ <group choice="req">
+ <arg>yes</arg>
+ <arg>no</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ If a HEAD requests is issued by the client Rivet detects
+ this case and sends back to the client a standard header
+ response. If the real header has to be examined (e.g.
+ for debugging) you can turn on this options which
+ causes Rivet to parse and run the script the requests refers
+ to. In this case the real header is returned to the client.
+ </para>
+ <para>This option is, by nature, only available at the global level</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>RivetDirConf</command>
+ <group choice="req">
+ <arg>BeforeScript</arg>
+ <arg>AfterScript</arg>
+ <arg>ErrorScript</arg>
+ <arg>UploadDirectory</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ These options are the same as for
+ <command>RivetServerConf</command>, except that they are
+ only valid for the directory where they are specified, and
+ its subdirectories. It may be specified in
+ <command>Directory</command> sections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>RivetUserConf</command>
+ <group choice="req">
+ <arg>BeforeScript</arg>
+ <arg>AfterScript</arg>
+ <arg>ErrorScript</arg>
+ <arg>UploadDirectory</arg>
+ </group>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ These options are the same as for
+ <command>RivetServerConf</command>, except that they are
+ only valid for the directory where they are specified, and
+ its subdirectories.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section id="commands">
+ <title>Rivet Tcl Commands and Variables</title>
+
+ <refentry id="var">
+ <refnamediv>
+ <refname>var</refname>
+ <refname>var_qs</refname>
+ <refname>var_post</refname>
+ <refpurpose>get the value of a form variable.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>var</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>var_qs</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>var_post</command>
+ <group choice="req">
+ <arg>get</arg>
+ <arg>list</arg>
+ <arg>exists</arg>
+ <arg>number</arg>
+ <arg>all</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ The <command>var</command> command retrieves information
+ about GET or POST variables sent to the script via client
+ request. It treats both GET and POST variables the same,
+ regardless of their origin. Note that there are two
+ additional forms of <command>var</command>:
+ <command>var_qs</command> and <command>var_post</command>.
+ These two restrict the retrieval of information to
+ parameters arriving via the querystring
+ (?foo=bar&bee=bop) or POSTing, respectively.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>var</command>
+ <arg choice="plain">get</arg>
+ <arg><replaceable>varname</replaceable></arg>
+ <arg><replaceable><optional>default</optional></replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the value of variable
+ <option><replaceable>varname</replaceable></option>
+ as a string (even if there are multiple values). If
+ the variable doesn't exist as a GET or POST
+ variable, the
+ <option><replaceable><optional>default</optional></replaceable></option>
+ value is returned, otherwise "" - an empty string -
+ is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>var</command>
+ <arg choice="plain">list</arg>
+ <arg><replaceable>varname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the value of variable
+ <option><replaceable>varname</replaceable></option> as a
+ list, if there are multiple values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>var</command>
+ <arg choice="plain">exists</arg>
+ <arg><replaceable>varname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns 1 if
+ <option><replaceable>varname</replaceable></option>
+ exists, 0 if it doesn't.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>var</command>
+ <arg choice="plain">number</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the number of variables.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>var</command>
+ <arg choice="plain">all</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Return a list of variable names and values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ See <xref linkend="variable_access"/>.
+ </para>
+
+ </refsect1>
+ </refentry>
+
+ <refentry id="upload">
+ <refnamediv>
+ <refname>upload</refname>
+ <refpurpose>handle a file uploaded by a client.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>upload</command>
+ <group choice="req">
+ <arg>channel</arg>
+ <arg>save</arg>
+ <arg>data</arg>
+ <arg>exists</arg>
+ <arg>size</arg>
+ <arg>type</arg>
+ <arg>filename</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>The upload command is for file upload manipulation.
+ See the relevant Apache Directives to further configure the
+ behavior of this Rivet feature.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">channel</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ When given the name of a file upload
+ <option><replaceable>uploadname</replaceable></option>,
+ returns a Tcl channel that can be used to access the
+ uploaded file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">save</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Saves the
+ <option><replaceable>uploadname</replaceable></option> in
+ the file
+ <option><replaceable>filename</replaceable></option>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">data</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns data uploaded to the server. This is binary clean
+ - in other words, it will work even with files like
+ images, executables, compressed files, and so on.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">exists</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns true if an upload named <arg>uploadname</arg>
+ exists. This can be used in scripts that are meant to
+ be run by different forms that send over uploads that
+ might need specific processing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">size</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the size of the file uploaded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">type</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ If the <varname>Content-type</varname> is set, it is
+ returned, otherwise, an empty string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">filename</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the filename on the remote host that uploaded the file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">tempname</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the name of the temporary file on the local host that the file was uploaded info.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
+ <arg choice="plain">names</arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns the variable names, as a list, of all the files
+ uploaded.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ See <xref linkend="upload"/>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="load_response">
+ <refnamediv>
+ <refname>load_response</refname>
+ <refpurpose>load form variables into an array.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>load_response</command>
+ <arg><replaceable>arrayName</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ Load any form variables passed to this page into an
+ array. If <command>load_response</command> is called without
+ arguments the array <option>response</option> is created in
+ the scope of the caller. If the variables var1,var2,var3...
+ having values val1,val2,val3... are passed to the page, the
+ resulting array will be a collection mapping var1,var2,var3...
+ to their corresponding values. <command>load_response</command>
+ was inspired by the same NeoWebScript procedure in the way
+ it deals with multiple assignments: if a variable
+ is assigned more than once the corresponding array element will be a
+ list of the values for the variable. This can be useful in the case
+ of forms with checkbox options that are given the same name.
+ Calling <command>load_response</command> several times for the same
+ array results in adding more values to the array at every call.
+ When needed it is left to the caller to empty the array between
+ two subsequent calls.
+ </refsect1>
+ </refentry>
+
+ <refentry id="load_headers">
+ <refnamediv>
+ <refname>load_headers</refname>
+ <refpurpose>get client request's headers.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>load_headers</command>
+ <arg><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Load the headers that come from a client request into the
+ provided array name, or use <option>headers</option> if no
+ name is provided.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="load_cookies">
+ <refnamediv>
+ <refname>load_cookies</refname>
+ <refpurpose>get any cookie variables sent by the client.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>load_cookies</command>
+ <arg choice="opt"><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ </refsect1>
+ <para>
+ Load the array of cookie variables into the specified
+ array name. Uses array <option>cookies</option> by
+ default.
+ </para>
+ </refentry>
+
+ <refentry id="load_env">
+ <refnamediv>
+ <refname>load_env</refname>
+ <refpurpose>get the request's environment variables.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>load_env</command>
+ <arg choice="opt"><replaceable>array_name</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Load the array of environment variables into the specified
+ array name. Uses array <option>::request::env</option> by
+ default.
+ </para>
+ <para>
+ As Rivet pages are run in the <option>::request</option>
+ namespace, it isn't necessary to qualify the array name
+ for most uses - it's ok to access it as
+ <option>env</option>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="env">
+ <refnamediv>
+ <refname>env</refname> <refpurpose>Loads a single
+ "environmental variable" into a Tcl variable.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>env</command>
+ <arg><replaceable>varName</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ If it is only necessary to load one environmental variable,
+ this command may be used to avoid the overhead of loading
+ and storing the entire array.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="include">
+ <refnamediv>
+ <refname>include</refname>
+ <refpurpose>includes a file into the output stream without modification.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>include</command>
+ <arg><replaceable>filename_name</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Include a file without parsing it for processing tags <?
+ and ?>. This is the best way to include an HTML file or
+ any other static content.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="parse">
+ <refnamediv>
+ <refname>parse</refname>
+ <refpurpose>parses a Rivet template file.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>parse</command>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Like the Tcl <command>source</command> command, but also
+ parses for Rivet <? and ?> processing tags. Using
+ this command, you can use one .rvt file from another.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="headers">
+ <refnamediv>
+ <refname>headers</refname>
+ <refpurpose>set and parse HTTP headers.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>headers</command>
+ <group choice="req">
+ <arg>set</arg>
+ <arg>redirect</arg>
+ <arg>add</arg>
+ <arg>type</arg>
+ <arg>numeric</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ The <command>headers</command> command is for setting and
+ parsing HTTP headers.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><cmdsynopsis>
+ <command>headers</command>
+ <arg choice="plain">set</arg>
+ <arg><replaceable>headername</replaceable></arg>
+ <arg><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Set arbitrary header names and values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>headers</command>
+ <arg choice="plain">redirect</arg>
+ <arg><replaceable>uri</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Redirect from the current page to a new
+ URI. <emphasis>Must</emphasis> be done in the first block
+ of TCL code.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>headers</command>
+ <arg choice="plain">add</arg>
+ <arg><replaceable>headername</replaceable></arg>
+ <arg><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>Add text to header
+ <varname>headername</varname>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><cmdsynopsis>
+ <command>headers</command>
+ <arg choice="plain">type</arg>
+ <arg><replaceable>content-type</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ This command sets the <constant>Content-type</constant>
+ header returned by the script, which is useful if you wish
+ to send content other than HTML with Rivet - PNG or jpeg
+ images, for example.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>headers</command>
+ <arg choice="plain">numeric</arg>
+ <arg><replaceable>response code</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>Set a numeric response code, such as 200, 404 or 500.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+
+ <refentry id="makeurl">
+ <refnamediv>
+ <refname>makeurl</refname>
+ <refpurpose>construct url's based on hostname, port.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>makeurl</command>
+ <arg><replaceable>filename</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Create a self referencing URL from a filename. For example:
+ <programlisting>makeurl /tclp.gif</programlisting>
+ returns
+ <computeroutput>http://[hostname]:[port]/tclp.gif</computeroutput>.
+ where hostname and port are the hostname and port of the
+ server in question.
+ </para>
+ </refsect1>
+ </refentry>
+
+
+ <refentry id="cookie">
+ <refnamediv>
+ <refname>cookie</refname>
+ <refpurpose>get and set cookies.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>cookie</command>
+ <arg>set</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ <arg><replaceable><optional>cookiValue</optional></replaceable></arg>
+ <arg>-days <replaceable>expireInDays</replaceable></arg>
+ <arg>-hours <replaceable>expireInHours</replaceable></arg>
+ <arg>-minutes <replaceable>expireInMinutes</replaceable></arg>
+ <arg>-expires <replaceable>Wdy, DD-Mon-YYYY HH:MM:SS GMT</replaceable></arg>
+ <arg>-path <replaceable>uriPathCookieAppliesTo</replaceable></arg>
+ <arg>-secure <replaceable>1/0</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>cookie</command>
+ <arg>get</arg>
+ <arg><replaceable>cookieName</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <command>cookie</command> gets or sets a cookie. When you
+ get a cookie, the command returns the value of the cookie,
+ or an empty string if no cookie exists.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="clock_to_rfc">
+ <refnamediv>
+ <refname>clock_to_rfc850_gmt</refname>
+ <refpurpose>create a rfc850 time from [clock seconds].</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>clock_to_rfc850_gmt</command>
+ <arg><replaceable>seconds</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Convert an integer-seconds-since-1970 click value to
+ RFC850 format, with the additional requirement that it be
+ GMT only.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="html">
+ <refnamediv>
+ <refname>html</refname>
+ <refpurpose>construct html tagged text.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>html</command>
+ <arg><replaceable>string</replaceable></arg>
+ <arg rep="repeat"><replaceable>arg</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Print text with the added ability to pass HTML tags
+ following the string. Example:
+ <programlisting>html "Test" b i</programlisting>
+ produces: <computeroutput><b><i>Test</i></b></computeroutput>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="incr0">
+ <refnamediv>
+ <refname>incr0</refname>
+ <refpurpose>increment a variable or set it to 1 if nonexistant.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>incr0</command>
+ <arg><replaceable>varname</replaceable></arg>
+ <arg><replaceable>num</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Increment a variable
+ <option><replaceable>varname</replaceable></option> by
+ <option><replaceable>num</replaceable></option>. If the
+ variable doesn't exist, create it instead of returning an
+ error.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="parray">
+ <refnamediv>
+ <refname>parray</refname>
+ <refpurpose>Tcl's <command>parray</command> with html formatting.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>parray</command>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <arg><replaceable><optional>pattern</optional></replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ An html version of the standard Tcl
+ <command>parray</command> command. Displays the entire
+ contents of an array in a sorted, nicely-formatted way.
+ Mostly used for debugging purposes.
+ </para>
+
+ </refsect1>
+ </refentry>
+
+ <refentry id="abort_page">
+ <refnamediv>
+ <refname>abort_page</refname>
+ <refpurpose>Stops outputing data to web page, similar in
+ purpose to PHP's <command>die</command> command.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>abort_page</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title> <para>This command flushes the
+ output buffer and stops the Tcl script from sending any more
+ data to the client. A normal Tcl script might use the
+ <command>exit</command> command, but that cannot be used in
+ Rivet without actually exiting the apache child
+ process!</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="no_body">
+ <refnamediv>
+ <refname>no_body</refname>
+ <refpurpose>Prevents Rivet from sending any content.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>no_body</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ This command is useful for situations where it is necessary
+ to only return HTTP headers and no actual content. For
+ instance, when returning a 304 redirect.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="escape_string">
+ <refnamediv>
+ <refname>escape_string</refname>
+ <refpurpose>convert a string into escaped characters.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>escape_string</command>
+ <arg>string</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Scans through each character in the specified string looking
+ for special characters, escaping them as needed, mapping
+ special characters to a quoted hexadecimal equivalent,
+ returning the result.
+ </para>
+ <para>
+ This is useful for quoting strings that are going to be
+ part of a URL.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="escape_sgml_chars">
+ <refnamediv>
+ <refname>escape_sgml_chars</refname>
+ <refpurpose>escape special SGML characters in a string.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>escape_sgml_chars</command>
+ <arg>string</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Scans through each character in the specified string looking
+ for any special (with respect to SGML, and hence HTML) characters
+ from the specified string, and returns the result.
+ For example, the right angle
+ bracket is escaped to the corrected ampersand gt symbol.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="escape_shell_command">
+ <refnamediv>
+ <refname>escape_shell_command</refname>
+ <refpurpose>escape shell metacharacters in a string.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>escape_shell_command</command>
+ <arg>string</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Scans through each character in the specified string looking
+ for any shell metacharacters, such as asterisk, less than and
+ greater than, parens, square brackets, curly brackets, angle
+ brackets, dollar signs, backslashes, semicolons, ampersands,
+ vertical bars, etc.
+ </para>
+ <para>
+ For each metacharacter found, it is quoted in the result by
+ prepending it with a backslash, returning the result.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
+
+ </refsect1>
+ </refentry>
+
+ <refentry id="unescape_string">
+ <refnamediv>
+ <refname>unescape_string</refname>
+ <refpurpose>unescape escaped characters in a string.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>unescape_string</command>
+ <arg>string</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Scans through each character in the specified string looking
+ for escaped character sequences (characters containing a
+ percent sign and two hexadecimal characters, unescaping them
+ back to their original character values, as needed, also mapping
+ plus signs to spaces, and returning the result.
+ </para>
+ <para>
+ This is useful for unquoting strings that have been quoted to
+ be part of a URL.
+ </para>
+ <note>
+ You must require the Rivet package in order to gain access to this command
+ </note>
+ </refsect1>
+ </refentry>
+
+ </section>
+
+ <section id="examples">
+ <title>Examples and Usage</title>
+ <para>
+ Some examples of Rivet usage follow. Some prior Tcl knowledge
+ is assumed. If you don't know much Tcl, don't worry, it's easy,
+ and there are some good resources available on the web that will
+ get you up to speed quickly. Go to the <link
+ linkend="websites">web sites</link> section and have a look.
+ </para>
+
+ <example id="hello world">
+ <title>Hello World</title>
+ <para>
+ As with any tool, it's always nice to see something work, so
+ let's create a small "Hello World" page.</para>
+ <para>
+ Assuming you have Apache configured correctly, create a file
+ called <filename>hello.rvt</filename> where Apache can find
+ it, with the following content:
+ </para>
+ <programlisting>&hello.rvt;</programlisting>
+ <para>
+ If you then access it with your browser, you should see a
+ blank page with the text "Hello World" (without the quotes) on
+ it.
+ </para>
+ </example>
+
+ <example id="table">
+ <title>Generate a Table</title>
+ <para>
+ In another simple example, we dynamically generate a table:
+ </para>
+ <programlisting>&table.rvt;</programlisting>
+ <para>
+ If you read the code, you can see that this is pure Tcl. We
+ could take the same code, run it outside of Rivet, and it
+ would generate the same HTML!
+ </para>
+ <para>
+ The result should look something like this:
+ </para>
+ <graphic fileref="table.png"/>
+
+ </example>
+
+ <example id="variable_access">
+ <title>Variable Access</title>
+ <para>
+ Here, we demonstrate how to access variables set by GET or
+ POST operations.
+ </para>
+ <para>
+ Given an HTML form like the following:
+ </para>
+ <programlisting>&vars.html;</programlisting>
+ <para>
+ We can use this Rivet script to get the variable values:
+ </para>
+ <programlisting>&vars.rvt;</programlisting>
+ <para>
+ The first statement checks to make sure that the
+ <varname>boss</varname> variable has been passed to the
+ script, and then does something with that information. If
+ it's not present, an error is added to the list of errors.
+ </para>
+ <para>
+ In the second block of code, the variable
+ <varname>salary</varname> is fetched, with one more error
+ check - because it's a number, it needs to be composed of
+ digits.
+ </para>
+ <para>
+ The <varname>boss</varname> variable isn't required to have
+ been sent - we set it to "Mr. Burns" if it isn't among the
+ information we received.
+ </para>
+ <para>
+ The last bit of variable handing code is a bit trickier.
+ Because <varname>skills</varname> is a listbox, and can
+ potentially have multiple values, we opt to receive them as a
+ list, so that at some point, we could iterate over them.
+ </para>
+ <para>
+ The script then checks to make sure that
+ <varname>errlist</varname> is empty and outputting a thankyou
+ message. If <varname>errlist</varname> is not empty, the list
+ of errors it contains is printed.
+ </para>
+ </example>
+
+ <example id="file_upload">
+ <title>File Upload</title>
+ <para>
+ The <command>upload</command> command endows Rivet with an
+ interface to access files transferred over http as parts of a
+ multipart form. The following HTML in one file, say,
+ <filename>upload.html</filename> creates a form with a text
+ input entry. By clicking the file chooser button the file
+ browser shows up and the user selects the file to be uploaded
+ (the file path will appear in the text input). In order to make
+ sure you're uploading the whole file you must combine the
+ action of the enctype and method attributes of the
+ <form...> tag in the way shown in the example. Failure
+ to do so would result in the client sending only the file's
+ path, rather than the actual contents.
+ </para>
+ <programlisting>&upload.html;</programlisting>
+ <para>
+ In the script invoked by the form
+ (<filename>upload.rvt</filename>) <command>upload</command>
+ <arg>argument ...</arg> commands can be used to manipulate the
+ various files uploaded.
+ </para>
+ <programlisting>&upload.rvt;</programlisting>
+ <para>
+ Don't forget that the apache server must have write access to
+ the directory where files are being created. The Rivet Apache
+ directives have a substantial impact on the upload process,
+ you have to carefully read the docs in order to set the
+ appropriate directives values that would match your
+ requirements.
+ </para>
+ <para>
+ It is also important to understand that some
+ <command>upload</command> commands are effective only when
+ used in a mutually exclusive way. Apache stores the data in
+ temporary files which are read by the <command>upload save
+ <arg>upload name</arg><arg>filename</arg></command> or by the
+ <command>upload data <arg>upload name</arg></command>
+ command. Subsequent calls to these 2 commands using the same
+ <arg>upload name</arg> argument will return no data on the
+ second call. Likewise <command>upload channel <arg>upload
+ name</arg></command> will return a Tcl file channel that you
+ can use in regular Tcl scripts only if you haven't already
+ read the data, for example with a call to the <command>upload
+ data <arg>upload name</arg></command> command.
+ </para>
+ </example>
+ <example id="file_download">
+ <title>File Download</title>
+ <para>
+ In general setting up a data file for being sent over http is
+ as easy as determining the file's URI and letting Apache's
+ do all that is needed. If this approach fits your design all
+ you have to do is to keep the downloadable files somewhere
+ within Apache's DocumentRoot (or in any of the directories
+ Apache has right to access).
+ </para>
+ <para>
+ When a client sends a request for a file, Apache takes
+ care of determining the filetype, sends appropriate headers to
+ the client and then the file content. The client is responsible
+ for deciding how to handle the data accordingly to the
+ "content-type" headers and its internal design. For example
+ when browsers give up trying to display a certain "content-type"
+ they display a download dialog box asking for directions from
+ the user.
+ </para>
+ <para>
+ Rivet can help if you have more sofisticated needs. For
+ instance you may be developing an application that uses
+ webpages to collect input data. This information might be
+ passed on to scripts or programs for processing.
+ In this case a real file representing the
+ data doesn't exist and the content is generated on demand
+ by the server.
+ In other circumstances you may need to dynamically inhibit
+ the download of specific files and hide them away,
+ Your scripts may expunge from the pages
+ every link to these files (your pages are dynamic, aren't
+ they?) and move them out of way, but it looks like a
+ cumbersome solution.
+ </para>
+ <para>
+ Putting Tcl and Rivet in charge of the whole download
+ mechanism helps in building cleaner and safer approaches to
+ the download problem.
+ </para>
+ <para>
+ In this example a procedure checks for the existence of a
+ parameter passed in by the browser. The parameter is the name
+ (without extension) of a pdf file.
+ Pdf files are stored in a directory whose path is
+ in the <command>pdf_repository</command> variable.
+ </para>
+ <para>
+ This code is reported as an example of how to control
+ the protocol using the <command>headers</command> command.
+ </para>
+ <programlisting>&download.tcl;</programlisting>
+ <para>
+ Before the pdf is sent the procedure sets the
+ <constant>Content-Type</constant>,
+ <constant>Content-Disposition</constant>,
+ <constant>Content-Description</constant> and
+ <constant>Content-Length</constant> headers to inform
+ the client about the file type, name and size. Notice that in
+ order to set the <constant>Content-Type</constant> header Rivet
+ uses a specialiezed form of the <command>headers</command>
+ command. Headers must be sent before data gets sent down the
+ output channel. Messing with this prescription causes an error
+ to be raised (in fact the protocol itself is been violated)
+ </para>
+ <para>
+ More information about the meaning of the mime headers in the
+ http context can be found at
+ <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"/>
+ </para>
+ </example>
+ <example id="ajax_xml_messaging">
+ <title>XML Messages and Ajax</title>
+ <para>
+ The <command>headers</command> command is crucial for generating
+ XML messages that have to be understood by JavaScript code used
+ in Ajax applications.
+ </para>
+ <para>
+ Ajax is a web programming technique that heavily relies on the
+ abilty of JavaScript (and other scriping languages like VBScript) to
+ manipulate dynamically the HTML structure of a page. In modern browsers
+ JavaScript code is enabled to send GET or POST requests to the webserver.
+ These requests can request the server to run scripts (for example Rivet
+ Tcl scripts) that build responses and to be sent back to the browser.
+ JavaScript code reads asynchronously these responses, elaborates
+ their content and accordingly modifies the page on display.
+ Ajax helps to build web applications that are more responsive and
+ flexible, if you can cope with the complexities, subtleties and
+ incompatibilities even among the most common browsers available.
+ Instead of going through the cycle of request-generation-transfer
+ of a page, Ajax allows the programmer to request and transmit only
+ the essential data thus matching the general requirement of separation
+ between data and user interface (and saving the server from sending over
+ the same html code and graphics when only a fraction of a page has
+ to be refreshed)
+ </para>
+ <para>
+ In Ajax applications the communication between client and server
+ is controlled by an instance of a specialized object: the non-IE world
+ (Firefox,Safari,Opera...) uses the XMLHttpRequest class to create it,
+ whereas IE uses the ActiveXObject class.
+ <note>
+ With the release of IE7 Microsoft introduced native support for
+ <ulink url="http://blogs.msdn.com/ie/archive/2006/01/23/516393.aspx">
+ XMLHttpRequest</ulink> class objects
+ </note>
+ By creating an instance of this class a POST or GET request can be sent
+ to the server, whose response is stored in a
+ property ('returnedText') of the communication object.
+ It's become widely customary to encode in XML messages the response
+ from the server to the browser. A number of XML specification are
+ being used for this, among which XML-RPC and SOAP are worth to be
+ quoted. Anyway, you can invent your own message definitions
+ (either based on XML or anything else), but one has to be aware of
+ the fact that if the http headers are properly set and the message
+ returned to the client is a well formed XML fragment, also the property
+ <ulink url="http://www.w3schools.com/ajax/ajax_responsexml.asp">
+ XMLResponse</ulink> is set with a reference to an object
+ that represent the
+ <ulink url="http://www.w3schools.com/dom/default.asp">
+ DOM</ulink> of the XML response.
+ By means of the XML W3C DOM tree methods and properties
+ you can write scripts that read and manipulate the data embedded in
+ the XML message.
+ </para>
+ <para>
+ In this example a Rivet script initializes an array with the
+ essential data regarding a few of the major composers of the
+ european music. This array plays the role of a database
+ which, in a real case, has is a real DBM which stores large
+ tables with thousands records and more complex and
+ extended information.
+ The script is designed to send back to the client two
+ types of responses: a catalog of the composers or a single
+ record of a composer.
+ </para>
+ <programlisting>&rivet_web_service.tcl;</programlisting>
+ <para>
+ For sake of brevity the JavaScript and HTML will not listed here.
+ They can be downloaded (along with the Tcl script) stored in the
+ <ulink url="http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz">
+ rivet-ajax.tar.gz</ulink> archive. By simply
+ opening this tar archive in a directory accessible by your
+ apache server and pointing your browser to the rivetService.html
+ page you should see a page with a drop-down list. Every time
+ a different name is picked from the list a new query is sent and
+ logged in the apache access.log file, even though the html
+ is never reloaded.
+ </para>
+ </example>
+ </section>
+
+ <section id="tcl_packages">
+ <title>Rivet Tcl Packages</title>
+ <para>
+ In addition to the core Apache module, Rivet provides a number
+ of Tcl packages that include potentially useful code.
+ </para>
+ <itemizedlist>
+
+ <listitem>
+ <para>commserver is a package providing a server that can be
+ used for IPC. Still experimental. Requires the comm package
+ from tcllib.</para>
+ </listitem>
+
+ <listitem>
+ <para>dio is a database abstraction layer.</para>
+ </listitem>
+
+ <listitem>
+ <para>dtcl is a compatibility package for mod_dtcl
+ applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>form - for creating forms.</para>
+ </listitem>
+
+ <listitem>
+ <para>rivet - some additional, useful routines.</para>
+ </listitem>
+
+ <listitem>
+ <para>tclrivet</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="dio">
+ <title>DIO - Database Interface Objects</title>
+ <refentry id="dio_package">
+ <refnamediv>
+ <refname>DIO</refname>
+ <refpurpose>Database Interface Objects</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>::DIO::handle</command>
+ <arg choice="plain"><replaceable>interface</replaceable></arg>
+ <arg choice="opt"><replaceable>objectName</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <command>DIO</command> is designed to be a generic,
+ object-oriented interface to SQL databases. Its main goal
+ is to be as generic as possible, but since not all SQL
+ databases support the exact same syntaxes, keeping code
+ generic between databases is left to the abilities of the
+ programmer. DIO simply provides a way to keep the Tcl
+ interface generic.
+ </para>
+ <para>
+ <option>interface</option> - The name of the database
+ interface. Currently supported interfaces are
+ <option>Postgresql</option> and <option>Mysql</option>.
+ </para>
+ <para>
+ If <option><replaceable>objectName</replaceable></option> is
+ specified, DIO creates an object of that name. If there is
+ no <option><replaceable>objectName</replaceable></option>
+ given, DIO will automatically generate a unique object ID
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-host</arg>
+ <arg choice="opt"><replaceable>hostname</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ The hostname of the computer to connect to. If none
+ is given, DIO assumes the local host.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-port</arg>
+ <arg><replaceable>portNumber</replaceable></arg>
+ </cmdsynopsis>
+ <para>The port number to connect to on <option>hostname</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-user</arg>
+ <arg><replaceable>username</replaceable></arg>
+ </cmdsynopsis>
+ <para>The username you wish to login to the server as.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-pass</arg>
+ <arg><replaceable>password</replaceable></arg>
+ </cmdsynopsis>
+ <para>The password to login to the server with.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-db</arg>
+ <arg><replaceable>database</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ The name of the database to connect to.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-table</arg>
+ <arg><replaceable>tableName</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ The default table to use when using built-in commands
+ for storing and fetching.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-keyfield</arg>
+ <arg><replaceable>keyFieldname</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ The default field to use as the primary key when using
+ built-in commands for storing and fetching.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-autokey</arg>
+ <group>
+ <arg>1</arg>
+ <arg>0</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ If this option is set to 1, DIO will attempt to
+ determine an automatic key for
+ <option>keyField</option> when storing and fetching.
+ In most databases, this requires that the
+ <option>sequence</option> also be specified. In the
+ case of MySQL, where sequences do not exist, autokey
+ must be used in conjunction with a table which has a
+ field specified as AUTO.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-sequence</arg>
+ <arg><replaceable>sequenceName</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ If DIO is automatically generating keys, it will use
+ this sequence as a means to gain a unique number for
+ the stored key.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>DIO Object Commands</title>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>array</arg>
+ <arg><replaceable>request</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Execute <option>request</option> as a SQL query and
+ create an array from the first record found. The
+ array is set with the fields of the table and the
+ values of the record found.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>autokey</arg>
+ <group choice="opt">
+ <arg>value</arg>
+ <arg>boolean</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Return the current autokey value. If
+ <option>value</option> is specified, it sets a new
+ value for the autokey option.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>close</arg>
+ </cmdsynopsis>
+ <para> Close the current database connection. This command is
+ automatically called when the DIO object is destroyed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>count</arg>
+ </cmdsynopsis>
+ <para> Return a count of the number of rows in the
+ specified (or current) table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>db</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current database. If
+ <option>value</option> is specified, it sets a new
+ value for the database. In most cases, the DIO object
+ will automatically connect to the new database when
+ this option is changed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>delete</arg>
+ <arg><replaceable>key</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Delete a record from the database where the primary
+ key matches <option>key</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>destroy</arg>
+ </cmdsynopsis>
+ <para>
+ Destroy the DIO object.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>errorinfo</arg>
+ <arg choice="opt">value</arg>
+ </cmdsynopsis>
+ <para><option>errorinfo</option> contains the value of
+ the last error, if any, to occur while executing a
+ request. When a request fails for any reason, this
+ variable is filled with the error message from the SQL
+ interface package.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>exec</arg>
+ <arg><replaceable>request</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Execute <option>request</option> as an SQL query.
+ When the exec command is called, the query is
+ executed, and a DIO result object is returned. From
+ there, the result object can be used to obtain
+ information about the query status and records in a
+ generic way. See <link linkend="resultobj">Result
+ Object Commands</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>fetch</arg>
+ <arg><replaceable>key</replaceable></arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Fetch a record from the database where the primary key
+ matches <option>key</option> and store the result in
+ an array called <option>arrayName</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>forall</arg>
+ <arg><replaceable>request</replaceable></arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <arg><replaceable>body</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Execute an SQL select <option>request</option> and iteratively
+ fill the array named <option>arrayName</option>
+ with elements named with the matching field names, and
+ values containing the matching values, repeatedly executing
+ the specified code <option>body</option>
+ for each row returned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>host</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current host value. If
+ <option>value</option> is specified, it sets a new
+ value for the host.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>insert</arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Insert fields from <option>arrayName</option> into the specified table in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>interface</arg>
+ </cmdsynopsis>
+ <para>
+ Return the database interface type, such as
+ <literal>Postgresql</literal> or <literal>Mysql</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>keyfield</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current keyfield. If
+ <option>value</option> is specified, it sets a new
+ value for the keyfield. <option>Value</option> can contain
+ multiple key fields as a Tcl list, if the table has multiple
+ key fields.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>keys</arg>
+ <arg choice="opt"><replaceable>pattern</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Return a list of keys in the database. If
+ <option>pattern</option> is specified, only the keys
+ matching will be returned.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>lastkey</arg>
+ </cmdsynopsis>
+ <para>
+ Return the last key that was used from
+ <option>sequence</option>. If sequence has not been
+ specified, this command returns an empty string.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>list</arg>
+ <arg>request</arg>
+ </cmdsynopsis>
+ <para>
+ Execute <option>request</option> as a SQL query and
+ return a list of the first column of each record
+ found.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>makekey</arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <arg choice="opt"><replaceable>keyfield</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Given an array containing key-value pairs and an optional
+ list of key fields (we use the object's keyfield if
+ none is specified), if we're doing auto keys, create
+ and return a new key, otherwise if it's a single key,
+ just return its value from the array, else if there are
+ multiple keys, return all the keys' values from the
+ array as a list.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>nextkey</arg>
+ </cmdsynopsis>
+ <para>Increment <option>sequence</option> and return the
+ next key to be used. If sequence has not been
+ specified, this command returns an empty
+ string.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>open</arg>
+ </cmdsynopsis>
+ <para>Open the connection to the current database. This
+ command is automatically called from any command which
+ accesses the database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>pass</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current pass value. If
+ <option>value</option> is specified, it sets a new
+ value for the password.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>port</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>Return the current port value. If <option>value</option> is
+ specified, it sets a new value for the port.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>quote</arg>
+ <arg><replaceable>string</replaceable></arg>
+ </cmdsynopsis>
+ <para>Return the specified <option>string</option> quoted in
+ a way that makes it acceptable as a value in a SQL statement.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>search</arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Search the current table, or the specified table if
+ -table tableName is specified, for rows matching
+ one or more fields as key-value pairs, and return
+ a query result handle.
+ See <link linkend="resultobj">Result Object Commands</link>
+ </para>
+ <para>
+ For example,
+ <programlisting>set res [DIO search -table people -firstname Bob]</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>sequence</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current sequence value. If <option>value</option> is
+ specified, it sets a new value for the sequence.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>store</arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Store the contents of <option>arrayName</option> in the
+ database, where the keys are the field names and the
+ array's values are the corresponding values. Do an SQL insert
+ if the corresponding row doesn't exist, or an update
+ if it does.
+ </para>
+ <para>
+ The table name must have been previously set
+ or specified with <arg>-table</arg>, and the key field(s) must
+ have been previously set or specified with
+ <arg>-keyfield</arg>.
+ </para>
+ <para>
+ Please note that the store method has significantly higher
+ overhead than
+ the update or insert methods, so if you know you are
+ inserting a row rather than updating one, it is advisable
+ to use the insert method and, likewise, if you know you
+ are updating rather than inserting, to use the
+ update method.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>string</arg>
+ <arg><replaceable>request</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Execute <option>request</option> as a SQL query and
+ return a string containing the first record
+ found.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>table</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>Return the current table. If
+ <option>value</option> is specified, it sets a new
+ value for the table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>update</arg>
+ <arg><replaceable>arrayName</replaceable></arg>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ <para>
+ Updates the row matching the contents of
+ <option>arrayName</option> in the database. The matching
+ row must already exist. The table can have already been
+ set or can be specified with <arg>-table</arg>, and
+ the key field(s) must either have been set or
+ specified with <arg>-keyfield</arg>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>objectName</replaceable></arg>
+ <arg>user</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current user value. If
+ <option>value</option> is specified, it sets a new
+ value for the user.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="resultobj">
+ <title>Result Object Commands</title>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>autocache</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current autocache value. If
+ <option>value</option> is specified, it sets a new
+ value for autocache.
+ </para>
+ <para>
+ If autocache is true, the result object will
+ automatically cache rows as you use them. This means
+ that the first time you execute a forall command, each
+ row is being cached in the result object itself and
+ will no longer need to access the SQL result.
+ <emphasis>Default is true</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>cache</arg>
+ </cmdsynopsis>
+ <para>
+ Cache the results of the current SQL result in the
+ result object itself. This means that even if the
+ database connection is closed and all the results of
+ the DIO object are lost, this result object will still
+ maintain a cached copy of its records.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>errorcode</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current errorcode value. If <option>value</option>
+ is specified, it sets a new value for errorcode.
+ </para>
+ <para>
+ <option>errorcode</option> contains the current code from the
+ SQL database which specifies the result of the query
+ statement which created this object. This variable
+ can be used to determine the success or failure of a
+ query.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>errorinfo</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current errorinfo value. If <option>value</option>
+ is specified, it sets a new value for errorinfo.
+ </para>
+ <para>
+ If an error occurred during the SQL query, DIO
+ attempts to set the value of <option>errorinfo</option> to the
+ resulting error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>fields</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current fields value. If
+ <option>value</option> is specified, it sets a new
+ value for fields.
+ </para>
+ <para>
+ <option>fields</option> contains the list of fields
+ used in this query. The fields are in order of the
+ fields retrieved for each row.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>forall</arg>
+ <arg><replaceable>-type</replaceable></arg>
+ <arg><replaceable>varName</replaceable></arg>
+ <arg><replaceable>body</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Execute <option>body</option> over each record in the
+ result object.
+ </para>
+ <para>Types:</para>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-array</arg>
+ </cmdsynopsis>
+ <para>
+ Create
+ <option><replaceable>varName</replaceable></option>
+ as an array where the indexes are the names of
+ the fields in the table and the values are the
+ values of the current row.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-keyvalue</arg>
+ </cmdsynopsis>
+ <para>
+ Set
+ <option><replaceable>varName</replaceable></option>
+ to a list containing key-value pairs of fields
+ and values from the current row. (-field value
+ -field value)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-list</arg>
+ </cmdsynopsis>
+ <para>
+ Set
+ <option><replaceable>varName</replaceable></option>
+ to a list that contains the values of the
+ current row.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>next</arg>
+ <arg><replaceable>-type</replaceable></arg>
+ <arg choice="opt"><replaceable>varName</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Retrieve the next record in the result object.
+ </para>
+ <para>Types:</para>
+ <variablelist>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-array</arg>
+ </cmdsynopsis>
+ <para>
+ Create
+ <option><replaceable>varName</replaceable></option>
+ as an array where the indexes are the names of
+ the fields in the table and the values are the
+ values of the current row.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-keyvalue</arg>
+ </cmdsynopsis>
+ <para>
+ Set
+ <option><replaceable>varName</replaceable></option>
+ to a list containing key-value pairs of fields
+ and values from the current row. (-field value
+ -field value)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain">-list</arg>
+ </cmdsynopsis>
+ <para>
+ Set
+ <option><replaceable>varName</replaceable></option>
+ to a list that contains the values of the
+ current row.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>numrows</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current numrows value. If <option>value</option> is
+ specified, it sets a new value for numrows.
+ </para>
+ <para>
+ <option>numrows</option> is the number of rows in this result.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>resultid</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current resultid value. If <option>value</option> is
+ specified, it sets a new value for resultid.
+ </para>
+ <para>
+ <option>resultid</option> in most databases is the result
+ pointer which was given us by the database. This
+ variable is not generic and should not really be used,
+ but it's there if you want it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <listitem>
+ <cmdsynopsis>
+ <arg choice="plain"><replaceable>resultObj</replaceable></arg>
+ <arg>rowid</arg>
+ <arg choice="opt"><replaceable>value</replaceable></arg>
+ </cmdsynopsis>
+ <para>
+ Return the current rowid value. If <option>value</option> is
+ specified, it sets a new value for rowid.
+ </para>
+ <para>
+ <option>rowid</option> contains the number of the
+ current result record in the result object. This
+ variable should not really be accessed outside of the
+ result object, but it's there if you want it.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ </refentry>
+ </section>
+
+
+ <section id="diodisplay">
+ <title>DIODisplay - Database Interface Objects Display Class</title>
+ <refentry id="diodisplay_package">
+ <refnamediv>
+ <refname>DIODisplay</refname>
+ <refpurpose>Database Interface Objects Display Class</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>DIODisplay</command>
+ <group>
+ <arg><replaceable>objectName</replaceable></arg>
+ <arg>#auto</arg>
+ </group>
+ <group choice="opt">
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>-option</arg>
+ <arg><replaceable>option</replaceable></arg>
+ <arg>...</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>
+ DIODisplay is an HTML display class that uses a DIO object
+ to do the database work and a form object to do the
+ displaying.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg choice="plain">-DIO</arg>
+ <arg choice="plain"><replaceable>dioObject</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ The DIO object to be used in conjunction with this
+ display object. This is a required field.
+ </para>
+ </listitem>
+ </varlistentry>
[... 1769 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-cvs-help@tcl.apache.org