Notes on the TWS server

How the resource is located

1. Parse the request into

   • Hostname
   • Path
   • Query String

2. Use the hostname and path as a lookup into the dispatcher table. The following information is obtained from the dispatcher table:

   • Path Prefix (the part of the path that matches the dispatcher table entry)
   • Document Root
   • The Authentication Realm
   • The TCL namespace in which dynamic pages should be evaluated

3. Use the information obtained from the dispatcher table to compute the following:

   • Path Suffix (the part of the path beyond the Path Prefix)
   • The translated path (append the the Path Suffix to the Document Root)

4. Optionally convert the translated path to all lower-case letters

5. Locate the file that will be used to satisfy the request using the following steps:

   1. If the translated path ends in "/", append "index"

   2. Check for files with the translated path as their basename and with any extension. If multiple files match, choose the first in lexical order.

   3. If no files are found in the previous step, replace the translated path with the path prefix followed by "notfound" and repeat the search.

   4. If still no files match, return a canned "Not Found" message.

6. From the file found in the previous step, use the extension of the filename to lookup a MIME-type and a handler type in the MIME-type table.

Processing of Dynamic Content

• Any text contained within "<% ... %>" is processed as TCL code.

  • The result of the TCL code replaces the original "<% ... %>" text.

  • Executing the "break" command causes all subsequent text to be ignored, even text after the closing "%>".

  • The code is evaluated in the namespace determined by the dispatcher table.

• Tcl variables are substituted if contained within "<$...>".

• Any text not within "<% ... %>" or "<$...>" is returned without change.

Tcl variables available to dynamic code

• If A is the name of a query parameter or a cookie, then the Tcl variable $Q(A) contains the value of that query parameter or cookie.

• Miscellanous information about the HTTP request is contained in an Tcl array variable called $D().

  D(content)	The complete text of the query string or the POST data
  D(cookie)	The names and values of all cookies passed to the server
  D(count)	In a keep-alive HTTP connection, this variable holds the number of prior requests sent over the same connection.
  D(document)	The full pathname of the file that is being interpreted.
  D(method)	The HTTP request method. Typically one of "GET" or "POST".
  D(path)	The Path part of the HTTP request.

• The dynamic code can change the value of the following elements of the $D() Tcl array variable:

  D(CONTENT-TYPE)	The MIME-type of the generated document is normally determined by the document suffix. But you can override the default MIME type by setting the value of this variable.
  D(EXPIRES)	You can set an expiration time for this document using this variable.
  D(set-cookie)	This variable holds a list of cookie settings that will be sent to the client.
  D(send-file)	If this variable is set to the name of a file, then that file is transmitted verbatim in place of the dynamically generated text.

Special commands available to dynamic code

The following new TCL commands are available to the code contained within <% ... %> of dynamic content:

• ::tws::require FILENAME

  This command sources the file named FILENAME. If FILENAME is a relative path, it is evaluated relative to the dynamic content file. The file will only be sourced once, on the first time this statement is executed.

• ::tws::redirect PATH

  This command causes the web-server to redirect the client to a different URL. The new URL is contained in the argument. The command operates by raising an exception, so no subsequent code will be executed.

• ::tws::select OPTIONS...

  The result of this command is HTML code for a "<SELECT>...</SELECT>" statement.

• ::tws::include FILENAME

• ::tws::%ifdef LIST CODE ...

• ::tws::htmlize TEXT

• ::tws::urlize TEXT

• ::tws::httpize TEXT

• ::tws::render TEXT

• ::tws::hsubst TEXT

• ::tws::ifdef VAR-LIST

• ::tws::ifanydef VAR-LIST

• ::tws::debug TEXT

• ::tws::parray VARIABLE-NAME