db_foreach-db_foreachstatement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ +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
@@ -407,7 +407,7 @@
db_1row-db_1rowstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] \ +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 the query does not return exactly
@@ -421,15 +421,15 @@
db_0or1row-db_0or1rowstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] \ +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 and returns 1. If no rows are returned,
returns 0. If more than one row is returned, throws an error.
db_string-db_stringstatement-namesql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ] +db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
Returns the first column of the result of SQL query sql.
If sql doesn't return a row,
returns default (or throws an error if
@@ -438,38 +438,38 @@
db_nextval-db_nextvalsequence-name +db_nextval sequence-name
Returns the next value for the sequence sequence-name (using a SQL statement
like SELECTsequence-name.nextval FROM DUAL). If sequence pooling is
enabled for the sequence, transparently uses a value from the pool
if available to save a round-trip to the database.
db_list-db_liststatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +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.
db_list_of_lists-db_list_of_listsstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list, each element of which is a list of all
column values in a row of the result of SQL query sql.
If sql doesn't return any
rows, returns an empty list. (Analogous to database_to_tcl_list_list.)
db_list_of_ns_sets-db_list_of_ns_setsstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +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.
db_dml-db_dmlstatement-namesql \ +db_dml statement-name sql \ [ -bind bind_set_id | -bind bind_value_list ] \ [ -blobs blob_list | -clobs clob_list | -blob_files blob_file_list | -clob_files clob_file_list ] @@ -501,11 +501,11 @@ db_blob_get_file
-db_write_clobstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_write_blobstatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_blob_get_filestatement-namesql [ -bind bind_set_id | -bind bind_value_list ] +db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Analogous to ns_ora
write_clob/write_blob/blob_get_file.
@@ -514,7 +514,7 @@
db_transaction
-db_transactioncode_block [ on_error { code_block } ]
+db_transaction code_block [ on_error { code_block } ]
Executes code_block transactionally.
Nested transactions are supported (end
transaction is transparently ns_db dml'ed when the outermost
@@ -614,7 +614,7 @@
db_with_handle
-db_with_handlevarcode_block
+db_with_handle var code_block
Places a database handle into the variable var
and executes code_block. This is useful when
you don't want to have to use the new API (db_foreach, db_1row, etc.), but need to use database
Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v
diff -u -r1.52.2.5 -r1.52.2.6
--- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 1 Nov 2019 13:16:18 -0000 1.52.2.5
+++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 2 May 2021 20:18:15 -0000 1.52.2.6
@@ -371,7 +371,8 @@
above.
db_foreach
-db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+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
@@ -390,7 +391,9 @@
The code block may contain break statements (which terminate the
loop and flush the database handle) and continue statements
(which continue to the next row of the loop).
db_1row
-db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+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 the query does not return exactly 1 row.
Example:
@@ -400,12 +403,16 @@
# Now $foo and $bar are set.
db_0or1row
-db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \
+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 and returns 1. If no rows are returned,
returns 0. If more than one row is returned, throws an error.
db_string
-db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
+db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
Returns the first column of the result of SQL query
sql. If sql doesn't return a
row, returns default (or throws an error if
@@ -414,33 +421,42 @@
database_to_tcl_string_or_null.
db_nextval
-db_nextval sequence-name
+db_nextval sequence-name
Returns the next value for the sequence sequence-name (using a
SQL statement like SELECT sequence-name.nextval FROM
DUAL). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database.
db_list
-db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
+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.
db_list_of_lists
-db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
+db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list, each element of which is a list of all column values
in a row of the result of SQL query sql. If
sql doesn't return any rows, returns an empty list.
(Analogous to database_to_tcl_list_list.)
db_list_of_ns_sets
-db_list_of_ns_sets statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
+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.
db_dml
-db_dml statement-name sql \
+db_dml statement-name sql \
[ -bind bind_set_id | -bind bind_value_list ] \
[ -blobs blob_list | -clobs clob_list |
-blob_files blob_file_list | -clob_files clob_file_list ]
@@ -472,18 +488,25 @@
db_write_blob,
db_blob_get_file
-db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] +db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] +db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] +db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Analogous to ns_ora write_clob/write_blob/blob_get_file.
db_release_unused_handles
db_release_unused_handles
Releases any allocated, unused database handles.
db_transaction-db_transaction code_block [ on_error { code_block } ] +db_transaction code_block [ on_error { code_block } ]
Executes code_block transactionally. Nested
transactions are supported (end transaction is transparently
ns_db dml'ed when the outermost transaction completes). The
@@ -594,8 +617,9 @@
db_with_handledb_with_handle var code_block -
Places a database handle into the variable var and
-executes code_block. This is useful when you don't
+
Places a database handle into the variable var and
+executes code_block. This is useful when you don't
want to have to use the new API (db_foreach,
db_1row, etc.), but need to use database handles explicitly.
Example:
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml,v diff -u -r1.12.2.3 -r1.12.2.4 --- openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml 1 Nov 2019 13:16:18 -0000 1.12.2.3 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/db-api.xml 2 May 2021 20:18:15 -0000 1.12.2.4 @@ -622,7 +622,7 @@- @@ -660,7 +660,7 @@db_foreach statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_foreach statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ] \code_block [ if_no_rowsif_no_rows_block ] - @@ -687,7 +687,8 @@db_1row statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_1row statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ]- @@ -703,7 +704,7 @@db_0or1row statement-name sql [ -bindbind_set_id | -bindbind_value_list ] \ +db_0or1row statement-name +sql [ -bindbind_set_id | -bindbind_value_list ] \ [ -column_arrayarray_name | -column_setset_name ]- db_string statement-name sql [ -defaultdefault ] [ -bindbind_set_id | -bindbind_value_list ] +db_string statement-name sql [ -defaultdefault ] [ -bindbind_set_id | -bindbind_value_list ]Returns the first column of the result of SQL query @@ -721,7 +722,7 @@ - db_nextval sequence-name +db_nextval sequence-name Returns the next value for the sequence sequence-name (using a @@ -737,7 +738,7 @@- db_list statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_list statement-name sql [ -bindbind_set_id | -bindbind_value_list ]Returns a Tcl list of the values in the first column of the result of SQL @@ -753,7 +754,8 @@ - db_list_of_lists statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_list_of_lists +statement-name sql [ -bindbind_set_id | -bindbind_value_list ]Returns a Tcl list, each element of which is a list of all column values @@ -769,7 +771,8 @@ - db_list_of_ns_sets statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_list_of_ns_sets +statement-name sql [ -bindbind_set_id | -bindbind_value_list ]Returns a list of ns_sets with the values of each column of each row @@ -783,7 +786,7 @@ - db_dml statement-name sql \ +db_dml statement-name sql \ [ -bindbind_set_id | -bindbind_value_list ] \ [ -blobsblob_list | -clobsclob_list | -blob_filesblob_file_list | -clob_filesclob_file_list ] @@ -835,11 +838,14 @@- db_write_clob statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_write_clob +statement-name sql [ -bindbind_set_id | -bindbind_value_list ] -db_write_blob statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_write_blob +statement-name sql [ -bindbind_set_id | -bindbind_value_list ] -db_blob_get_file statement-name sql [ -bindbind_set_id | -bindbind_value_list ] +db_blob_get_file +statement-name sql [ -bindbind_set_id | -bindbind_value_list ]Analogous to ns_ora write_clob/write_blob/blob_get_file . @@ -865,7 +871,7 @@- db_transaction code_block [ on_error {code_block } ] +db_transaction code_block [ on_error {code_block } ]Executes transactionally. Nested @@ -938,7 +944,7 @@ code_block @@ -1038,7 +1044,7 @@ db_multirow [ -local ] [ -append ] [ -extendcolumn_list ] \ -var-name statement-name sql \ +var-name statement-name sql \ [ -bindbind_set_id | -bindbind_value_list ] \code_block [ if_no_rowsif_no_rows_block ] db_with_handle - db_with_handle var code_block +db_with_handle var code_block