NaviServer Tcl Libraries(n) 4.99.2 ""

NAME

NaviServer Tcl Libraries - NaviServer Tcl Libraries

    TABLE OF CONTENTS
    DESCRIPTION
    What Are Tcl Libraries?
    When to Use Tcl Libraries
    Tcl Libraries
    Tcl Script Order of Evaluation
    Tcl-only Modules
    Configuration for Tcl-only Modules
        Example of Tcl Initialization with Tcl-only Modules
        Configuration for Tcl Libraries
    How to Build and Debug Tcl Scripts

A Tcl library is simply a directory containing Tcl scripts that are sourced at startup by a virtual server. You can create private libraries for individual virtual servers and public libraries that affect all or some of an installation's virtual servers.

Each Tcl file in a library often contains one or more calls to ns_register_proc, ns_schedule_proc, or ns_register_filter to bind a script to a specific URL or URL hierarchy, plus the Tcl scripts that will handle the URL(s). This example shows the ns_register_proc function being used to bind the Tcl procedure "hello" to handle a GET request for /example/hello, plus the "hello" procedure itself:

ns_register_proc GET /example/hello hello

proc hello {conn context} { ns_return $conn 200 text/plain "Hello World" }

Tcl libraries can also be created that contain no registration functions; they may just contain Tcl scripts that are called from ADPs.

When NaviServer processes a method/URL request, it checks to see if there is a Tcl script in the virtual server's private or shared library to handle the method and URL. A private Tcl script registered to handle a URL overrides a shared Tcl script registered to handle the same URL.

When to Use Tcl Libraries

The alternative to embedding Tcl scripts in HTML pages using ADPs (see Chapter 2), is to store Tcl scripts in Tcl libraries. The situations listed below are well-suited to the Tcl libraries approach.

Inheritance: If you want one Tcl script to handle an URL and all of its sub-URLs, it's better to store the script in a Tcl library and register it using ns_register_proc to handle an URL hierarchy. For example, you may want to manage a server domain name change by redirecting every response to the corresponding domain name on another server.
Special Extensions: If you want one Tcl script to handle all files with a specific extension, like /*.csv, you would register the script with ns_register_proc to handle those files.
Scheduled Procedures: If you want a Tcl script to be run at specific intervals, you can use the ns_schedule_* functions to run a script from the Tcl library at scheduled intervals. These procedures do not normally involve returning HTML pages and so are not well suited to ADPs.
Filters: If you want a Tcl script to be called at pre-authorization, post-authorization, or trace time for a group of URLs, you would register a filter using the ns_register_filter function.
Re-using Tcl Scripts: If there are Tcl scripts that you want to use in multiple situations, you can store them in a Tcl library and invoke them from within any ADP or Tcl script.

Tcl Libraries

Tcl libraries are initialized from a Tcl directory specified for each server. The private Tcl directory is specified with the Library configuration parameter in the ns/server/servername/tcl section. It defaults to /modules/tcl under NaviSerer hom einstallation. You can specify a Tcl directory for each server.

The shared Tcl libray directory is specified by tcllibrary parameter in the ns/parameters section and it defaults to /tcl under NaviServer home installation.

Note that the directories you specify need not reside under the NaviServer installation directory. This allows you to keep user-defined scripts physically separate from the scripts supplied by NaviServer.

Tcl Script Order of Evaluation

At server startup time, Tcl initialization is performed in the following steps for the server:

If a Tcl directory is specified, the init.tcl file in that directory is sourced first (if it exists), and then all the remaining .tcl files are sourced alphabetically.
For each module (including any Tcl-only modules as described on page 25) in the server: If a private Tcl directory is specified, the init.tcl file in the module-name subdirectory of the private directory is sourced first (if it exists), and then all the remaining .tcl files are sourced alphabetically.

Tcl-only Modules

As described in the "Tcl Libraries" section, you can define a Tcl directory for each server. However, none of the subdirectories under the Tcl directories will be initialized unless you load a corresponding module. For example, if the ServerA server has a Tcl directory defined as /home/mydir/tcl/a, and the nsdb and perm modules are loaded, then the following directories will be initialized as server start-up:

/home/mydir/tcl/a

/home/mydir/tcl/a/nsdb

/home/mydir/tcl/a/perm

If you want another directory under /home/tcl/a that contains Tcl scripts to be initialized also, you must load a Tcl-only module for it into the server using the "Tcl" keyword.

Configuration for Tcl-only Modules

To load a Tcl-only module, add the following line to your configuration file:

ns_section "ns/server/servername/modules" ns_param mytcl Tcl

Then, at server start-up, the /home/mydir/tcl/a/mytcl directory will be initialized too. You can load any number of Tcl-only modules into a virtual server to have the Tcl scripts in the corresponding directories initialized.

For Tcl-only modules, no C module file is loaded. Only the corresponding Tcl directories are initialized.

Example of Tcl Initialization with Tcl-only Modules

This example shows demonstrates the order in which Tcl scripts are initialized at startup time for a server. The Library parameter is not set, so the library for S1 defaults to /modules/tcl. A Tcl-only module called M1 is loaded for S1 as follows:

ns_section "ns/server/S1/modules" ns_param M1 Tcl

The library for server S1 (/modules/tcl) contains these files:

abc.tcl

The library for module M1 (/modules/tcl/M1) contains these files:

init.tcl

priv.tcl

script1.tcl

The Tcl files will be sourced in this order:

/module/tcl/abc.tcl

/module/tcl/M1/init.tcl

/module/tcl/M1/priv.tcl

/module/tcl/M1/script1.tcl

Configuration for Tcl Libraries

Configuration for Tcl libraries is handled in the ns/server/server-name/tcl section of the configuration file. The parameters in that section are described in detail on page 61 of the NaviServer Administrator's Guide. Some parameters to note are:

Debug, which prints the names of files sourced at server startup to the log file
Library, which defines the Tcl library for the server

To configure Tcl-only modules, see page 25.

How to Build and Debug Tcl Scripts

Follow these steps to build and debug your Tcl scripts:

Create a .tcl file containing a Tcl script in the directory specified by the Library parameter (see page 26) for your server. Include a call to ns_register_proc to register your script to an URL or URL hierarchy.
Test your script by accessing an URL that it is registered for. For example, if you registered the hello script to the /example/hello URL as follows:

ns_register_proc GET /example/hello hello

Then you would test the script by visiting the URL

http://yourserver/example/hello.
After testing your script, you may want to make changes to it. Edit the script file and open the URL associated with the script (such as the /example/hello URL in the above example) again in your browser and perform a Reload to see the new results.