Index: openacs.org-dev/packages/acs-templating/tcl/query-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-templating/tcl/query-procs.tcl,v
diff -u -r1.1.1.1 -r1.1.1.2
--- openacs.org-dev/packages/acs-templating/tcl/query-procs.tcl	9 Jul 2002 17:34:59 -0000	1.1.1.1
+++ openacs.org-dev/packages/acs-templating/tcl/query-procs.tcl	8 Oct 2002 15:46:50 -0000	1.1.1.2
@@ -33,52 +33,44 @@
 nsv_set __template_query_persistent_timeout . .
 
 
-# @public query
-
-# Perform a database query
-
-# @option maxrows    Limits the query results of a multirow query
-#                    to a fixed number of rows.
-# @option cache      Cache the query results keyed on an identifier
-#                    that is unique for both the query and the bind variables
-#                    used in the query.  The cached result reflects
-#                    any initial specification of maxrows and startrows.
-# @option refresh    Force a query to be performed even if it is cached,
-#                    and refresh the cache.
-#                    Only applicable if the cache option is specified as well.
-#                    Does not affect a previously specified timeout period.
-# @option timeout    The maximum period of time for which the cached results
-#                    are valid in seconds.  Only applicable for
-#                    persistently cached results.
-# @option persistent Cache the query results persistently, so that
-#                    all subsequent requests use the results.
-
 ad_proc -public template::query { statement_name result_name type sql args } {
     Public interface to template query api.  This routine parses the arguements and
     dispatches to the query command specified by the type arguement.
 
- @option maxrows    Limits the query results of a multirow query
-                    to a fixed number of rows.
- @option cache      Cache the query results keyed on an identifier
-                    that is unique for both the query and the bind variables
-                    used in the query.  The cached result reflects
-                    any initial specification of maxrows and startrows.
- @option refresh    Force a query to be performed even if it is cached,
-                    and refresh the cache.
-                    Only applicable if the cache option is specified as well.
-                    Does not affect a previously specified timeout period.
- @option timeout    The maximum period of time for which the cached results
-                    are valid in seconds.  Only applicable for
-                    persistently cached results.
- @option persistent Cache the query results persistently, so that
-                    all subsequent requests use the results.
+    @option maxrows    Limits the query results of a multirow query
+                       to a fixed number of rows.
 
-    @return 1 if query was a success, 0 if it failed
+    @option cache      Cache the query results keyed on an identifier
+                       that is unique for both the query and the bind variables
+                       used in the query.  The cached result reflects
+                       any initial specification of maxrows and startrows.
+
+    @option refresh    Force a query to be performed even if it is cached,
+                       and refresh the cache.
+                       <p>
+                       Only applicable if the cache option is specified as
+                       well. Does not affect a previously specified timeout 
+                       period.
+
+    @option timeout    The maximum period of time for which the cached results
+                       are valid in seconds.  Only applicable for
+                       persistently cached results.
+
+    @option persistent Cache the query results persistently, so that
+                       all subsequent requests use the results.
+
     @param statement_name Standard db_api query name
-    @param result_name Tcl variable name when doing an uplevel to set the returned result
+
+    @param result_name Tcl variable name when doing an uplevel to 
+           set the returned result
+
     @param type The query type
+
     @param sql The sql to be used for the query
+
     @param args Optional args: uplevel, cache, maxrows
+
+    @return 1 if query was a success, 0 if it failed
 } {
 
   set sql [string trim $sql]
@@ -121,14 +113,16 @@
   return $ret_code
 }
 
-# @private onevalue
+ad_proc -private template::query::onevalue { statement_name db result_name sql } {
+    Process a onevalue query.  Use a single array to store the results.
 
-# Process a onevalue query.  Use a single array to store the results.
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
 
-ad_proc -private template::query::onevalue { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 
 } {
@@ -151,14 +145,16 @@
   }
 }
 
-# @private onerow
+ad_proc -private template::query::onerow { statement_name db result_name sql } {
+    Process a onerow query.  Use a single array to store the results.
 
-# Process a onerow query.  Use a single array to store the results.
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
 
-ad_proc -private template::query::onerow { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -191,16 +187,18 @@
   }
 }
 
-# @private multirow
+ad_proc -private template::query::multirow { statement_name db result_name sql } {
+    Process a multirow query.  Use an array for each row row in the
+    result.  Arrays are named name0, name1, name2 etc.  The variable
+    name.rowcount is also defined for checking and iteration.
 
-# Process a multirow query.  Use an array for each row row in the
-# result.  Arrays are named name0, name1, name2 etc.  The variable
-# name.rowcount is also defined for checking and iteration.
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
 
-ad_proc -private template::query::multirow { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -273,9 +271,15 @@
 }
 
 ad_proc -private template::query::multilist { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
+    Process a multilist query.
+
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
+
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -307,15 +311,20 @@
   return $rows
 }
 
-# Creates a data source where the values for each row 
-# are returned as a list.  Rows are grouped according
-# to the column values specified in the -groupby option
-# See template::util::lnest for more details.
 
 ad_proc -private template::query::nestedlist { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
+    Creates a data source where the values for each row 
+    are returned as a list.  Rows are grouped according
+    to the column values specified in the -groupby option
+    See template::util::lnest for more details.
+
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
+
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -356,9 +365,15 @@
 }
 
 ad_proc -private template::query::onelist { statement_name db result_name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
+    Process a onelist query.
+
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
+
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -382,9 +397,15 @@
 }
 
 ad_proc -private template::query::dml { statement_name db name sql } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
+    Process an SQL statement that is not a query; perhaps update or insert
+
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
+
     @param db Database handle
+
     @param result_name Tcl variable name to use when setting the result
+
     @param sql Query to use when processing this command
 } {
 
@@ -393,17 +414,17 @@
   db_exec dml $db $statement_name "$sql" 3
 }
 
-# @private get_cached_result
 
-# Looks in the appropriate cache for the named query result
-# If a valid result is found, then sets the result in the returning
-# stack frame.
-
-# @return 1 if result was successfully retrieved, 0 if failed
-
 ad_proc -private get_cached_result { name type } {
+    Looks in the appropriate cache for the named query result
+    If a valid result is found, then sets the result in the returning
+    stack frame.
+
     @param name Name of cached result-set
+
     @param type Type of query
+
+    @return 1 if result was successfully retrieved, 0 if failed
 } {
 
   upvar opts opts
@@ -470,8 +491,6 @@
   return $success
 }
 
-# @private set_cached_result
-
 ad_proc -private set_cached_result {} {
 
     Places a query result in the appropriate cache.
@@ -505,12 +524,16 @@
   }
 }
 
-# Deprecated!
+ad_proc -public -deprecated template::query::iterate { statement_name sql body } {
+    @param statement_name Standard db_api statement name used to hook 
+                          into query dispatcher
 
-ad_proc -public template::query::iterate { statement_name sql body } {
-    @param statement_name Standard db_api statement name used to hook into query dispatcher
     @param sql Query to use when processing this command
-    @param body Code body to be execute for each result row of the returned query
+
+    @param body Code body to be execute for each result row of the 
+                returned query
+
+    @see db_foreach
 } {
 
     db_with_handle db {
@@ -538,9 +561,6 @@
     }
 }
 
-# Flush the cached queries where the query name matches the
-# specified string match
-
 ad_proc -private template::query::flush_cache { cache_match } {
 
     Flush the cached queries where the query name matches the
@@ -569,31 +589,81 @@
 
 }
 
-# Perform get/set operations on a multirow datasource
 
+ad_proc -public multirow {
+    {-ulevel 1}
+    {-local:boolean}
+    op
+    name
+    args
+} { 
+    multirow is really template::multirow or possibly 
+    template::query::multirow depending on context.
+    the "template::" or "template::query::"
+    may be ommitted depending on what the namespace 
+    is.  .tcl pages are evaluated in the template:: 
+    namespace.
+
+    @see template::multirow
+    @see template::query::multirow
+} -        
+
 ad_proc -public template::multirow { 
   {-ulevel 1}
   {-local:boolean}
-  op
+  command
   name
   args
 } {
-  @param local If set, the multirow will be looked for in the scope the number of levels up
-         given by ulevel (normally the caller's scope), instead of the
-         [template::adp_level] scope, which is the default.
-  @param ulevel Used in conjunction with the "local" parameter to specify how many levels up
-         the multirow variable resides.
-  @param op Multirow datasource operation: create, extend, append, size, get, set, foreach
-  @param name Name of the multirow datasource
-  @param args optional args
+    Create/Manipulate a multirow datasource (for use with &lt;multiple&gt; tags)
+
+    <dl>
+    <dt> <b>template::multirow create datasourcename column [column ...]</b></dt>
+    <dd> creates a multirow datasource of datasourcename </dd>
+    <dt> <b>template::multirow extend datasourcename column [column ...] </b></dt>
+    <dd> extend adds a column to an existing multirow</dd>
+    <dt> <b>template::multirow append datasourcename value [value ...]</b></dt>
+    <dd> appends the row to an existing multirow.</dd>
+    <dt> <b>template::multirow size datasourcename</b></dt>
+    <dd> returns the rowcount</dd>
+    <dt> <b>template::multirow get datasourcename rownum [column]</b></dt>
+    <dd> returns the row of of data (or the particular row/column if column is provided)</dd>
+    <dt> <b>template::multirow get datasourcename rownum column value</b></dt>
+    <dd> set an element value</dd>
+    <dt> <b>template::multirow foreach datasource code </b></dt>
+    <dd> evaluate code block for each row (like db_foreach)</dd>
+    <dt> <b>template::multirow upvar datasource [new_name]</b></dt>
+    <dd> upvar the multirow, aliasing to new_name if provided</dd>
+    </dl>
+    
+    @param local 
+           If set, the multirow will be looked for in the scope the number 
+           of levels up given by ulevel (normally the caller's scope), 
+           instead of the <code>[template::adp_level]</code> scope, which 
+           is the default.
+
+    @param ulevel 
+           Used in conjunction with the "local" parameter to specify how 
+           many levels up the multirow variable resides.
+
+    @param command
+           Multirow datasource operation: create, extend, append, 
+                                          size, get, set, foreach
+
+    @param name Name of the multirow datasource
+
+    @param args optional args
+
+    @see db_multirow
+    @see template::query::multirow
 } {  
   if { $local_p } {
     set multirow_level_up $ulevel
   } else {
     set multirow_level_up \#[adp_level]
   }
   
-  switch -exact $op {
+  switch -exact $command {
 
     create {
       upvar $multirow_level_up $name:rowcount rowcount $name:columns columns
@@ -739,7 +809,7 @@
     }
 
     default {
-      error "Unknown op $op in template::multirow.
+      error "Unknown command $command in template::multirow.
       Must be create, extend, append, get, set, size, upvar, or foreach."
     }
   }