Index: openacs.org-dev/packages/acs-core-docs/www/xml/kernel/db-api.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-core-docs/www/xml/kernel/db-api.xml,v
diff -u -N -r1.1.1.1 -r1.1.1.2
--- openacs.org-dev/packages/acs-core-docs/www/xml/kernel/db-api.xml 9 Jul 2002 17:34:57 -0000 1.1.1.1
+++ openacs.org-dev/packages/acs-core-docs/www/xml/kernel/db-api.xml 31 Jul 2002 16:30:50 -0000 1.1.1.2
@@ -2,7 +2,8 @@
Database Access API
-by Jon Salz
+by Jon Salz. Revised and expanded by
+Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
@@ -609,52 +610,6 @@
-
-Sequence Pooling
-
-
-The database library can transparently maintain pools of sequence values, so
-that each request for a new sequence value (using db_nextval)
-does not incur a roundtrip to the server. For instance, this functionality is
-very useful in the security/sessions library, which very frequently allocates
-values from the sec_id_seq sequence. To utilize this
-functionality for a particular sequence, register the sequence to be pooled,
-either using the db_register_pooled_sequence procedure at server
-startup time, or by including a configuration parameter of the form
-
-
-
-
-
-PoolSequence.sequence_name_seq=count
-
-
-
-
-in any configuration section in the yourservername.ini
-file, e.g., e.g.,
-
-
-
-
-
-[ns/server/yourservername/acs/security]
-PoolSequence.sec_id_seq=20
-
-
-
-
-The database library will allocate this number of sequence values at server
-startup. It will periodically scan pools and allocate new values for
-sequences which are less than half-full. (This normally occurs every 60
-seconds, and is configurable via the
-PooledSequenceUpdateInterval parameter in the
-[ns/server/yourservername/acs/database] configuration
-section.)
-
-
-
-
API
@@ -665,26 +620,8 @@
release the database handle.
-
-
-
-db_abort_transaction
-
-
-
-db_abort_transaction
-
-
-Aborts all levels of a transaction. That is if this is called within
-several nested transactions, all of them are terminated. Use this insetead of
-db_dml "abort" "abort transaction".
-
-
-
-
-
db_null
@@ -785,55 +722,41 @@
-db_nextval
+db_string
-db_nextval sequence-name
+db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
-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
-(see ).
+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
+default is unspecified). Analogous to
+database_to_tcl_string and
+database_to_tcl_string_or_null.
-db_register_pooled_sequence
+db_nextval
-db_register_pooled_sequence sequence-name pool-size
+db_nextval sequence-name
-Registers the sequence sequence-name to be pooled, with a pool
-size of pool-size sequence values (see ).
+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
+(see ).
-db_string
-
-
-
-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
-default is unspecified). Analogous to
-database_to_tcl_string and
-database_to_tcl_string_or_null.
-
-
-
-
-
db_list
@@ -866,6 +789,20 @@
+db_list_of_ns_sets
+
+
+
+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
@@ -1003,6 +940,99 @@
+db_abort_transaction
+
+
+
+
+db_abort_transaction
+
+
+Aborts all levels of a transaction. That is if this is called within
+several nested transactions, all of them are terminated. Use this insetead of
+db_dml "abort" "abort transaction".
+
+
+
+
+
+
+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.
+
+
+
+ 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]
+}
+
+
+
+
+
db_resultrows
@@ -1059,54 +1089,166 @@
-db_nullify_empty_string
+
+
+
+ db_name
+
+
+
+
+
+
+ db_name
+
+
+
+ Returns the name of the database, as returned by the driver.
+
+
+
+
+
+
+
+ db_type
+
+
+
+
+
+
+ db_type
+
+
+
+ Returns the RDBMS type (i.e. oracle, postgresql) this OpenACS installation is
+ using. The nsv ad_database_type is set up during the bootstrap process.
+
+
+
-
-
-db_nullify_empty_string string
-
+
+
+
+
+ db_compatible_rdbms_p
+
+
+
+
+
+ db_compatible_rdbms_p db_type
+
+
+ Returns 1 if the given db_type is compatible with the current RDBMS.
+
+
+
+
+
+
+
+ db_package_supports_rdbms_p
+
+
+
+
+
+ db_package_supports_rdbms_p db_type_list
+
+
+ Returns 1 if db_type_list contains the current RDMBS type. A package
+ intended to run with a given RDBMS must note this in it's package info
+ file regardless of whether or not it actually uses the database.
+
+
+
-For true SQL purists, we provide the convenience function
-db_nullify_empty_string, which returns
-[db_null] if its string argument is the empty string
-and can be used to encapsulate another Oracle quirk:
+
+
+
+
+ db_legacy_package_p
+
+
+
+
+
+ db_legacy_package_p db_type_list
+
+
+ Returns 1 if the package is a legacy package. We can only tell for certain if
+ it explicitly supports Oracle 8.1.6 rather than the OpenACS more general oracle.
+
+
+
-
+
+
+
+
+ db_version
+
+
+
+
+
+ db_version
+
+
+ Returns the RDBMS version (i.e. 8.1.6 is a recent Oracle version; 7.1 a
+ recent PostgreSQL version.
+
+
+
-
+
+
+
+
+ db_current_rdbms
+
+
+
+
+
+ db_current_rdbms
+
+
+ Returns the current rdbms type and version.
+
+
+
-set baz ""
-
-# Clean out the foo table
-#
-db_dml unused "delete from foo"
-
-db_dml unused "insert into foo(baz) values('$baz')"
-
-set n_rows [db_string unused "select count(*) from foo where baz is null"]
-#
-# $n_rows is 1; in effect, the "baz is null" criterion is matching
-# the empty string we just inserted (because of Oracle's coercion
-# quirk)
-
-
-
-
-To balance out this asymmetry, you can explicitly set baz to
-null by writing:
-
-
-
-
-
-db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
-
-
-
-
+
+
+
+
+ db_known_database_types
+
+
+
+
+
+ db_known_database_types
+
+
+ Returns a list of three-element lists describing the database engines known
+ to OpenACS. Each sublist contains the internal database name (used in file
+ paths, etc), the driver name, and a "pretty name" to be used in selection
+ forms displayed to the user.
+
+
+ The nsv containing the list is initialized by the bootstrap script and should
+ never be referenced directly by user code.
+ Returns the current rdbms type and version.
+
+
+