Index: openacs.org-dev/packages/acs-core-docs/www/xml/developers-guide/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/xml/developers-guide/db-api.xml,v
diff -u -r1.1.1.1 -r1.1.1.2
--- openacs.org-dev/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 9 Jul 2002 17:34:57 -0000 1.1.1.1
+++ openacs.org-dev/packages/acs-core-docs/www/xml/developers-guide/db-api.xml 11 Aug 2002 00:42:48 -0000 1.1.1.2
@@ -16,6 +16,11 @@
coherent API for database access which makes this even easier.
+
+ More detailed information about the DB api is available at
+ .
+
+
@@ -607,6 +612,92 @@
+ db_multirow
+
+
+
+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
+ of the form
+ var_name:1, var_name:2, etc,
+ setting var_name:rowcount to the total number
+ of rows, and setting var_name:columns to a
+ list of column names.
+
+
+
+ Each row also has a column, rownum, automatically
+ added and set to the row number, starting with 1. Note that this will
+ override any column in the SQL statement named 'rownum', also if you're
+ using the Oracle rownum pseudo-column.
+
+
+
+ If the -local is passed, the variables defined
+ by db_multirow will be set locally (useful if you're compiling dynamic templates
+ in a function or similar situations).
+
+
+
+ You may supply a code block, which will be executed for each row in
+ the loop. This is very useful if you need to make computations that
+ are better done in Tcl than in SQL, for example using ns_urlencode
+ or ad_quotehtml, etc. When the Tcl code is executed, all the columns
+ from the SQL query will be set as local variables in that code. Any
+ changes made to these local variables will be copied back into the
+ multirow.
+
+
+
+ You may also add additional, computed columns to the multirow, using the
+ -extend { col_1 col_2 ... } switch. This is
+ useful for things like constructing a URL for the object retrieved by
+ the query.
+
+
+
+ If you're constructing your multirow through multiple queries with the
+ same set of columns, but with different rows, you can use the
+ -append switch. This causes the rows returned by this query
+ to be appended to the rows already in the multirow, instead of starting
+ a clean multirow, as is the normal behavior. The columns must match the
+ columns in the original multirow, or an error will be thrown.
+
+
+
+ Your code block may call continue in order to skip a row
+ and not include it in the multirow. Or you can call break
+ to skip this row and quit looping.
+
+
+
+
+ Notice the nonstandard numbering (everything
+ else in Tcl starts at 0); the reason is that the graphics designer, a non
+ programmer, may wish to work with row numbers.
+
+
+
+ Example:
+
+
+
+db_multirow -extend { user_url } users users_query {
+ select user_id first_names, last_name, email from cc_users
+} {
+ set user_url [acs_community_member_url -user_id $user_id]
+}
+
+
+
+
+
@@ -1095,3 +1186,8 @@
+