| <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Rivet</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="Apache Rivet"><div class="titlepage"><div><div><h2 class="title"><a name="id360123"></a>Apache Rivet</h2></div><div><div class="author"><h3 class="author"><span class="firstname">The Rivet Team</span></h3><div class="affiliation"><span class="orgname">The Apache Software Foundation<br></span><div class="address"><p><br> |
| <code class="email"><<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>></code><br> |
| </p></div></div></div></div><div><p class="copyright">Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#introduction">Introduction to Apache Rivet</a></span></dt><dt><span class="section"><a href="#installation">Apache Rivet Installation</a></span></dt><dt><span class="section"><a href="#directives">Rivet Apache Directives</a></span></dt><dt><span class="section"><a href="#commands">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#var">var</a></span><span class="refpurpose"> — get the value of a form variable.</span></dt><dt><span class="refentrytitle"><a href="#upload">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</span></dt><dt><span class="refentrytitle"><a href="#load_response">load_response</a></span><span class="refpurpose"> — load form variables into an array.</span></dt><dt><span class="refentrytitle"><a href="#load_headers">load_headers</a></span><span class="refpurpose"> — get client request's headers.</span></dt><dt><span class="refentrytitle"><a href="#load_cookies">load_cookies</a></span><span class="refpurpose"> — get any cookie variables sent by the client.</span></dt><dt><span class="refentrytitle"><a href="#load_env">load_env</a></span><span class="refpurpose"> — get the request's environment variables.</span></dt><dt><span class="refentrytitle"><a href="#env">env</a></span><span class="refpurpose"> — Loads a single |
| "environmental variable" into a Tcl variable.</span></dt><dt><span class="refentrytitle"><a href="#include">include</a></span><span class="refpurpose"> — includes a file into the output stream without modification.</span></dt><dt><span class="refentrytitle"><a href="#parse">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</span></dt><dt><span class="refentrytitle"><a href="#headers">headers</a></span><span class="refpurpose"> — set and parse HTTP headers.</span></dt><dt><span class="refentrytitle"><a href="#makeurl">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="#cookie">cookie</a></span><span class="refpurpose"> — get and set cookies.</span></dt><dt><span class="refentrytitle"><a href="#clock_to_rfc">clock_to_rfc850_gmt</a></span><span class="refpurpose"> — create a rfc850 time from [clock seconds].</span></dt><dt><span class="refentrytitle"><a href="#html">html</a></span><span class="refpurpose"> — construct html tagged text.</span></dt><dt><span class="refentrytitle"><a href="#incr0">incr0</a></span><span class="refpurpose"> — increment a variable or set it to 1 if nonexistant.</span></dt><dt><span class="refentrytitle"><a href="#parray">parray</a></span><span class="refpurpose"> — Tcl's <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> with html formatting.</span></dt><dt><span class="refentrytitle"><a href="#abort_page">abort_page</a></span><span class="refpurpose"> — Stops outputing data to web page, similar in |
| purpose to PHP's <span style="font-family:monospace"><span class="command"><strong>die</strong></span></span> command.</span></dt><dt><span class="refentrytitle"><a href="#no_body">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</span></dt><dt><span class="refentrytitle"><a href="#escape_string">escape_string</a></span><span class="refpurpose"> — convert a string into escaped characters.</span></dt><dt><span class="refentrytitle"><a href="#escape_sgml_chars">escape_sgml_chars</a></span><span class="refpurpose"> — escape special SGML characters in a string.</span></dt><dt><span class="refentrytitle"><a href="#escape_shell_command">escape_shell_command</a></span><span class="refpurpose"> — escape shell metacharacters in a string.</span></dt><dt><span class="refentrytitle"><a href="#unescape_string">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a string.</span></dt><dt><span class="refentrytitle"><a href="#apache_log_error">apache_log_error</a></span><span class="refpurpose"> — log messages to the Apache error log</span></dt><dt><span class="refentrytitle"><a href="#apache_table">apache_table</a></span><span class="refpurpose"> — access and manipulate Apache tables in the request structure.</span></dt></dl></dd><dt><span class="section"><a href="#examples">Examples and Usage</a></span></dt><dt><span class="section"><a href="#tcl_packages">Rivet Tcl Packages</a></span></dt><dt><span class="section"><a href="#dio">DIO - Database Interface Objects</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#dio_package">DIO</a></span><span class="refpurpose"> — Database Interface Objects</span></dt></dl></dd><dt><span class="section"><a href="#diodisplay">DIODisplay - Database Interface Objects Display Class</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#diodisplay_package">DIODisplay</a></span><span class="refpurpose"> — Database Interface Objects Display Class</span></dt></dl></dd><dt><span class="section"><a href="#session_package">Session Package</a></span></dt><dd><dl><dt><span class="section"><a href="#id381026">Introduction</a></span></dt><dt><span class="section"><a href="#requirements">Requirements</a></span></dt><dt><span class="section"><a href="#id381362">Preparing To Use It</a></span></dt><dt><span class="section"><a href="#id381407">Example Usage</a></span></dt><dt><span class="section"><a href="#id381463">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="#id381660">Session Configuration Options</a></span></dt><dt><span class="section"><a href="#id381888">Session Methods</a></span></dt><dt><span class="section"><a href="#id382114">Getting Additional Randomness From The Entropy File</a></span></dt></dl></dd><dt><span class="section"><a href="#form">Form: An HTML Form Fields Generation Utility</a></span></dt><dd><dl><dt><span class="section"><a href="#id382744">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="#form_package">form</a></span><span class="refpurpose"> — a Tcl command object for creating HTML forms</span></dt></dl></dd><dt><span class="section"><a href="#calendar_package">Calendar Package</a></span></dt><dd><dl><dt><span class="section"><a href="#id387514">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="#calendar">Calendar</a></span><span class="refpurpose"> — Utility class the builds and prints a calendar table</span></dt><dt><span class="refentrytitle"><a href="#xml_calendar">XmlCalendar</a></span><span class="refpurpose"> — Prints XML formatted calendar tables</span></dt><dt><span class="refentrytitle"><a href="#html_calendar">HtmlCalendar</a></span><span class="refpurpose"> — Concrete class derived from XmlCalendar</span></dt></dl></dd><dt><span class="section"><a href="#help">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="#id389501">Mailing Lists</a></span></dt><dt><span class="section"><a href="#id389528">Newsgroup</a></span></dt><dt><span class="section"><a href="#websites">Web Sites</a></span></dt><dt><span class="section"><a href="#id389901">Bug Tracking System</a></span></dt><dt><span class="section"><a href="#id389917">IRC</a></span></dt><dt><span class="section"><a href="#id389928">Editing Rivet Template Files</a></span></dt></dl></dd><dt><span class="section"><a href="#internals">Rivet Internals</a></span></dt><dd><dl><dt><span class="section"><a href="#id389735">Initialization</a></span></dt><dt><span class="section"><a href="#id389686">RivetChan</a></span></dt><dt><span class="section"><a href="#id390255">The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</a></span></dt><dt><span class="section"><a href="#id390300">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="#id390342">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="#upgrading">Upgrading from mod_dtcl or NeoWebScript</a></span></dt><dd><dl><dt><span class="section"><a href="#id390476">mod_dtcl</a></span></dt><dt><span class="section"><a href="#id390487">NeoWebScript</a></span></dt></dl></dd></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>1. <a href="#hello%20world">Hello World</a></dt><dt>2. <a href="#id369279">Generate a Table</a></dt><dt>3. <a href="#variable_access">Variable Access</a></dt><dt>4. <a href="#file_upload">File Upload</a></dt><dt>5. <a href="#file_download">File Download</a></dt><dt>6. <a href="#ajax_xml_messaging">XML Messages and Ajax</a></dt></dl></div><p style="width:90%"> |
| Document revision: $Revision: 959821 $, last modified 2010-07-20 21:49:04+02:00$ by $Author: mxmanghi $. |
| </p><div class="section" title="Introduction to Apache Rivet"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction to Apache Rivet</h2></div></div></div><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| 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! |
| </p></div><div class="section" title="Apache Rivet Installation"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="installation"></a>Apache Rivet Installation</h2></div></div></div><div class="procedure"><ol class="procedure" type="1"><li class="step" title="Check Dependencies"><p class="title"><b>Check Dependencies</b></p><p style="width:90%"> |
| To install Rivet, you will need Tcl 8.4 or greater. Rivet can be compiled to work |
| with either Apache 1.3.xx or Apache 2.2.xx server. |
| It is known to run on Linux, FreeBSD, OpenBSD, Solaris and HPUX. Windows NT is also possible |
| - please see the directions in the distribution. |
| </p></li><li class="step" title="Get Rivet"><p class="title"><b>Get Rivet</b></p><p style="width:90%"> |
| Download the sources at <a class="ulink" href="http://tcl.apache.org/rivet/download.html" target="_top">http://tcl.apache.org/rivet/download.html</a>. Currently |
| the only way to obtain Rivet. In the future, we hope to have a FreeBSD port, Debian package, RPM's, and windows |
| binaries. |
| </p></li><li class="step" title="Install Tcl"><p class="title"><b>Install Tcl</b></p><p style="width:90%"> |
| 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 build scripts where Tcl is via |
| the --with-tcl option to <span style="font-family:monospace"><span class="command"><strong>configure</strong></span></span> (see below). |
| </p></li><li class="step" title="Get and Install Apache Sources"><p class="title"><b>Get and Install Apache Sources</b></p><p style="width:90%"> |
| 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 |
| --with-apxs option to <span style="font-family:monospace"><span class="command"><strong>configure</strong></span></span> (see below). |
| </p><p style="width:90%"> |
| The source code for the Apache web server may be found by |
| following the links here: <a class="ulink" href="http://httpd.apache.org/" target="_top">http://httpd.apache.org/</a>. |
| </p></li><li class="step" title="Uncompress Sources"><p class="title"><b>Uncompress Sources</b></p><p style="width:90%"> |
| 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. |
| |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">gunzip rivet-X.X.X.tar.gz |
| tar -xvf rivet-X.X.X.tar.gz</pre><p style="width:90%"> |
| |
| </p></li><li class="step" title="Building Rivet"><p class="title"><b>Building Rivet</b></p><ol type="a" class="substeps"><li class="step" title="Step 6.a"><p style="width:90%"> |
| On Linux or Unix systems, Rivet uses the standard <span style="font-family:monospace"><span class="command"><strong>./configure ; make ; make install</strong></span></span> technique. |
| </p><p style="width:90%"> |
| There are several rivet specific options to configure that might be useful (or needed): |
| </p><div class="variablelist"><dl><dt><span class="term">--with-tcl</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This points to the directory where the |
| <code class="filename">tclConfig.sh</code> file is located. |
| </div></div></dd><dt><span class="term">--with-tclsh</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">This points to the location of the |
| <code class="filename">tclsh</code> executable.</div></div></dd><dt><span class="term">--with-apxs</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The location of the <code class="filename">apxs</code> |
| program that provides information about the |
| configuration and compilation options of Apache modules.</div></div></dd><dt><span class="term">--with-apache-version=[1|2]</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option tells the build scripts whether you want to build Rivet for the |
| Apache 1.x or Apache 2.x server. |
| </div></div></dd><dt><span class="term">--with-apache-include[=DIR]</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Locates the Apache include files on your computer, if they're not in standard directory. |
| </div></div></dd><dt><span class="term">--enable-version-display=[yes|no]</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option enables Rivet to display its version in the logfiles when Apache is started. |
| The default is to keep Rivet version hidden. |
| </div></div></dd><dt><span class="term">--with-rivet-target-dir=DIR</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option tells the install script where Rivet's Tcl packages have to be copied. |
| </div></div></dd></dl></div><p style="width:90%"> |
| </p><p style="width:90%"> |
| Example: configuring the build system to compile Rivet for an apache 2.x server, using tcl8.5 and |
| specifying a custom name for the apxs program. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| ./configure --with-tcl=/usr/lib/tcl8.5/ --with-tclsh=/usr/bin/tclsh8.5 \ |
| --with-apxs=/usr/bin/apxs2 --with-apache=/usr --with-apache-version=2 |
| </pre></li><li class="step" title="Run make"><p class="title"><b>Run make</b></p><p style="width:90%"> |
| At this point, you are ready to run make, which should |
| run to completion without any errors (a warning or two |
| is ok, generally). |
| </p></li><li class="step" title="Install"><p class="title"><b>Install</b></p><p style="width:90%"> |
| Now, you are ready to run the <span style="font-family:monospace"><span class="command"><strong>make |
| install</strong></span></span> to install the resulting files. |
| This should copy the shared object (like |
| <code class="filename">mod_rivet.so</code>, if one was |
| successfully created, into Apache's |
| <code class="filename">libexec</code> directory, as well as |
| install some support scripts and various code. |
| </p></li></ol></li><li class="step" title="Apache Configuration Files"><p class="title"><b>Apache Configuration Files</b></p><p style="width:90%"> |
| Rivet is relatively easy to configure - we start off by |
| adding the module itself: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">LoadModule rivet_module <em class="replaceable"><code>/usr/lib/apache2/modules/mod_rivet.so</code></em> |
| </pre><p style="width:90%"> |
| 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: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">AddType application/x-httpd-rivet .rvt |
| AddType application/x-rivet-tcl .tcl</pre><p style="width:90%"> |
| These tell Apache to process files with the |
| <code class="filename">.rvt</code> and <code class="filename">.tcl</code> |
| extensions as Rivet files. |
| </p><p style="width:90%"> |
| The characters encoding can be changed using the <span style="font-family:monospace"><span class="command"><strong>header type</strong></span></span> command, |
| but you can also change the default charset for the whole site: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">AddType 'application/x-httpd-rivet;charset=utf-8' rvt</pre><p style="width:90%"> |
| All the pages generated by Rivet on this site will be sent with a |
| <span style="font-family:monospace"><span class="command"><strong>Content-Type:'text/html;charset=utf-8'</strong></span></span> header. |
| </p><p style="width:90%">You may also wish to use Rivet files as index files for |
| directories. In that case, you would do the following:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</pre><p style="width:90%"> |
| For other directives that Rivet provides for Apache |
| configuration, please see <a class="xref" href="#directives" title="Rivet Apache Directives">the section called “Rivet Apache Directives”</a>. |
| </p></li></ol></div></div><div class="section" title="Rivet Apache Directives"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="directives"></a>Rivet Apache Directives</h2></div></div></div><p style="width:90%"> |
| These directives are used within the Apache httpd server |
| configuration files to modify Apache Rivet's behavior. Their |
| precedence is as follows: <span style="font-family:monospace"><span class="command"><strong>RivetDirConf</strong></span></span>, |
| <span style="font-family:monospace"><span class="command"><strong>RivetUserConf</strong></span></span>, |
| <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, meaning that DirConf will |
| override UserConf, which will in turn override ServerConf. |
| </p><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetServerConf</span> (<span style="font-family:monospace; font-weight: bold;">CacheSize</span> | <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> | <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> | <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> | <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> | <span style="font-family:monospace; font-weight: bold;">UploadFilesToVar</span> | <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> | <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"><span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span> 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. |
| </div><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">CacheSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Sets the size of the internal page cache, where |
| <em class="replaceable"><code>size</code></em> is |
| the number of byte-compiled pages to be cached for |
| future use. Default is |
| <span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> / 5, or 50, |
| if <span style="font-family:monospace"><span class="command"><strong>MaxRequestsPerChild</strong></span></span> is 0. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option is completely global, even when using |
| separate, per-virtual host interpreters. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">GlobalInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tcl script that is run when each interpreter is |
| initialized. <em class="replaceable"><code>script</code></em> |
| is an actual Tcl script, so to run a file, you would |
| do: |
| |
| <pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf GlobalInitScript "source /var/www/foobar.tcl"</pre> |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option is ignored in virtual hosts. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildInitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this script is run in addition to |
| any global childinitscript. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ChildExitScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Script to be evaluated when each Apache child |
| process exits. This is the logical place to clean |
| up resources created in |
| ChildInitScript, if necessary. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this script is run in addition to |
| any global childexitscript. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">BeforeScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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 GlobalInitScript |
| ChildInitScript when you are first |
| developing a web site. |
| <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| This code is evaluated at the global level, not |
| inside the request namespace where pages are |
| evaluated. |
| </td></tr></table></div> |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this option takes precedence over |
| the global setting. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">AfterScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Script to be called after each server parsed (.rvt) page. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this option takes precedence over |
| the global setting. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>script</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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 ErrorScript 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. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this option takes precedence over |
| the global setting. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>directory</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Directory to place uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this option takes precedence over |
| the global setting. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadMaxSize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>size</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Maximum size for uploaded files.</div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In virtual hosts, this option takes precedence over |
| the global setting. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">UploadFilesToVar</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">SeparateVirtualInterps</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex">This option is, by nature, only available at the |
| global level.</div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">HonorHeaderOnlyRequests</span> (<span style="font-family:monospace; font-weight: bold;">yes</span> | <span style="font-family:monospace; font-weight: bold;">no</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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 this options on. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex">This option is, by nature, only available at the global level</div></div></dd></dl></div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetDirConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| These options are the same as for |
| <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are |
| only valid for the directory where they are specified, and |
| its subdirectories. It may be specified in <span style="font-family:monospace"><span class="command"><strong>Directory</strong></span></span> |
| sections. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">RivetUserConf</span> (<span style="font-family:monospace; font-weight: bold;">BeforeScript</span> | <span style="font-family:monospace; font-weight: bold;">AfterScript</span> | <span style="font-family:monospace; font-weight: bold;">ErrorScript</span> | <span style="font-family:monospace; font-weight: bold;">UploadDirectory</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| These options are the same as for |
| <span style="font-family:monospace"><span class="command"><strong>RivetServerConf</strong></span></span>, except that they are |
| only valid for the directory where they are specified, and |
| its subdirectories. |
| </div></div></dd></dl></div></div><div class="section" title="Rivet Tcl Commands and Variables"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="commands"></a>Rivet Tcl Commands and Variables</h2></div></div></div><div class="refentry" title="var"><a name="var"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>var, var_qs, var_post — get the value of a form variable.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">number</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var_qs</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">number</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var_post</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">list</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">number</span> | <span style="font-family:monospace; font-weight: bold;">all</span>)</div></div></div><div class="refsect1" title="Description"><a name="id363073"></a><h2>Description</h2><p style="width:90%"> |
| The <span style="font-family:monospace"><span class="command"><strong>var</strong></span></span> 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 <span style="font-family:monospace"><span class="command"><strong>var</strong></span></span>: |
| <span style="font-family:monospace"><span class="command"><strong>var_qs</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>var_post</strong></span></span>. |
| These two restrict the retrieval of information to |
| parameters arriving via the querystring |
| (?foo=bar&bee=bop) or POSTing, respectively. |
| </p><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">get</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">default</span>?</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the value of variable |
| <em class="replaceable"><code>varname</code></em> |
| as a string (even if there are multiple values). If |
| the variable doesn't exist as a GET or POST |
| variable, the |
| <em class="replaceable"><code>?<span class="optional">default</span>?</code></em> |
| value is returned, otherwise "" - an empty string - |
| is returned. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">list</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the value of variable |
| <em class="replaceable"><code>varname</code></em> as a |
| list, if there are multiple values. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">exists</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns 1 if |
| <em class="replaceable"><code>varname</code></em> |
| exists, 0 if it doesn't. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">number</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the number of variables. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">var</span> <span style="font-family:monospace; font-weight: bold;">all</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return a list of variable names and values. |
| </div></div></dd></dl></div><p style="width:90%"> |
| See <a class="xref" href="#variable_access" title="Example 3. Variable Access">Example 3, “Variable Access”</a>. |
| </p></div></div><div class="refentry" title="upload"><div class="refentry.separator"><hr></div><a name="upload"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>upload — handle a file uploaded by a client.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> (<span style="font-family:monospace; font-weight: bold;">channel</span> | <span style="font-family:monospace; font-weight: bold;">save</span> | <span style="font-family:monospace; font-weight: bold;">data</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">size</span> | <span style="font-family:monospace; font-weight: bold;">type</span> | <span style="font-family:monospace; font-weight: bold;">filename</span>)</div></div></div><div class="refsect1" title="Description"><a name="id363411"></a><h2>Description</h2><p style="width:90%">The upload command is for file upload manipulation. |
| See the relevant Apache Directives to further configure the |
| behavior of this Rivet feature. |
| </p><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">channel</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| When given the name of a file upload |
| <em class="replaceable"><code>uploadname</code></em>, |
| returns a Tcl channel that can be used to access the |
| uploaded file. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">save</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Saves the |
| <em class="replaceable"><code>uploadname</code></em> in |
| the file |
| <em class="replaceable"><code>filename</code></em>. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">data</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">exists</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns true if an upload named ?<span style="font-family:monospace; font-weight: bold;">uploadname</span>? |
| 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. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">size</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the size of the file uploaded. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">type</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If the <code class="varname">Content-type</code> is set, it is |
| returned, otherwise, an empty string. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">filename</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the filename on the remote host that uploaded the file. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">tempname</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uploadname</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the name of the temporary file on the local host that the file was uploaded into. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">upload</span> <span style="font-family:monospace; font-weight: bold;">names</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the variable names, as a list, of all the files |
| uploaded. |
| </div></div></dd></dl></div><p style="width:90%"> |
| See <a class="xref" href="#upload" title="upload">upload</a>. |
| </p></div></div><div class="refentry" title="load_response"><div class="refentry.separator"><hr></div><a name="load_response"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_response — load form variables into an array.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_response</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id363839"></a><h2>Description</h2><p style="width:90%"> |
| Load any form variables passed to this page into an |
| array. If <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> is called without |
| arguments the array response 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. <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> |
| 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 <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> 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. |
| </p></div></div><div class="refentry" title="load_headers"><div class="refentry.separator"><hr></div><a name="load_headers"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_headers — get client request's headers.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_headers</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id363911"></a><h2>Description</h2><p style="width:90%"> |
| Load the headers that come from a client request into the |
| provided array name, or use headers if no |
| name is provided. |
| </p></div></div><div class="refentry" title="load_cookies"><div class="refentry.separator"><hr></div><a name="load_cookies"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_cookies — get any cookie variables sent by the client.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_cookies</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id363962"></a><h2>Description</h2></div><p style="width:90%"> |
| Load the array of cookie variables into the specified |
| array name. Uses array cookies by |
| default. |
| </p></div><div class="refentry" title="load_env"><div class="refentry.separator"><hr></div><a name="load_env"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>load_env — get the request's environment variables.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">load_env</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>array_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364012"></a><h2>Description</h2><p style="width:90%"> |
| Load the array of environment variables into the specified |
| array name. Uses array ::request::env by |
| default. |
| </p><p style="width:90%"> |
| As Rivet pages are run in the ::request |
| namespace, it isn't necessary to qualify the array name |
| for most uses - it's ok to access it as |
| env. |
| </p></div></div><div class="refentry" title="env"><div class="refentry.separator"><hr></div><a name="env"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>env — Loads a single |
| "environmental variable" into a Tcl variable.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">env</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364074"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p></div></div><div class="refentry" title="include"><div class="refentry.separator"><hr></div><a name="include"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>include — includes a file into the output stream without modification.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">include</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename_name</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364122"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p></div></div><div class="refentry" title="parse"><div class="refentry.separator"><hr></div><a name="parse"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>parse — parses a Rivet template file.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">parse</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364172"></a><h2>Description</h2><p style="width:90%"> |
| Like the Tcl <span style="font-family:monospace"><span class="command"><strong>source</strong></span></span> command, but also |
| parses for Rivet <? and ?> processing tags. Using |
| this command, you can use one .rvt file from another. |
| </p></div></div><div class="refentry" title="headers"><div class="refentry.separator"><hr></div><a name="headers"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>headers — set and parse HTTP headers.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> (<span style="font-family:monospace; font-weight: bold;">set</span> | <span style="font-family:monospace; font-weight: bold;">redirect</span> | <span style="font-family:monospace; font-weight: bold;">add</span> | <span style="font-family:monospace; font-weight: bold;">type</span> | <span style="font-family:monospace; font-weight: bold;">numeric</span>)</div></div></div><div class="refsect1" title="Description"><a name="id364261"></a><h2>Description</h2><p style="width:90%"> |
| The <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command is for setting and |
| parsing HTTP headers. |
| </p><div class="variablelist"><dl><dt><span class="term"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">set</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>headername</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set arbitrary header names and values. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">redirect</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>uri</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Redirect from the current page to a new |
| URI. <span class="emphasis"><em>Must</em></span> be done in the first block |
| of TCL code. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">add</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>headername</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Add text to header |
| <code class="varname">headername</code>.</div></div></dd><dt><span class="term"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">type</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>content-type</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This command sets the <code class="constant">Content-type</code> |
| 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. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">headers</span> <span style="font-family:monospace; font-weight: bold;">numeric</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>response code</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Set a numeric response code, such as 200, 404 or 500. |
| </div></div></dd></dl></div></div></div><div class="refentry" title="makeurl"><div class="refentry.separator"><hr></div><a name="makeurl"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>makeurl — construct url's based on hostname, port.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">makeurl</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>filename</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364535"></a><h2>Description</h2><p style="width:90%"> |
| Create a self referencing URL from a filename. For example: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">makeurl /tclp.gif</pre><p style="width:90%"> |
| returns |
| <code class="computeroutput">http://[hostname]:[port]/tclp.gif</code>. |
| where hostname and port are the hostname and port of the |
| server in question. |
| </p></div></div><div class="refentry" title="cookie"><div class="refentry.separator"><hr></div><a name="cookie"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>cookie — get and set cookies.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">cookie</span> ?<span style="font-family:monospace; font-weight: bold;">set</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>cookieName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">cookiValue</span>?</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-days <em class="replaceable"><code>expireInDays</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-hours <em class="replaceable"><code>expireInHours</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-minutes <em class="replaceable"><code>expireInMinutes</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-expires <em class="replaceable"><code>Wdy, DD-Mon-YYYY HH:MM:SS GMT</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-path <em class="replaceable"><code>uriPathCookieAppliesTo</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-secure <em class="replaceable"><code>1/0</code></em></span>?</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">cookie</span> ?<span style="font-family:monospace; font-weight: bold;">get</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>cookieName</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364692"></a><h2>Description</h2><p style="width:90%"> |
| <span style="font-family:monospace"><span class="command"><strong>cookie</strong></span></span> 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. |
| </p></div></div><div class="refentry" title="clock_to_rfc850_gmt"><div class="refentry.separator"><hr></div><a name="clock_to_rfc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>clock_to_rfc850_gmt — create a rfc850 time from [clock seconds].</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">clock_to_rfc850_gmt</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>seconds</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364745"></a><h2>Description</h2><p style="width:90%"> |
| Convert an integer-seconds-since-1970 click value to |
| RFC850 format, with the additional requirement that it be |
| GMT only. |
| </p></div></div><div class="refentry" title="html"><div class="refentry.separator"><hr></div><a name="html"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>html — construct html tagged text.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">html</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>string</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arg</code></em></span>...?</div></div></div><div class="refsect1" title="Description"><a name="id364800"></a><h2>Description</h2><p style="width:90%"> |
| Print text with the added ability to pass HTML tags |
| following the string. Example: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">html "Test" b i</pre><p style="width:90%"> |
| produces: <code class="computeroutput"><b><i>Test</i></b></code> |
| </p></div></div><div class="refentry" title="incr0"><div class="refentry.separator"><hr></div><a name="incr0"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>incr0 — increment a variable or set it to 1 if nonexistant.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">incr0</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varname</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>num</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364866"></a><h2>Description</h2><p style="width:90%"> |
| Increment a variable |
| <em class="replaceable"><code>varname</code></em> by |
| <em class="replaceable"><code>num</code></em>. If the |
| variable doesn't exist, create it instead of returning an |
| error. |
| </p></div></div><div class="refentry" title="parray"><div class="refentry.separator"><hr></div><a name="parray"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>parray — Tcl's <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> with html formatting.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">parray</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>?<span class="optional">pattern</span>?</code></em></span>?</div></div></div><div class="refsect1" title="Description"><a name="id364936"></a><h2>Description</h2><p style="width:90%"> |
| An html version of the standard Tcl |
| <span style="font-family:monospace"><span class="command"><strong>parray</strong></span></span> command. Displays the entire |
| contents of an array in a sorted, nicely-formatted way. |
| Mostly used for debugging purposes. |
| </p></div></div><div class="refentry" title="abort_page"><div class="refentry.separator"><hr></div><a name="abort_page"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>abort_page — Stops outputing data to web page, similar in |
| purpose to PHP's <span style="font-family:monospace"><span class="command"><strong>die</strong></span></span> command.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">abort_page</span> </div></div></div><div class="refsect1" title="Description"><a name="id364987"></a><h2>Description</h2><p style="width:90%">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 |
| <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> command, but that cannot be used in |
| Rivet without actually exiting the apache child |
| process!</p></div></div><div class="refentry" title="no_body"><div class="refentry.separator"><hr></div><a name="no_body"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>no_body — Prevents Rivet from sending any content.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">no_body</span> </div></div></div><div class="refsect1" title="Description"><a name="id365032"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p></div></div><div class="refentry" title="escape_string"><div class="refentry.separator"><hr></div><a name="escape_string"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_string — convert a string into escaped characters.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_string</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id365079"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| This is useful for quoting strings that are going to be |
| part of a URL. |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| You must require the Rivet package in order to gain access to this command |
| </td></tr></table></div></div></div><div class="refentry" title="escape_sgml_chars"><div class="refentry.separator"><hr></div><a name="escape_sgml_chars"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_sgml_chars — escape special SGML characters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_sgml_chars</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id365134"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| You must require the Rivet package in order to gain access to this command |
| </td></tr></table></div></div></div><div class="refentry" title="escape_shell_command"><div class="refentry.separator"><hr></div><a name="escape_shell_command"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>escape_shell_command — escape shell metacharacters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">escape_shell_command</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id365186"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| For each metacharacter found, it is quoted in the result by |
| prepending it with a backslash, returning the result. |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| You must require the Rivet package in order to gain access to this command |
| </td></tr></table></div></div></div><div class="refentry" title="unescape_string"><div class="refentry.separator"><hr></div><a name="unescape_string"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>unescape_string — unescape escaped characters in a string.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">unescape_string</span> ?<span style="font-family:monospace; font-weight: bold;">string</span>?</div></div></div><div class="refsect1" title="Description"><a name="id365242"></a><h2>Description</h2><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| This is useful for unquoting strings that have been quoted to |
| be part of a URL. |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| You must require the Rivet package in order to gain access to this command |
| </td></tr></table></div></div></div><div class="refentry" title="apache_log_error"><div class="refentry.separator"><hr></div><a name="apache_log_error"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>apache_log_error — log messages to the Apache error log</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_log_error</span> ?<span style="font-family:monospace; font-weight: bold;">priority</span>? ?<span style="font-family:monospace; font-weight: bold;">message</span>?</div></div></div><div class="refsect1" title="Description"><a name="id365305"></a><h2>Description</h2><p style="width:90%">The apache_log_error command logs a message to the |
| Apache error log, whose name and location have been |
| set by the ErrorLog directive. |
| </p><p style="width:90%"> |
| Priority must be one of |
| debug, |
| info, |
| notice, |
| warning, |
| err, |
| crit, |
| alert, or |
| emerg. |
| </p></div></div><div class="refentry" title="apache_table"><div class="refentry.separator"><hr></div><a name="apache_table"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>apache_table — access and manipulate Apache tables in the request structure.</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> (<span style="font-family:monospace; font-weight: bold;">get</span> | <span style="font-family:monospace; font-weight: bold;">set</span> | <span style="font-family:monospace; font-weight: bold;">exists</span> | <span style="font-family:monospace; font-weight: bold;">unset</span> | <span style="font-family:monospace; font-weight: bold;">names</span> | <span style="font-family:monospace; font-weight: bold;">array_get</span> | <span style="font-family:monospace; font-weight: bold;">clear</span>)</div></div></div><div class="refsect1" title="Description"><a name="id365435"></a><h2>Description</h2><p style="width:90%">The apache_table command is for accessing and manipulating |
| Apache tables in the request structure. |
| </p><p style="width:90%"> |
| The table name must be one of |
| notes, |
| headers_in, |
| headers_out, |
| err_headers_out, or |
| subprocess_env. |
| </p><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">get</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| When given the name of an Apache table |
| <em class="replaceable"><code>tablename</code></em> |
| and the name of a key |
| <em class="replaceable"><code>tablename</code></em>, |
| returns the value of the key in the table, or an empty |
| string. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">set</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">set</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>list</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Stores the |
| <em class="replaceable"><code>value</code></em> in |
| the table |
| <em class="replaceable"><code>tablename</code></em> |
| under the key |
| <em class="replaceable"><code>key</code></em>. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| For the list form, |
| <em class="replaceable"><code>list</code></em> contains |
| a list of zero or more pairs of key-value pairs to be |
| set into the table |
| <em class="replaceable"><code>tablename</code></em>. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">exists</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns 1 if the specified key, |
| <em class="replaceable"><code>key</code></em>, |
| exists in table |
| <em class="replaceable"><code>tablename</code></em>, |
| else 0. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">unset</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Removes the key-value pair referenced by |
| <em class="replaceable"><code>key</code></em> |
| from the table |
| <em class="replaceable"><code>tablename</code></em>. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">names</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns a list of all of the keys present in the table |
| <em class="replaceable"><code>tablename</code></em>. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">array_get</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns a list of key-value pairs from the table |
| <em class="replaceable"><code>tablename</code></em>. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">apache_table</span> <span style="font-family:monospace; font-weight: bold;">clear</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tablename</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Clears the contents of the specified table. |
| </div></div></dd></dl></div></div></div></div><div class="section" title="Examples and Usage"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="examples"></a>Examples and Usage</h2></div></div></div><p style="width:90%"> |
| 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 |
| <a class="link" href="#websites" title="Web Sites">web sites</a> section and have a look. |
| </p><div class="example"><a name="hello%20world"></a><p class="title"><b>Example 1. Hello World</b></p><div class="example-contents"><p style="width:90%"> |
| As with any tool, it's always nice to see something work, so |
| let's create a small "Hello World" page.</p><p style="width:90%"> |
| Assuming you have Apache configured correctly, create a file |
| called <code class="filename">hello.rvt</code> where Apache can find |
| it, with the following content: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><? |
| puts "Hello World" |
| ?> |
| </pre><p style="width:90%"> |
| If you then access it with your browser, you should see a |
| blank page with the text "Hello World" (without the quotes) on |
| it. |
| </p></div></div><br class="example-break"><div class="example"><a name="id369279"></a><p class="title"><b>Example 2. Generate a Table</b></p><div class="example-contents"><p style="width:90%"> |
| In another simple example, we dynamically generate a table: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><? puts "<table>\n" |
| for {set i 1} { $i <= 8 } {incr i} { |
| puts "<tr>\n" |
| for {set j 1} {$j <= 8} {incr j} { |
| set num [ expr $i * $j * 4 - 1] |
| puts [ format "<td bgcolor=\"%02x%02x%02x\" > $num $num $num </td>\n" \ |
| $num $num $num ] |
| } |
| puts "</tr>\n" |
| } |
| puts "</table>\n" ?> |
| </pre><p style="width:90%"> |
| 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! |
| </p><p style="width:90%"> |
| The result should look something like this: |
| </p><div><img src="table.png"></div></div></div><br class="example-break"><div class="example"><a name="variable_access"></a><p class="title"><b>Example 3. Variable Access</b></p><div class="example-contents"><p style="width:90%"> |
| Here, we demonstrate how to access variables set by GET or |
| POST operations. |
| </p><p style="width:90%"> |
| Given an HTML form like the following: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> <form action="vars.rvt"> |
| <table> |
| <tbody> |
| <tr> |
| <td><b>Title:</b></td> |
| <td><input name="title"></td> |
| </tr> |
| <tr> |
| <td><b>Salary:</b></td> |
| <td><input name="salary"></td> |
| </tr> |
| <tr> |
| <td><b>Boss:</b></td> |
| <td><input name="boss"></td></tr> |
| <tr> |
| <td><b>Skills:</b></td> |
| <td> |
| <select name="skills" multiple="multiple"> |
| <option>c</option> |
| <option>java</option> |
| <option>Tcl</option> |
| <option>Perl</option> |
| </select> |
| </td> |
| </tr> |
| <tr> |
| <td><input type="submit"></td> |
| </tr> |
| </tbody> |
| </table> |
| </form> |
| </pre><p style="width:90%"> |
| We can use this Rivet script to get the variable values: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><? |
| set errlist {} |
| if { [var exists title] } { |
| set title [var get title] |
| } else { |
| set errlist "You need to enter a title" |
| } |
| |
| if { [var exists salary] } { |
| set salary [var get salary] |
| if { ! [string is digit $salary] } { |
| lappend errlist "Salary must be a number" |
| } |
| } else { |
| lappend errlist "You need to enter a salary" |
| } |
| |
| if { [var exists boss] } { |
| set boss [var get boss] |
| } else { |
| set boss "Mr. Burns" |
| } |
| |
| if { [var exists skills] } { |
| set skills [var list skills] |
| } else { |
| lappend errlist "You need to enter some skills" |
| } |
| |
| if { [llength $errlist] != 0 } { |
| foreach err $errlist { |
| puts "<b> $err </b>" |
| } |
| } else { |
| puts "Thanks for the information!" |
| ?> |
| <table> |
| <tbody> |
| <tr> |
| <td><b>Title:</b></td> |
| <td><? puts $title ?></td> |
| </tr> |
| <tr> |
| <td><b>Boss:</b></td> |
| <td><? puts $boss ?></td> |
| </tr> |
| <tr> |
| <td><b>Salary:</b></td> |
| <td><? puts $salary ?></td> |
| </tr> |
| <tr> |
| <td><b>Skills:</b></td> |
| <td><? puts $skills ?></td> |
| </tr> |
| </tbody> |
| </table> |
| <? |
| } |
| ?> |
| </pre><p style="width:90%"> |
| The first statement checks to make sure that the |
| <code class="varname">boss</code> 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. |
| </p><p style="width:90%"> |
| In the second block of code, the variable |
| <code class="varname">salary</code> is fetched, with one more error |
| check - because it's a number, it needs to be composed of |
| digits. |
| </p><p style="width:90%"> |
| The <code class="varname">boss</code> variable isn't required to have |
| been sent - we set it to "Mr. Burns" if it isn't among the |
| information we received. |
| </p><p style="width:90%"> |
| The last bit of variable handing code is a bit trickier. |
| Because <code class="varname">skills</code> 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. |
| </p><p style="width:90%"> |
| The script then checks to make sure that |
| <code class="varname">errlist</code> is empty and outputting a thankyou |
| message. If <code class="varname">errlist</code> is not empty, the list |
| of errors it contains is printed. |
| </p></div></div><br class="example-break"><div class="example"><a name="file_upload"></a><p class="title"><b>Example 4. File Upload</b></p><div class="example-contents"><p style="width:90%"> |
| The <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> 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, |
| <code class="filename">upload.html</code> 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. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><form action="foo.rvt" enctype="multipart/form-data" method="post"> |
| <input type="file" name="MyUpload"></input> |
| <input type="submit" value="Send File"></input> |
| </form> |
| </pre><p style="width:90%"> |
| In the script invoked by the form |
| (<code class="filename">upload.rvt</code>) <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> |
| ?<span style="font-family:monospace; font-weight: bold;">argument ...</span>? commands can be used to manipulate the |
| various files uploaded. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><? |
| upload save MyUpload /tmp/uploadfiles/file1 |
| puts "Saved file [upload filename MyUpload] \ |
| ([upload size MyUpload] bytes) to server" |
| ?></pre><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| It is also important to understand that some |
| <span style="font-family:monospace"><span class="command"><strong>upload</strong></span></span> commands are effective only when |
| used in a mutually exclusive way. Apache stores the data in |
| temporary files which are read by the <span style="font-family:monospace"><span class="command"><strong>upload save |
| ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? ?<span style="font-family:monospace; font-weight: bold;">filename</span>?</strong></span></span> or by the |
| <span style="font-family:monospace"><span class="command"><strong>upload data ?<span style="font-family:monospace; font-weight: bold;">upload name</span>?</strong></span></span> |
| command. Subsequent calls to these 2 commands using the same |
| ?<span style="font-family:monospace; font-weight: bold;">upload name</span>? argument will return no data on the |
| second call. Likewise <span style="font-family:monospace"><span class="command"><strong>upload channel ?<span style="font-family:monospace; font-weight: bold;">upload |
| name</span>?</strong></span></span> 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 <span style="font-family:monospace"><span class="command"><strong>upload |
| data ?<span style="font-family:monospace; font-weight: bold;">upload name</span>?</strong></span></span> command. |
| </p></div></div><br class="example-break"><div class="example"><a name="file_download"></a><p class="title"><b>Example 5. File Download</b></p><div class="example-contents"><p style="width:90%"> |
| 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). |
| </p><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| 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. |
| </p><p style="width:90%"> |
| Putting Tcl and Rivet in charge of the whole download |
| mechanism helps in building cleaner and safer approaches to |
| the download problem. |
| </p><p style="width:90%"> |
| 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 <span style="font-family:monospace"><span class="command"><strong>pdf_repository</strong></span></span> variable. |
| </p><p style="width:90%"> |
| This code is reported as an example of how to control |
| the protocol using the <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"># Code example for the transmission of a pdf file. |
| |
| if {[var exists pdfname]} { |
| set pdfname [var get pdfname] |
| |
| # let's build the full path to the pdf file. The 'pdf_repository' |
| # directory must be readable by the apache children |
| |
| set pdf_full_path [file join $pdf_repository ${pdfname}.pdf] |
| if {[file exists $pdf_full_path]} { |
| |
| # Before the file is sent we inform the client about the file type and |
| # file name. The client can be proposed a filename different from the |
| # original one. In this case, this is the point where a new file name |
| # must be generated. |
| |
| headers type "application/pdf" |
| headers add Content-Disposition "attachment; filename=${pdfname}.pdf" |
| headers add Content-Description "PDF Document" |
| |
| # The pdf is read and stored in a Tcl variable. The file handle is |
| # configured for a binary read: we are just shipping raw data to a |
| # client. The following 4 lines of code can be replaced by any code |
| # that is able to retrieve the data to be sent from any data source |
| # (e.g. database, external program, other Tcl code) |
| |
| set paper [open $pdf_full_path r] |
| fconfigure $paper -translation binary |
| set pdf [read $paper] |
| close $paper |
| |
| # Now we got the data: let's tell the client how many bytes we are |
| # about to send (useful for the download progress bar of a dialog box) |
| |
| headers add Content-Length [string length $pdf] |
| |
| # Let's send the actual file content |
| |
| puts $pdf |
| } else { |
| source pdf_not_found_error.rvt |
| } |
| } else { |
| source parameter_not_defined_error.rvt |
| } |
| </pre><p style="width:90%"> |
| Before the pdf is sent the procedure sets the |
| <code class="constant">Content-Type</code>, |
| <code class="constant">Content-Disposition</code>, |
| <code class="constant">Content-Description</code> and |
| <code class="constant">Content-Length</code> headers to inform |
| the client about the file type, name and size. Notice that in |
| order to set the <code class="constant">Content-Type</code> header Rivet |
| uses a specialiezed form of the <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> |
| 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) |
| </p><p style="width:90%"> |
| More information about the meaning of the mime headers in the |
| http context can be found at |
| <a class="ulink" href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" target="_top">http://www.w3.org/Protocols/rfc2616/rfc2616.html</a> |
| </p></div></div><br class="example-break"><div class="example"><a name="ajax_xml_messaging"></a><p class="title"><b>Example 6. XML Messages and Ajax</b></p><div class="example-contents"><p style="width:90%"> |
| The <span style="font-family:monospace"><span class="command"><strong>headers</strong></span></span> command is crucial for generating |
| XML messages that have to be understood by JavaScript code used |
| in Ajax applications. |
| </p><p style="width:90%"> |
| Ajax is a web programming technique that heavily relies on the abilty of a web browser to run in backround |
| JavaScript functions. JavaScript functions can be run as callbacks of events generated by a user interaction |
| but they can also react to other I/O events, for example network events. |
| Modern browsers endow JavaScript with the ability to build http GET/POST requests to be sent to a remote |
| webserver. Generally these requests refer to scripts (e.g. Tcl scripts run by Rivet) which inherit as |
| variables the arguments encoded in the request. |
| The output produced by these scripts is sent back to the browser where callbacks functions extract |
| information and hand it down to functions that directly manipulate a page's DOM. |
| Therefore through Ajax becomes possible to build web applications that are more responsive and flexible: |
| instead of going through the cycle of request-generation-transfer-display |
| of a whole page, Ajax scripts request from a webserver only the essential data to be displayed. |
| Ajax emphasizes the requirement of separation between data and user interface, saves |
| the server from sending over the same html code and graphics if only a fraction of a page has to be |
| updated, allows the programmer to design flexible solutions for complex forms and makes possible |
| to find new innovative approaches to simple problems (e.g. Google tips that show up as you type in |
| a query). A downside of this approach is the large number of complexities, subtleties and incompatibilities |
| that still exist in the way different versions of popular browsers handle the DOM elements of a page. |
| </p><p style="width:90%"> |
| JavaScript can handle the communication between client and server through an instance of a |
| specialized object. For quite a long time 2 approaches existed, the non-IE world (Firefox,Safari,Opera...) |
| used the XMLHttpRequest class to create this object, whereas IE (before IE7) used the ActiveXObject class. |
| With the release of IE7 Microsoft introduced native support for XMLHttpRequest class objects thus enabling |
| programmers with a unique method for the development of dynamic pages. |
| </p><p style="width:90%"> |
| By creating an instance of this class a POST or GET request can be sent to the server and the response is |
| stored in a property ('returnedText') of the communication object. It's become widely customary to encode |
| these responses in XML messages. You can invent your own message structure (either based on XML or anything |
| else), but one has to be aware that if the http headers are properly set and the message returned to the |
| client is a well formed XML fragment, also the property XMLResponse is assigned with a reference to an object |
| that represents the DOM of the XML response. By means of the XML W3C DOM interface the programmer can easily |
| manipulate the data embedded in the XML message. |
| </p><p style="width:90%"> |
| 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. The script sends back to the |
| client two types of responses: a catalog of the composers or a single record of a composer. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"># |
| # Ajax query servelet: a pseudo database is built into the dictionary 'composers' with the |
| # purpose of emulating the role of a real data source. |
| # The script answers with 2 types of responses: a catalog of the record ids and a database |
| # entry matching a given rec_id. The script obviously misses the error handling and the |
| # likes. Just an example to see rivet sending xml data to a browser. The full Tcl, JavaScript |
| # and HTML code are available from http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz |
| |
| # This example requires Tcl8.5 or Tcl8.4 with package 'dict' |
| # (http://pascal.scheffers.net/software/tclDict-8.5.2.tar.gz) |
| # |
| |
| # A pseudo database. rec_id matches a record in the db |
| |
| set composers [dict create 1 {first_name Claudio middle_name "" last_name Monteverdi \ |
| lifespan 1567-1643 era Renaissance/Baroque} \ |
| 2 {first_name Johann middle_name Sebastian last_name Bach \ |
| lifespan 1685-1750 era Baroque } \ |
| 3 {first_name Ludwig middle_name "" last_name "van Beethoven" \ |
| lifespan 1770-1827 era Classical/Romantic} \ |
| 4 {first_name Wolfgang middle_name Amadeus last_name Mozart \ |
| lifespan 1756-1791 era Classical } \ |
| 5 {first_name Robert middle_name "" last_name Schumann \ |
| lifespan 1810-1856 era Romantic} ] |
| |
| # we use the 'load' argument in order to determine the type of query |
| # |
| # load=catalog: we have to return a list of the names in the database |
| # load=composer&res_id=<id>: the script is supposed to return the record |
| # having <id> as record id |
| |
| if {[var exists load]} { |
| |
| # the xml declaration is common to every message (error messages included) |
| |
| set xml "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n" |
| switch [var get load] { |
| catalog { |
| append xml "<catalog>\n" |
| foreach nm [dict keys $composers] { |
| set first_name [dict get $composers $nm first_name] |
| set middle_name [dict get $composers $nm middle_name] |
| set last_name [dict get $composers $nm last_name] |
| append xml " <composer key=\"$nm\">$first_name " |
| if {[string length [string trim $middle_name]] > 0} { |
| append xml "$middle_name " |
| } |
| append xml "$last_name</composer>\n" |
| } |
| append xml "</catalog>\n" |
| } |
| composer { |
| append xml "<composer>\n" |
| if {[var exists rec_id]} { |
| set rec_id [var get rec_id] |
| if {[dict exists $composers $rec_id]} { |
| |
| foreach {k v} [dict get $composers $rec_id] { |
| append xml "<$k>$v</$k>\n" |
| } |
| |
| } |
| } |
| append xml "</composer>\n" |
| } |
| } |
| |
| # we have to tell the client this is an XML message. Failing to do so |
| # would result in an XMLResponse property set to null |
| |
| headers type "text/xml" |
| headers add Content-Length [string length $xml] |
| puts $xml |
| } |
| |
| </pre><p style="width:90%"> |
| For sake of brevity the JavaScript and HTML will not listed here. They can be downloaded (along with the Tcl |
| script) stored in the <a class="ulink" href="http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz" target="_top">rivet-ajax.tar.gz</a> 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. |
| </p></div></div><br class="example-break"></div><div class="section" title="Rivet Tcl Packages"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="tcl_packages"></a>Rivet Tcl Packages</h2></div></div></div><p style="width:90%"> |
| In addition to the core Apache module, Rivet provides a number |
| of Tcl packages that include potentially useful code. |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| commserver is a package providing a server that can be |
| used for IPC. Still experimental. Requires the comm package |
| from tcllib. |
| </div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex">dio is a database abstraction layer.</div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| dtcl is a compatibility package for mod_dtcl |
| applications. |
| </div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex">form - for creating forms.</div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex">rivet - some additional, useful routines.</div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex">tclrivet</div></li></ul></div></div><div class="section" title="DIO - Database Interface Objects"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="dio"></a>DIO - Database Interface Objects</h2></div></div></div><div class="refentry" title="DIO"><a name="dio_package"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>DIO — Database Interface Objects</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::DIO::handle</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>interface</code></em></span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div></div><div class="refsect1" title="Description"><a name="id370308"></a><h2>Description</h2><p style="width:90%"> |
| <span style="font-family:monospace"><span class="command"><strong>DIO</strong></span></span> 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. |
| </p><p style="width:90%"> |
| interface - The name of the database |
| interface. Currently supported interfaces are |
| Postgresql and Mysql. |
| </p><p style="width:90%"> |
| If <em class="replaceable"><code>objectName</code></em> is |
| specified, DIO creates an object of that name. If there is |
| no <em class="replaceable"><code>objectName</code></em> |
| given, DIO will automatically generate a unique object ID |
| </p></div><div class="refsect1" title="Options"><a name="id370351"></a><h2>Options</h2><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-host</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>hostname</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The hostname of the computer to connect to. If none |
| is given, DIO assumes the local host. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-port</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>portNumber</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The port number to connect to on hostname.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-user</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>username</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The username you wish to login to the server as.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-pass</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>password</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The password to login to the server with.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-db</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>database</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The name of the database to connect to. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-table</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tableName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default table to use when using built-in commands |
| for storing and fetching.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyfield</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>keyFieldname</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default field to use as the primary key when using |
| built-in commands for storing and fetching.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-autokey</span> (<span style="font-family:monospace; font-weight: bold;">1</span> | <span style="font-family:monospace; font-weight: bold;">0</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If this option is set to 1, DIO will attempt to |
| determine an automatic key for |
| keyField when storing and fetching. |
| In most databases, this requires that the |
| sequence 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-sequence</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>sequenceName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If DIO is automatically generating keys, it will use |
| this sequence as a means to gain a unique number for |
| the stored key.</div></div></dd></dl></div></div><div class="refsect1" title="DIO Object Commands"><a name="id370662"></a><h2>DIO Object Commands</h2><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">array</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute request 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">autokey</span>? (<span style="font-family:monospace; font-weight: bold;">value</span> | <span style="font-family:monospace; font-weight: bold;">boolean</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current autokey value. If |
| value is specified, it sets a new |
| value for the autokey option.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">close</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> Close the current database connection. This command is |
| automatically called when the DIO object is destroyed.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">count</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> Return a count of the number of rows in the |
| specified (or current) table.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">db</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current database. If |
| value 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">delete</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Delete a record from the database where the primary |
| key matches key.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">destroy</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Destroy the DIO object. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorinfo</span>? ?<span style="font-family:monospace; font-weight: bold;">value</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">errorinfo 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">exec</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute request 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 <a class="link" href="#resultobj" title="Result Object Commands">Result |
| Object Commands</a> |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">fetch</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Fetch a record from the database where the primary key |
| matches key and store the result in |
| an array called arrayName. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">forall</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>body</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute an SQL select request and iteratively |
| fill the array named arrayName |
| with elements named with the matching field names, and |
| values containing the matching values, repeatedly executing |
| the specified code body |
| for each row returned. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">host</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current host value. If |
| value is specified, it sets a new |
| value for the host. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">insert</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Insert fields from arrayName into the specified table in the database. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">interface</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the database interface type, such as |
| <code class="literal">Postgresql</code> or <code class="literal">Mysql</code>. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">keyfield</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current keyfield. If |
| value is specified, it sets a new |
| value for the keyfield. Value can contain |
| multiple key fields as a Tcl list, if the table has multiple |
| key fields. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">keys</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>pattern</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return a list of keys in the database. If |
| pattern is specified, only the keys |
| matching will be returned. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">lastkey</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the last key that was used from |
| sequence. If sequence has not been |
| specified, this command returns an empty string. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">list</span>? ?<span style="font-family:monospace; font-weight: bold;">request</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute request as a SQL query and |
| return a list of the first column of each record |
| found. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">makekey</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>keyfield</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">nextkey</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Increment sequence and return the |
| next key to be used. If sequence has not been |
| specified, this command returns an empty |
| string.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">open</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Open the connection to the current database. This |
| command is automatically called from any command which |
| accesses the database.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">pass</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current pass value. If |
| value is specified, it sets a new |
| value for the password. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">port</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the current port value. If value is |
| specified, it sets a new value for the port.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">quote</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>string</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the specified string quoted in |
| a way that makes it acceptable as a value in a SQL statement. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">search</span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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 <a class="link" href="#resultobj" title="Result Object Commands">Result Object Commands</a> |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| For example, |
| <pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">set res [DIO search -table people -firstname Bob]</pre> |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">sequence</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current sequence value. If value is |
| specified, it sets a new value for the sequence. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">store</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Store the contents of arrayName 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. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The table name must have been previously set |
| or specified with ?<span style="font-family:monospace; font-weight: bold;">-table</span>?, and the key field(s) must |
| have been previously set or specified with |
| ?<span style="font-family:monospace; font-weight: bold;">-keyfield</span>?. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">string</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute request as a SQL query and |
| return a string containing the first record |
| found.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">table</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the current table. If |
| value is specified, it sets a new |
| value for the table.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">update</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Updates the row matching the contents of |
| arrayName in the database. The matching |
| row must already exist. The table can have already been |
| set or can be specified with ?<span style="font-family:monospace; font-weight: bold;">-table</span>?, and |
| the key field(s) must either have been set or |
| specified with ?<span style="font-family:monospace; font-weight: bold;">-keyfield</span>?. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">user</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current user value. If |
| value is specified, it sets a new |
| value for the user. |
| </div></div></dd></dl></div></div><div class="refsect1" title="Result Object Commands"><a name="resultobj"></a><h2>Result Object Commands</h2><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">autocache</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current autocache value. If |
| value is specified, it sets a new |
| value for autocache. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| <span class="emphasis"><em>Default is true</em></span>. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">cache</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorcode</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current errorcode value. If value |
| is specified, it sets a new value for errorcode. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| errorcode 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorinfo</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current errorinfo value. If value |
| is specified, it sets a new value for errorinfo. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If an error occurred during the SQL query, DIO |
| attempts to set the value of errorinfo to the |
| resulting error message. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">fields</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current fields value. If |
| value is specified, it sets a new |
| value for fields. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| fields contains the list of fields |
| used in this query. The fields are in order of the |
| fields retrieved for each row. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">forall</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>-type</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>body</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Execute body over each record in the |
| result object. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex">Types:</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-array</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Create |
| <em class="replaceable"><code>varName</code></em> |
| 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyvalue</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set |
| <em class="replaceable"><code>varName</code></em> |
| to a list containing key-value pairs of fields |
| and values from the current row. (-field value |
| -field value) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-list</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set |
| <em class="replaceable"><code>varName</code></em> |
| to a list that contains the values of the |
| current row. |
| </div></div></dd></dl></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">next</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>-type</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Retrieve the next record in the result object. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex">Types:</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-array</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Create |
| <em class="replaceable"><code>varName</code></em> |
| 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyvalue</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set |
| <em class="replaceable"><code>varName</code></em> |
| to a list containing key-value pairs of fields |
| and values from the current row. (-field value |
| -field value) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-list</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set |
| <em class="replaceable"><code>varName</code></em> |
| to a list that contains the values of the |
| current row. |
| </div></div></dd></dl></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">numrows</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current numrows value. If value is |
| specified, it sets a new value for numrows. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| numrows is the number of rows in this result. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">resultid</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current resultid value. If value is |
| specified, it sets a new value for resultid. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| resultid 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. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">rowid</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current rowid value. If value is |
| specified, it sets a new value for rowid. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| rowid 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. |
| </div></div></dd></dl></div></div></div></div><div class="section" title="DIODisplay - Database Interface Objects Display Class"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="diodisplay"></a>DIODisplay - Database Interface Objects Display Class</h2></div></div></div><div class="refentry" title="DIODisplay"><a name="diodisplay_package"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>DIODisplay — Database Interface Objects Display Class</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">DIODisplay</span> (<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> | <span style="font-family:monospace; font-weight: bold;">#auto</span>) (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div></div><div class="refsect1" title="Description"><a name="id376153"></a><h2>Description</h2><p style="width:90%"> |
| DIODisplay is an HTML display class that uses a DIO object |
| to do the database work and a form object to do the |
| displaying. |
| </p></div><div class="refsect1" title="Options"><a name="id376164"></a><h2>Options</h2><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-DIO</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>dioObject</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The DIO object to be used in conjunction with this |
| display object. This is a required field. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-cleanup</span> (<span style="font-family:monospace; font-weight: bold;">1</span> | <span style="font-family:monospace; font-weight: bold;">0</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If cleanup is true, when the display object is shown, |
| it will automatically destroy the DIO object, the form |
| object and itself. Default is true. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-confirmdelete</span> (<span style="font-family:monospace; font-weight: bold;">1</span> | <span style="font-family:monospace; font-weight: bold;">0</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If confirmdelete is true, attempting to delete a |
| record from the database first requires that the user |
| confirm that they wish to delete it. If it is false, |
| deletion occurs without prompting the user. Defaults |
| to true. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-errorhandler</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>procName</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The name of a procedure to handle errors when they |
| occur. During the processing of requests and pages, |
| sometimes unexpected errors can occur. This procedure |
| will handle any errors. It is called with a single |
| argument, the error string. Use of the Tcl errorInfo |
| and errorCode variables is also recommended though. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If no errorhandler is specified, the handle_error |
| method within the Display object will handle the |
| error. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-fields</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldList</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Specify a list of fields to be used in this object. |
| The fields list is actually created by using the |
| <span style="font-family:monospace"><span class="command"><strong>field</strong></span></span> command to add fields to the |
| display, but this option can be useful to sometimes |
| over-set the list of fields created. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-form</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>formObject</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| A Rivet form object to use when displaying a form. If |
| one is not specified, the display object will |
| automatically create one when it is necessary. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-functions</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>functionList</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| A list of functions to be displayed in the main menu. |
| This is a list of functions the user is allowed to |
| execute. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-pagesize</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>pageSize</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| How many records to show per page on a search or |
| list. Default is 25. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-rowfields</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldList</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| A list of fields to display in each row of a search or |
| list. When a search or list is conducted and the |
| resulting rows are displayed, this list will limit |
| which fields are displayed. Default is all fields. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-rowfunctions</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>functionList</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| A list of functions to display in each row of a search |
| or list. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-searchfields</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldList</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| A list of fields to allow a user to search by. This |
| list will appear in the main screen as a drop-down box |
| of fields the user can search on. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-title</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>title</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The title of the display object. This will be output |
| as the title of the HTML document. |
| </div></div></dd></dl></div><div class="refsect2" title="DIO Display Object Commands"><a name="id376656"></a><h3>DIO Display Object Commands</h3><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">cleanup</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current cleanup value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for the cleanup |
| option. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">delete</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Delete the specified key from the |
| database. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default action of this method is to call the DIO |
| object's delete command. This method can be |
| overridden. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">destroy</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Destroy the diodisplay object. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">DIO</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current DIO value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for DIO. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">errorhandler</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current errorhandler value. If |
| <em class="replaceable"><code>value</code></em> is specified, it |
| sets a new value for errorhandler. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">fetch</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Fetch the specified <em class="replaceable"><code>key</code></em> |
| from the database and store it as an array in |
| <em class="replaceable"><code><em class="replaceable"><code>arrayName</code></em></code></em>. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default of this method is to call the DIO object's fetch command. |
| This method can be overridden. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">field</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldName</code></em></span> (<span style="font-family:monospace; font-weight: bold;">-arg</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arg</code></em></span>...)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Create a new field object and add it to the display. |
| When a field is added to the display, a new object |
| of the DIODisplayField class is created with its |
| values. See [FIXME - LINK] DIO Display Fields for |
| options and values. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">fields</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current fields value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for fields. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">form</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current form value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for form. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">function</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>functionName</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Add a new function to the list of possible |
| functions. The display object will only execute |
| methods and procs which are defined as functions by |
| the object. This is to protect the program from |
| executing a different procedure other than what is |
| allowed. The <span style="font-family:monospace"><span class="command"><strong>function</strong></span></span> command |
| adds a new function to the list of allowable |
| functions. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">functions</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current functions value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for functions. See |
| [FIXME - LINK DIO Display Functions] for a list of |
| default functions. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">pagesize</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current form pagesize. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for pagesize. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">rowfields</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current form rowfields. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for rowfields. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">rowfooter</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Output the footer of a list of rows to the web page. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method can be overridden. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">rowfunctions</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current rowfunctions value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for rowfunctions. |
| |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">rowheader</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Output the header of a list of rows to the web page. |
| By default, this is an HTML table with a top row |
| listing the fields in the table. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method can be overridden. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">searchfields</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current searchfields value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for searchfields. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">show</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Show the display object. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This is the main method of the display class. It |
| looks for a variable called <code class="varname">mode</code> |
| to be passed in through a form response and uses |
| that mode to execute the appropriate function. If |
| mode is not given, the <span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span> |
| function is called. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function should be called for every page. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">showform</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Display the form of the object. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method displays the form for this display |
| object. It is used in the <span style="font-family:monospace"><span class="command"><strong>Add</strong></span></span> |
| and <span style="font-family:monospace"><span class="command"><strong>Edit</strong></span></span> methods but can be |
| called separately if needed. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method can be overridden if the default look of |
| a form needs to be changed. By default, the form |
| displayed is simply the fields in a table, in order. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">showrow</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Display a single row of a resulting list or search. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method is used to display a single row while |
| displaying the result of a list or search. |
| <em class="replaceable"><code>arrayName</code></em> |
| is a fetched array of the record. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method can be overriden if the default look of |
| a row needs to be changed. By default, each row is |
| output as a table row with each field as a table |
| data cell. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">showview</span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Display the view of the object. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method displays the view for this display |
| object. It is used in the |
| <span style="font-family:monospace"><span class="command"><strong>Details</strong></span></span> methods but can be |
| called separately if needed. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This method can be overridden if the default look of |
| a view needs to be changed. By default, the view |
| displayed is simply the fields in a table, in order. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">store</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Store the specified |
| <em class="replaceable"><code>arrayName</code></em> |
| in the database. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default of this method is to call the DIO |
| object's store command. This method can be |
| overridden. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">text</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current text value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for text. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">title</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current title value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for title. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">type</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current type value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for type. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>objectName</code></em></span> <span style="font-family:monospace; font-weight: bold;">value</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the current value value. If |
| <em class="replaceable"><code>value</code></em> is |
| specified, it sets a new value for value. |
| </div></div></dd></dl></div></div><div class="refsect2" title="DIO Display Functions"><a name="id377949"></a><h3>DIO Display Functions</h3><p style="width:90%"> |
| These functions are called from the |
| <span style="font-family:monospace"><span class="command"><strong>show</strong></span></span> method when a form response |
| variable called <code class="varname">mode</code> is set. If no |
| mode has been set, the default mode is |
| <span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span>. The show method will handle |
| the necessary switching of functions. The show method |
| also handles checking to make sure the function given is a |
| true function. If not, an error message is displayed. |
| New functions can be added as methods or by use of the |
| <span style="font-family:monospace"><span class="command"><strong>function</strong></span></span> command, and any of the |
| default functions can be overridden with new methods to |
| create an entirely new class. These are the default |
| functions provided. |
| </p><div class="variablelist"><dl><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Add</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Show a form that allows the user to add a new entry |
| to the database. This function calls |
| <span style="font-family:monospace"><span class="command"><strong>showform</strong></span></span> to display the form |
| for adding the entry. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Cancel</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The <span style="font-family:monospace"><span class="command"><strong>Cancel</strong></span></span> function does nothing |
| but redirect back to the <span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span> |
| function. This is handy for forms which have a |
| cancel button to point to. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Delete</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If <code class="varname">confirmdelete</code> is true (the |
| default), the <span style="font-family:monospace"><span class="command"><strong>Delete</strong></span></span> function |
| will ask the user if they're sure they want to |
| delete the record from the database. If |
| <code class="varname">confirmdelete</code> is false, or if the |
| user confirms they wish to delete, this function |
| calls the <span style="font-family:monospace"><span class="command"><strong>DoDelete</strong></span></span> function to do |
| the actual deletion of a record. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Details</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Display the view of a single record from the database. This function calls |
| the <span style="font-family:monospace"><span class="command"><strong>showview</strong></span></span> method to display a single record from the database. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>DoDelete</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function actually deletes a record from the |
| database. Once it has deleted the record, it |
| redirects the user back to the |
| <span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span> function. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Edit</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Show a form that allows the user to edit an existing |
| entry to the database. This function calls |
| <span style="font-family:monospace"><span class="command"><strong>showform</strong></span></span> to display the form for |
| editing the entry and fills in the fields with the |
| values retrieved from the database. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>List</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function lists the entires contents of the |
| database. Each record is output in a row using the |
| <span style="font-family:monospace"><span class="command"><strong>showrow</strong></span></span> method. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function is the main function of the display |
| object. If there is no mode, or once most commands |
| complete, the user will be redirected to this |
| function. The default <span style="font-family:monospace"><span class="command"><strong>Main</strong></span></span> |
| function displays a list of functions the user can |
| execute, a list of searchfields the user can search |
| on, and a query field. This query field is used by |
| all of the other functions to determine what the |
| user is trying to find. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| In the case of a <span style="font-family:monospace"><span class="command"><strong>search</strong></span></span>, query |
| specifies what string the user is looking for in the |
| specified search field. In the case of |
| <span style="font-family:monospace"><span class="command"><strong>delete</strong></span></span>, |
| <span style="font-family:monospace"><span class="command"><strong>details</strong></span></span> or |
| <span style="font-family:monospace"><span class="command"><strong>edit</strong></span></span>, the query specifies the |
| database key to access. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Save</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function saves any data passed to using the |
| <span style="font-family:monospace"><span class="command"><strong>store</strong></span></span> method. This is primarily |
| used by the <span style="font-family:monospace"><span class="command"><strong>add</strong></span></span> and |
| <span style="font-family:monospace"><span class="command"><strong>edit</strong></span></span> commands to store the |
| results of the form the user has filled out. |
| </div></div></dd><dt><span class="term"><span style="font-family:monospace"><span class="command"><strong>Search</strong></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This function searches the database for any row |
| whose <code class="varname">searchBy</code> field matches |
| <code class="varname">query</code>. Once any number of records |
| are found, <span style="font-family:monospace"><span class="command"><strong>Search</strong></span></span> displays the |
| results in rows. |
| </div></div></dd></dl></div></div><div class="refsect2" title="DIO Display Fields"><a name="id378296"></a><h3>DIO Display Fields</h3><p style="width:90%"> |
| Display fields are created with the |
| <span style="font-family:monospace"><span class="command"><strong>field</strong></span></span> command of the DIODisplay object. |
| Each field is created as a new DIODisplayField object or |
| as a subclass of DIODisplayField. The standard form |
| fields use the standard field class, while specialized |
| field types use a class with different options but still |
| supports all of the same commands and values a generic |
| field does. |
| </p><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace"><em class="replaceable"><code>displayObject</code></em></span> <span style="font-family:monospace; font-weight: bold;">field</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldname</code></em></span> (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span>...)</div></div><p style="width:90%"> |
| These are the standard options supported by field types: |
| </p><div class="variablelist"><dl><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-formargs</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arguments</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| When a field is created, any argument which is not a |
| standard option is assumed to be an argument passed |
| to the form object when the field is shown in a |
| form. These arguments are all appended to the |
| <code class="varname">formargs</code> variable. You can use |
| this option to override or add options after the |
| initial creation of an object |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-readonly</span> (<span style="font-family:monospace; font-weight: bold;">1</span> | <span style="font-family:monospace; font-weight: bold;">0</span>)</div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If <code class="varname">readonly</code> is set to true, the |
| field will not display a form entry when displaying |
| in a form. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-text</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>text</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The text displayed next to the form or view field. |
| By default, DIODisplay tries to figure out a pretty |
| way to display the field name. This text will |
| override that default and display whatever is |
| specified. |
| </div></div></dd><dt><span class="term"> |
| <div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-type</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>fieldType</code></em></span> </div></div> |
| </span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The type of field this is. This type is used when |
| creating the field in the form object. |
| <em class="replaceable"><code>fieldType</code></em> |
| can be any of the accepted form field types. See |
| [FIXME - LINK DIO Field Types] for a list of types |
| available. |
| </div></div></dd></dl></div><p style="width:90%"> |
| All other arguments, unless specified in an individual |
| field type, are passed directly to the form object when |
| the field is created. So, you can pass |
| -size or -maxsize to |
| specify the length and maximum length of the field entry. |
| Or, if type were textarea, you could define |
| -rows and -cols to |
| specify its row and column count. |
| </p></div><div class="refsect2" title="DIO Display Field Types"><a name="id378572"></a><h3>DIO Display Field Types</h3><p style="width:90%"> |
| The following is a list of recognized field types by |
| DIODisplay. Some are standard HTML form fields, and |
| others are DIODisplay fields which execute special actions |
| and functions. |
| </p></div></div></div></div><div class="section" title="Session Package"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="session_package"></a>Session Package</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="id381026"></a>Introduction</h3></div></div></div><p style="width:90%"> |
| This is session management code. It provides an interface |
| to allow you to generate and track a browser's visit as a |
| "session", giving you a unique session ID and an interface |
| for storing and retrieving data for that session on the |
| server. |
| </p><p style="width:90%"> |
| This is an alpha/beta release -- documentation is not in |
| final form, but everything you need should be in this file. |
| </p><p style="width:90%"> |
| Using sessions and their included ability to store and |
| retrieve session-related data on the server, programmers can |
| generate more secure and higher-performance websites. For |
| example, hidden fields do not have to be included in forms |
| (and the risk of them being manipulated by the user |
| mitigated) since data that would be stored in hidden fields |
| can now be stored in the session cache on the server. Forms |
| are then faster since no hidden data is transmitted -- |
| hidden fields must be sent twice, once in the form to the |
| broswer and once in the response from it. |
| </p><p style="width:90%"> |
| Robust login systems, etc, can be built on top of this code. |
| </p></div><div class="section" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a name="requirements"></a>Requirements</h3></div></div></div><p style="width:90%"> |
| Currently has only been tested with Postgresql, MySql and Oracle. |
| All DB interfacing is done through DIO, though, so it |
| should be relatively easy to add support for other |
| databases. |
| </p></div><div class="section" title="Preparing To Use It"><div class="titlepage"><div><div><h3 class="title"><a name="id381362"></a>Preparing To Use It</h3></div></div></div><p style="width:90%">Create the tables in your SQL server. With Postgres, |
| do a <span style="font-family:monospace"><span class="command"><strong>psql www</strong></span></span> or whatever DB you |
| connect as, then a backslash-i on |
| <code class="filename">session-create.sql</code></p><p style="width:90%">(If you need to delete the tables, use <code class="filename">session-drop.sql</code>)</p><p style="width:90%">The session code by default requires a DIO handle |
| called <code class="varname">DIO</code> (the name of which can be |
| overridden). We get it by doing a</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| RivetServerConf ChildInitScript "package require DIO" |
| RivetServerConf ChildInitScript "::DIO::handle Postgresql DIO -user www" |
| </pre></div><div class="section" title="Example Usage"><div class="titlepage"><div><div><h3 class="title"><a name="id381407"></a>Example Usage</h3></div></div></div><p style="width:90%">In your httpd.conf, add:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION"</pre><p style="width:90%"> |
| This tells Rivet you want to create a session object named |
| SESSION in every child process Apache creates.</p><p style="width:90%"> |
| You can configure the session at this point using numerous |
| key-value pairs (which are defined later in this doc). |
| Here's a quick example:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "package require Session; Session SESSION \ |
| -cookieLifetime 120 -debugMode 1"</pre><p style="width:90%"> |
| Turn debugging on -debugMode 1 to figure |
| out what's going on -- it's really useful, if |
| verbose.</p><p style="width:90%"> |
| In your .rvt file, when you're generating the <HEAD> |
| section: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">SESSION activate</pre><p style="width:90%"> |
| Activate handles everything for you with respect to |
| creating new sessions, and for locating, validating, and |
| updating existing sessions. Activate will either locate |
| an existing session, or create a new one. Sessions will |
| automatically be refreshed (their lifetimes extended) as |
| additional requests are received during the session, all |
| under the control of the key-value pairs controlling the |
| session object. |
| </p></div><div class="section" title="Using Sessions From Your Code"><div class="titlepage"><div><div><h3 class="title"><a name="id381463"></a>Using Sessions From Your Code</h3></div></div></div><p style="width:90%">The main methods your code will use are:</p><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| After doing a <span style="font-family:monospace"><span class="command"><strong>SESSION activate</strong></span></span>, |
| this will return a 32-byte ASCII-encoded random |
| hexadecimal string. Every time this browser comes |
| to us with a request within the timeout period, this |
| same string will be returned (assuming they have |
| cookies enabled). |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION</span> <span style="font-weight:bold ; font-family:monospace">is_new_session</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex">returns 1 if it's a new session or 0 if it has |
| previously existed (i.e. it's a zero if this request |
| represents a "return" or subsequent visit to a |
| current session.)</div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This will return why this request is the first |
| request of a new session, either "no_cookie" saying |
| the browser didn't give us a session cookie, |
| "no_session" indicating we got a cookie but couldn't |
| find it in our session table, or "timeout" where |
| they had a cookie and we found the matching session |
| but the session has timed out. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Given the name of a package, a key, and some data. |
| Stores the data in the rivet session cache table. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Given a package name and a key, return the data |
| stored by the store method, or an empty string if |
| none was set. (Status is set to the DIO error that |
| occurred, it can be fetched using the status |
| method.) |
| </div></div></dd></dl></div></div><div class="section" title="Session Configuration Options"><div class="titlepage"><div><div><h3 class="title"><a name="id381660"></a>Session Configuration Options</h3></div></div></div><p style="width:90%">The following key-value pairs can be specified when a |
| session object (like SESSION above) is created:</p><div class="variablelist"><dl><dt><span class="term">sessionLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">how many seconds the session will live for. |
| 7200 == 2 hours |
| </div></div></dd><dt><span class="term">sessionRefreshInterval</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If a request is processed for a browser that |
| currently has a session and this long has elapsed |
| since the session update time was last updated, |
| update it. 900 == 15 minutes. so if at least 15 |
| minutes has elapsed and we've gotten a new request |
| for a page, update the session update time, |
| extending the session lifetime (sessions that are in |
| use keep getting extended). |
| </div></div></dd><dt><span class="term">cookieName</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"></div> |
| name of the cookie stored on the user's web browser |
| default rivetSession |
| </div></dd><dt><span class="term">dioObject</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The name of the DIO object we'll use to access the |
| database (default DIO) |
| </div></div></dd><dt><span class="term">gcProbability</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The probability that garbage collection will occur |
| in percent. (default 1%, i.e. 1)</div></div></dd><dt><span class="term">gcMaxLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">the number of seconds after which |
| data will be seen as "garbage" and cleaned up -- |
| defaults to 1 day (86400)</div></div></dd><dt><span class="term">refererCheck</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The substring you want to check each |
| HTTP referer for. If the referer was sent by the |
| browser and the substring is not found, the session |
| will be deleted. (not coded yet)</div></div></dd><dt><span class="term">entropyFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The |
| name of a file that random binary data can be read |
| from. (<code class="filename">/dev/urandom</code>) Data will |
| be used from this file to help generate a |
| super-hard-to-guess session ID.</div></div></dd><dt><span class="term">entropyLength</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The number of bytes which will be |
| read from the entropy file. If 0, the entropy file |
| will not be read (default 0)</div></div></dd><dt><span class="term">scrambleCode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Set the scramble code to something unique for the |
| site or your app or whatever, to slightly increase |
| the unguessability of session ids (default "some |
| random string")</div></div></dd><dt><span class="term">cookieLifetime</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The lifetime of the cookie in |
| minutes. 0 means until the browser is closed (I |
| think). (default 0)</div></div></dd><dt><span class="term">cookiePath</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The |
| webserver subpath that the session cookie applies to |
| (defaults to |
| <code class="filename">/</code>)</div></div></dd><dt><span class="term">cookieSecure</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Specifies whether the cookie should |
| only be sent over secure connections, 0 = any, 1 = |
| secure connections only (default |
| 0)</div></div></dd><dt><span class="term">sessionTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that session |
| info will be stored in (default |
| <code class="varname">rivet_session</code>)</div></div></dd><dt><span class="term">sessionCacheTable</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The name of the table that contains |
| cached session data (default |
| <code class="varname">rivet_session_cache</code>)</div></div></dd><dt><span class="term">debugMode</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">Set |
| debug mode to 1 to trace through and see the session |
| object do its thing (default 0)</div></div></dd><dt><span class="term">debugFile</span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:1.5ex ; padding .5ex">The |
| file handle that debugging messages will be written |
| to (default |
| <code class="varname">stdout</code>) |
| </div></div></dd></dl></div></div><div class="section" title="Session Methods"><div class="titlepage"><div><div><h3 class="title"><a name="id381888"></a>Session Methods</h3></div></div></div><p style="width:90%"> |
| The following methods can be invoked to find out |
| information about the current session, store and fetch |
| server data identified with this session, etc: |
| </p><div class="variablelist"><dl><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION status</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Return the status of the last operation |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION id</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Get the session ID of the current browser. Returns |
| an empty string if there's no session (will not |
| happen is SESSION activate has been issued.) |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION new_session_reason</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Returns the reason why there wasn't a previous |
| session, either "no_cookie" saying the browser |
| didn't give us a session cookie, "no_session" |
| indicating we got a cookie but couldn't find it in |
| the session table, or "timeout" when we had a cookie |
| and a session but the session had timed out. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION store</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>data</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Given a package name, a key string, and a data |
| string, store the data in the rivet session |
| cache. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION fetch</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>packageName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Given a package name and a key, return the data |
| stored by the store method, or an empty string if |
| none was set. Status is set to the DIO error that |
| occurred, it can be fetched using the status |
| method. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION delete</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Given a user ID and looking at their IP address we |
| inherited from the environment (thanks, Apache), |
| remove them from the session table. (the session |
| table is how the server remembers stuff about |
| sessions). If the session ID was not specified the |
| current session is deleted. |
| </div></div></dd><dt><span class="term"></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">SESSION activate</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Find and validate the session ID if they have one. |
| If they don't have one or it isn't valid (timed out, |
| etc), create a session and drop a cookie on |
| them. |
| </div></div></dd></dl></div></div><div class="section" title="Getting Additional Randomness From The Entropy File"><div class="titlepage"><div><div><h3 class="title"><a name="id382114"></a>Getting Additional Randomness From The Entropy File</h3></div></div></div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">RivetServerConf ChildInitScript "Session SESSION -entropyFile /dev/urandom \ |
| -entropyLength 10 -debugMode 1"</pre><p style="width:90%"> |
| This options say we want to get randomness from an entropy |
| file (random data pseudo-device) of /dev/urandom, to get ten |
| bytes of random data from that entropy device, and to turn |
| on debug mode, which will cause the SESSION object to output |
| all manner of debugging information as it does stuff. This |
| has been tested on FreeBSD and appears to work. |
| </p></div></div><div class="section" title="Form: An HTML Form Fields Generation Utility"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="form"></a>Form: An HTML Form Fields Generation Utility</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="id382744"></a>Introduction</h3></div></div></div><p style="width:90%"> |
| The <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> package is a utility for generating html forms. A <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> |
| object command saves the programmer from typing the cumbersome html code of input elements, |
| working out a solution for better standardization and readability of the code. |
| <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> requires that only the minimum necessary to distinguish the element is |
| typed, greatly simplyfing the development of forms. |
| Options to the command are treated as a list of parameter-value pairs that become the defaults |
| for the corresponding attributes of the form. |
| </p><p style="width:90%"> |
| A <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> object has specialized menthods to generate all of the standard |
| input fields, i.e. text, password, hidden, generic button, submit or reset buttons and |
| image. <span style="font-family:monospace"><span class="command"><strong>form</strong></span></span> creates select input fields, radiobutton and checkbox |
| boolean options groups. Also new inputs introduced with HTML5 are supported: color, date, |
| datetime, datetime-local, email, file, month, number, range, search, tel, time, url, week. |
| </p><p style="width:90%"> |
| Other input elements can be generated using the general purpose 'field' method. |
| </p></div><div class="refentry" title="form"><a name="form_package"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>form — a Tcl command object for creating HTML forms</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">form</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>form_name</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">-option1 <em class="replaceable"><code>value_1</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-option2 <em class="replaceable"><code>value_2</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">...</span>?</div></div></div><div class="refsect1"><a name="id383158"></a><p style="width:90%"> |
| creates and returns a new Tcl command named <em class="replaceable"><code>form_name</code></em>. |
| </p><div class="refsect2" title="Options"><a name="id383168"></a><h3>Options</h3><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-method</span> ?<span style="font-family:monospace; font-weight: bold;">post|get</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The http method for sending the form data back to the server. |
| Possible values are get or post |
| </div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| At the time of writing only the 'get' method is implemented |
| </td></tr></table></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-name</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>form_name</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| a name for the form being created: this value becomes the value of the |
| attribute 'name' in the <form> tag. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-defaults</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>default_values</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| an array of default values to be assigned to the fields of the form. |
| Every name in the array is matched with an input field, when |
| a given field gets added to the form it is initialized with the |
| value of the corresponding variable in the array. |
| This option works well in conjuction with the |
| <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> command of Rivet when default |
| values come from another form. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-action</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>URL</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The URL the data are being sent to. If no ?<span style="font-family:monospace; font-weight: bold;">-action</span>? switch is specified |
| the data are sent to the form's URL. |
| </div></div></dd></dl></div></div></div><div class="refsect1" title="Form Object Commands"><a name="id383335"></a><h2>Form Object Commands</h2><p style="width:90%"> |
| Form object commands follow the usual syntax of Tcl commands with a ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>subcommand</code></em></span>? argument playing the |
| role of a switch among various functionalities of the command. Form objects also need the ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>name</code></em></span>? parameter |
| which is to become the value of the 'name' attribute in an input field. This argument is the key that has to be |
| used by the server-side script to retrieve the input field value. |
| </p><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| form_object <span style="font-family:monospace; font-weight: bold;">subcommand</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">-option1 <em class="replaceable"><code>value1</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-option2 <em class="replaceable"><code>value2</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">...</span>?</div></div></div></dd></dl></div><p style="width:90%"> |
| Options passed to a subcommand are copied into the tag as attribute="value" pairs. |
| Some subcommands (e.g. form, radiobuttons and checkboxes) treat specific options in a way |
| that fits the specific organization and function of these fields. |
| </p><p style="width:90%"> |
| Exceptions to this general syntax are the <span style="font-family:monospace"><span class="command"><strong>field</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>end</strong></span></span> subcommands. |
| <span style="font-family:monospace"><span class="command"><strong>field</strong></span></span> is an abstract input field creation method and requires an additional |
| parameter specifiyng the type of field to create. Every concrete input field generation command |
| uses this subcommand internally to print the final html. |
| </p></div><div class="refsect1" title="Subcommands"><a name="id383457"></a><h2>Subcommands</h2><div class="refsect2"><a name="id383462"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">start</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">-method <em class="replaceable"><code>get | post</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-name <em class="replaceable"><code>form_name</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-defaults <em class="replaceable"><code>default_values</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-action <em class="replaceable"><code>URL</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Print the <form> tag with all its attributes. |
| This command must be called as first in the form generation |
| process. The following is a sample of code creating a form named 'formname' whose data will |
| be sent via the GET method. Initial form fields values will be obtained from array |
| <code class="varname">response</code> |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| form myform -defaults response -method get -name formname |
| myform start |
| myform text text_entry -size 20 |
| myform select option_selected -values {opt1 opt2 opt3 opt4} |
| myform submit submit -value Search |
| myform end</pre><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The code prints a form that sends a text entry content and the option value |
| associated with a radiobutton. The URL of the server script is the same that |
| created the form. Use the ?<span style="font-family:monospace; font-weight: bold;">-url</span>? option to specify a different url. |
| </div></div></dd></dl></div><div class="refsect3" title="Options"><a name="id383577"></a><div style="padding:4 ; margin-top:3 ; margin-left: 5%;">Options</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-method</span> ?<span style="font-family:monospace; font-weight: bold;">post|get</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The method to be used to encode the form data. |
| Possible values are get or post |
| </div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| Currently, only the 'get' method is implemented |
| </td></tr></table></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-name</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>form_name</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| a name for the form being generated: this value becomes the value of the |
| attribute 'name' in the <form> tag. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-defaults</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>default_values</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| an array of default values to be assigned to the fields of the form. |
| Every name in the array is matched with an input field, when |
| a given field gets added to the form it is initialized with the |
| value of the corresponding variable in the array. |
| This option works well in conjuction with the |
| <span style="font-family:monospace"><span class="command"><strong>load_response</strong></span></span> command of Rivet when default values |
| come from another form. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-action</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>URL</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The URL the data will be sent to. If no ?<span style="font-family:monospace; font-weight: bold;">-action</span>? switch is specified |
| the data are sent to the form's URL. |
| </div></div></dd></dl></div></div></div><div class="refsect2"><a name="id383742"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">end</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Print the </form> closing tag. This command must |
| be called last in the form generation process |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id383772"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">field</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">type</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Print a field of the given ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>type</code></em></span>? and ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>name</code></em></span>?, |
| including any default key-value pairs defined for this field |
| type and optional key-value pairs included with the statement |
| </div></div></dd></dl></div><div class="refsect3" title="Options"><a name="id383842"></a><div style="padding:4 ; margin-top:3 ; margin-left: 5%;">Options</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-opt1</span> ?<span style="font-family:monospace; font-weight: bold;">val1</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Option description |
| </div></div></dd></dl></div></div></div><div class="refsect2"><a name="id383884"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">radiobuttons</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">-values <em class="replaceable"><code>values</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-labels <em class="replaceable"><code>labels</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| the <span style="font-family:monospace"><span class="command"><strong>radiobutton</strong></span></span> creates a whole radiobutton group |
| with the values and labels specified in the argument list. |
| If no ?<span style="font-family:monospace; font-weight: bold;">-labels</span>? switch is |
| passed to the subcommand the values are printed as labels of |
| the radiobutton. |
| </div><div class="refsect3" title="Options"><a name="id383963"></a><div style="padding:4 ; margin-top:3 ; margin-left: 5%;">Options</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-values</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>values_list</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| List of values associated with the radiobuttons to be displayed |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-labels</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>labels_list</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| List of labels to be printed with every radiobutton. There must |
| be a label for every radiobutton |
| </div></div></dd></dl></div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Example: |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| form myform -defaults response -method get -name formname |
| myform start |
| myform text text_entry -size 20 |
| myform radiobuttons fruit -values {big medium small} \ |
| -labels {Watermelon Orange Strawberry} \ |
| -class myradiobclass |
| myform submit submit -value Search |
| myform end</pre><div style="margin-bottom:1.5ex ; padding .5ex"> |
| will print the following HTML code. |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| <input type="radio" name="fruit" class="myradiobclass" value="big" />Watermelon |
| <input type="radio" name="fruit" class="myradiobclass" value="medium" />Orange |
| <input type="radio" name="fruit" class="myradiobclass" value="small" />Strawberry |
| </pre><div style="margin-bottom:1.5ex ; padding .5ex"> |
| if the <code class="varname">response</code> array has a variable for the name 'fruit' the corresponding |
| radiobutton field is automatically checked. The options ?<span style="font-family:monospace; font-weight: bold;">values</span>? and ?<span style="font-family:monospace; font-weight: bold;">labels</span>? |
| are used internally and don't get into the tag attributes. If a ?<span style="font-family:monospace; font-weight: bold;">labels</span>? |
| option is not given, labels are assigned using the ?<span style="font-family:monospace; font-weight: bold;">values</span>? list. |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384112"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">checkbox</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">-label <em class="replaceable"><code>label</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-value <em class="replaceable"><code>value</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The <span style="font-family:monospace; font-weight: bold;">checkbox</span> subcommand emits a checkbox |
| type input field with the name, label and value attributes set |
| according to the parameters passed to the subcommand. |
| </div><div class="refsect3" title="Options"><a name="id384184"></a><div style="padding:4 ; margin-top:3 ; margin-left: 5%;">Options</div><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-values</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>values_list</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| List of values associated with the checkboxes to be displayed |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-left: 5%; margin-bottom:3 ; width:70%;"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-labels</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>labels_list</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| List of labels to be printed with every checkbox. There must |
| be a label for every checkbox |
| </div></div></dd></dl></div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Example: |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">myform checkbox options -value opt1 -label "Option 1" |
| myform checkbox options -value opt2 -label "Option 2" |
| myform checkbox options -value opt3 -label "Option 3" |
| myform checkbox options -value opt4 -label "Option 4"</pre><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Provided opt2 was in response array (in the list valued 'options' variable) that |
| initialized the form, the output would look like this |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"><input type="checkbox" name="options" label="Option 1" value="opt1" />Option 1 |
| <input type="checkbox" name="options" label="Option 2" value="opt2" |
| checked="checked" />Option 2 |
| <input type="checkbox" name="options" label="Option 3" value="opt3" />Option 3 |
| <input type="checkbox" name="options" label="Option 4" value="opt4" />Option 4</pre></div></dd></dl></div></div><div class="refsect2"><a name="id384289"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">password</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Same as text, but the input is obfuscated so as not to reveal the text being typed |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384335"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">hidden</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| hidden input element: typicall embedded in a form in order to |
| pass status variables. |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384382"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">submit</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| emits the code for a classical HTML submit button. Example: the following |
| code |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| <pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| form myform -defaults response -method get -name feedsearch |
| myform start |
| myform submit submit -value Search</pre> |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Would emit a form like this |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| <form...> |
| <input type="submit" name="submit" value="Search" /> |
| </form></pre></div></dd></dl></div></div><div class="refsect2"><a name="id384448"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">button</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| emits the code for a button field having ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>name</code></em></span>? as name |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384504"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">reset</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Classical HTML reset button that resets the input fields |
| back to their initial values |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384551"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">image</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an image input field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384597"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">checkbox</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits a checkbox input field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384643"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">radio</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits a radiobutton input field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384689"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">color</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "color" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384736"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">date</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "date" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384782"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">datetime</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "datetime" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384828"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">datetime_local</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "datetime_local" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384874"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">email</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "email" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384920"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">file</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "file" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id384966"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">month</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "month" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385012"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">number</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "number" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385059"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">range</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "range" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385105"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">search</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "search" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385151"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">tel</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "tel" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385197"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">time</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "time" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385243"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">url</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "url" form field |
| </div></div></dd></dl></div></div><div class="refsect2"><a name="id385289"></a><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">week</span> ?<span style="font-family:monospace; font-weight: bold;">name</span>? ?<span style="font-family:monospace; font-weight: bold;">args</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Emits an HTML 5 "week" form field |
| </div></div></dd></dl></div></div></div></div></div><div class="section" title="Calendar Package"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="calendar_package"></a>Calendar Package</h2></div></div></div><div class="section" title="Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="id387514"></a>Introduction</h3></div></div></div><p style="width:90%"> |
| The package is based on the Calendar class, a class capable |
| of printing an ascii calendar table that closely resembles the output |
| of the typical Unix <span style="font-family:monospace"><span class="command"><strong>cal</strong></span></span> command. The internal |
| code is written entirely in Tcl, therefore doesn't rely on the |
| existance of <span style="font-family:monospace"><span class="command"><strong>cal</strong></span></span> on the system. |
| XmlCalendar inherits the basic methods and adds XML tagging to the |
| table. XmlCalendar prints an XML calendar table whose header, |
| weekdays banner and days rows tags are configurable. |
| Also specific days or specific weeks can be given arbitrary attributes. |
| </p><p style="width:90%"> |
| Calendar core methods are based on the |
| <a class="ulink" href="http://wiki.tcl.tk/17964" target="_top">cal</a> procedure |
| written by Richard Suchenwirth and published on the |
| <a class="ulink" href="http://wiki.tcl.tk" target="_top">Tcl Wiki</a> |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| The Calendar package uses Tcl <span style="font-family:monospace"><span class="command"><strong>dict</strong></span></span> command to manage markup |
| information. Hence either Tcl8.5 or Tcl8.4 with |
| <a class="ulink" href="http://wiki.tcl.tk/5042" target="_top">package dict</a> are required. |
| </td></tr></table></div></div><div class="refentry" title="Calendar"><a name="calendar"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>Calendar — Utility class the builds and prints a calendar table</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">Calendar</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>calendar_name</code></em></span> </div></div></div><div class="refsect1" title="Calendar object subcommands"><a name="id387904"></a><h2>Calendar object subcommands</h2><p style="width:90%"> |
| The main public command for a calendar object is |
| <span style="font-family:monospace"><span class="command"><strong>emit</strong></span></span> that returns a calendar table |
| </p></div><div class="refsect1"><a name="id387921"></a><div class="variablelist"><p style="width:90%"> |
| The method <span style="font-family:monospace"><span class="command"><strong>emit</strong></span></span> when invoked with a single argument |
| takes it as an year number and prints the whole calendar of |
| that year. When invoked with 2 arguments takes the first as a month, either |
| expressed in its shortened form ('Jan','Feb',...) or as a number in the |
| range 1-12. The second argument is a year number. |
| </p><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| calendar_obj <span style="font-weight:bold ; font-family:monospace">emit</span> </div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| calendar_obj <span style="font-weight:bold ; font-family:monospace">emit</span> ?<span style="font-family:monospace; font-weight: bold;">month</span>? ?<span style="font-family:monospace; font-weight: bold;">year</span>?</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| calendar_obj <span style="font-weight:bold ; font-family:monospace">emit</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>month | year</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The method 'emit' if invoked without arguments returns an |
| ASCII formatted calendar of the current month |
| </div><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| set cal [Calendar #auto] |
| set current_month [$cal emit] |
| puts $current_month |
| Jun 2010 |
| Su Mo Tu We Th Fr Sa |
| 1 2 3 4 5 |
| 6 7 8 9 10 11 12 |
| 13 14 15 16 17 18 19 |
| 20 21 22 23 24 25 26 |
| 27 28 29 30</pre></div></dd></dl></div></div></div><div class="refentry" title="XmlCalendar"><div class="refentry.separator"><hr></div><a name="xml_calendar"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>XmlCalendar — Prints XML formatted calendar tables</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">XmlCalendar</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>calendar_name</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">-option1 <em class="replaceable"><code>option_list</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-option2 <em class="replaceable"><code>option_list</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">...</span>?</div></div></div><div class="refsect1"><a name="id388088"></a><p style="width:90%"> |
| An XmlCalendar object is created and returned. XmlCalendar objects |
| print XML formatted calendar tables. The markup can be customized |
| using the configuration options. |
| </p><p style="width:90%"> |
| Configuration options accept odd-length lists as values. An option_list has the following |
| structure |
| </p><p style="width:90%"> |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">tag_name attr11 val1 attr2 val2 ...</pre><p style="width:90%"> |
| </p><p style="width:90%"> |
| The first element of an option list is a tag name, the remaining terms are therefore |
| an even-length sublist which is interpreted as a sequence of attribute-value pairs that |
| will in turn become attributes of the tag. |
| </p></div><div class="refsect1" title="Methods"><a name="id388114"></a><h2>Methods</h2><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| cal_obj <span style="font-weight:bold ; font-family:monospace">emit</span> -opt1 val1 -opt2 val2</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| cal_obj <span style="font-weight:bold ; font-family:monospace">emit</span> ?<span style="font-family:monospace; font-weight: bold;">month</span>? ?<span style="font-family:monospace; font-weight: bold;">year</span>? -opt1 val1 -opt2 val2</div></div><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> |
| cal_obj <span style="font-weight:bold ; font-family:monospace">emit</span> ?<span style="font-family:monospace; font-weight: bold;"> |
| <em class="replaceable"><code>month | year</code></em></span>? -opt1 val1 |
| -opt2 val2</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The method 'emit' if invoked without arguments returns an |
| XML calendar table of the current month |
| </div></div></dd></dl></div></div><div class="refsect1"><a name="id388206"></a><div class="refsect2" title="Options"><a name="id388208"></a><h3>Options</h3><div class="variablelist"><dl><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-container (tag_name |
| attr11 val1 attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Assigns an options list to the XML element that |
| will hold the whole table. |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The default tag for the container is 'calendar', with no attributes. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-header (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Assigns tag name and attributes to the XML header element (default: calheader) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-body (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Assigns tag name and attributes to the XML body element of the table (default: calbody) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-banner (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Assigns tag name and attributes to the XML banner element of the table (default: monthyear) |
| </div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| The header of a calendar table is made of a banner, showing the Month and Year number, and |
| of a weekdays bar. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-foot (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Assigns tag name and attributes to the XML foot element |
| of the table (default: calfoot). |
| </div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| This option was added for completeness, but it's not implemented yet |
| </td></tr></table></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-banner_month (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element holding the |
| month name (default:month) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-banner_year (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element holding the |
| month name (default: year) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-weekdays (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element holding the |
| weekday header (default: weekdays) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-weekdays_cell (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element holding the |
| each single weekday (default: wkdays) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-days_row (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element holding the |
| each row of the calendar table (default: week) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-days_cell (tag_name attr11 val1 |
| attr2 val2 ...)</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| Tag name and attributes for the XML element representing |
| a cell in the calendar table (default: day) |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-cell_function proc</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| If set this option is the name of a procedure that gets |
| called for every day of the month. The procedure must |
| accept 4 argument representing day, month, year and weekday |
| and must return an odd-length list interpreted in the same |
| way as options lists. |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-current_day day</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option works as a simple method for pointing out |
| a specific day of the month. If set with a day number |
| that day will get the class attribute automatically |
| set as "current" |
| </div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">-current_weekday 0-6 | today</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> |
| This option works as a simple method for pointing out |
| a specific weekday of the month. If set with a weekday |
| index (0: Sunday, 6: Saturday) the corresponding cell in |
| the weekdays header will get the class attribute automatically |
| set as "current_wkday" |
| </div></div></dd></dl></div></div></div></div><div class="refentry" title="HtmlCalendar"><div class="refentry.separator"><hr></div><a name="html_calendar"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>HtmlCalendar — Concrete class derived from XmlCalendar</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="background:#ccccff ; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">HtmlCalendar</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>calendar_name</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">-option1 <em class="replaceable"><code>option_list</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">-option2 <em class="replaceable"><code>option_list</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;">...</span>?</div></div></div><div class="refsect1"><a name="id388727"></a><p style="width:90%"> |
| Concrete XmlCalendar class for printing html calendar tables. The markup of the class |
| is xhtml compliant and prints a code fragment for inclusion in a webpage. |
| The following is the class definition. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| ::itcl::class HtmlCalendar { |
| inherit XmlCalendar |
| |
| constructor {args} {XmlCalendar::constructor $args} { |
| $this configure -container table \ |
| -header thead \ |
| -body tbody \ |
| -banner tr \ |
| -banner_month {th colspan 3 style "text-align: right;"} \ |
| -banner_year {th colspan 4 style "text-align: left;"} \ |
| -weekdays tr \ |
| -weekday_cell th \ |
| -days_row tr \ |
| -days_cell td |
| } |
| }</pre></div><div class="refsect1"><a name="id388746"></a><p style="width:90%"> |
| A sample output from HtmlCalendar (with some styling) |
| </p><p style="width:90%"> |
| </p><div><img src="calendar.png"></div><p style="width:90%"> |
| </p></div></div></div><div class="section" title="Resources - How to Get Help"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="help"></a>Resources - How to Get Help</h2></div></div></div><div class="section" title="Mailing Lists"><div class="titlepage"><div><div><h3 class="title"><a name="id389501"></a>Mailing Lists</h3></div></div></div><p style="width:90%"> |
| The Rivet mailing list is the first place you should turn for |
| help. If you haven't found the solution to your problem in the documentation |
| or you have a question, idea, or comment about the Rivet code itself send email to |
| <code class="email"><<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>></code>. To subscribe to the list, post email to |
| <code class="email"><<a class="email" href="mailto:rivet-dev-subscribe@tcl.apache.org">rivet-dev-subscribe@tcl.apache.org</a>></code>. |
| </p><p style="width:90%"> |
| The mailing list archives are available at <a class="ulink" href="http://mail-archives.apache.org/mod_mbox/tcl-rivet-dev/" target="_top">http://mail-archives.apache.org/mod_mbox/tcl-rivet-dev/</a> |
| </p></div><div class="section" title="Newsgroup"><div class="titlepage"><div><div><h3 class="title"><a name="id389528"></a>Newsgroup</h3></div></div></div><p style="width:90%"> |
| The <a class="ulink" href="news:comp.lang.tcl" target="_top">news:comp.lang.tcl</a> newsgroup is a good |
| place to ask about Tcl questions in general. Rivet developers |
| also follow the newsgroup, but it's best to ask Rivet-specific |
| questions on the Rivet list. |
| </p></div><div class="section" title="Web Sites"><div class="titlepage"><div><div><h3 class="title"><a name="websites"></a>Web Sites</h3></div></div></div><p style="width:90%"> |
| There are several web sites that cover Apache and Tcl |
| extensively. |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| <a class="ulink" href="http://tcl.apache.org" target="_top">http://tcl.apache.org</a> is the home for the |
| Apache Tcl project. Go there for the latest versions of |
| our software (if you aren't reading these pages off of the |
| site!). |
| </div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| <a class="ulink" href="http://httpd.apache.org/docs/" target="_top">http://httpd.apache.org/docs/</a> is the first |
| place to go for questions about the Apache web server. |
| </div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| <a class="ulink" href="http://www.tcl.tk" target="_top">http://www.tcl.tk</a> is the canonical site |
| for Tcl information. |
| </div></li><li class="listitem"><div style="margin-bottom:1.5ex ; padding .5ex"> |
| <a class="ulink" href="http://wiki.tcl.tk" target="_top">http://wiki.tcl.tk</a> is the Tcl'ers Wiki, a |
| free-form place to search for answers and ask for help. |
| </div></li></ul></div></div><div class="section" title="Bug Tracking System"><div class="titlepage"><div><div><h3 class="title"><a name="id389901"></a>Bug Tracking System</h3></div></div></div><p style="width:90%"> |
| Apache Rivet uses the Apache Bug Tracking system at <a class="ulink" href="http://issues.apache.org/bugzilla/" target="_top">http://issues.apache.org/bugzilla/</a>. Here, |
| you can report problems, or check and see if existing issues |
| are already known and being dealt with. |
| </p></div><div class="section" title="IRC"><div class="titlepage"><div><div><h3 class="title"><a name="id389917"></a>IRC</h3></div></div></div><p style="width:90%"> |
| Occasionally, someone from the Rivet team is on IRC at |
| irc.freenode.net, channel #tcl. |
| </p></div><div class="section" title="Editing Rivet Template Files"><div class="titlepage"><div><div><h3 class="title"><a name="id389928"></a>Editing Rivet Template Files</h3></div></div></div><p style="width:90%"> |
| Rivet makes available code for two popular editors, |
| <span class="application">emacs</span> and |
| <span class="application">vim</span> to facilitate the editing of |
| Rivet template files. The key concept is that the editor is |
| aware of the <? and ?> tags and switches back and forth |
| between Tcl and HTML modes as the cursor moves. These files, |
| <code class="filename">two-mode-mode.el</code> and |
| <code class="filename">rvt.vim</code> are available in the |
| <code class="filename">contrib/</code> directory. |
| </p></div></div><div class="section" title="Rivet Internals"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="internals"></a>Rivet Internals</h2></div></div></div><p style="width:90%"> |
| This section easily falls out of date, as new code is added, old |
| code is removed, and changes are made. The best place to look |
| is the source code itself. If you are interested in the changes |
| themselves, the Subversion revision control system |
| (<span style="font-family:monospace"><span class="command"><strong>svn</strong></span></span>) can provide you with information about |
| what has been happening with the code. |
| </p><div class="section" title="Initialization"><div class="titlepage"><div><div><h3 class="title"><a name="id389735"></a>Initialization</h3></div></div></div><p style="width:90%"> |
| When Apache is started, (or when child Apache processes are |
| started if a threaded Tcl is used), |
| <code class="function">Rivet_InitTclStuff</code> is called, which |
| creates a new interpreter, or one interpreter per virtual |
| host, depending on the configuration. It also initializes |
| various things, like the <span class="structname">RivetChan</span> |
| channel system, creates the Rivet-specific Tcl commands, and |
| executes Rivet's <code class="filename">init.tcl</code>. The caching |
| system is also set up, and if there is a |
| <span style="font-family:monospace"><span class="command"><strong>GlobalInitScript</strong></span></span>, it is run. |
| </p></div><div class="section" title="RivetChan"><div class="titlepage"><div><div><h3 class="title"><a name="id389686"></a>RivetChan</h3></div></div></div><p style="width:90%"> |
| The <span class="structname">RivetChan</span> system was created in |
| order to have an actual Tcl channel that we could redirect |
| standard output to. This lets us use, for instance, the |
| regular <span style="font-family:monospace"><span class="command"><strong>puts</strong></span></span> command in .rvt pages. It |
| works by creating a channel that buffers output, and, at |
| predetermined times, passes it on to Apache's IO system. |
| Tcl's regular standard output is replaced with an instance of |
| this channel type, so that, by default, output will go to the |
| web page. |
| </p></div><div class="section" title="The global Command"><div class="titlepage"><div><div><h3 class="title"><a name="id390255"></a>The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</h3></div></div></div><p style="width:90%"> |
| Rivet aims to run standard Tcl code with as few surprises as |
| possible. At times this involves some compromises - in this |
| case regarding the <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> command. The |
| problem is that the command will create truly global |
| variables. If the user is just cut'n'pasting some Tcl code |
| into Rivet, they most likely just want to be able to share the |
| variable in question with other procs, and don't really care |
| if the variable is actually persistant between pages. The |
| solution we have created is to create a proc |
| <span style="font-family:monospace"><span class="command"><strong>::request::global</strong></span></span> that takes the place of |
| the <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> command in Rivet templates. If |
| you really need a true global variable, use either |
| <span style="font-family:monospace"><span class="command"><strong>::global</strong></span></span> or add the :: namespace qualifier |
| to variables you wish to make global. |
| </p></div><div class="section" title="Page Parsing, Execution and Caching"><div class="titlepage"><div><div><h3 class="title"><a name="id390300"></a>Page Parsing, Execution and Caching</h3></div></div></div><p style="width:90%"> |
| When a Rivet page is requested, it is transformed into an |
| ordinary Tcl script by parsing the file for the <? ?> |
| processing instruction tags. Everything outside these tags |
| becomes a large <span style="font-family:monospace"><span class="command"><strong>puts</strong></span></span> statement, and |
| everything inside them remains Tcl code. |
| </p><p style="width:90%"> |
| Each .rvt file is evaluated in its own |
| <code class="constant">::request</code> namespace, so that it is not |
| necessary to create and tear down interpreters after each |
| page. By running in its own namespace, though, each page will |
| not run afoul of local variables created by other scripts, |
| because they will be deleted automatically when the namespace |
| goes away after Apache finishes handling the request. |
| </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"> |
| One current problem with this system is that while |
| variables are garbage collected, file handles are not, so |
| that it is very important that Rivet script authors make |
| sure to close all the files they open. |
| </td></tr></table></div><p style="width:90%"> |
| </p><p style="width:90%"> |
| After a script has been loaded and parsed into it's "pure Tcl" |
| form, it is also cached, so that it may be used in the future |
| without having to reload it (and re-parse it) from the disk. |
| The number of scripts stored in memory is configurable. This |
| feature can significantly improve performance. |
| </p></div><div class="section" title="Debugging Rivet and Apache"><div class="titlepage"><div><div><h3 class="title"><a name="id390342"></a>Debugging Rivet and Apache</h3></div></div></div><p style="width:90%"> |
| If you are interested in hacking on Rivet, you're welcome to |
| contribute! Invariably, when working with code, things go |
| wrong, and it's necessary to do some debugging. In a server |
| environment like Apache, it can be a bit more difficult to |
| find the right way to do this. Here are some techniques to |
| try. |
| </p><p style="width:90%"> |
| The first thing you should know is that Apache can be launched |
| as a <span class="emphasis"><em>single process</em></span> with the |
| -X argument:</p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">httpd -X</pre>. |
| <p style="width:90%"> |
| On Linux, one of the first things to try is the system call |
| tracer, <span style="font-family:monospace"><span class="command"><strong>strace</strong></span></span>. You don't even have to |
| recompile Rivet or Apache for this to work. |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting">strace -o /tmp/outputfile -S 1000 httpd -X</pre><p style="width:90%">This command will run httpd in the system call tracer, |
| which leaves its output (there is potentially a lot of it) in |
| <code class="filename">/tmp/outputfile</code>. The -S |
| option tells <span style="font-family:monospace"><span class="command"><strong></strong></span></span>strace to only record the |
| first 1000 bytes of a syscall. Some calls such as |
| <code class="function">write</code> can potentially be much longer than |
| this, so you may want to increase this number. The results |
| are a list of all the system calls made by the program. You |
| want to look at the end, where the failure presumably occured, |
| to see if you can find anything that looks like an error. If |
| you're not sure what to make of the results, you can always |
| ask on the Rivet development mailing list. |
| </p><p style="width:90%"> |
| If <span style="font-family:monospace"><span class="command"><strong>strace</strong></span></span> (or its equivalent on your |
| operating system) doesn't answer your question, it may be time |
| to debug Apache and Rivet. To do this, you will need to run |
| the <span style="font-family:monospace"><span class="command"><strong>./configure.tcl</strong></span></span> script with the |
| -enable-symbols option, and recompile. |
| </p><p style="width:90%"> |
| Since it's easier to debug a single process, we'll still run |
| Apache in single process mode with -X: |
| </p><pre style="background:#ccc; margin: 2ex; margin-right: 10%; padding: 1ex; border: dashed black 1px ; white-space: pre; font-family: monospace; font-size: 90%;" class="programlisting"> |
| @ashland [~] $ gdb /usr/sbin/apache.dbg |
| GNU gdb 5.3-debian |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, covered by the GNU General Public License, and you are |
| welcome to change it and/or distribute copies of it under certain conditions. |
| Type "show copying" to see the conditions. |
| There is absolutely no warranty for GDB. Type "show warranty" for details. |
| This GDB was configured as "powerpc-linux"... |
| (gdb) run -X |
| Starting program: /usr/sbin/apache.dbg -X |
| [New Thread 16384 (LWP 13598)] |
| . |
| . |
| . |
| </pre><p style="width:90%"> |
| When your apache session is up and running, you can request a |
| web page with the browser, and see where things go wrong (if |
| you are dealing with a crash, for instance). |
| </p></div></div><div class="section" title="Upgrading from mod_dtcl or NeoWebScript"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="upgrading"></a>Upgrading from mod_dtcl or NeoWebScript</h2></div></div></div><p style="width:90%"> |
| Rivet is a break from the past, in that we, the authors, have |
| attempted to take what we like best about our past efforts, and |
| leave out or change things we no longer care for. Backwards |
| compatibility was not a primary goal when creating Rivet, but we |
| do provide this information which may be of use to those wishing |
| to upgrade from mod_dtcl or NWS installations. |
| </p><div class="section" title="mod_dtcl"><div class="titlepage"><div><div><h3 class="title"><a name="id390476"></a>mod_dtcl</h3></div></div></div><p style="width:90%"> |
| Rivet was originally based on the dtcl code, but it has |
| changed (improved!) quite a bit. The concepts remain the |
| same, but many of the commands have changed. |
| </p></div><div class="section" title="NeoWebScript"><div class="titlepage"><div><div><h3 class="title"><a name="id390487"></a>NeoWebScript</h3></div></div></div><p style="width:90%">TODO</p></div></div></div></body></html> |
