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 ""} } { - Returns a list of ns_sets with the values of each column of each row - returned byt he sql query specified. + 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 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,9 +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 query sql, saving results in variables
+
+
+ Performs the SQL query sql, saving results in variables
of the form
var_name:1, var_name:2, etc,
setting var_name:rowcount to the total number
@@ -519,7 +546,7 @@
upvar $level_up "$var_name:rowcount" counter
upvar $level_up "$var_name:columns" columns
- if { !$append_p } {
+ if { !$append_p || ![info exists counter]} {
set counter 0
}
@@ -534,7 +561,7 @@
lappend local_columns [ns_set key $selection $i]
}
set local_columns [concat $local_columns $extend]
- if { !$append_p } {
+ if { !$append_p || ![info exists columns] } {
# store the list of columns in the var_name:columns variable
set columns $local_columns
} else {
@@ -621,8 +648,17 @@
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, setting variables to column values. Returns 1 if a row is returned, or 0 if no row is returned.
+ 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.
} {
ad_arg_parser { bind column_array column_set } $args
@@ -668,8 +704,17 @@
}
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, setting variables to column values. Raises an error if no rows are returned.
+ 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.
} {
if { ![uplevel db_0or1row $args] } {
@@ -679,14 +724,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. Multiple db_transactions 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 to error_code
+ To handle errors, use db_transaction {transaction_code} on_error {error_code_block}. Any error generated in
+ transaction_code will be caught automatically and process control will transfer to error_code_block
with a variable errmsg 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 error_code the transaction will be aborted.
+ error message to the user. Following the execution of error_code_block the transaction will be aborted.
If you want to explicity abort the transaction, call db_abort_transaction
from within the transaction_code block or the error_code block.
@@ -715,7 +762,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 +919,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 {