dqd_utils: AOLserver General Utilities

Compiling and Installing

1. Set the environment variable INST to the location where you have installed AOLserver.

2. Unpack dqd_utils-1.7.tar.gz in the location of your choice.

3. Change into the dqd_utils-1.7 directory and run make install. You must do this as a user that has write access to $INST/bin.

Example:

export INST=/usr/local/aolserver
tar xzf dqd_utils-1.7.tar.gz
cd dqd_utils-1.7
make install

Configuring AOLserver

Add this to your nsd.tcl:

ns_section "ns/server/server1/modules"
ns_param dqd_utils dqd_utils.so

Commands

These are the commands provided by dqd_utils.

dqd_internalredirect url

url must be a URL starting with a slash (for example, /foo/bar.html). This command passes url to Ns_ConnRedirect. This makes the server restart the main request handler as if url was the URL in the original request. The server does not re-run preauth or postauth filters.

dqd_md5 plaintext

This command computes the MD5 hash of plaintext and returns the hash as a string of 32 hexadecimal characters. For example:

set hash [dqd_md5 "this is a string"]

This example sets hash to "b37e16c620c055cf8207b999e3270e9b".

unlist list var1 var2 ...

This command assigns the elements of $list to the named variables. For example:

set list {foo bar baz}
unlist $list a b c d

This example sets a to "foo", b to "bar", c to "baz", and d to "" (the empty string). The unlist command is faster and more concise than a series of set/lindex commands.

dqd_nssetToList setid listvar

This command assigns the values of set identified by setid to a list stored in listvar. For example:

ns_db getrow $db $rowSet
dqd_nssetToList $rowSet rowList

This example results in rowList containing a list of the database column values for the retrieved row.

dqd_detachfile channelid name

channelid must be the id of a open Tcl channel in the current interpreter. This command removes the channel from the current interpreter and stores it in a private namespace as name. The private namespace is shared with the dqd_attachfile command.

Example:

# At server startup...

    set cid [open "/etc/passwd" r]
dqd_detachfile $cid passwd
ns_share passwdLock
set passwdLock [ns_mutex create]

dqd_attachfile name

This command looks up name in the private namespace shared with dqd_detachfile. It removes the associated channel from the private namespace and attaches the channel to the current Tcl interpreter. The command returns the new Tcl channel id.

Example:

# In a request handler...

ns_share passwdLock
ns_mutex lock $passwdLock
set cid [dqd_attachfile passwd]

seek $cid 0
set line [gets $cid]

dqd_detachfile $cid passwd
ns_mutex unlock $passwdLock

dqd_register_proxy method protocol script

This command registers a handler for proxy HTTP requests. method is an HTTP method such as GET or POST (case is significant). protocol is a URL protocol id such as http or ftp. script is a Tcl script.

When the server receives an HTTP request containing a full URL (including a protocol and a hostname), and request method and protocol match method and protocol, the server runs script. The server does not call any preauth or postauth filters or the authentication handler. The server does call trace handlers after script returns. Typically script is simply the name of a Tcl proc.

dqd_rowsToXml dbhandle rowset

This command turns a set of rows from a database into XML. The result is a <table> element containing one <r> element for each row. Each <r> contains one element for each column, using the column name as the tag. The XML will not contain any whitespace that is not part of a field name or value. For example, this code:

	set db [ns_db gethandle]
	set row [ns_db select $db {select id, name from users}]
	dqd_rowsToXml $row
    

will produce something like this:

<table><r><id>1</id><name>Joe</name></r><r><id>2</id><name>Fred</name></r><r><id>3</id><name>Bob</name><r></table>

dqd_rowsToJavaScript dbhandle rowset

This command turns a set of rows from a database into JavaScript. The result is a list of objects, one object per row. Each object has one field for each column. For example, this code:

	set db [ns_db gethandle]
	set row [ns_db select $db {select id, name from users}]
	dqd_rowsToJavaScript $row
    

will produce something like this:

[{id:'1',name:'Joe'},{id:'2',name:'Fred'},{id:'3',name:'Bob'}]

The output is intended to be JSON-compliant.