Index: openacs-4/packages/acs-tcl/tcl/00-database-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-tcl/tcl/Attic/00-database-procs.tcl,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-tcl/tcl/00-database-procs.tcl 12 May 2002 20:57:02 -0000 1.12
+++ openacs-4/packages/acs-tcl/tcl/00-database-procs.tcl 30 Jul 2002 19:20:39 -0000 1.13
@@ -213,7 +213,8 @@
}
proc_doc db_string { statement_name sql args } {
-
+ Usage: <b>db_string</b> <i>statement-name sql</i> [ <tt>-default</tt> <i>default</i> ] [ <tt>-bind</tt> <i>bind_set_id</i> | <tt>-bind</tt> <i>bind_value_list</i> ]
+
Returns the first column of the result of the SQL query $sql.
If the query doesn't return a row, returns $default (or raises an error if no $default is provided).
@@ -237,9 +238,11 @@
}
proc_doc db_list { statement_name sql args } {
-
- Returns a list containing the first column of each row returned by the SQL query $sql.
-
+ Usage: <b>db_list</b> <i>statement-name sql</i> [ <tt>-bind</tt> <i>bind_set_id</i> | <tt>-bind</tt> <i>bind_value_list</i> ]
+
+ Returns a Tcl list of the values in the first column of the result of SQL query <tt>sql</tt>.
+ If <tt>sql</tt> doesn't return any rows, returns an empty list. Analogous to <tt>database_to_tcl_list</tt>.
+
} {
ad_arg_parser { bind } $args
@@ -258,8 +261,12 @@
}
proc_doc db_list_of_lists { statement_name sql args } {
+ Usage: <b>db_list_of_lists</b> <i>statement-name sql</i> [ <tt>-bind</tt> <i>bind_set_id</i> | <tt>-bind</tt> <i>bind_value_list</i> ]
- Returns a list containing lists of the values in each column of each row returned by the SQL query $sql.
+ Returns a Tcl list, each element of which is a list of all column
+ values in a row of the result of the SQL query<tt>sql</tt>. If
+ <tt>sql</tt> doesn't return any rows, returns an empty list.
+ Analogous to <tt>database_to_tcl_list_list</tt>.
} {
ad_arg_parser { bind } $args
@@ -289,12 +296,14 @@
sql
{args ""}
} {
+ Usage: <b>db_list_of_ns_sets</b> <i>statement-name sql</i> [ <tt>-bind</tt> <i>bind_set_id</i> | <tt>-bind</tt> <i>bind_value_list</i> ]
+
Returns a list of ns_sets with the values of each column of each row
- returned byt he sql query specified.
+ returned by the sql query specified.
@param statement_name The name of the query.
@param sql The SQL to be executed.
- @param args Any additional arguments, such as a 'if_no_rows'
+ @param args Any additional arguments.
@return list of ns_sets, one per each row return by the SQL query
} {
@@ -315,10 +324,20 @@
}
proc_doc db_foreach { statement_name sql args } {
- Usage: db_foreach statement_name sql [-bind ns_set | list of bind variables] code_block [if_no_rows if_no_rows_code_block]
+ Usage:
+ <pre>
+ <b><i>db_foreach</i></b> <em><i>statement-name sql</i></em> [ -bind <em><i>bind_set_id</i></em> | -bind <em><i>bind_value_list</i></em> ] \
+ [ -column_array <em><i>array_name</i></em> | -column_set <em><i>set_name</i></em> ] \
+ <em><i>code_block</i></em> [ if_no_rows <em><i>if_no_rows_block ]</i></em>
- Performs the SQL query $sql, executing code_block once for each row with variables set to column values.
+ </pre>
+ Performs the SQL query <em><i><tt>sql</tt></i></em>, executing
+ <em><i><tt>code_block</tt></i></em> once for each row with variables set to
+ column values (or a set or array populated if <tt>-column_array</tt> or
+ <tt>column_set</tt> is specified). If the query returns no rows, executes
+ <em><i><tt>if_no_rows_block</tt></i></em> (if provided). </p>
+
<p>Example:
<blockquote><pre>db_foreach greeble_query "select foo, bar from greeble" {
@@ -425,8 +444,17 @@
var_name
statement_name
sql
- args } {
+ args
+} {
+ Usage:
+ <pre>
+ <b><i>
+ db_multirow</i></b> [ -local ] [ -append ] [ -extend <em><i>column_list</i></em> ] \
+ <em><i>var-name statement-name sql</i></em> [ -bind <em><i>bind_set_id</i></em> | -bind <em><i>bind_value_list</i></em> ] \
+ <em><i>code_block</i></em> [ if_no_rows <em><i>if_no_rows_block ]</i></em>
+ </pre>
+
Performs the SQL query <code>sql</code>, saving results in variables
of the form
<code><i>var_name</i>:1</code>, <code><i>var_name</i>:2</code>, etc,
@@ -621,9 +649,18 @@
ad_proc db_0or1row { statement_name sql args } {
+ Usage:
+ <pre>
+ <b><i>
+ db_0or1row</i></b> <i>statement-name sql</i> [ -bind <i>bind_set_id</i> | -bind <i>bind_value_list</i> ] \
+ [ -column_array <i>array_name</i> | -column_set <i>set_name</i> ]
+
+ </pre>
+ Performs the SQL query sql. If a row is returned, sets variables
+ to column values (or a set or array populated if -column_array
+ or column_set is specified) and returns 1. If no rows are returned,
+ returns 0. If more than one row is returned, throws an error.
- Performs the SQL query $sql, setting variables to column values. Returns 1 if a row is returned, or 0 if no row is returned.
-
} {
ad_arg_parser { bind column_array column_set } $args
@@ -668,9 +705,18 @@
}
ad_proc db_1row { args } {
+ Usage:
+ <pre>
+ <b><i>
+ db_1row</i></b> <i>statement-name sql</i> [ -bind <i>bind_set_id</i> | -bind <i>bind_value_list</i> ] \
+ [ -column_array <i>array_name</i> | -column_set <i>set_name</i> ]
+
+ </pre>
+ Performs the SQL query sql. If a row is returned, sets variables
+ to column values (or a set or array populated if -column_array
+ or column_set is specified). If no rows are returned,
+ throws an error.
- Performs the SQL query $sql, setting variables to column values. Raises an error if no rows are returned.
-
} {
if { ![uplevel db_0or1row $args] } {
return -code error "Query did not return any rows."
@@ -679,14 +725,16 @@
ad_proc db_transaction { transaction_code args } {
+ Usage: <b><i>db_transaction</i></b> <i>code_block</i> [ on_error { <i>error_code_block</i> } ]
+
Executes transaction_code with transactional semantics. This means that either all of the database commands
within transaction_code are committed to the database or none of them are. Multiple <code>db_transaction</code>s may be
nested (end transaction is transparently ns_db dml'ed when the outermost transaction completes).<p>
- To handle errors, use <code>db_transaction {transaction_code} on_error {error_code}</code>. Any error generated in
- <code>transaction_code</code> will be caught automatically and process control will transfer to <code>error_code</code>
+ To handle errors, use <code>db_transaction {transaction_code} on_error {error_code_block}</code>. Any error generated in
+ <code>transaction_code</code> will be caught automatically and process control will transfer to <code>error_code_block</code>
with a variable <code>errmsg</code> set. The error_code block can then clean up after the error, such as presenting a usable
- error message to the user. Following the execution of <code>error_code</code> the transaction will be aborted.
+ error message to the user. Following the execution of <code>error_code_block</code> the transaction will be aborted.
If you want to explicity abort the transaction, call <code>db_abort_transaction</code>
from within the transaction_code block or the error_code block.<p>
@@ -715,7 +763,7 @@
global db_state
- set syn_err "db_transaction: Invalid arguments. Use db_transaction { code } \[on_error { error_code }\] "
+ set syn_err "db_transaction: Invalid arguments. Use db_transaction { code } \[on_error { error_code_block }\] "
set arg_c [llength $args]
if { $arg_c != 0 && $arg_c != 2 } {
@@ -872,7 +920,9 @@
ad_proc db_abort_transaction {} {
- Aborts a transaction.
+ Aborts all levels of a transaction. That is if this is called within
+ several nested transactions, all of them are terminated. Use this
+ instead of db_dml "abort" "abort transaction".
} {
global db_state
db_with_handle db {