File: tcl-general.html

package info (click to toggle)
aolserver4 4.5.1-18.1
links: PTS, VCS
area: main
in suites: stretch
size: 12,008 kB
sloc: ansic: 45,126; tcl: 5,533; sh: 1,037; makefile: 380; pascal: 219; php: 13
file content (502 lines) | stat: -rw-r--r-- 8,708 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<h1>General Tcl Information</h1>

<p>
<small>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/tcl-general.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
</small>
<p>

<a href=#1>Tcl Interpreters</a>

<p>

<a href=#2>Global Variables</a>

<p>

<a href=#3>Sharing Files Between Interpreters</a>

<p>

<a href=#4>Working with Ns_Set and Form Data</a>

<p>

This chapter contains general information about using Tcl whether you
are using the ADP approach or the Tcl Libraries approach, both of
which use the same features of Tcl.


<p>

<h2><a name=1>Tcl Interpreters</a></h2>

<p>

   During AOLserver initialization, only one interpreter exists. While
   modules are loaded and initialized, they may add procedures to the
   interpreter. When initialization is complete (all modules are loaded
   and all Tcl libraries have been executed), the interpreter may no
   longer be changed.

<p>

   Each connection thread that requires Tcl will create a copy of the
   original interpreter.

<p>

   The AutoClose parameter, which is on by default, will close all
   non-shared files opened by an interpreter when Ns_TclDeAllocateInterp
   is invoked. Ns_TclDeAllocateInterp is called after each Tcl request
   procedure. It is recommended that you leave the AutoClose parameter
   set to on.

<p>

<h2><a name=2>Global Variables</a></h2>

<p>

   In earlier releases of the AOLserver, global variables were shared
   between all Tcl interpreters in a virtual server. Beginning in Version
   2.2, each Tcl interpreter has its own global variable table, so global
   variables are shared only within each Tcl interpreter by default. The
   ns_share command allows you to make a variable available to all
   interpreters in a virtual server.

<p>

   Global variables are flushed when the Tcl interpreter is deallocated.
   A Tcl interpreter is deallocated explicitly when
   Ns_TclDeallocateInterp is called or implicitly at the end of a
   connection. This allows Tcl filter functions to access global
   variables set in ADPs.

<p>

   

<h2><a name=3>Sharing Files Between Interpreters</a></h2>

<p>

   To share a file between the interpreters in a group, use the Tcl
   detach command. A shared file is left open after an interpreter is
   deallocated when the AutoClose parameter is on (it is on by default).
<br>
   For example:
<br>
    #init time:
<br>
    set sharedFile [open myfile.dat]
<br>
    detach $sharedFile
<br>

<p>

   You must manually close the shared file (by performing a close) when
   it is no longer needed or when the server is shut down.

<p>

   Note that there is no implicit locking between interpreters. This
   means that one interpreter can be performing a gets command on the
   shared file at the same time another interpreter performs a close on
   the same file. The results are unpredictable, and could potentially
   cause a core dump. To avoid this situation, use a mutex to protect
   access to the file whenever it is accessed.

<p>

   For example:, at initialization time (for example, in your init.tcl
   script), open a shared file and create a mutex:
<br>
    set sharedLock [ns_mutex create]
<br>
    set sharedFile [open myfile.dat]
<br>
    detach $sharedFile
<br>

<p>

   At run time, use the mutex to protect any actions you perform on the
   shared file:
<br>
    ns_share sharedLock
<br>
    ns_share sharedFile
<br>
    ns_mutex lock $sharedLock
<br>
    puts $sharedFile ...
<br>
    gets $sharedFile ...
<br>
    ns_mutex unlock $sharedLock
<br>

<p>

   At shutdown (for example, in your shutdown procedure registered with
   ns_atshutdown), close the file and destroy the lock:
<br>
    ns_share sharedLock
<br>
    ns_share sharedFile
<br>
    close $SharedFile
<br>
    ns_mutex destroy $SharedLock
<br>


<p>

<h2><a name=4>Working with Ns_Set and Form Data</a></h2>

<p>

   An AOLserver operation procedure often manipulates sets of key-value
   pairs of string data, for example:

<p>

<br>
          rows of data from the database
<br>
          HTTP header information
<br>
          HTML form data
<br>

<p>

    Ns_Set Data Structure

<p>

   In the AOLserver C API these data are manipulated using the Ns_Set
   data structure. In the Tcl API the ns_set command can be used to
   manipulate underlying Ns_Set data structures that are generated by the
   AOLserver communications layer or the database services module.

<p>

   The example below shows a typical use of the ns_set Tcl command to
   manipulate Ns_Set structures.
<pre>
   # Example 2: Show header data
    #
    # Things to notice:
    # * The same function is registered for two different URLs
    # with different context.
    #
    # * The headers are pulled out of the conn using the
    # ns_conn function.
    #
    # * The value for a particular header line is extracted
    # with "ns_set get".

    ns_register_proc GET /example/showbrowser \
        showheader USER-AGENT
    ns_register_proc GET /example/showrefer \
        showheader REFER

    proc showheader {conn key} {
          set value [ns_set get [ns_conn headers $conn] $key]
          ns_return $conn 200 text/plain "$key: $value"
    }
</pre>

<p>

    Form Data

<p>

   Some Database Services Tcl functions take formdata arguments. You can
   get the form data for a form by calling ns_conn form. An ns_set
   structure containing key/value pairs is returned, which you can
   manipulate using the ns_set function. The key/value pairs for search,
   entry, and update forms are provided below.

<p>

   Search Form Data

<p>

         Key

<p>

   Value

<p>

   ColSelected.columnname

<p>

   "on" or "off"

<p>

   ColOperator.columnname

<p>

   search operator

<p>

   (=, &lt;, &gt;, &lt;=, &gt;=, is null, is not null)

<p>

   ColValue.columnname

<p>

   search value for text, integer, real, or boolean fields

<p>

   ColValue.columnname.NULL

<p>

   "t" or "f" (true or false), indicates whether to search for the
   specified date, time, or timestamp field

<p>

   ColValue.columnname.month

<p>

   month portion of search value for date and timestamp fields

<p>

   ColValue.columnname.day

<p>

   day portion of search value for date and timestamp fields

<p>

   ColValue.columnname.year

<p>

   year portion of search value for date and timestamp fields

<p>

   ColValue.columnname.time

<p>

   time portion of search value for time and timestamp fields

<p>

   ColValue.columnname.ampm

<p>

   "AM" or "PM" designation of search value for time and timestamp fields

<p>

   OrderBy.n

<p>

   name of column to order the results by (where n is 0 for the first
   order by column, 1 for the second order by column, and so on)

<p>

   Queryinfo.Distinct

<p>

   "on" or "off", indicates whether query should eliminate duplicate
   records

<p>

   Pref.MaxToReturn

<p>

   integer, maximum number of records to return

<p>

   Entry Form Data

<p>

         Key

<p>

   Value

<p>

   ColValue.columnname

<p>

   value for text, integer, real, or boolean fields

<p>

   ColValue.columnname.NULL

<p>

   "t" or "f" (true or false), indicates whether a date, time, or
   timestamp field is null or the value specified in the date/time
   portions

<p>

   ColValue.columnname.month

<p>

   month portion of value for date and timestamp fields

<p>

   ColValue.columnname.day

<p>

   day portion of value for date and timestamp fields

<p>

   ColValue.columnname.year

<p>

   year portion of value for date and timestamp fields

<p>

   ColValue.columnname.time

<p>

   time portion of value for time and timestamp fields

<p>

   ColValue.columnname.ampm

<p>

   "AM" or "PM" designation of value for time and timestamp fields

<p>

   Update/Delete Form Data

<p>

             Key

<p>

   Value

<p>

   ColValue.columnname

<p>

   value for text, integer, real, or boolean fields

<p>

   ColValue.columnname.NULL

<p>

   "t" or "f" (true or false), indicates whether a date, time, or
   timestamp field is null or the value specified in the date/time
   portions

<p>

   ColValue.columnname.month

<p>

   month portion of value for date and timestamp fields

<p>

   ColValue.columnname.day

<p>

   day portion of value for date and timestamp fields

<p>

   ColValue.columnname.year

<p>

   year portion of value for date and timestamp fields

<p>

   ColValue.columnname.time

<p>

   time portion of value for time and timestamp fields

<p>

   ColValue.columnname.ampm

<p>

   "AM" or "PM" designation of value for time and timestamp fields

<p>

   RowID.columnname

<p>

   all the RowID values that specify the row to update or delete

<p>


<p>

                
</body>
</html>