$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/tcl-general.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
Sharing Files Between Interpreters
Working with Ns_Set and Form Data
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.
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.
Each connection thread that requires Tcl will create a copy of the original interpreter.
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.
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.
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.
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).
For example:
#init time:
set sharedFile [open myfile.dat]
detach $sharedFile
You must manually close the shared file (by performing a close) when it is no longer needed or when the server is shut down.
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.
For example:, at initialization time (for example, in your init.tcl
script), open a shared file and create a mutex:
set sharedLock [ns_mutex create]
set sharedFile [open myfile.dat]
detach $sharedFile
At run time, use the mutex to protect any actions you perform on the
shared file:
ns_share sharedLock
ns_share sharedFile
ns_mutex lock $sharedLock
puts $sharedFile ...
gets $sharedFile ...
ns_mutex unlock $sharedLock
At shutdown (for example, in your shutdown procedure registered with
ns_atshutdown), close the file and destroy the lock:
ns_share sharedLock
ns_share sharedFile
close $SharedFile
ns_mutex destroy $SharedLock
An AOLserver operation procedure often manipulates sets of key-value pairs of string data, for example:
rows of data from the database
HTTP header information
HTML form data
Ns_Set Data Structure
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.
The example below shows a typical use of the ns_set Tcl command to manipulate Ns_Set structures.
# 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" }
Form Data
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.
Search Form Data
Key
Value
ColSelected.columnname
"on" or "off"
ColOperator.columnname
search operator
(=, <, >, <=, >=, is null, is not null)
ColValue.columnname
search value for text, integer, real, or boolean fields
ColValue.columnname.NULL
"t" or "f" (true or false), indicates whether to search for the specified date, time, or timestamp field
ColValue.columnname.month
month portion of search value for date and timestamp fields
ColValue.columnname.day
day portion of search value for date and timestamp fields
ColValue.columnname.year
year portion of search value for date and timestamp fields
ColValue.columnname.time
time portion of search value for time and timestamp fields
ColValue.columnname.ampm
"AM" or "PM" designation of search value for time and timestamp fields
OrderBy.n
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)
Queryinfo.Distinct
"on" or "off", indicates whether query should eliminate duplicate records
Pref.MaxToReturn
integer, maximum number of records to return
Entry Form Data
Key
Value
ColValue.columnname
value for text, integer, real, or boolean fields
ColValue.columnname.NULL
"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
ColValue.columnname.month
month portion of value for date and timestamp fields
ColValue.columnname.day
day portion of value for date and timestamp fields
ColValue.columnname.year
year portion of value for date and timestamp fields
ColValue.columnname.time
time portion of value for time and timestamp fields
ColValue.columnname.ampm
"AM" or "PM" designation of value for time and timestamp fields
Update/Delete Form Data
Key
Value
ColValue.columnname
value for text, integer, real, or boolean fields
ColValue.columnname.NULL
"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
ColValue.columnname.month
month portion of value for date and timestamp fields
ColValue.columnname.day
day portion of value for date and timestamp fields
ColValue.columnname.year
year portion of value for date and timestamp fields
ColValue.columnname.time
time portion of value for time and timestamp fields
ColValue.columnname.ampm
"AM" or "PM" designation of value for time and timestamp fields
RowID.columnname
all the RowID values that specify the row to update or delete