Index: openacs.org-dev/packages/acs-bootstrap-installer/tcl/40-db-query-dispatcher-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-bootstrap-installer/tcl/40-db-query-dispatcher-procs.tcl,v
diff -u -r1.1.1.1 -r1.1.1.2
--- openacs.org-dev/packages/acs-bootstrap-installer/tcl/40-db-query-dispatcher-procs.tcl	9 Jul 2002 17:34:56 -0000	1.1.1.1
+++ openacs.org-dev/packages/acs-bootstrap-installer/tcl/40-db-query-dispatcher-procs.tcl	8 Oct 2002 15:46:41 -0000	1.1.1.2
@@ -1,42 +1,78 @@
-
-#
 # Query Dispatching for multi-RDBMS capability
 # The OpenACS Project
 #
 # Ben Adida (ben@mit.edu)
 #
 # STATE OF THIS FILE (7/12/2001) - ben:
 # This is now patched to use ns_xml 1.4 which works!
-#
 
 # The Query Dispatcher is documented at http://openacs.org/
+# The Query Dispatcher needs ns_xml to work.
 
 # This doesn't use the ad_proc construct, or any significant aD constructs,
 # because we want this piece to be usable in a separate context. While this makes
 # the coding somewhat more complicated, it's still easy to document and write clear,
 # virgin Tcl code.
 
-# This needs ns_xml to work.
 
+
+# The following code allows ad_proc to be used
+# here (a local workalike is declared if absent).
+# added 2002-09-11 Jeff Davis (davis@xarg.net)
+if {! [string equal {} [info procs ad_library]]} { 
+    ad_library {
+        Query Dispatching for multi-RDBMS capability
+
+        @author Ben Adida (ben@openforce.net)
+        @cvs-id $Id$
+    } 
+}
+
+if { ! [string equal {} [info procs ad_proc]] } {
+    set remove_ad_proc_p 0
+} else { 
+    set remove_ad_proc_p 1
+    proc ad_proc {name arglist args} { 
+        # args can be {docs body} {body} {docs -} 
+        # make sure it is non empty and does not end in -
+        if {[llength $args] && ![string equal [lindex $args end] "-"]} { 
+            proc $name $arglist [lindex $args end]
+        }
+    }
+}
+
+
 ##################################
 # The RDBMS Data Abstraction
 ##################################
 
-proc db_rdbms_create {type version} {
+ad_proc db_rdbms_create {type version} {
+    @return rdbms descriptor
+} { 
     return [list $type $version]
 }
 
-proc db_rdbms_get_type {rdbms} {
+ad_proc db_rdbms_get_type {rdbms} {
+    @param rdbms descriptor constructed by db_rdbms_create
+
+    @return rdbms name
+} { 
     return [lindex $rdbms 0]
 }
 
-proc db_rdbms_get_version {rdbms} {
+ad_proc db_rdbms_get_version {rdbms} {
+    @param rdbms descriptor constructed by db_rdbms_create
+
+    @return version identifier
+} { 
     return [lindex $rdbms 1]
 }
 
-proc db_rdbms_compatible_p {rdbms_test rdbms_pattern} {
-    db_qd_log Debug "The RDBMS_TEST is [db_rdbms_get_type $rdbms_test] - [db_rdbms_get_version $rdbms_test]"
-    db_qd_log Debug "The RDBMS_PATTERN is [db_rdbms_get_type $rdbms_pattern] - [db_rdbms_get_version $rdbms_pattern]"
+ad_proc db_rdbms_compatible_p {rdbms_test rdbms_pattern} {
+    @return 0 if test incompatible with pattern, 1 if miscible
+} { 
+    db_qd_log QDDebug "The RDBMS_TEST is [db_rdbms_get_type $rdbms_test] - [db_rdbms_get_version $rdbms_test]"
+    db_qd_log QDDebug "The RDBMS_PATTERN is [db_rdbms_get_type $rdbms_pattern] - [db_rdbms_get_version $rdbms_pattern]"
 
     # If the pattern is for all RDBMS, then yeah, compatible
     if {[empty_string_p [db_rdbms_get_type $rdbms_test]]} {
@@ -45,7 +81,7 @@
 
     # If the RDBMS types are not the same, we have a problem
     if {[db_rdbms_get_type $rdbms_test] != [db_rdbms_get_type $rdbms_pattern]} {
-	db_qd_log Debug "compatibility - RDBMS types are different!"
+	db_qd_log QDDebug "compatibility - RDBMS types are different!"
 	return 0
     }
 
@@ -55,12 +91,12 @@
     }
 
     # If the query being tested was written for a version that is older than 
-	# the current RDBMS then we have compatibility. Otherwise we don't.
+    # the current RDBMS then we have compatibility. Otherwise we don't.
     if {[db_rdbms_get_version $rdbms_test] <= [db_rdbms_get_version $rdbms_pattern]} {
 	return 1
     }
 
-    db_qd_log Debug "compatibility - version numbers are bad!"
+    db_qd_log QDDebug "compatibility - version numbers are bad!"
     return 0
 }
 
@@ -72,35 +108,60 @@
 
 
 
-# The Constructor
 
-proc db_fullquery_create {queryname querytext bind_vars_lst query_type rdbms load_location} {
+ad_proc db_fullquery_create {queryname querytext bind_vars_lst query_type rdbms load_location} {
+    FullQuery Data Abstraction Constructor
+} { 
     return [list $queryname $querytext $bind_vars_lst $query_type $rdbms $load_location]
 }
 
 # The Accessor procs
 
-proc db_fullquery_get_name {fullquery} {
+ad_proc db_fullquery_get_name {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return name
+} {
     return [lindex $fullquery 0]
 }
 
-proc db_fullquery_get_querytext {fullquery} {
+ad_proc db_fullquery_get_querytext {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return query text
+} {
     return [lindex $fullquery 1]
 }
 
-proc db_fullquery_get_bind_vars {fullquery} {
+ad_proc db_fullquery_get_bind_vars {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return bind vars
+} {
     return [lindex $fullquery 2]
 }
 
-proc db_fullquery_get_query_type {fullquery} {
+ad_proc db_fullquery_get_query_type {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return query type
+} {
     return [lindex $fullquery 3]
 }
 
-proc db_fullquery_get_rdbms {fullquery} {
+ad_proc db_fullquery_get_rdbms {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return rdbms descriptor
+} {
     return [lindex $fullquery 4]
 }
 
-proc db_fullquery_get_load_location {fullquery} {
+ad_proc db_fullquery_get_load_location {fullquery} {
+    Accessor for fullquery data abstraction
+    @param fullquery datastructure constructed by db_fullquery_create 
+    @return load location 
+} {
     return [lindex $fullquery 5]
 }
 
@@ -111,9 +172,10 @@
 #
 ################################################
 
-# For now, we're going to say that versions are numbers and that
-# there is always backwards compatibility.
-proc db_qd_pick_most_specific_query {rdbms query_1 query_2} {
+ad_proc db_qd_pick_most_specific_query {rdbms query_1 query_2} {
+    For now, we're going to say that versions are numbers and that
+    there is always backwards compatibility.
+} {
     set rdbms_1 [db_fullquery_get_rdbms $query_1]
     set rdbms_2 [db_fullquery_get_rdbms $query_2]
 
@@ -143,16 +205,19 @@
 #
 ################################################
 
-# A procedure that is called from the outside world (APM) 
-# to load a particular file
-proc db_qd_load_query_file {file_path} {
+ad_proc db_qd_load_query_file {file_path} {
+    A procedure that is called from the outside world (APM) 
+    to load a particular file
+} { 
     if { [catch {db_qd_internal_load_cache $file_path} errmsg] } {
         db_qd_log Error "Error parsing queryfile $file_path:\n\n$errmsg"
     }
 }
 
-# Find the fully qualified name of the query
-proc db_qd_get_fullname {local_name {added_stack_num 1}} {
+
+ad_proc db_qd_get_fullname {local_name {added_stack_num 1}} {
+    Find the fully qualified name of the query
+} { 
     # We do a check to see if we already have a fullname.
     # Since the DB procs are a bit incestuous, this might get
     # called more than once. DAMMIT! (ben)
@@ -170,7 +235,7 @@
 
     # If util_memoize, we have to go back up one in the stack
     if {[lindex $proc_name 0] == "util_memoize"} {
-	db_qd_log Debug "util_memoize! going up one level"
+	db_qd_log QDDebug "util_memoize! going up one level"
 	set proc_name [info level [expr "-2 - $added_stack_num"]]
     }
 
@@ -184,12 +249,12 @@
 
 	# TEST
 	for {set i 0} {$i < 6} {incr i} {
-	    if {[catch {db_qd_log Debug "LEVEL=$i= [info level [expr "-1 - $i"]]"} errmsg]} {}
+	    if {[catch {db_qd_log QDDebug "LEVEL=$i= [info level [expr "-1 - $i"]]"} errmsg]} {}
 	}
 
 	# Check the ad_conn stuff
 	if {[ns_conn isconnected]} {
-	    if {[catch {db_qd_log Debug "the ad_conn file is [ad_conn file]"} errmsg]} {}
+	    if {[catch {db_qd_log QDDebug "the ad_conn file is [ad_conn file]"} errmsg]} {}
 	}
 
 	# Now we do a check to see if this is a directly accessed URL or a 
@@ -203,27 +268,27 @@
         switch $proc_name {
 
             ns_sourceproc {
-                db_qd_log Debug "We are in a WWW page, woohoo!"
+                db_qd_log QDDebug "We are in a WWW page, woohoo!"
                 set real_url_p 1
                 set url [ns_conn url]
             }
 
             rp_handle_tcl_request {
-                db_qd_log Debug "We are in a VUH page sourced by rp_handle_tcl_request, woohoo!"
+                db_qd_log QDDebug "We are in a VUH page sourced by rp_handle_tcl_request, woohoo!"
                 set real_url_p 0
                 regsub {\.vuh} [ad_conn file] {} url
                 set url [ad_make_relative_path $url]
                 regsub {^/?packages} $url {} url
             }
 
             template::frm_page_handler {
-                db_qd_log Debug "We are in the template system's form page debugger!"
+                db_qd_log QDDebug "We are in the template system's form page debugger!"
                 set real_url_p 1
                 regsub {\.frm} [ad_conn url] {} url
             }
 
             default {
-                db_qd_log Debug "We are in a WWW page sourced by apm_source, woohoo!"
+                db_qd_log QDDebug "We are in a WWW page sourced by apm_source, woohoo!"
                 set real_url_p 0
                 set url [lindex $proc_name 1]
                 set url [ad_make_relative_path $url]
@@ -243,7 +308,7 @@
 	# We insert the "www" after the package key
 	regexp {^([^\.]*)(.*)} $url all package_key rest
 
-	db_qd_log Debug "package key is $package_key and rest is $rest"
+	db_qd_log QDDebug "package key is $package_key and rest is $rest"
 
 	if {$real_url_p} {
 	    set full_name [db_qd_make_absolute_path "${package_key}.www${rest}." $local_name]
@@ -263,14 +328,14 @@
         # (Openacs - DanW)
 
         set calling_namespace [string range [uplevel [expr 1 + $added_stack_num] {namespace current}] 2 end]
-        db_qd_log Debug "calling namespace = $calling_namespace"
+        db_qd_log QDDebug "calling namespace = $calling_namespace"
 
         if {![string equal $calling_namespace ""] && 
             ![regexp {::} $proc_name all]} {
 
             set proc_name ${calling_namespace}::${proc_name}
         }
-	db_qd_log Debug "proc_name is -$proc_name-"
+	db_qd_log QDDebug "proc_name is -$proc_name-"
 
 	# We use the ad_proc construct!! 
 	# (woohoo, can't believe that was actually useful!)
@@ -279,14 +344,14 @@
 	# probably dealing with one of the bootstrap procs, and so we just
 	# return a bogus proc name
 	if {![nsv_exists api_proc_doc $proc_name]} {
-	    db_qd_log Debug "there is no documented proc with name $proc_name -- we used default SQL"
+	    db_qd_log QDDebug "there is no documented proc with name $proc_name -- we used default SQL"
 	    return [db_qd_null_path]
 	}
 
 	array set doc_elements [nsv_get api_proc_doc $proc_name]
 	set url $doc_elements(script)
 
-	db_qd_log Debug "tcl file is $url"
+	db_qd_log QDDebug "tcl file is $url"
 
 	regsub {.tcl$} $url {} url
 
@@ -298,30 +363,49 @@
 	# We need to remove packages.
 	regexp {^packages\.(.*)} $url all rest
 
-	db_qd_log Debug "TEMP - QD: proc_name is $proc_name"
-	db_qd_log Debug "TEMP - QD: local_name is $local_name"
+	db_qd_log QDDebug "TEMP - QD: proc_name is $proc_name"
+	db_qd_log QDDebug "TEMP - QD: local_name is $local_name"
 
 	# set full_name "acs.$rest.${proc_name}.${local_name}"
 	set full_name [db_qd_make_absolute_path "${rest}.${proc_name}." $local_name]
     }
 
-    db_qd_log Debug "generated fullname of $full_name"
+    db_qd_log QDDebug "generated fullname of $full_name"
+    
+    # aks - making debug output actually useable
+    if {[llength $proc_name] > 1} {
+        
+        set proc_name_with_parameters "[lindex $proc_name 0] "
+        
+        set i 1
+        foreach parameter [lrange $proc_name  1 end] {
+            append proc_name_with_parameters "parameter$i: $parameter " 
+            incr i
+        }
+    } else {
+        set proc_name_with_parameters $proc_name
+    }
+
+    db_qd_log QDDebug "db_qd_get_fullname: following query in file: $url proc: $proc_name_with_parameters"
+
     return $full_name
 }
 
-# Fetch a query with a given name
-#
-# This procedure returns the latest FullQuery data structure
-# given proper scoping rules for a complete/global query name.
-# This may or may not be cached, the caller need not know.
-proc db_qd_fetch {fullquery_name {rdbms {}}} {
+ad_proc db_qd_fetch {fullquery_name {rdbms {}}} {
+    Fetch a query with a given name
+
+    This procedure returns the latest FullQuery data structure
+    given proper scoping rules for a complete/global query name.
+    This may or may not be cached, the caller need not know.
+} { 
     # For now we consider that everything is cached
     # from startup time
     return [db_qd_internal_get_cache $fullquery_name]
 }
 
-# Do the right thing 
-proc db_qd_replace_sql {statement_name sql} {
+ad_proc db_qd_replace_sql {statement_name sql} {
+    @return sql for statement_name (defaulting to sql if not found)
+} { 
     set fullquery [db_qd_fetch $statement_name]
 
     if {![empty_string_p $fullquery]} {
@@ -333,23 +417,27 @@
     return $sql
 }
 
-# fetch a query snippet.  used to provide db-specific query snippets when 
-# porting highly dynamic queries.  (OpenACS - DanW)
-proc db_map {snippet_name} {
+ad_proc db_map {snippet_name} {
+    fetch a query snippet.  used to provide db-specific query snippets when 
+    porting highly dynamic queries.  (OpenACS - DanW)
+} { 
     set fullname [db_qd_get_fullname $snippet_name]
     set fullquery [db_qd_fetch $fullname]
     set sql [db_fullquery_get_querytext $fullquery]
 
-    db_qd_log Debug "PARTIALQUERY FOR $fullname: $sql"
+    db_qd_log QDDebug "PARTIALQUERY FOR $fullname: $sql"
     return [uplevel 1 [list subst -nobackslashes $sql]]
 }
 
-# Check compatibility of a FullQuery against an RDBMS
-#
-# This procedure returns true or false. The RDBMS argument
-# can be left out, in which case, the currently running RDBMS
-# is the one against which compatibility will be checked.
-proc db_fullquery_compatible_p {fullquery {rdbms {}}} {
+ad_proc db_fullquery_compatible_p {fullquery {rdbms {}}} {
+    Check compatibility of a FullQuery against an RDBMS
+
+    This procedure returns true or false. The RDBMS argument
+    can be left out, in which case, the currently running RDBMS
+    is the one against which compatibility will be checked.
+
+    NOTE: not complete -- should return something depending on compatibility of RDBMSs
+} { 
     set query_rdbms [db_fullquery_get_rdbms $fullquery]
 
     # NOTE: not complete
@@ -366,22 +454,23 @@
 #
 ######################################################
 
-# Load up a bunch of queries from a file pointer
-#
-# The file_tag parameter is for later flushing of a series
-# of queries when a particular query file has been changed.
-#
-# DRB: it is now used to track the mtime of the query file when loaded,
-# used by the APM to determine when a package should be reloaded.  This
-# code depends on the file tag parameter being set to the actual file path
-# to the query file.
 
-proc db_qd_internal_load_queries {file_pointer file_tag} {
+ad_proc db_qd_internal_load_queries {file_pointer file_tag} {
+    Load up a bunch of queries from a file pointer
+
+    The file_tag parameter is for later flushing of a series
+    of queries when a particular query file has been changed.
+
+    DRB: it is now used to track the mtime of the query file when loaded,
+    used by the APM to determine when a package should be reloaded.  This
+    code depends on the file tag parameter being set to the actual file path
+    to the query file.
+} { 
     # While there are surely efficient ways of loading large files,
     # we're going to assume smaller files for now. Plus, this doesn't happen
     # often.
 
-    db_qd_log Debug "Loading $file_tag"
+    db_qd_log QDDebug "Loading $file_tag"
 
     # Read entire contents
     set whole_file [read $file_pointer]
@@ -392,18 +481,16 @@
     # Iterate and parse out each query
     set parsing_state [db_qd_internal_parse_init $whole_file $file_tag]
     
-    db_qd_log Debug "parsing state - $parsing_state"
-
     # We need this for queries with relative paths
     set acs_file_path [ad_make_relative_path $file_tag]
     set queryname_root [db_qd_internal_get_queryname_root $acs_file_path]
 
-    db_qd_log Debug "queryname root is $queryname_root"
+    db_qd_log QDDebug "db_qd_internal_load_queries: \n file: [lindex $parsing_state 4] \n default_rdbms: [lindex $parsing_state 3] \n queryname_root: $queryname_root"
 
     while {1} {
 	set result [db_qd_internal_parse_one_query $parsing_state]
 	
-	db_qd_log Debug "one parse result -$result-"
+	db_qd_log QDDebug "one parse result -$result-"
 
 	# If we get the empty string, we are done parsing
 	if {$result == ""} {
@@ -413,7 +500,7 @@
 	set one_query [lindex $result 0]
 	set parsing_state [lindex $result 1]
 
-	db_qd_log Debug "loaded one query - [db_fullquery_get_name $one_query]"
+	db_qd_log QDDebug "loaded one query - [db_fullquery_get_name $one_query]"
 
 	# Relative Path for the Query
 	if {[db_qd_relative_path_p [db_fullquery_get_name $one_query]]} {
@@ -429,7 +516,7 @@
 
 	    set one_query $new_fullquery
 
-	    db_qd_log Debug "relative path, replaced name with $new_name"
+	    db_qd_log QDDebug "relative path, replaced name with $new_name"
 	}
 
 	# Store the query
@@ -442,9 +529,10 @@
 }
 
 
-# Load from Cache
-proc db_qd_internal_get_cache {fullquery_name} {
 
+ad_proc db_qd_internal_get_cache {fullquery_name} {
+    Load from Cache
+} { 
     # If we have no record
     if {![nsv_exists OACS_FULLQUERIES $fullquery_name]} {
 	return ""
@@ -459,7 +547,7 @@
     }
 
     # See if we have the correct location for this query
-    db_qd_log Debug "query $fullquery_name from [db_fullquery_get_load_location $fullquery_array]"
+    db_qd_log QDDebug "query $fullquery_name from [db_fullquery_get_load_location $fullquery_array]"
 
     # reload the fullquery
     set fullquery_array [nsv_get OACS_FULLQUERIES $fullquery_name]
@@ -468,10 +556,9 @@
     return $fullquery_array
 }
 
-# Store in Cache
-#
-# The load_location is the file where this query was found
-proc db_qd_internal_store_cache {fullquery} {
+ad_proc db_qd_internal_store_cache {fullquery} {
+    Store in Cache.  The load_location is the file where this query was found.
+} { 
 
     # Check if it's compatible at all!
     if {![db_rdbms_compatible_p [db_fullquery_get_rdbms $fullquery] [db_current_rdbms]]} {
@@ -481,7 +568,7 @@
 
     set name [db_fullquery_get_name $fullquery]
 
-    db_qd_log Debug "Query $name is compatible! fullquery = $fullquery, name = $name"
+    db_qd_log QDDebug "Query $name is compatible! fullquery = $fullquery, name = $name"
 
     # If we already have a query for that name, we need to
     # figure out which one is *most* compatible.
@@ -494,8 +581,10 @@
     nsv_set OACS_FULLQUERIES $name $fullquery
 }
 
-# Flush queries for a particular file path, and reload them
-proc db_qd_internal_load_cache {file_path} {
+
+ad_proc db_qd_internal_load_cache {file_path} {
+    Flush queries for a particular file path, and reload them
+} {
     # First we actually need to flush queries that are associated with that file tag
     # in case they are not all replaced by reloading that file. That is nasty! Oh well.
 
@@ -512,7 +601,9 @@
 ## NAMING
 ##
 
-proc db_qd_internal_get_queryname_root {relative_path} {
+ad_proc db_qd_internal_get_queryname_root {relative_path} {
+    @return relative path with trailing .
+} { 
     # remove the prepended "/packages/" string
     regsub {^\/?packages\/} $relative_path {} relative_path
 
@@ -540,8 +631,9 @@
 ## The architecture of this parsing scheme allows for streaming XML parsing
 ## in the future. But right now we keep things simple
 
-# Initialize the parsing state
-proc db_qd_internal_parse_init {stuff_to_parse file_path} {
+ad_proc db_qd_internal_parse_init {stuff_to_parse file_path} {
+    Initialize the parsing state
+} { 
     
     # Do initial parse
     set parsed_doc [xml_parse -persist $stuff_to_parse]
@@ -554,29 +646,28 @@
 
     # Check that it's a queryset
     if {[xml_node_get_name $root_node] != "queryset"} {
-	db_qd_log Debug "OH OH, error, first node is [xml_node_get_name $root_node]"
-	# CHANGE THIS: throw an error!!!
-	return ""
+	db_qd_log Error "OH OH, error, first node is [xml_node_get_name $root_node] and not 'queryset'"
+        return ""
     }
 
     # Extract the default RDBMS if there is one
     set rdbms_nodes [xml_node_get_children_by_name $root_node rdbms]
     if {[llength $rdbms_nodes] > 0} {
 	set default_rdbms [db_rdbms_parse_from_xml_node [lindex $rdbms_nodes 0]]
-	db_qd_log Debug "Detected DEFAULT RDBMS for whole queryset: $default_rdbms"
+	db_qd_log QDDebug "Detected DEFAULT RDBMS for whole queryset: $default_rdbms"
     } else {
 	set default_rdbms ""
     }
 
     set parsed_stuff [xml_node_get_children_by_name $root_node fullquery]
+    db_qd_log QDDebug "db_qd_internal_parse_init extra info : index: $index; parsed_stuff: $parsed_stuff; parsed_doc: $parsed_doc;"
 
-    db_qd_log Debug "end of parse_init: $index; $parsed_stuff; $parsed_doc; $default_rdbms; $file_path"
-
     return [list $index $parsed_stuff $parsed_doc $default_rdbms $file_path]
 }
 
-# Parse one query using the query state
-proc db_qd_internal_parse_one_query {parsing_state} {
+ad_proc db_qd_internal_parse_one_query {parsing_state} {
+    Parse one query using the query state
+} { 
     
     # Find the index that we're looking at
     set index [lindex $parsing_state 0]
@@ -591,16 +682,12 @@
     set default_rdbms [lindex $parsing_state 3]
     set file_path [lindex $parsing_state 4]
 
-    db_qd_log Debug "default_rdbms is $default_rdbms"
-
-    db_qd_log Debug "node_list is $node_list with length [llength $node_list] and index $index"
-
     # BASE CASE
     if {[llength $node_list] <= $index} {
 	# Clean up
 	xml_doc_free $parsed_doc
 
-	db_qd_log Debug "Cleaning up, done parsing"
+	db_qd_log QDDebug "Cleaning up, done parsing"
 
 	# return nothing
 	return ""
@@ -625,9 +712,10 @@
 }
 
 
-# Parse one query from an XML node
-proc db_qd_internal_parse_one_query_from_xml_node {one_query_node {default_rdbms {}} {file_path {}}} {
-    db_qd_log Debug "parsing one query node in XML with name -[xml_node_get_name $one_query_node]-"
+ad_proc db_qd_internal_parse_one_query_from_xml_node {one_query_node {default_rdbms {}} {file_path {}}} {
+    Parse one query from an XML node
+} { 
+    db_qd_log QDDebug "parsing one query node in XML with name -[xml_node_get_name $one_query_node]-"
 
     # Check that this is a fullquery
     if {[xml_node_get_name $one_query_node] != "fullquery"} {
@@ -644,7 +732,7 @@
     
     # If we have no RDBMS specified, use the default
     if {[llength $rdbms_nodes] == 0} {
-	db_qd_log Debug "Wow, Nelly, no RDBMS for this query, using default rdbms $default_rdbms"
+	db_qd_log QDDebug "Wow, Nelly, no RDBMS for this query, using default rdbms $default_rdbms"
 	set rdbms $default_rdbms
     } else {
 	set rdbms_node [lindex $rdbms_nodes 0]
@@ -654,8 +742,9 @@
     return [db_fullquery_create $queryname $querytext [list] "" $rdbms $file_path]
 }
 
-# Parse and RDBMS struct from an XML fragment node
-proc db_rdbms_parse_from_xml_node {rdbms_node} {
+ad_proc db_rdbms_parse_from_xml_node {rdbms_node} {
+    Parse and RDBMS struct from an XML fragment node
+} { 
     # Check that it's RDBMS
     if {[xml_node_get_name $rdbms_node] != "rdbms"} {
 	db_qd_log Debug "PARSER = BAD RDBMS NODE!"
@@ -666,7 +755,7 @@
     set type [xml_node_get_content [xml_node_get_first_child_by_name $rdbms_node type]]
     set version [xml_node_get_content [xml_node_get_first_child_by_name $rdbms_node version]]
 
-    db_qd_log Debug "PARSER = RDBMS parser - $type - $version"
+    db_qd_log QDDebug "PARSER = RDBMS parser - $type - $version"
 
     return [db_rdbms_create $type $version]
 }
@@ -676,17 +765,21 @@
 ## RELATIVE AND ABSOLUTE QUERY PATHS
 ##
 
-# The token that indicates the root of all queries
-proc db_qd_root_path {} {
+ad_proc db_qd_root_path {} {
+    The token that indicates the root of all queries
+} { 
     return "dbqd."
 }
 
-proc db_qd_null_path {} {
+ad_proc db_qd_null_path {} {
+    The null path 
+} { 
     return "[db_qd_root_path].NULL"
 }
 
-# Check if the path is relative
-proc db_qd_relative_path_p {path} {
+ad_proc db_qd_relative_path_p {path} {
+    Check if the path is relative
+} { 
     set root_path [db_qd_root_path]
     set root_path_length [string length $root_path]
 
@@ -698,16 +791,18 @@
     }
 }
 
-# Make a path absolute
-proc db_qd_make_absolute_path {relative_root suffix} {
+
+ad_proc db_qd_make_absolute_path {relative_root suffix} {
+    Make a path absolute
+} { 
     return "[db_qd_root_path]${relative_root}$suffix"
 }
 
 
 ##
 ## Extra Utilities to Massage the system and Rub it in all the right ways
 ##
-proc db_qd_internal_prepare_queryfile_content {file_content} {
+ad_proc db_qd_internal_prepare_queryfile_content {file_content} {
     
     set new_file_content ""
 
@@ -749,7 +844,7 @@
 	set rest_of_file_content [string range $rest_of_file_content [expr "$first_querytext_close + $querytext_close_len"] end]
     }
 
-    db_qd_log Debug "new massaged file content: \n $new_file_content \n"
+    db_qd_log QDDebug "new massaged file content: \n $new_file_content \n"
 
     return $new_file_content
 }
@@ -759,9 +854,16 @@
 ## Logging
 ##
 
-proc db_qd_log {level msg} {
-    # Centralized DB QD logging
-    # We switch everything to debug for now
-    ns_log $level "QD_LOGGER = $msg"
+ad_proc db_qd_log {level msg} {
+    Centralized DB QD logging
+    If you want to debug the DQ, change QDDebug below to Debug
+} { 
+    if {![string equal "QDDebug" $level]} {
+        ns_log $level "$msg"
+    }
 }
 
+# clean up after ourselves here.
+if { $remove_ad_proc_p } { 
+    rename ad_proc {}
+}