Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

table_name (required)

column_name (required)

Returns:

'numeric' for number type columns, 'text' otherwise Throws an error if no such column exists.

Author:

Yon Feldman (yon@arsdigita.com) DEPRECATED: it is unclear what the purpose of this proc is. For instance, on a Linux/Postgres installation, ad_column_type acs_objects object_type -> 'numeric'. When things should happen based on the column type, maybe a better approach is to rely on more complete or consistent api, or on the information schema.

See Also:

• db_column_type, https://wikipedia.org/wiki/Information_schema

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Implementation of subsite::parameter_changed for acs-tcl.

Switches:

-package_id (required)

the package_id of the package the parameter was changed for

-parameter (required)

the parameter name

-value (required)

the new value

See Also:

• callback::subsite::parameter_changed::contract

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Performs the specified SQL query. 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.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-cache_key (optional)

Cache the result using given value as the key. Default is to not cache.

-cache_pool (optional, defaults to "db_cache_pool")

Override the default db_cache_pool

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

-bind (optional)

bind variables, passed either as an ns_set id, or via bind value list

-column_array (optional)

array to be populated with values

-column_set (optional)

ns_set to be populated with values

Parameters:

statement_name (required)

name of the SQL query

sql (required)

SQL query to be executed

Returns:

1 if variables are set, 0 if no rows are returned. If more than one row is returned, throws an error.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__caching, db__0or1row, db__1row

A wrapper for db_0or1row, which produces an error if no rows are returned.

Switches:

-subst (optional, defaults to "all")

Returns:

1 if variables are set, otherwise an exception is thrown.

See Also:

• db_0or1row

Partial Call Graph (max 5 caller/called nodes):

Testcases:

test_apm_parameter__register, test_apm_package_instance__new, apm_version_names_compare, apm__test_info_file, site_node_get_children, acs_user__registered_user_p, acs_user__ban_approve, parameter_register_test, parameter__check_procs, community_cc_procs, person_procs_test, party_procs_test, db__1row, util_http_json_encoding, ad_context_bar_multirow, acs_object_procs_test, ad_proc_permission_permission_p

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".

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__transaction

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Parameters:

sql (required)

bind_start_idx (required)

bind_end_idx (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

This proc emulates the bind variable substitution in the PostgreSQL driver. Since this is a temporary hack, we do it in Tcl instead of hacking up the driver to support plsql calls. This is only used for the db_exec_plpgsql function.

Parameters:

sql (required)

bind (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db_bind_var_substitution

PostgreSQL only.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

Parameters:

statement_name (required)

sql (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

TODO: This proc should probably be changed to take a final file argument, only, rather than the current args variable length argument list. Currently, it is called only 4 places in OpenACS, and each place args, if used at all, is always "-file $file". However, such a change might break custom code... I'm not sure. --atp@piskorski.com, 2003/04/09 11:39 EDT

Parameters:

statement_name (required)

sql (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

apm_tarballs

Converts a Tcl boolean (1/0) into a SQL boolean (t/f)

Parameters:

bool (required)

Returns:

t or f

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db_boolean

Switches:

-dbn (optional)

The database name to use. Uses the default database if not supplied.

Returns:

Call ns_db bouncepool on all pools for the named database.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

table_name (required)

column_name (required)

Returns:

1 if the row exists in the table, 0 if not.

Author:

Lars Pind <lars@pinds.com>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

acs_subsite_attributes

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-complain (optional, boolean)

throw an error when datatype is not found

Parameters:

table_name (required)

column_name (required)

Returns:

the Oracle Data Type for the specified column.
-1 if the table or column doesn't exist.
an error if table or column doesn't exist and -complain flag was specified

Author:

Yon Feldman <yon@arsdigita.com>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

datamodel__acs_attribute_check

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

table_name (required)

Returns:

a Tcl list of all the columns in the table with the given name.

Author:

Lars Pind <lars@pinds.com>

Changelog:

yon@arsdigita.com 20000711 changed to return lowercase column names

Partial Call Graph (max 5 caller/called nodes):

Testcases:

datamodel__acs_attribute_check

Parameters:

db_type (required)

Returns:

1 if the given db_type is compatible with the current RDBMS.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Do a DML statement.

args can be one of: -clobs, -blobs, -clob_files or -blob_files. See the db-api doc referenced below for more information.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

Parameters:

statement_name (required)

sql (required)

See Also:

• /doc/db-api-detailed

Partial Call Graph (max 5 caller/called nodes):

Testcases:

apm__test_info_file, db__transaction, db__transaction_bug_3440

Normally, a dbn is passed to this proc. Unfortunately, there are one or two cases where a proc that needs to call this one has only a db handle, not the dbn that handle came from. Therefore, they instead use -handle_p 1 and pass the db handle. Hmm, as of 2018, it seems that in most cases, db_driverkey is called with a handle.

Switches:

-handle_p (optional, defaults to "0")

Parameters:

dbn (required)

Returns:

The driverkey for use in db_* API switch statements.

Author:

Andrew Piskorski <atp@piskorski.com>

Created:

2003/04/08

Partial Call Graph (max 5 caller/called nodes):

Testcases:

create_form_with_form_instance

A helper procedure to execute a SQL statement, potentially binding depending on the value of the $bind variable in the calling environment (if set).

Switches:

-subst (optional, defaults to "all")

Parameters:

type (required)

db (required)

statement_name (required)

pre_sql (required)

ulevel (optional, defaults to "2")

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__0or1row, db__1row, xowiki_test_cases

A helper procedure to execute a SQL statement, potentially binding depending on the value of the $bind variable in the calling environment (if set).

Switches:

-ulevel (optional, defaults to "2")

Parameters:

type (required)

db (required)

statement_name (required)

pre_sql (required)

file (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

A helper procedure to execute a SQL statement, potentially binding depending on the value of the $bind variable in the calling environment (if set).

Switches:

-ulevel (optional, defaults to "2")

-subst (optional, defaults to "all")

Parameters:

type (required)

db (required)

statement_name (required)

pre_sql (required)

file (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

A helper procedure to execute a SQL statement, potentially binding depending on the value of the $bind variable in the calling environment (if set). Low level replacement for db_exec which emulates blob handling.

Switches:

-ulevel (optional, defaults to "2")

-subst (optional, defaults to "all")

Parameters:

type (required)

db (required)

statement_name (required)

pre_sql (required)

file (optional)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

PostgreSQL only.

A helper procedure to execute a SQL statement, potentially binding depending on the value of the $bind variable in the calling environment (if set).

Low level replacement for db_exec which replaces inline code with a proc. db proc is dropped after execution. This is a temporary fix until we can port all of the db_exec_plsql calls to simple selects of the inline code wrapped in function calls.

emulation of plsql calls from oracle. This routine takes the plsql statements and wraps them in a function call, calls the function, and then drops the function. Future work might involve converting this to cache the function calls

This proc is private - use db_exec_plsql instead!

Parameters:

db (required)

statement_name (required)

pre_sql (required)

fname (required)

See Also:

• db_exec_plsql

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Oracle: Executes a PL/SQL statement, and returns the variable of bind variable :1.

PostgreSQL: Performs a pl/pgsql function or procedure call. The caller must perform a select query that returns the value of the function.

Examples:

    # Oracle:
    db_exec_plsql delete_note {
        begin  note.del(:note_id);  end;
    }

    # PostgreSQL:
    db_exec_plsql delete_note {
        select note__delete(:note_id);
    }
    

If you need the return value, then do something like this:

    # Oracle:
    set new_note_id [db_exec_plsql create_note {
        begin
        :1 := note.new(
                       owner_id => :user_id,
                       title    => :title,
                       body     => :body,
                       creation_user => :user_id,
                       creation_ip   => :peeraddr,
                       context_id    => :package_id
                       );
        end;
    }]

    # PostgreSQL:
    set new_note_id [db_exec_plsql create_note {
        select note__new(
                         null,
                         :user_id,
                         :title,
                         :body,
                         'note',
                         now(),
                         :user_id,
                         :peeraddr,
                         :package_id
                         );
    }]
    

You can call several pl/SQL statements at once, like this:

    # Oracle:
    db_exec_plsql delete_note {
        begin
        note.del(:note_id);
        note.del(:another_note_id);
        note.del(:yet_another_note_id);
        end;
    }

    # PostgreSQL:
    db_exec_plsql delete_note {
        select note__delete(:note_id);
        select note__delete(:another_note_id);
        select note__delete(:yet_another_note_id);
    }
    

yourfilename.tcl:

    db_exec_plsql delete_note {}

yourfilename-oracle.xql:

    <fullquery name="delete_note">
    <querytext>
    begin
    note.del(:note_id);
    end;
    </querytext>
    </fullquery>

yourfilename-postgresql.xql:

    <fullquery name="delete_note">
    <querytext>
    select note__delete(:note_id);
    </querytext>
    </fullquery>

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-bind (optional)

Parameters:

statement_name (required)

sql (required)

See Also:

• /doc/db-api-detailed

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db_bind_var_substitution

Flush the given cache of entries with keys that match the given pattern.

Switches:

-cache_key_pattern (optional, defaults to "*")

The "string match" pattern used to flush keys (default is to flush all entries)

-cache_pool (optional, defaults to "db_cache_pool")

The pool to flush (default is to flush db_cache_pool)

Author:

Don Baccus <dhogasa@pacifier.com>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__caching

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 (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). In place of 'if_no_rows' also the 'else' keyword can be used.

Example:

db_foreach greeble_query "select foo, bar from greeble" {
        ns_write "<li>foo=$foo; bar=$bar\n"
    } if_no_rows {
        # This block is optional.
        ns_write "<li>No greebles!\n"
    }

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-subst (optional, defaults to "all")

Parameters:

statement_name (required)

sql (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__db_foreach, db__transaction_bug_3440

PostgreSQL and NSDB only. Return the database name from the first database pool. It assumes the datasource is properly formatted since we've already verified that we can connect to the pool. On the longer range, it might be better to use SQL queries, at least in cases, where database is already connected. PostgreSQL: SELECT current_database() Oracle: SELECT name from v$database; SELECT ora_database_name FROM dual

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

database name

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

PostgreSQL only.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the name of the database host from the first database pool. It assumes the datasource is properly formatted since we've already verified that we can connect to the pool.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the password parameter from the driver section of the first database pool for the dbn.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

PostgreSQL only.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the pgbin parameter from the driver section of the first database pool.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

acs_tcl_exec_required_dependencies, acs_tcl_exec_optional_dependencies

PostgreSQL only.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the port number from the first database pool. It assumes the datasource is properly formatted since we've already verified that we can connect to the pool. It returns an empty string for an empty port value.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Given a piece of SQL, return the indices of single quotes. This is useful when we do bind var substitution because we should not attempt bind var substitution inside quotes. Examples:

    sql          return value
    {'a'}           {0 2}
    {'a''}           {}
    {'a'a'a'}       {0 2 4 6}
    {a'b'c'd'}      {1 3 5 7}
    

Parameters:

sql (required)

See Also:

• db_bind_var_substitution

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db_get_quote_indices

Oracle only.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

a valid Oracle user@database/password string to access a database through sqlplus.

This proc may well work for databases other than Oracle, but its return value won't really be of any use.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the username parameter from the driver section of the first database pool for the dbn.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

A helper procedure to perform an ns_db getrow, invoking developer support routines as necessary.

Parameters:

db (required)

selection (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

xowiki_test_cases

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Get the last used inactive handle.

Switches:

-dbn (optional)

database name

Returns:

last active handle or empty string

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Parameters:

db_type_list (required)

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-cache_key (optional)

Cache the result using given value as the key. Default is to not cache.

-cache_pool (optional, defaults to "db_cache_pool")

Override the default db_cache_pool

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

-bind (optional)

bind variables, passed either as an ns_set id, or via bind value list

Parameters:

statement_name (required)

name of the SQL query.

sql (required)

SQL query to be executed.

Returns:

a Tcl list of the values in the first column of the result of SQL query sql. If the SQL query doesn't return any rows, returns an empty list.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__caching, db__list_variants

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-cache_key (optional)

Cache the result using given value as the key. Default is to not cache.

-cache_pool (optional, defaults to "db_cache_pool")

Override the default db_cache_pool

-with_headers (optional, boolean)

when specified, first line of returned list of lists will always be the list of column names as reported by the database. Useful when you want to dynamically assign variables to values returned in the list of lists.

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

-columns_var (optional)

-bind (optional)

bind variables, passed either as an ns_set id, or via bind value list

Parameters:

statement_name (required)

name of the SQL query.

sql (required)

SQL query to be executed.

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, unless with_headers flag was specified and in this case the only element in the list will be the list of headers. It checks if the element is I18N and replaces it, thereby reducing the need to do this with every single package

Partial Call Graph (max 5 caller/called nodes):

Testcases:

auth_authority_api, parameter__check_procs, db__caching, db__list_variants

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-subst (optional, defaults to "all")

-columns_var (optional)

-bind (optional)

bind variables, passed either as an ns_set id, or via bind value list

Parameters:

statement_name (required)

name of the SQL query.

sql (required)

SQL query to be executed.

Returns:

a list of ns_sets with the values of each column of each row returned by the SQL query specified.
list of ns_sets, one per each row return by the SQL query

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__db_foreach, db__caching, db__transaction_bug_3440, db__list_variants

Loads a CSV formatted file into a table using PostgreSQL's COPY command or Oracle's SQL*Loader utility. The filename format consists of a sequence number used to control the order in which tables are loaded, and the table name with "-" replacing "_". This is a bit of a kludge but greatly speeds the loading of large amounts of data, such as is done when various "ref-*" packages are installed.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-callback (optional, defaults to "apm_ns_write_callback")

Parameters:

file (required)

Filename in the format dd-table-name.ctl where 'dd' is a sequence number used to control the order in which data is loaded. This file is an RDBMS-specific data loader control file.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

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. Usage:

db_multirow [ -local ] [ -upvar_level n_levels_up ] [ -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 ]

If "cache_key" is set, cache the array that results from the query *and* any code block for future use. When this result is returned from cache, THE CODE BLOCK IS NOT EXECUTED. Therefore, any values calculated by the code block that aren't listed as arguments to "extend" will not be created. In practice this impacts relatively few queries, but do take care.

You can not simultaneously append to and cache a nonempty multirow.

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). Use the -upvar_level switch to specify how many levels up the variable should be set. The default behavior (i.e., when no "-local" is specified) depends on the calling environment: when "db_multirow" is called from an ADP file the variables are set in the ADP environment. Otherwise, the default behavior is "-local".

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 ns_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]
    }

Switches:

-local (optional, boolean)

-append (optional, boolean)

-upvar_level (optional, defaults to "1")

-unclobber (optional, boolean)

If set, will cause the proc to not overwrite local variables. Actually, what happens is that the local variables will be overwritten, so you can access them within the code block. However, if you specify -unclobber, we will revert them to their original state after execution of this proc.

-extend (optional)

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-cache_key (optional)

Cache the result using given value as the key. Default is to not cache.

-cache_pool (optional, defaults to "db_cache_pool")

Override the default db_cache_pool

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

Parameters:

var_name (required)

name of the Tcl multirow array

statement_name (required)

name of the SQL query

sql (required)

SQL query to be executed

See Also:

• template::multirow

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__caching, db__transaction_bug_3440

Used inside the code_block to db_multirow to ask whether this row is the last row before the value of 'column' changes, or the last row of the result set.

This is useful when you want to build up a multirow for a master/slave table pair, where you only want one row per row in the master table, but you want to include data from the slave table in a column of the multirow.

Here's an example:

    # Initialize the lines variable to hold a list of order line summaries
    set lines [list]

    # Start building the multirow. We add the dynamic column 'lines_pretty', which will
    # contain the pretty summary of the order lines.
    db_multirow -extend { lines_pretty } orders select_orders_and_lines {
        select o.order_id,
        o.customer_name,
        l.item_name,
        l.quantity
        from   orders o,
        order_lines l
        where  l.order_id = o.order_id
        order  by o.order_id, l.item_name
    } {
        lappend lines "$quantity $item_name"
        if { [db_multirow_group_last_row_p -column order_id] } {
            # Last row of this order, prepare the pretty version of the order lines
            set lines_pretty [join $lines ", "]

            # Reset the lines list, so we start from a fresh with the next row
            set lines [list]
        } else {
            # There are yet more order lines to come for this order,
            # continue until we've collected all the order lines
            # The 'continue' keyword means this line will not be added to the resulting multirow
            continue
        }
    }
    

Switches:

-column (required)

The name of the column defining the groups.

Returns:

1 if this is the last row before the column value changes, 0 otherwise.

Author:

Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Helper function for db_multirow, performing the actual DB queries.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the name of the database as reported by the driver.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

cr_item_search_triggers, acs_tcl_exec_required_dependencies, acs_tcl_exec_optional_dependencies, datamodel__named_constraints, acs_object_procs_test

Example:

    set new_object_id [db_nextval acs_object_id_seq]
    

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

sequence (required)

the name of an SQL sequence

Returns:

the next value for a sequence. This can utilize a pool of sequence values.

See Also:

• /doc/db-api-detailed

Partial Call Graph (max 5 caller/called nodes):

Testcases:

acs_object_procs_test, ad_proc_permission_grant_and_revoke, ad_proc_permission_permission_p

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

n (required)

Returns:

the name of the pool used for the nth-nested selection (0-relative).

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Returns:

an empty string, which Oracle thinks is null. Deprecated: This routine was invented to provide an RDBMS-specific null value but doesn't actually work. I (DRB) left it in to speed porting - we should really clean up the code and pull out the calls instead, though.

See Also:

• ""

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

A convenience function that returns [db_null] if $string is the empty string. Deprecated: essentially just returns the passed string.

Parameters:

string (required)

See Also:

• db_null

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Quotes a string value to be placed in a SQL statement. Use the built-in ns_dbquotevalue instead, which cares also about the surrounding quotes.

Parameters:

string (required)

See Also:

• ns_dbquotevalue

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Releases any database handles that are presently unused.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__db_foreach, db__caching, db__transaction_bug_3440

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the number of rows affected by the last DML command.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

xowiki_test_cases

Sources a SQL file into Oracle (SQL*Plus format file) or PostgreSQL (psql format file).

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-callback (optional, defaults to "apm_ns_write_callback")

Parameters:

file (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Oracle only.

Sources a SQLJ file using loadjava.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-callback (optional, defaults to "apm_ns_write_callback")

Parameters:

file (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

the name of the global db_state array for the given database name.

Author:

Andrew Piskorski <atp@piskorski.com>

Created:

2003/03/16

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

-cache_key (optional)

Cache the result using given value as the key. Default is to not cache.

-cache_pool (optional, defaults to "db_cache_pool")

Override the default db_cache_pool

-subst (optional, defaults to "all")

Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands

-default (optional)

Return value in case the SQL query returns no value

-bind (optional)

bind variables, passed either as an ns_set id, or via bind value list

Parameters:

statement_name (required)

name of the SQL query

sql (required)

SQL query to be executed

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__caching, db__transaction, db__transaction_bug_3440, nullchar, db__string

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

table_name (required)

Returns:

1 if a table with the specified name exists in the database, otherwise 0.

Authors:

Don Baccus <dhogaza@pacifier.com>

Lars Pind <lars@pinds.com>

Partial Call Graph (max 5 caller/called nodes):

Testcases:

datamodel__acs_object_type_check, object_type_table_name

Switches:

-pattern (optional)

Will be used as LIKE 'pattern%' to limit the number of tables returned.

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Returns:

a Tcl list of all the tables owned by the connected user.

Authors:

Don Baccus <dhogaza@pacifier.com>

Lars Pind <lars@pinds.com>

Changelog:

yon@arsdigita.com 20000711 changed to return lowercase table names

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Usage: db_transaction transaction_code [ 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_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_block the transaction will be aborted. If you want to explicitly abort the transaction, call db_abort_transaction from within the transaction_code block or the error_code block.

Example 1:
In this example, db_dml triggers an error, so control passes to the on_error block which prints a readable error.

    db_transaction {
        db_dml test "nonsense"
    } on_error {
        ad_return_error "Error in blah/foo/bar" "The error was: $errmsg"
    }
    

    db_transaction {
        db_dml test {insert into footest values(1)}
        nonsense
        db_dml test {insert into footest values(2)}
    }
    

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

transaction_code (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__transaction, db__transaction_bug_3440

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.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db_bind_var_substitution, nullchar, sql_date

Returns:

the RDBMS version (i.e. 8.1.6 is a recent Oracle version; 7.1 a recent PostgreSQL version)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

sql_date

Place a usable database handle in db and executes code_block.

Switches:

-dbn (optional)

Database name to use. If empty_string, use the default database

Parameters:

db (required)

Name of the handle variable used in the code block

code_block (required)

code block to be executed with handle

Partial Call Graph (max 5 caller/called nodes):

Testcases:

db__0or1row, db__1row, xowiki_test_cases

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

statement_name (required)

sql (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Switches:

-dbn (optional)

The database name to use. If empty_string, uses the default database.

Parameters:

statement_name (required)

sql (required)

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.