websh/quickref/response_data

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Response data handling</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Websh Reference 3.6.0b5"><link rel="up" href="index.html" title="Websh Reference 3.6.0b5"><link rel="prev" href="request_data_handling.html" title="Request data handling"><link rel="next" href="logging.html" title="Logging"></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">Response data handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="request_data_handling.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="logging.html">Next</a></td></tr></table><hr></div><div class="section" title="Response data handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="response_data_handling"></a>Response data handling</h2></div></div></div><p style="width:90%"> Websh can send output to any Tcl channel and to global variables (<span style="font-family:monospace"><span class="command"><strong>web::put</strong></span></span>). Optionally, data is scanned for Tcl code before it is output to a channel (<span style="font-family:monospace"><span class="command"><strong>web::putx</strong></span></span>). Websh manages <span class="emphasis"><em>response objects</em></span> that are related to Tcl channels and are identified using the name of the corresponding Tcl channel. Configuration is achieved with <span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span>. </p><div class="section" title="web::response"><div class="titlepage"><div><div><h3 class="title"><a name="web::response"></a><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::response</code></span> </span></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::response</code></span> ?<em class="replaceable"><code>option</code></em>?</span></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::response</code></span> ?<em class="replaceable"><code>subcommand</code></em>? <em class="replaceable"><code>args</code></em></span></div><p style="width:90%"> Subcommands are <tt>-select</tt>, <tt>-set</tt>, <tt>-lappend</tt>, <tt>-names</tt>, <tt>-count</tt>, <tt>-unset</tt>, <tt>-reset</tt>, and <tt>-resetall</tt> Options are <tt>-sendheader</tt>, <tt>-httpresponse</tt>, and <tt>-bytessent</tt>.</p><p style="width:90%"> Selects the default response object and sets and accesses properties of the response object, and returns the name of the response object. </p><p style="width:90%"> </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the name of the currently selected response object. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-select</tt> ?<span class="optional"><tt>#</tt></span>?<em class="replaceable"><code>channelName</code></em> </span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Selects <tt><em class="replaceable"><code>channelName</code></em></tt> as new response object. If the <tt><em class="replaceable"><code>channelName</code></em></tt> is prepended by a <tt>#</tt>, it refers to a global variable named <tt><em class="replaceable"><code>channelName</code></em></tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-set</tt> <tt><em class="replaceable"><code>key</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets property <tt>key</tt> to <tt>value</tt>, or returns current value if <tt>value</tt> is omitted. The <tt>keys</tt> are names of HTTP header fields (do not include ':' at the end of the header field name) and <tt>value</tt> the corresponding value of the field (like Content-Type) and their values (like text/html).</div><div style="margin-bottom:6"> Example:</div><div style="margin-bottom:6"> <code class="literal"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> -set Content-Type text/plain</code>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-names</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the list of known keys. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-count</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns number of items in list of <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-unset</tt> ?<span class="optional"><tt><em class="replaceable"><code>key</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes the value of <tt>key</tt>, if <tt>key</tt> is given, or all keys. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-sendheader</tt> ?<span class="optional"><tt>boolean</tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the sendheader flag which indicates and controls whether the HTTP headers have been or should be sent. It is initially set to 1 and set to 0 after the first call of <span style="font-family:monospace"><span class="command"><strong>web::put</strong></span></span> or <span style="font-family:monospace"><span class="command"><strong>web::putx</strong></span></span>. If <tt>boolean</tt> is omitted, returns the current value. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-httpresponse</tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Sets or gets the HTTP response like "HTTP/1.0 200 OK" for the given (or default) channel. If no <tt>value</tt> given, returns the the current HTTP response set. In the case of the Apache module mod_websh, Apache replaces the protocol "HTTP/??" in the reponse with "HTTP/1.1". </div><div style="margin-bottom:6"> <span class="emphasis"><em>Note</em></span>: Depending on the CGI implementation of your web server, this does not always work. A working alternative for newer versions of Apache is to set a Status header in the response as follows: </div><div style="margin-bottom:6"> <code class="literal"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> -set Status "400 Bad Request"</code>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-bytessent</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the number of bytes that have already been sent to this channel. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-reset</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Resets the 'sendheader' flag for the channel to true, the HTTP response to the default "HTTP/?? 200 OK", removes any HTTP headers set, and resets the names of the query string parameters for the timestamp and the command to their default values ("t" and "cmd", respectively). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::response</strong></span></span> <tt>-resetall</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Performs a <span style="font-family:monospace"><span class="command"><strong>web::response -reset</strong></span></span> on all registered channels. </div></div></dd></dl></div><p style="width:90%"> </p><div class="example"><a name="id2737705"></a><p class="title"><b>Example�10.�<span style="font-family:monospace"><span class="command">web::response</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> % web::response stdout % web::response -select stderr stdout % web::response stderr % web::response -sendheader 1 % web::response -names Content-Type Generator % web::response Content-Type text/html % web::response -bytessent 0 % web::response -set Set-Cookie "my cookie that contains data" % web::put "Hello, world\n" Content-Type: text/html Set-Cookie: my cookie that contains data Generator: websh3.6.0 Hello, world % </pre></div></div><p style="width:90%"><br class="example-break"> </p></div><div class="section" title="web::put"><div class="titlepage"><div><div><h3 class="title"><a name="web::put"></a><span style="font-family:monospace"><span class="command"><strong>web::put</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::put</code></span> ? ?#? <em class="replaceable"><code>channel</code></em> ? <em class="replaceable"><code>text</code></em></span></div><p style="width:90%"> Sends output to a Tcl channel. No newline is added to output. If ?<span class="optional"><tt><em class="replaceable"><code>channel</code></em></tt></span>? is ommitted, output is sent to the current default channel. The default channel can be changed with <span style="font-family:monospace"><span class="command"><strong>web::response <tt>-select</tt> ?<span class="optional"><tt>#</tt></span>?<tt><em class="replaceable"><code>channel</code></em></tt></strong></span></span>. The optional hash ("#") denotes that output should be sent to a global variable named <tt><em class="replaceable"><code>channel</code></em></tt> instead of a Tcl channel. </p></div><div class="section" title="web::putx"><div class="titlepage"><div><div><h3 class="title"><a name="web::putx"></a><span style="font-family:monospace"><span class="command"><strong>web::putx</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::putx</code></span> ? ?#? <em class="replaceable"><code>channel</code></em> ? <em class="replaceable"><code>text</code></em></span></div><p style="width:90%"> Writes <tt>text</tt> to the specified channel. Code in curly brackets is eval'd, unless the brackets are escaped by "\". These markup characters '{...}' can be changed to '<? ... ?>' with '<span style="font-family:monospace"><span class="command"><strong>web::config putxmarkup tag</strong></span></span>'. The optional hash ("#") denotes that output should be sent to a global variable named <tt><em class="replaceable"><code>channel</code></em></tt> instead of a Tcl channel. </p></div><div class="section" title="web::putxfile"><div class="titlepage"><div><div><h3 class="title"><a name="web::putxfile"></a><span style="font-family:monospace"><span class="command"><strong>web::putxfile</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::putxfile</code></span> ? ?#? <em class="replaceable"><code>channel</code></em> ? <em class="replaceable"><code>file</code></em> ?<em class="replaceable"><code>msg</code></em>?</span></div><p style="width:90%"> Like <span style="font-family:monospace"><span class="command"><strong>web::putx</strong></span></span>, but takes input from a file. </p><p style="width:90%"> Returns 0 on success, 1 otherwise. If an error occurs, an error message is written to <tt>msg</tt>. If only two arguments are passed, then <tt>channel</tt> takes precedence. The optional hash ("#") denotes that output should be sent to a global variable named <tt><em class="replaceable"><code>channel</code></em></tt> instead of a Tcl channel. </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request_data_handling.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="logging.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Request data handling�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Logging</td></tr></table></div></body></html>

websh/quickref/response_data_handling.html (169 lines of code) (raw):