Index: openacs-4/packages/acs-templating/tcl/query-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/query-procs.tcl,v diff -u -r1.8 -r1.9 --- openacs-4/packages/acs-templating/tcl/query-procs.tcl 9 Jul 2002 15:45:19 -0000 1.8 +++ openacs-4/packages/acs-templating/tcl/query-procs.tcl 1 Sep 2002 19:09:28 -0000 1.9 @@ -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. +
+ 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,14 @@
}
}
-# 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
} {
db_with_handle db {
@@ -538,9 +559,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,23 +587,32 @@
}
-# Perform get/set operations on a multirow datasource
-
ad_proc -public template::multirow {
{-ulevel 1}
{-local:boolean}
op
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
+ Perform get/set operations on a multirow datasource
+
+ @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
} {
if { $local_p } {
set multirow_level_up $ulevel