Standard Application Direct URLs

The server has several modules that provide Application Direct URLs. These Application Direct URLs let you control the server or examine its state from any Web browser. You can look at the implementation of these modules as examples for your own application.

Status

The /status URL is implemented in the status.tcl file. The status module implements the display of hit counts, document hits, and document misses (i.e., documents not found). The Status_Url command enables the Application Direct URLs and assigns the top-level URL for the status module. The default configuration file contains this command:

Status_Url /status

Table 18-8 shows the URLs implemented by the status module:

Table 18-8. Status Application Direct URLs

/status	Main status page showing summary counters and hit count histograms.
/status/doc	Shows hit counts for each page. This page lets you sort by name or hit count, and limit files by patterns.
/status/domain	Shows hit counts for each domain in the server.
/status/hello	A trivial URL that returns "hello".
/status/notfound	Shows miss counts for URLs that users tried to fetch.
/status/size	Displays an estimated size of Tcl code and Tcl data used by the TclHttpd program.
/status/text	This is a version of the main status page that doesn't use the graphical histograms of hit counts.

Debugging

The /debug URL is implemented in the debug.tcl file. The debug module has several useful URLs that let you examine variable values and other internal state. It is turned on with this command in the default configuration file:

Debug_Url /debug

Table 18-9 lists the /debug URLs. These URLs often require parameters that you can specify directly in the URL. For example, the /debug/echo URL echoes its query parameters:

http://yourserver:port/debug/echo?name=value&name2=val2

Note: The debug URL is active in the default configuration. If it makes you nervous, then delete the call to Debug_Url from the httpdthread.tcl file.

The sample URL tree that is included in the distribution includes the file htdocs/hacks.html. This file has several small forms that use the /debug URLs to examine variables and source files. It may seem dangerous to have these facilities, but I reason that because my source directories are under my control, it cannot hurt to reload any source files. In general, the library scripts contain only procedure definitions and no global code that might reset state inappropriately. In practice, the ability to tune (i.e., fix bugs) in the running server has proven useful to me on many occasions. It lets you evolve your application without restarting it!

Table 18-9. Debug Application Direct URLs

/debug/after	Lists the outstanding after events.
/debug/dbg	Connects to TclPro Debugger. This takes a host and port parameter. You need to install prodebug.tcl from TclPro into the server's script library directory.
/debug/echo	Echoes its query parameters. Accepts a title parameter.
/debug/errorInfo	Displays the errorInfo variable along with the server's version number and Webmaster email. Accepts title and errorInfo arguments.
/debug/parray	Displays a global array variable. The name of the variable is specified with the aname parameter.
/debug/pvalue	A more general value display function. The name of the variable is specified with the aname parameter. This can be a variable name, an array name, or a pattern that matches several variable names.
/debug/raise	Raises an error (to test error handling). Any parameters become the error string.
/debug/source	Sources a file from either the server's main library directory or the Doc_TemplateLibrary directory. The file is specified with the source parameter.

Example 18-19 shows the implementation of /debug/source. You can see that it limits the files to the main script library and to the script library associated with document templates.

Example 18-19 The /debug/source Application Direct URL implementation

proc Debug/source {source} {
   global Httpd Config errorInfo
   set source [file tail $source]
   set dirlist $Httpd(library)   ;# TclHttpd implementation
   lappend dirlist $Config(lib)  ;# Application custom code
   foreach dir $dirlist {
      set file [file join $dir $source]
      if {[file exists $file]} break
   }
   set error [catch {uplevel #0 [list source $file]} result]
   set html "<title>Source $source</title>\n"
   if {$error} {
      append html "<H1>Error in $source</H1>\n"
      append html "<pre>$result<p>$errorInfo</pre>"
   } else {
      append html "<H1>Reloaded $source</H1>\n"
      append html "<pre>$result</pre>"
   }
   return $html
}

Sending Email

The /mail URL is implemented in the mail.tcl file. The mail module implements various form handlers that email form data. Currently, it is UNIX-specific because it uses /usr/lib/sendmail to send the mail. It is turned on with this command in the default configuration file:

Mail_Url /mail

The Application Direct URLs shown in Table 18-10 are useful form handlers. You can specify them as the ACTION parameter in your <FORM> tags. The mail module provides two Tcl procedures that are generally useful. The MailInner procedure is the one that sends mail. It is called like this:

Table 18-10. Application Direct URLS that email form results

/mail/bugreport	Sends email with the errorInfo from a server error. It takes an email parameter for the destination address and an errorInfo parameter. Any additional arguments get included into the message.
/mail/forminfo	Sends email containing form results. It requires these parameters: sendto for the destination address, subject for the mail subject, href and label for a link to display on the results page. Any additional arguments are formatted with the Tcl list command for easy processing by programs that read the mail.
/mail/formdata	This is an older form of /mail/forminfo that doesn't format the data into Tcl lists. It requires only the email and subject parameters. The rest are formatted into the message body.

MailInner sendto subject from type body

The sendto and from arguments are email addresses. The type is the MIME type (e.g., text/plain or text/html) and appears in a Content-Type header. The body contains the mail message without any headers.

The Mail_FormInfo procedure is designed for use in HTML+Tcl template files. It takes no arguments but instead looks in current query data for its parameters. It expects to find the same arguments as the /mail/forminfo direct URL. Using a template with Mail_FormInfo gives you more control over the result page than posting directly to /mail/forminfo, and is illustrated in Example 18-12 on page 272.