<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Apache Rivet 3.0</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 3.0"><link rel="next" href="installation.html" title="Apache Rivet 3.0 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 3.0</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 3.0</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 version 3.0</a></span></dt><dt><span class="section"><a href="installation.html">Apache Rivet 3.0 Installation</a></span></dt><dt><span class="section"><a href="cmake.html">Building Rivet 3.0 with CMake</a></span></dt><dd><dl><dt><span class="section"><a href="cmake.html#idm185">CMake build procedure and examples</a></span></dt></dl></dd><dt><span class="section"><a href="directives.html">Apache Rivet 3.0 Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="directives.html#idm200">Apache Rivet Configuration lines</a></span></dt><dt><span class="section"><a href="directives.html#idm212">Configuration Directives</a></span></dt></dl></dd><dt><span class="section"><a href="processing.html">Apache Rivet HTTP Request Processing</a></span></dt><dd><dl><dt><span class="section"><a href="processing.html#idm574">Tcl Scripts Processing</a></span></dt><dt><span class="section"><a href="processing.html#idm583">Example: basic OO Rivet Application</a></span></dt></dl></dd><dt><span class="section"><a href="request.html">Apache Child Processes Lifecycle and Request Processing</a></span></dt><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#idm719"></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> </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_script.html">url_script</a></span><span class="refpurpose"> — get the code of the URL referenced Tcl script or Rivet template</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#idm3234">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#idm3243">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#idm3253">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#idm3265">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#idm3311">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#idm3389">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#idm3445">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#idm3451">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#idm3915">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="entities.html">RivetEntities</a></span></dt><dd><dl><dt><span class="section"><a href="entities.html#idm4121">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="asciiglyphs.html">AsciiGlyphs</a></span></dt><dd><dl><dt><span class="section"><a href="asciiglyphs.html#idm4161">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#idm4177">Example</a></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#idm4182">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#idm4310">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#idm4317">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#idm4337">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#idm4341">IRC</a></span></dt><dt><span class="section"><a href="help.html#idm4344">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#idm4356">Rivet approach to Apache Multiprocessing Models</a></span></dt><dt><span class="section"><a href="internals.html#idm4369">mod_rivet MPM Bridge callbacks</a></span></dt><dt><span class="section"><a href="internals.html#idm4403">Server Initialization and MPM Bridge</a></span></dt><dt><span class="section"><a href="internals.html#idm4406">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#idm4411">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#idm4419">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#idm4427">Extending Rivet by developing C code procedures</a></span></dt><dt><span class="section"><a href="internals.html#idm4451">Debugging Rivet and Apache</a></span></dt></dl></dd><dt><span class="section"><a href="lazybridge.html">Example: the <span class="quote">“<span class="quote">Lazy</span>”</span> bridge</a></span></dt><dd><dl><dt><span class="section"><a href="lazybridge.html#idm4481">The rationale of threaded bridges</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4485">Lazy bridge data structures</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4500">Handling Tcl's exit core command</a></span></dt><dt><span class="section"><a href="lazybridge.html#idm4519">HTTP request processing with the lazy bridge</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#idm1925">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#calendar_example">A Calendar Utility</a></dt></dl></div><p style="width:90%">
    	Document revision: $Revision: 1821687 $, last modified 2018-01-20 11:56:35+01:00$ by $Author: mxmanghi $.
  	</p><div class="section"><div class="titlepage"><div><div><hr><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction to Apache Rivet version 3.0</h2></div></div></div><p style="width:90%">
      Apache Rivet is a system for creating dynamic web content by
      integrating the 
		<a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl programming language</a> within the 
      <a class="ulink" href="http://httpd.apache.org" target="_top">Apache Web Server</a>.
      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).
    </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="idm21"></a>Apache MPM and Rivet Bridge Modules</h3></div></div></div><p style="width:90%">
	        	Rivet 3.0 is a major rewriting of mod_rivet, the Apache HTTP
	        	Websever module at the core of Rivet. Unlike in previous versions of 
	        	mod_rivet which only supported the <a class="ulink" href="" target="_top">prefork MPM</a>
	        	(<a class="ulink" href="" target="_top">Multiprocessing Module</a>), 
	        	starting with 3.0 we attained full support of different MPM for
	        	the Apache framework.
        </p><p style="width:90%">
        		Threaded <a class="ulink" href="" target="_top">MPM</a>
        		integration was achieved by making mod_rivet multithreaded and
        		modular itself, introducing the MPM-module bridge concept.
        		We developed a set of loadable modules 
        		which are supposed not only to overcome the issues related to threading but also
        		to offer the best possible MPM mod_rivet integration.
        		As a side effect of this modular design mod_rivet is not only able to integrate
        		with its environment but also to work as a framework for writing more MPM bridges
        		designed along different multi-threading schemes and workload management models. 
        		See the <a class="link" href="internals.html" title="Rivet Internals">internals</a> section of this manual for
        		further reading. MPM bridges are loaded accordingly to a heuristics of rules based
        		on the Apache introspection calls but they can be determined in the configuration. 
        		Only a bridge can be loaded at a time.
        </p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm29"></a>Request Processing</h3></div></div></div><p style="width:90%">
    			Request processing was performed in mod_rivet version 2.x by chaining together 3 scripts
    	</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">BeforeScript, if defined in the configuration</li><li class="listitem">The URI referenced Tcl script or rvt template dermined with
 				respect to the <a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/core.html#documentroot" target="_top">DocumentRoot</a> and following 
 				other resource determination methods such the ones offered by 
 				<a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/mod_alias.html" target="_top">mod_alias</a> and by
 				<a class="ulink" href="https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html" target="_top">mod_rewrite</a>.
 			</li><li class="listitem">AfterScript, if defined in the configuration</li></ul></div><p style="width:90%">
			Errors and exceptions (raised by the <a class="link" href="abort_page.html" title="abort_page">::rivet::abort_page</a> command)
			are handled by the ErrorScript and AbortScript (ErrorScript has a default implementation
			if undefined in the configuration)
		</p><p style="width:90%">
			Rivet 3.0 implements a new <a class="link" href="request.html" title="Apache Child Processes Lifecycle and Request Processing">request processing scheme</a> 
			entirely based on Tcl. By default rivet 3.0 provides compatiblity with the 
			version 2.x scheme to handle a request but this can be entirely overridden by
			the developer replacing the central request handling procedure. See the 
			<a class="link" href="request.html" title="Apache Child Processes Lifecycle and Request Processing">request processing</a> page for further reading 
		</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a name="idm44"></a>Acknowledgements</h3></div></div></div><p style="width:90%">This version of Rivet received substantial contributions from George Petasis who solved
    	several problems with the threaded code, improved the code in several ways and made the CMake
    	based build scripts</p></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 3.0 Installation</td></tr></table></div></body></html>