<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Apache Rivet</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="next" href="installation.html" title="Apache Rivet Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Apache Rivet</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="idm1"></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">&lt;<a class="email" href="mailto:rivet-dev@tcl.apache.org">rivet-dev@tcl.apache.org</a>&gt;</code><br>
	        </p></div></div></div></div><div><p class="copyright">Copyright © 2002-2018 Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="index.html#introduction">Introduction to Apache Rivet</a></span></dt><dt><span class="section"><a href="installation.html">Apache Rivet Installation</a></span></dt><dt><span class="section"><a href="request.html">Apache Child Processes Lifecycle and Request Processing</a></span></dt><dt><span class="section"><a href="directives.html">Rivet Apache Directives</a></span></dt><dd><dl><dt><span class="section"><a href="directives.html#idm269"></a></span></dt><dt><span class="section"><a href="directives.html#idm274"></a></span></dt></dl></dd><dt><span class="section"><a href="commands.html">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><dt><span class="section"><a href="commands.html#idm512"></a></span></dt><dt><span class="refentrytitle"><a href="shorthand.html">&lt;?= ... ?&gt;</a></span><span class="refpurpose"> — 
				Shorthand construct for single strings output
			</span></dt><dt><span class="refentrytitle"><a href="abort_code.html">abort_code</a></span><span class="refpurpose"> — 
				Returns the code passed to <span style="font-family:monospace"><span class="command"><strong>abort_page</strong></span></span>
				earlier during the request processing
			</span></dt><dt><span class="refentrytitle"><a href="abort_page.html">abort_page</a></span><span class="refpurpose"> — 
		    Stops outputting 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="apache_log_error.html">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.html">apache_table</a></span><span class="refpurpose"> — access and manipulate Apache tables in the request structure.</span></dt><dt><span class="refentrytitle"><a href="catch.html">catch</a></span><span class="refpurpose"> — wraps core command <span style="font-family:monospace"><span class="command"><strong>catch</strong></span></span> and handles in
			a special way fake error conditions resulting from calls to <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span>
			and <span style="font-family:monospace"><span class="command"><strong>abort_page</strong></span></span></span></dt><dt><span class="refentrytitle"><a href="clock_to_rfc.html">clock_to_rfc850_gmt</a></span><span class="refpurpose"> — create a rfc850 time from [clock seconds].</span></dt><dt><span class="refentrytitle"><a href="cookie.html">cookie</a></span><span class="refpurpose"> — get, set and delete cookies.</span></dt><dt><span class="refentrytitle"><a href="debug.html">debug</a></span><span class="refpurpose"> — 
		    A command to print strings, arrays
		    and the values of variables as specified by the arguments.
		</span></dt><dt><span class="refentrytitle"><a href="env.html">env</a></span><span class="refpurpose"> — 
		    Loads a single "environmental variable" into a Tcl variable.
		</span></dt><dt><span class="refentrytitle"><a href="escape_sgml_chars.html">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.html">escape_shell_command</a></span><span class="refpurpose"> — escape shell metacharacters in a string.</span></dt><dt><span class="refentrytitle"><a href="escape_string.html">escape_string</a></span><span class="refpurpose"> — convert a string into escaped characters.</span></dt><dt><span class="refentrytitle"><a href="exit.html">exit</a></span><span class="refpurpose"> — terminate execution and child process</span></dt><dt><span class="refentrytitle"><a href="headers.html">headers</a></span><span class="refpurpose"> — set and parse HTTP headers.</span></dt><dt><span class="refentrytitle"><a href="html.html">html</a></span><span class="refpurpose"> — construct html tagged text.</span></dt><dt><span class="refentrytitle"><a href="http_accept.html">http_accept</a></span><span class="refpurpose"> — Parse HTTP Accept header lines</span></dt><dt><span class="refentrytitle"><a href="import_keyvalue_pairs.html">import_keyvalue_pairs</a></span><span class="refpurpose"> — Import an argument list into the named array</span></dt><dt><span class="refentrytitle"><a href="include.html">include</a></span><span class="refpurpose"> — includes a file into the output stream without modification.</span></dt><dt><span class="refentrytitle"><a href="incr0.html">incr0</a></span><span class="refpurpose"> — increment a variable or set it to 1 if nonexistent.</span></dt><dt><span class="refentrytitle"><a href="inspect.html">inspect</a></span><span class="refpurpose"> — Introspection command for Rivet configuration</span></dt><dt><span class="refentrytitle"><a href="lassign_array.html">lassign_array</a></span><span class="refpurpose"> — Assign a list of values to array variables</span></dt><dt><span class="refentrytitle"><a href="lempty.html">lempty</a></span><span class="refpurpose"> — 
		    Returns 1 if &lt;list&gt; is empty or 0 if it has any elements.  
		    This command emulates the TclX lempty command.
		</span></dt><dt><span class="refentrytitle"><a href="lmatch.html">lmatch</a></span><span class="refpurpose"> — 
		    Look for elements in &lt;list&gt; that match &lt;pattern&gt;
		</span></dt><dt><span class="refentrytitle"><a href="load_cookies.html">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.html">load_env</a></span><span class="refpurpose"> — get the request's environment variables.</span></dt><dt><span class="refentrytitle"><a href="load_headers.html">load_headers</a></span><span class="refpurpose"> — get client request's headers.</span></dt><dt><span class="refentrytitle"><a href="load_response.html">load_response</a></span><span class="refpurpose"> — load form variables into an array.</span></dt><dt><span class="refentrytitle"><a href="lremove.html">lremove</a></span><span class="refpurpose"> — remove from a list elements matching one or more patterns</span></dt><dt><span class="refentrytitle"><a href="makeurl.html">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="no_body.html">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</span></dt><dt><span class="refentrytitle"><a href="parray.html">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="parse.html">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</span></dt><dt><span class="refentrytitle"><a href="raw_post.html">raw_post</a></span><span class="refpurpose"> — get the unmodified body of a POST request sent by the client.</span></dt><dt><span class="refentrytitle"><a href="redirect.html">redirect</a></span><span class="refpurpose"> — Interrupt processing and divert to a new URL</span></dt><dt><span class="refentrytitle"><a href="read_file.html">read_file</a></span><span class="refpurpose"> — 
		    Read the entire contents of a file and return it as a string.			
		</span></dt><dt><span class="refentrytitle"><a href="try.html">try</a></span><span class="refpurpose"> — 
				Catch error and exception conditions
			</span></dt><dt><span class="refentrytitle"><a href="unescape_string.html">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a string.</span></dt><dt><span class="refentrytitle"><a href="upload.html">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</span></dt><dt><span class="refentrytitle"><a href="url_query.html">url_query</a></span><span class="refpurpose"> — builds a URL query from parameter-value pairs</span></dt><dt><span class="refentrytitle"><a href="var.html">var</a></span><span class="refpurpose"> — get the value of a form variable.</span></dt><dt><span class="refentrytitle"><a href="wrap.html">wrap</a></span><span class="refpurpose"> — 
		    Split a string on newlines. 
		</span></dt><dt><span class="refentrytitle"><a href="wrapline.html">wrapline</a></span><span class="refpurpose"> — 
		    Split the line into multiple lines by splitting on space characters 
		</span></dt><dt><span class="refentrytitle"><a href="xml.html">xml</a></span><span class="refpurpose"> — 
                XML Fragments creation
            </span></dt></dl></dd><dt><span class="section"><a href="examples.html">Examples and Usage</a></span></dt><dt><span class="section"><a href="tcl_packages.html">Rivet Tcl Packages</a></span></dt><dt><span class="section"><a href="dio.html">DIO - Database Interface Objects</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="dio_package.html">DIO</a></span><span class="refpurpose"> — Database Interface Objects</span></dt></dl></dd><dt><span class="section"><a href="diodisplay.html">DIODisplay - Database Interface Objects Display Class</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="diodisplay_package.html">DIODisplay</a></span><span class="refpurpose"> — Database Interface Objects Display Class</span></dt></dl></dd><dt><span class="section"><a href="session_package.html">Session Package</a></span></dt><dd><dl><dt><span class="section"><a href="session_package.html#idm3032">Introduction</a></span></dt><dt><span class="section"><a href="session_package.html#requirements">Requirements</a></span></dt><dt><span class="section"><a href="session_package.html#idm3041">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#idm3051">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#idm3063">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#idm3109">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#idm3187">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#idm3243">Getting Additional Randomness From The Entropy File</a></span></dt></dl></dd><dt><span class="section"><a href="form.html">Form: An HTML Form Fields Generation Utility</a></span></dt><dd><dl><dt><span class="section"><a href="form.html#idm3249">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="form_package.html">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.html">Calendar Package</a></span></dt><dd><dl><dt><span class="section"><a href="calendar_package.html#idm3713">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="calendar.html">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.html">XmlCalendar</a></span><span class="refpurpose"> — Prints XML formatted calendar tables</span></dt><dt><span class="refentrytitle"><a href="html_calendar.html">HtmlCalendar</a></span><span class="refpurpose"> — Concrete class derived from XmlCalendar</span></dt></dl></dd><dt><span class="section"><a href="asciiglyphs.html">AsciiGlyphs</a></span></dt><dd><dl><dt><span class="section"><a href="asciiglyphs.html#idm3919">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="toglyphs.html">toGlyphs</a></span><span class="refpurpose"> — 
	            	print large ASCII glyphs
	            </span></dt><dt><span class="section"><a href="asciiglyphs.html#idm3935">Example</a></span></dt></dl></dd><dt><span class="section"><a href="entities.html">RivetEntities</a></span></dt><dd><dl><dt><span class="section"><a href="entities.html#idm3940">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="encode.html">encode</a></span><span class="refpurpose"> — 
                encode a string replacing every occurrence of characters for 
                which an SGML entity exists
            </span></dt><dt><span class="refentrytitle"><a href="decode.html">decode</a></span><span class="refpurpose"> — 
                decode an SGML encoded string replacing every entity with the
                corresponding character
            </span></dt></dl></dd><dt><span class="section"><a href="formbroker.html">The Form Broker</a></span></dt><dd><dl><dt><span class="section"><a href="formbroker.html#idm3980">Introduction</a></span></dt><dt><span class="refentrytitle"><a href="fb.html">FormBroker</a></span><span class="refpurpose"> — 
               Form broker object creator
            </span></dt></dl></dd><dt><span class="section"><a href="help.html">Resources - How to Get Help</a></span></dt><dd><dl><dt><span class="section"><a href="help.html#idm4108">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#idm4115">Newsgroup</a></span></dt><dt><span class="section"><a href="help.html#websites">Web Sites</a></span></dt><dt><span class="section"><a href="help.html#idm4135">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#idm4139">IRC</a></span></dt><dt><span class="section"><a href="help.html#idm4142">Editing Rivet Template Files</a></span></dt></dl></dd><dt><span class="section"><a href="internals.html">Rivet Internals</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#idm4154">Initialization</a></span></dt><dt><span class="section"><a href="internals.html#idm4161">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#idm4166">The <span style="font-family:monospace"><span class="command"><strong>global</strong></span></span> Command</a></span></dt><dt><span class="section"><a href="internals.html#idm4174">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#idm4182">Extending Rivet by developing C procedures implementing new commands</a></span></dt><dt><span class="section"><a href="internals.html#idm4208">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="upgrading.html">Upgrading from mod_dtcl or NeoWebScript</a></span></dt><dd><dl><dt><span class="section"><a href="upgrading.html#idm4238">mod_dtcl</a></span></dt><dt><span class="section"><a href="upgrading.html#idm4241">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="examples.html#hello_world">Hello World</a></dt><dt>2. <a href="examples.html#idm1719">Generate a Colorful Table</a></dt><dt>3. <a href="examples.html#variable_access">Variable Access</a></dt><dt>4. <a href="examples.html#file_upload">File Upload</a></dt><dt>5. <a href="examples.html#file_download">File Download</a></dt><dt>6. <a href="examples.html#ajax_xml_messaging">XML Messages and Ajax</a></dt><dt>7. <a href="examples.html#calexample">A Calendar Utility</a></dt></dl></div><p style="width:90%">
    Document released as part of Rivet 2.4.0 (2018-11-24 11:03:21+01:00).
  </p><div class="section"><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 focused on the current version of Rivet, but
     still 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 class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm19"></a>New commands in Rivet 2.4</h3></div></div></div><p style="width:90%">
        		Rivet 2.4 introduces 2 new commands <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span>
        		and <span style="font-family:monospace"><span class="command"><strong>::rivet::catch</strong></span></span>
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> was introduced to help mod_rivet to
    				give the command <span style="font-family:monospace"><span class="command"><strong>exit</strong></span></span> a more sensible behavior within
    				the context of the Apache HTTP Web Server. In fact the core command has
    				become an alias of <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span> which interrupts the 
    				script execution and hands control to any <span style="font-family:monospace"><span class="command"><strong>AbortScript</strong></span></span>, 
    				completes the request and just before returning to the web server framework terminates 
    				the child process by calling <span style="font-family:monospace"><span class="command"><strong>Tcl_Exit</strong></span></span></li><li class="listitem">
         		Since <span style="font-family:monospace"><span class="command"><strong>::rivet::abort_page</strong></span></span> and <span style="font-family:monospace"><span class="command"><strong>::rivet::exit</strong></span></span>
         		interrupt a script execution returning a <span class="emphasis"><em>TCL_ERROR</em></span> code
         		any call to a <span style="font-family:monospace"><span class="command"><strong>catch</strong></span></span> construct would trap this error and AbortScript 
         		could be executed only by throwing the error condition again. We introduced the
         		<span style="font-family:monospace"><span class="command"><strong>::rivet::catch</strong></span></span> in order to simplify these operations.
         		If any real error occurs the procedure returns 
         		1 and fills the optional arguments with their expected values, otherwise
         		execution is interrupted control passed on to
         		<span style="font-family:monospace"><span class="command"><strong>AbortScript</strong></span></span></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="installation.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Apache Rivet Installation</td></tr></table></div></body></html>