| <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> |
