You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-cvs@tcl.apache.org by mx...@apache.org on 2009/06/24 14:47:45 UTC
svn commit: r788000 [3/6] - in /tcl/site/rivet/manual: ./ images/
Added: tcl/site/rivet/manual/examples.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/examples.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/examples.html (added)
+++ tcl/site/rivet/manual/examples.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,467 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Examples and Usage</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="unescape_string.html" title="unescape_string"><link rel="next" href="tcl_packages.html" title="Rivet Tcl Packages"></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">Examples and Usage</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="unescape_string.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="tcl_packages.html"><img src="images/next.png" alt="Next"></a
></td></tr></table></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="help.html#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="id500984"></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 JavaScript (and other scriping languages like VBScript) to
+ manipulate dynamically the HTML structure of a page. In modern browsers
+ JavaScript code is enabled to send GET or POST requests to the webserver.
+ These requests can request the server to run scripts (for example Rivet
+ Tcl scripts) that build responses and to be sent back to the browser.
+ JavaScript code reads asynchronously these responses, elaborates
+ their content and accordingly modifies the page on display.
+ Ajax helps to build web applications that are more responsive and
+ flexible, if you can cope with the complexities, subtleties and
+ incompatibilities even among the most common browsers available.
+ Instead of going through the cycle of request-generation-transfer
+ of a page, Ajax allows the programmer to request and transmit only
+ the essential data thus matching the general requirement of separation
+ between data and user interface (and saving the server from sending over
+ the same html code and graphics when only a fraction of a page has
+ to be refreshed)
+ </p><p style="width:90%">
+ In Ajax applications the communication between client and server
+ is controlled by an instance of a specialized object: the non-IE world
+ (Firefox,Safari,Opera...) uses the XMLHttpRequest class to create it,
+ whereas IE uses the ActiveXObject class.
+ </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">
+ With the release of IE7 Microsoft introduced native support for
+ <a class="ulink" href="http://blogs.msdn.com/ie/archive/2006/01/23/516393.aspx" target="_top">
+ XMLHttpRequest</a> class objects
+ </td></tr></table></div><p style="width:90%">
+ By creating an instance of this class a POST or GET request can be sent
+ to the server, whose response is stored in a
+ property ('returnedText') of the communication object.
+ It's become widely customary to encode in XML messages the response
+ from the server to the browser. A number of XML specification are
+ being used for this, among which XML-RPC and SOAP are worth to be
+ quoted. Anyway, you can invent your own message definitions
+ (either based on XML or anything else), but one has to be aware of
+ the fact that if the http headers are properly set and the message
+ returned to the client is a well formed XML fragment, also the property
+ <a class="ulink" href="http://www.w3schools.com/ajax/ajax_responsexml.asp" target="_top">
+ XMLResponse</a> is set with a reference to an object
+ that represent the
+ <a class="ulink" href="http://www.w3schools.com/dom/default.asp" target="_top">
+ DOM</a> of the XML response.
+ By means of the XML W3C DOM tree methods and properties
+ you can write scripts that read and manipulate the data embedded in
+ the XML message.
+ </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
+ which, in a real case, has is a real DBM which stores large
+ tables with thousands records and more complex and
+ extended information.
+ The script is designed to send back to the client two
+ types of responses: a catalog of the composers or a single
+ record of a composer.
+ </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"># The database array contains xml fragments representing the
+# results of queries to a database. Many databases are now able
+# to produce the results of a query in XML.
+#
+#array unset composer
+#
+set composer(1) "<composer>\n"
+append composer(1) " <first_name>Claudio</first_name>\n"
+append composer(1) " <last_name>Monteverdi</last_name>\n"
+append composer(1) " <lifespan>1567-1643</lifespan>\n"
+append composer(1) " <era>Renaissance/Baroque</era>\n"
+append composer(1) " <key>1</key>\n"
+append composer(1) "</composer>\n"
+
+set composer(2) "<composer>\n"
+append composer(2) " <first_name>Johann Sebastian</first_name>\n"
+append composer(2) " <last_name>Bach</last_name>\n"
+append composer(2) " <lifespan>1685-1750</lifespan>\n"
+append composer(2) " <era>Baroque</era>\n"
+append composer(2) " <key>2</key>\n"
+append composer(2) "</composer>\n"
+
+set composer(3) "<composer>\n"
+append composer(3) " <first_name>Ludwig</first_name>\n"
+append composer(3) " <last_name>van Beethoven</last_name>\n"
+append composer(3) " <lifespan>1770-1827</lifespan>\n"
+append composer(3) " <era>Romantic</era>\n"
+append composer(3) " <key>3</key>\n"
+append composer(3) "</composer>\n"
+
+set composer(4) "<composer>\n"
+append composer(4) " <first_name>Wolfgang Amadaeus</first_name>\n"
+append composer(4) " <last_name>Mozart</last_name>\n"
+append composer(4) " <lifespan>1756-1791</lifespan>\n"
+append composer(4) " <era>Classical</era>\n"
+append composer(4) " <key>4</key>\n"
+append composer(4) "</composer>\n"
+
+set composer(5) "<composer>\n"
+append composer(5) " <first_name>Robert</first_name>\n"
+append composer(5) " <last_name>Schumann</last_name>\n"
+append composer(5) " <lifespan>1810-1856</lifespan>\n"
+append composer(5) " <era>Romantic</era>\n"
+append composer(5) " <key>5</key>\n"
+append composer(5) "</composer>\n"
+
+# 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 [array names composer] {
+ if {[regexp {<last_name>(.+)</last_name>} $composer($nm) m last_name] && \
+ [regexp {<first_name>(.+)</first_name>} $composer($nm) m first_name]} {
+ append xml " <composer key='$nm'>$first_name $last_name</composer>\n"
+ }
+ }
+ append xml "</catalog>"
+ }
+ composer {
+ if {[var exists rec_id]} {
+ set rec_id [var get rec_id]
+ if {[info exists composer($rec_id)]} {
+ append xml $composer($rec_id)
+ }
+ }
+ }
+ }
+
+# 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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unescape_string.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="tcl_packages.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">unescape_string </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Rivet Tcl Packages</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/headers.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/headers.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/headers.html (added)
+++ tcl/site/rivet/manual/headers.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,25 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>headers</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="parse.html" title="parse"><link rel="next" href="makeurl.html" title="makeurl"></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">headers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="parse.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right"> <a accesskey="n" href="makeurl.html"><img src="images/next.png" alt="Next"></a></td></tr></table><
/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="id497511"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parse.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="makeurl.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">parse </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> makeurl</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/help.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/help.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/help.html (added)
+++ tcl/site/rivet/manual/help.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,48 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Resources - How to Get Help</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="session_package.html" title="Session Package"><link rel="next" href="internals.html" title="Rivet Internals"></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">Resources - How to Get Help</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="session_package.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="internals.html"><img src="images/next.png" alt="
Next"></a></td></tr></table></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="id514657"></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="id514998"></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="id515077"></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="id515093"></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="id515104"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="session_package.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="internals.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Session Package </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Rivet Internals</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/html.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/html.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/html.html (added)
+++ tcl/site/rivet/manual/html.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,6 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>html</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="clock_to_rfc.html" title="clock_to_rfc850_gmt"><link rel="next" href="incr0.html" title="incr0"></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">html</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="clock_to_rfc.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right"> <a accesskey="n" href="incr0.html"><img src="images/next.png" alt="Next"></a></t
d></tr></table></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="id498050"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="clock_to_rfc.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="incr0.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">clock_to_rfc850_gmt </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> incr0</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/images/blank.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/blank.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/blank.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/caution.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/caution.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/caution.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/draft.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/draft.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/draft.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/home.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/home.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/home.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/important.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/important.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/important.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/next.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/next.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/next.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/note.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/note.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/note.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/prev.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/prev.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/prev.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/tip.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/tip.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/tip.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/toc-blank.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/toc-blank.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/toc-blank.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/toc-minus.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/toc-minus.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/toc-minus.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/toc-plus.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/toc-plus.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/toc-plus.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/up.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/up.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/up.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/images/warning.png
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/images/warning.png?rev=788000&view=auto
==============================================================================
Binary file - no diff available.
Propchange: tcl/site/rivet/manual/images/warning.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tcl/site/rivet/manual/include.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/include.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/include.html (added)
+++ tcl/site/rivet/manual/include.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,5 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>include</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="env.html" title="env"><link rel="next" href="parse.html" title="parse"></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">include</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="env.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right"> <a accesskey="n" href="parse.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div cl
ass="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="id497372"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="env.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="parse.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">env </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> parse</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/incr0.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/incr0.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/incr0.html (added)
+++ tcl/site/rivet/manual/incr0.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,7 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>incr0</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="commands.html" title="Rivet Tcl Commands and Variables"><link rel="prev" href="html.html" title="html"><link rel="next" href="parray.html" title="parray"></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">incr0</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="html.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Rivet Tcl Commands and Variables</th><td width="20%" align="right"> <a accesskey="n" href="parray.html"><img src="images/next.png" alt="Next"></a></td></tr></table></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="id498116"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="html.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="commands.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="parray.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">html </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> parray</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/index.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/index.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/index.html (added)
+++ tcl/site/rivet/manual/index.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,28 @@
+<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.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" title="Apache Rivet"><div class="titlepage"><div><div><h2 class="title"><a name="id467156"></a>Apache Rivet</h2></div><div><div class="author"><h3 class="author"><span c
lass="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 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="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="directives.html">Rivet Apache Directives</a></span></dt><dt><span class="section"><a href="commands.html">Rivet Tcl Commands and Variables</a></span></dt><dd><dl><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="upload.html">upload</a></span><span class="refpurpose"> — handle a file uploaded by a client.</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="load_headers.html">load_headers</a></span><span class="refpurpose"> — get client request's headers.</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="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="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="parse.html">parse</a></span><span class="refpurpose"> — parses a Rivet template file.</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="makeurl.html">makeurl</a></span><span class="refpurpose"> — construct url's based on hostname, port.</span></dt><dt><span class="refentrytitle"><a href="cookie.html">cookie</a></span><span class="refpurpose"> — get and set cookies.</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="html.html">html</a></span><span class="refpurpose"> — construct html tagged text.</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 nonexistant.</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="abort_page.html">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.html">no_body</a></span><span class="refpurpose"> — Prevents Rivet from sending any content.</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="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="unescape_string.html">unescape_string</a></span><span class="refpurpose"> — unescape escaped characters in a st
ring.</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#id512930">Introduction</a></span></dt><dt><span class="section"><a hre
f="session_package.html#requirements">Requirements</a></span></dt><dt><span class="section"><a href="session_package.html#id513285">Preparing To Use It</a></span></dt><dt><span class="section"><a href="session_package.html#id513331">Example Usage</a></span></dt><dt><span class="section"><a href="session_package.html#id513387">Using Sessions From Your Code</a></span></dt><dt><span class="section"><a href="session_package.html#id513584">Session Configuration Options</a></span></dt><dt><span class="section"><a href="session_package.html#id513818">Session Methods</a></span></dt><dt><span class="section"><a href="session_package.html#id514044">Getting Additional Randomness From The Entropy File</a></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#id514657">Mailing Lists</a></span></dt><dt><span class="section"><a href="help.html#id514998">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#id515077">Bug Tracking System</a></span></dt><dt><span class="section"><a href="help.html#id515093">IRC</a></span></dt><dt><span class="section"><a href="help.html#id515104">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#id514828">Initialization</a></span></dt><dt><span class="section"><a href="internals.html#id514892">RivetChan</a></span></dt><dt><span class="section"><a href="internals.html#id515432">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#id515477">Page Parsing, Execution and Caching</a></span></dt><dt><span class="section"><a href="internals.html#id515518">Debugging Rivet and A
pache</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#id515646">mod_dtcl</a></span></dt><dt><span class="section"><a href="upgrading.html#id515657">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%20world">Hello World</a></dt><dt>2. <a href="examples.html#id500984">Generate a 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></dl></div><p style="width:90%">
+ Document revision: $Revision: 787687 $, last modified 2009-06-23 17:34:58+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><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>
Added: tcl/site/rivet/manual/installation.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/installation.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/installation.html (added)
+++ tcl/site/rivet/manual/installation.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,97 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Rivet Installation</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="index.html" title="Apache Rivet"><link rel="next" href="directives.html" title="Rivet Apache Directives"></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 Installation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="directives.html"><img src="images/next.png" alt="Next"></a></td></
tr></table></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 and
+ Apache 1.3.xx. It is known to run on Linux, FreeBSD,
+ OpenBSD, and Solaris and HPUX. Windows NT is also possible
+ - please see the directions in the distribution. Note that
+ Rivet does not currently work with Apache 2.
+ </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 where Tcl is via
+ the -with-tclconfig option to
+ <span style="font-family:monospace"><span class="command"><strong>configure.tcl</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.tcl</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 tcl-rivet-X.X.X.tar.gz
+tar -xvf tcl-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
+ ./configure ; make ; make install technique.
+ </p><p style="width:90%">
+ There are several options to configure that might be useful
+ or necessary:
+ </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 of Apache modules.</div></div></dd></dl></div><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">cd src/
+./configure --with-tcl=/usr/lib/tcl8.4/ --with-tclsh=/usr/bin/tclsh8.4 \
+ --with-apxs=/usr/bin/apxs
+</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/apache/1.3/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 if you want to change the default charset for the whole site or directory hierarchy
+ a new charset can be embedded in a AddType line in a way similar to the html pages encoding.
+ </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%">
+ Pages which this configuration applies to send back to the client
+ 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.html" title="Rivet Apache Directives">the section called “Rivet Apache Directives”</a>.
+ </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="directives.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Apache Rivet </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Rivet Apache Directives</td></tr></table></div></body></html>
Added: tcl/site/rivet/manual/internals.html
URL: http://svn.apache.org/viewvc/tcl/site/rivet/manual/internals.html?rev=788000&view=auto
==============================================================================
--- tcl/site/rivet/manual/internals.html (added)
+++ tcl/site/rivet/manual/internals.html Wed Jun 24 12:47:44 2009
@@ -0,0 +1,125 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Rivet Internals</title><link rel="stylesheet" href="rivet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Apache Rivet"><link rel="up" href="index.html" title="Apache Rivet"><link rel="prev" href="help.html" title="Resources - How to Get Help"><link rel="next" href="upgrading.html" title="Upgrading from mod_dtcl or NeoWebScript"></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">Rivet Internals</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="help.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="upgrading.html"><img src="images/next.png" alt="Next"></a>
</td></tr></table></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="id514828"></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="id514892"></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="id515432"></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="id515477"></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="id515518"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="help.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="upgrading.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Resources - How to Get Help </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Upgrading from mod_dtcl or NeoWebScript</td></tr></table></div></body></html>
---------------------------------------------------------------------
To unsubscribe, e-mail: site-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: site-cvs-help@tcl.apache.org