| The server has several modules that provide application-direct URLs. These application-direct URLs lets 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 Assuming this configuration, the following URLs are implemented: Table 18-9. 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/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-10 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
Table 18-10. Debug application-direct URLs.| /debug/after | Lists the outstanding after events. | | /debug/dbg | Connect 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 e-mail. 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. |
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. Example 18-15 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. 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! Example 18-15 The /debug/source application-direct URL implementation. proc Debug/source {source} { global Httpd Doc set source [file tail $source] set dirlist $Httpd(library) if {[info exists Doc(templateLibrary)]} { lappend dirlist $Doc(templateLibrary) } 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} { global errorInfo 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 } Administration The /admin URL is implemented in the admin.tcl file. The admin module lets you load URL redirect tables, and it provides URLs that reset some of the counters maintained by the server. It is turned on with this command in the default configuration file: Admin_Url /admin Currently, there is only one useful admin URL. The /admin/redirect/reload URL sources the file named redirect in the document root. This file is expected to contain a number of Url_Redirect commands that establish URL redirects. These are useful if you change the names of pages and want the old names to still work. The administration module has a limited set of application-direct URLs because the simple application-direct mechanism doesn't provide the right hooks to check authentication credentials. The HTML+Tcl templates work better with the authentication schemes. 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-11 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: MailInner sendto subject from type body The sendto and from arguments are e-mail 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. Table 18-11. Application-direct URLS that e-mail form results.| /mail/bugreport | Sends e-mail 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 e-mail 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. |
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-10 on page 257. | 
