Working with Ns_Set and Form Data

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 (see page 55)

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.

1. From a Page window in AOLpress choose menu item Tools Administer Server... Choose your server from the dialog that appears. If it is not listed, type in http:// followed by the name of the host where the server is running. A page containing links to several server functions appears. If you're using another browser, go to the /NS/Admin page on your server.

2. Scroll down to the section labeled Tcl Scripting and follow the link to View/Edit Shared Script Files.

3. The AOLserver returns a page with a list of links to existing Tcl scripts and subdirectories containing Tcl scripts to view and/or modify. Scroll to the end of the page and enter sets.test in the entry box labeled Create a new script called.

4. Press the Create... button. The AOLserver returns a page with a large text area form where you can enter the text of the script.

5. Enter the following text of the script below (lines beginning with a # sign are comments and may safely be skipped):

    # 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"
    }
    

1. Press the Create Tcl Script button.

   The AOLserver:

   • creates the file sets.test in the appropriate Tcl directory of the AOLserver home directory

   • sources the new sets.test file to evaluate the ns_register_proc and proc commands to register the single showheader operation procedure, for the /example/showbrowser and /example/showrefer URLs

   • returns a Tcl script update form containing the sets.test script file to allow you further modify or delete the new script

2. Because the AOLserver is a dynamic extensible environment, the /example/showbrowser and /example/showrefer URLs are immediately registered to be handled by the showheader procedure. To test the new operations, open the /example/showbrowser or /example/showrefer URLs in any browser.

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