Index: openacs-4/packages/acs-tcl/tcl/00-database-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-tcl/tcl/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: db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] + 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: db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + + Returns a Tcl list of the values in the first column of the result of SQL query sql. + If sql doesn't return any rows, returns an empty list. Analogous to database_to_tcl_list. + } { ad_arg_parser { bind } $args @@ -258,8 +261,12 @@ } proc_doc db_list_of_lists { statement_name sql args } { + Usage: db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ] - 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 querysql. If + sql doesn't return any rows, returns an empty list. + Analogous to database_to_tcl_list_list. } { ad_arg_parser { bind } $args @@ -289,12 +296,14 @@ sql {args ""} } { + Usage: db_list_of_ns_sets statement-name sql [ -bind bind_set_id | -bind bind_value_list ] + 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: +
+ db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] \ + code_block [ if_no_rows if_no_rows_block ] - Performs the SQL query $sql, executing code_block once for each row with variables set to column values. ++ Performs the SQL query sql, executing + code_block once for each row with variables set to + column values (or a set or array populated if -column_array or + column_set is specified). If the query returns no rows, executes + if_no_rows_block (if provided). +
Example:
db_foreach greeble_query "select foo, bar from greeble" { @@ -425,8 +444,17 @@ var_name statement_name sql - args } { + args +} { + Usage: ++ + db_multirow [ -local ] [ -append ] [ -extend column_list ] \ + var-name statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + code_block [ if_no_rows if_no_rows_block ] ++ Performs the SQL querysql
, saving results in variables of the formvar_name:1
,var_name:2
, etc, @@ -621,9 +649,18 @@ ad_proc db_0or1row { statement_name sql args } { + Usage: ++ + db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] + ++ 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: ++ + db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ + [ -column_array array_name | -column_set set_name ] + ++ 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: db_transaction code_block [ on_error { error_code_block } ] + 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. Multipledb_transaction
s may be nested (end transaction is transparently ns_db dml'ed when the outermost transaction completes).- To handle errors, use
db_transaction {transaction_code} on_error {error_code}
. Any error generated in -transaction_code
will be caught automatically and process control will transfer toerror_code
+ To handle errors, usedb_transaction {transaction_code} on_error {error_code_block}
. Any error generated in +transaction_code
will be caught automatically and process control will transfer toerror_code_block
with a variableerrmsg
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 oferror_code
the transaction will be aborted. + error message to the user. Following the execution oferror_code_block
the transaction will be aborted. If you want to explicity abort the transaction, calldb_abort_transaction
from within the transaction_code block or the error_code block.@@ -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 {