Response data handling

Websh can send output to any Tcl channel and to global variables (web::put). Optionally, data is scanned for Tcl code before it is output to a channel (web::putx). Websh manages response objects that are related to Tcl channels and are identified using the name of the corresponding Tcl channel. Configuration is achieved with web::response.



web::response ?option?

web::response ?subcommand? args

Subcommands are -select, -set, -lappend, -names, -count, -unset, -reset, and -resetall Options are -sendheader, -httpresponse, and -bytessent.

Selects the default response object and sets and accesses properties of the response object, and returns the name of the response object.

Returns the name of the currently selected response object.
web::response -select ?#?channelName
Selects channelName as new response object. If the channelName is prepended by a #, it refers to a global variable named channelName.
web::response -set key ?value?
Sets property key to value, or returns current value if value is omitted. The keys are names of HTTP header fields (do not include ':' at the end of the header field name) and value the corresponding value of the field (like Content-Type) and their values (like text/html).
web::response -set Content-Type text/plain.
web::response -names
Returns the list of known keys.
web::response -count key
Returns number of items in list of key.
web::response -unset ?key?
Deletes the value of key, if key is given, or all keys.
web::response -sendheader ?boolean?
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 web::put or web::putx. If boolean is omitted, returns the current value.
web::response -httpresponse ?value?
Sets or gets the HTTP response like "HTTP/1.0 200 OK" for the given (or default) channel. If no value 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".
Note: 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:
web::response -set Status "400 Bad Request".
web::response -bytessent
Returns the number of bytes that have already been sent to this channel.
web::response -reset
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).
web::response -resetall
Performs a web::response -reset on all registered channels.

Example 10. web::response

% web::response
% web::response -select stderr
% web::response
% web::response -sendheader
% web::response -names
Content-Type Generator
% web::response Content-Type
% web::response -bytessent
% 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


web::put ? ?#? channel ? text

Sends output to a Tcl channel. No newline is added to output. If ?channel? is ommitted, output is sent to the current default channel. The default channel can be changed with web::response -select ?#?channel. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.


web::putx ? ?#? channel ? text

Writes text 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 'web::config putxmarkup tag'. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.


web::putxfile ? ?#? channel ? file ?msg?

Like web::putx, but takes input from a file.

Returns 0 on success, 1 otherwise. If an error occurs, an error message is written to msg. If only two arguments are passed, then channel takes precedence. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.