• Publicity: Public Only All

01-database-procs.tcl

An API for managing database queries.

Location:
packages/acs-tcl/tcl/01-database-procs.tcl
Created:
15 Apr 2000
Author:
Jon Salz <jsalz@arsdigita.com>
CVS Identification:
$Id: 01-database-procs.tcl,v 1.1.2.29 2021/03/03 10:32:57 gustafn Exp $

Procedures in this file

Detailed information

ad_column_type (public)

 ad_column_type [ -dbn dbn ] table_name column_name
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
table_name
column_name
Returns:
'numeric' for number type columns, 'text' otherwise Throws an error if no such column exists.
Author:
Yon Feldman <yon@arsdigita.com>

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

Testcases:
No testcase defined.

db_0or1row (public)

 db_0or1row [ -dbn dbn ] [ -cache_key cache_key ] \
    [ -cache_pool cache_pool ] [ -subst subst ] statement_name sql \
    [ -bind bind ] [ -column_array column_array ] \
    [ -column_set column_set ]

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.

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 (defaults to "db_cache_pool") (optional)
Override the default db_cache_pool
-subst (defaults to "all") (optional)
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 tbe populated with values
Parameters:
statement_name
sql
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):
%3 test_db__0or1row db__0or1row (test acs-tcl) db_0or1row db_0or1row test_db__0or1row->db_0or1row test_db__1row db__1row (test acs-tcl) test_db__1row->db_0or1row test_db__caching db__caching (test acs-tcl) test_db__caching->db_0or1row acs::test::require_package_instance acs::test::require_package_instance (public) acs::test::require_package_instance->db_0or1row acs_mail_lite::get_address_array acs_mail_lite::get_address_array (private) acs_mail_lite::get_address_array->db_0or1row acs_mail_lite::imap_conn_set acs_mail_lite::imap_conn_set (private) acs_mail_lite::imap_conn_set->db_0or1row acs_mail_lite::inbound_cache_hit_p acs_mail_lite::inbound_cache_hit_p (private) acs_mail_lite::inbound_cache_hit_p->db_0or1row acs_mail_lite::sched_parameters acs_mail_lite::sched_parameters (public) acs_mail_lite::sched_parameters->db_0or1row

Testcases:
db__caching, db__0or1row, db__1row

db_1row (public)

 db_1row [ -subst subst ] [ args... ]

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

Switches:
-subst (defaults to "all") (optional)
Returns:
1 if variables are set.

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_object_procs_test acs_object_procs_test (test acs-tcl) db_1row db_1row test_acs_object_procs_test->db_1row test_acs_user__ban_approve acs_user__ban_approve (test acs-tcl) test_acs_user__ban_approve->db_1row test_acs_user__registered_user_p acs_user__registered_user_p (test acs-tcl) test_acs_user__registered_user_p->db_1row test_ad_context_bar_multirow ad_context_bar_multirow (test acs-tcl) test_ad_context_bar_multirow->db_1row test_ad_proc_permission_permission_p ad_proc_permission_permission_p (test acs-tcl) test_ad_proc_permission_permission_p->db_1row Class ::xo::db::Class Class ::xo::db::Class (public) Class ::xo::db::Class->db_1row Class ::xo::db::CrClass Class ::xo::db::CrClass (public) Class ::xo::db::CrClass->db_1row Class ::xo::db::CrFolder Class ::xo::db::CrFolder (public) Class ::xo::db::CrFolder->db_1row acs_messaging_first_ancestor acs_messaging_first_ancestor (public) acs_messaging_first_ancestor->db_1row acs_object::get acs_object::get (public) acs_object::get->db_1row

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

db_abort_transaction (public)

 db_abort_transaction [ -dbn dbn ]

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):
%3 test_db__transaction db__transaction (test acs-tcl) db_abort_transaction db_abort_transaction test_db__transaction->db_abort_transaction db_transaction db_transaction (public) db_transaction->db_abort_transaction forum::message::new forum::message::new (public) forum::message::new->db_abort_transaction packages/acs-subsite/www/admin/rel-segments/constraints/new.tcl packages/acs-subsite/ www/admin/rel-segments/constraints/new.tcl packages/acs-subsite/www/admin/rel-segments/constraints/new.tcl->db_abort_transaction

Testcases:
db__transaction

db_bind_var_substitution (public)

 db_bind_var_substitution sql [ bind ]

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
bind (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 test_db_bind_var_substitution db_bind_var_substitution (test acs-tcl) db_bind_var_substitution db_bind_var_substitution test_db_bind_var_substitution->db_bind_var_substitution db_exec_lob_postgresql db_exec_lob_postgresql (private) db_exec_lob_postgresql->db_bind_var_substitution db_exec_plpgsql db_exec_plpgsql (private) db_exec_plpgsql->db_bind_var_substitution ds_collect_db_call ds_collect_db_call (public) ds_collect_db_call->db_bind_var_substitution

Testcases:
db_bind_var_substitution

db_blob_get (public)

 db_blob_get [ -dbn dbn ] [ -subst subst ] statement_name sql \
    [ args... ]

PostgreSQL only.

Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
-subst (defaults to "all") (optional)
Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands
Parameters:
statement_name
sql

Partial Call Graph (max 5 caller/called nodes):
%3 cr_write_content-lob cr_write_content-lob (private) db_blob_get db_blob_get cr_write_content-lob->db_blob_get search::content_get search::content_get (private) search::content_get->db_blob_get

Testcases:
No testcase defined.

db_blob_get_file (public)

 db_blob_get_file [ -dbn dbn ] statement_name sql [ args... ]
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
sql

Partial Call Graph (max 5 caller/called nodes):
%3 apm_extract_tarball apm_extract_tarball (public) db_blob_get_file db_blob_get_file apm_extract_tarball->db_blob_get_file content::revision::export_to_filesystem-lob content::revision::export_to_filesystem-lob (private) content::revision::export_to_filesystem-lob->db_blob_get_file packages/acs-subsite/www/shared/portrait-bits.tcl packages/acs-subsite/ www/shared/portrait-bits.tcl packages/acs-subsite/www/shared/portrait-bits.tcl->db_blob_get_file packages/photo-album/www/album-export.tcl packages/photo-album/ www/album-export.tcl packages/photo-album/www/album-export.tcl->db_blob_get_file publish::write_multiple_blobs publish::write_multiple_blobs (private) publish::write_multiple_blobs->db_blob_get_file

Testcases:
No testcase defined.

db_boolean (public)

 db_boolean bool

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

Parameters:
bool
Returns:
t or f

Partial Call Graph (max 5 caller/called nodes):
%3 auth::sync::job::end_get_document auth::sync::job::end_get_document (public) db_boolean db_boolean auth::sync::job::end_get_document->db_boolean auth::sync::job::start auth::sync::job::start (public) auth::sync::job::start->db_boolean group::member_p_not_cached group::member_p_not_cached (private) group::member_p_not_cached->db_boolean lang::message::edit lang::message::edit (private) lang::message::edit->db_boolean lang::message::register lang::message::register (public) lang::message::register->db_boolean

Testcases:
No testcase defined.

db_bounce_pools (public)

 db_bounce_pools [ -dbn dbn ]
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):
%3 apm_package_install_data_model apm_package_install_data_model (private) db_bounce_pools db_bounce_pools apm_package_install_data_model->db_bounce_pools

Testcases:
No testcase defined.

db_column_exists (public)

 db_column_exists [ -dbn dbn ] table_name column_name
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
table_name
column_name
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):
%3 test_acs_subsite_attributes acs_subsite_attributes (test acs-subsite) db_column_exists db_column_exists test_acs_subsite_attributes->db_column_exists attribute::delete attribute::delete (public) attribute::delete->db_column_exists packages/schema-browser/www/column-comments-2.tcl packages/schema-browser/ www/column-comments-2.tcl packages/schema-browser/www/column-comments-2.tcl->db_column_exists

Testcases:
acs_subsite_attributes

db_column_type (public)

 db_column_type [ -dbn dbn ] [ -complain ] table_name column_name
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
-complain (boolean) (optional)
throw an error when datatype is not found
Parameters:
table_name
column_name
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>
Changelog:
10 July, 2000: changed to return error if column name doesn't exist (mdettinger@arsdigita.com)
11 July, 2000: changed to return lowercase data types (yon@arsdigita.com)
11 July, 2000: changed to return error using the db_string default clause (yon@arsdigita.com)

Partial Call Graph (max 5 caller/called nodes):
%3 test_datamodel__acs_attribute_check datamodel__acs_attribute_check (test acs-tcl) db_column_type db_column_type test_datamodel__acs_attribute_check->db_column_type ad_column_type ad_column_type (public) ad_column_type->db_column_type plpgsql_utility::generate_function_signature plpgsql_utility::generate_function_signature (public) plpgsql_utility::generate_function_signature->db_column_type plpgsql_utility::table_column_type plpgsql_utility::table_column_type (public, deprecated) plpgsql_utility::table_column_type->db_column_type xo::db::require proc default xo::db::require proc default xo::db::require proc default->db_column_type

Testcases:
datamodel__acs_attribute_check

db_columns (public)

 db_columns [ -dbn dbn ] table_name
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
table_name
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):
%3 test_datamodel__acs_attribute_check datamodel__acs_attribute_check (test acs-tcl) db_columns db_columns test_datamodel__acs_attribute_check->db_columns

Testcases:
datamodel__acs_attribute_check

db_compatible_rdbms_p (public)

 db_compatible_rdbms_p db_type
Parameters:
db_type
Returns:
1 if the given db_type is compatible with the current RDBMS.

Partial Call Graph (max 5 caller/called nodes):
%3 tsearch2::build_query tsearch2::build_query (private) db_compatible_rdbms_p db_compatible_rdbms_p tsearch2::build_query->db_compatible_rdbms_p

Testcases:
No testcase defined.

db_dml (public)

 db_dml [ -dbn dbn ] [ -subst subst ] statement_name sql [ args... ]

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 (defaults to "all") (optional)
Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands
Parameters:
statement_name
sql

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_apm__test_info_file apm__test_info_file (test acs-tcl) db_dml db_dml test_apm__test_info_file->db_dml test_db__transaction db__transaction (test acs-tcl) test_db__transaction->db_dml test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_dml aa_log_final aa_log_final (private) aa_log_final->db_dml aa_log_result aa_log_result (public) aa_log_result->db_dml aa_run_testcase aa_run_testcase (private) aa_run_testcase->db_dml acs::test::user::delete acs::test::user::delete (public) acs::test::user::delete->db_dml acs_mail_lite::after_upgrade acs_mail_lite::after_upgrade (private) acs_mail_lite::after_upgrade->db_dml

Testcases:
apm__test_info_file, db__transaction, db__transaction_bug_3440

db_driverkey (public)

 db_driverkey [ -handle_p handle_p ] dbn

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 (defaults to "0") (optional)
Parameters:
dbn
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):
%3 test_create_form_with_form_instance create_form_with_form_instance (test xowiki) db_driverkey db_driverkey test_create_form_with_form_instance->db_driverkey ad_acs_require_basic_schemata ad_acs_require_basic_schemata (private) ad_acs_require_basic_schemata->db_driverkey category::list::rewrite_query category::list::rewrite_query (public) category::list::rewrite_query->db_driverkey content::revision::new content::revision::new (public) content::revision::new->db_driverkey cr_write_content-lob cr_write_content-lob (private) cr_write_content-lob->db_driverkey db_blob_get db_blob_get (public) db_blob_get->db_driverkey

Testcases:
create_form_with_form_instance

db_exec (public)

 db_exec [ -subst subst ] type db statement_name pre_sql [ ulevel ] \
    [ args... ]

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 (defaults to "all") (optional)
Parameters:
type
db
statement_name
pre_sql
ulevel (defaults to "2")

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__0or1row db__0or1row (test acs-tcl) db_exec db_exec test_db__0or1row->db_exec test_db__1row db__1row (test acs-tcl) test_db__1row->db_exec test_xowiki_test_cases xowiki_test_cases (test xowiki) test_xowiki_test_cases->db_exec db_0or1row db_0or1row (public) db_0or1row->db_exec db_dml db_dml (public) db_dml->db_exec db_exec_plsql db_exec_plsql (public) db_exec_plsql->db_exec db_list db_list (public) db_list->db_exec db_list_of_ns_sets db_list_of_ns_sets (public) db_list_of_ns_sets->db_exec

Testcases:
db__0or1row, db__1row, xowiki_test_cases

db_exec_plsql (public)

 db_exec_plsql [ -dbn dbn ] statement_name sql [ -bind bind ]

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);
    }
    
If you are using xql files then put the body of the query in a yourfilename-oracle.xql or yourfilename-postgresql.xql file, as appropriate. E.g. the first example transformed to use xql files looks like this:

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
sql

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_db_bind_var_substitution db_bind_var_substitution (test acs-tcl) db_exec_plsql db_exec_plsql test_db_bind_var_substitution->db_exec_plsql acs_cr_scheduled_release_exec acs_cr_scheduled_release_exec (private) acs_cr_scheduled_release_exec->db_exec_plsql acs_sc::contract::new acs_sc::contract::new (public) acs_sc::contract::new->db_exec_plsql acs_sc::contract::operation::new acs_sc::contract::operation::new (public) acs_sc::contract::operation::new->db_exec_plsql acs_sc::impl::alias::new acs_sc::impl::alias::new (public) acs_sc::impl::alias::new->db_exec_plsql acs_sc::impl::binding::new acs_sc::impl::binding::new (public) acs_sc::impl::binding::new->db_exec_plsql

Testcases:
db_bind_var_substitution

db_flush_cache (public)

 db_flush_cache [ -cache_key_pattern cache_key_pattern ] \
    [ -cache_pool cache_pool ]

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

Switches:
-cache_key_pattern (defaults to "*") (optional)
The "string match" pattern used to flush keys (default is to flush all entries)
-cache_pool (defaults to "db_cache_pool") (optional)
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):
%3 test_db__caching db__caching (test acs-tcl) db_flush_cache db_flush_cache test_db__caching->db_flush_cache acs_mail_lite::section_id_of acs_mail_lite::section_id_of (private) acs_mail_lite::section_id_of->db_flush_cache application_group::delete application_group::delete (public) application_group::delete->db_flush_cache packages/acs-lang/www/admin/locale-edit.tcl packages/acs-lang/ www/admin/locale-edit.tcl packages/acs-lang/www/admin/locale-edit.tcl->db_flush_cache

Testcases:
db__caching

db_foreach (public)

 db_foreach [ -dbn dbn ] [ -subst subst ] statement_name sql \
    [ args... ]

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 (defaults to "all") (optional)
Parameters:
statement_name
sql

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__db_foreach db__db_foreach (test acs-tcl) db_foreach db_foreach test_db__db_foreach->db_foreach test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_foreach aa_test::get_test_doc aa_test::get_test_doc (private) aa_test::get_test_doc->db_foreach acs_mail_lite::send_immediately acs_mail_lite::send_immediately (private) acs_mail_lite::send_immediately->db_foreach acs_mail_lite::sweeper acs_mail_lite::sweeper (private) acs_mail_lite::sweeper->db_foreach acs_messaging_process_queue acs_messaging_process_queue (private) acs_messaging_process_queue->db_foreach acs_object_type_hierarchy acs_object_type_hierarchy (public) acs_object_type_hierarchy->db_foreach

Testcases:
db__db_foreach, db__transaction_bug_3440

db_get_database (public)

 db_get_database [ -dbn dbn ]

PostgreSQL only.

Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Returns:
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.

Partial Call Graph (max 5 caller/called nodes):
%3 db_load_sql_data db_load_sql_data (public) db_get_database db_get_database db_load_sql_data->db_get_database db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_database packages/acs-subsite/www/admin/system/db-locks.tcl packages/acs-subsite/ www/admin/system/db-locks.tcl packages/acs-subsite/www/admin/system/db-locks.tcl->db_get_database

Testcases:
No testcase defined.

db_get_dbhost (public)

 db_get_dbhost [ -dbn dbn ]

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):
%3 db_load_sql_data db_load_sql_data (public) db_get_dbhost db_get_dbhost db_load_sql_data->db_get_dbhost db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_dbhost

Testcases:
No testcase defined.

db_get_password (public)

 db_get_password [ -dbn dbn ]
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):
%3 db_load_sql_data db_load_sql_data (public) db_get_password db_get_password db_load_sql_data->db_get_password db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_password

Testcases:
No testcase defined.

db_get_pgbin (public)

 db_get_pgbin [ -dbn dbn ]

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):
%3 db_load_sql_data db_load_sql_data (public) db_get_pgbin db_get_pgbin db_load_sql_data->db_get_pgbin db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_pgbin

Testcases:
No testcase defined.

db_get_port (public)

 db_get_port [ -dbn dbn ]

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):
%3 db_load_sql_data db_load_sql_data (public) db_get_port db_get_port db_load_sql_data->db_get_port db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_port

Testcases:
No testcase defined.

db_get_sql_user (public)

 db_get_sql_user [ -dbn dbn ]

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):
%3 db_load_sql_data db_load_sql_data (public) db_get_sql_user db_get_sql_user db_load_sql_data->db_get_sql_user db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_sql_user db_source_sqlj_file db_source_sqlj_file (public) db_source_sqlj_file->db_get_sql_user

Testcases:
No testcase defined.

db_get_username (public)

 db_get_username [ -dbn dbn ]
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):
%3 db_load_sql_data db_load_sql_data (public) db_get_username db_get_username db_load_sql_data->db_get_username db_source_sql_file db_source_sql_file (public) db_source_sql_file->db_get_username

Testcases:
No testcase defined.

db_known_database_types (public)

 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.

Partial Call Graph (max 5 caller/called nodes):
%3 apm_package_supported_databases apm_package_supported_databases (public) db_known_database_types db_known_database_types apm_package_supported_databases->db_known_database_types

Testcases:
No testcase defined.

db_list (public)

 db_list [ -dbn dbn ] [ -cache_key cache_key ] \
    [ -cache_pool cache_pool ] [ -subst subst ] statement_name sql \
    [ -bind bind ]
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 (defaults to "db_cache_pool") (optional)
Override the default db_cache_pool
-subst (defaults to "all") (optional)
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
sql
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.

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__caching db__caching (test acs-tcl) db_list db_list test_db__caching->db_list test_db__list_variants db__list_variants (test acs-tcl) test_db__list_variants->db_list acs_mail_lite::inbound_queue_pull acs_mail_lite::inbound_queue_pull (private) acs_mail_lite::inbound_queue_pull->db_list acs_mail_lite::inbound_queue_release acs_mail_lite::inbound_queue_release (private) acs_mail_lite::inbound_queue_release->db_list acs_object_type::supertypes acs_object_type::supertypes (private) acs_object_type::supertypes->db_list acs_sc::contract::get_operations acs_sc::contract::get_operations (public) acs_sc::contract::get_operations->db_list acs_user_extension::list_extensions acs_user_extension::list_extensions (public) acs_user_extension::list_extensions->db_list

Testcases:
db__caching, db__list_variants

db_list_of_lists (public)

 db_list_of_lists [ -dbn dbn ] [ -cache_key cache_key ] \
    [ -cache_pool cache_pool ] [ -with_headers ] [ -subst subst ] \
    statement_name sql [ -bind bind ]
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 (defaults to "db_cache_pool") (optional)
Override the default db_cache_pool
-with_headers (boolean) (optional)
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 (defaults to "all") (optional)
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
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, 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):
%3 test_auth_authority_api auth_authority_api (test acs-authentication) db_list_of_lists db_list_of_lists test_auth_authority_api->db_list_of_lists test_db__caching db__caching (test acs-tcl) test_db__caching->db_list_of_lists test_db__list_variants db__list_variants (test acs-tcl) test_db__list_variants->db_list_of_lists test_parameter__check_procs parameter__check_procs (test acs-tcl) test_parameter__check_procs->db_list_of_lists acs_mail_lite::inbound_queue_pull_one acs_mail_lite::inbound_queue_pull_one (private) acs_mail_lite::inbound_queue_pull_one->db_list_of_lists acs_mail_lite::unique_id_parse acs_mail_lite::unique_id_parse (private) acs_mail_lite::unique_id_parse->db_list_of_lists acs_sc::impl::get_options acs_sc::impl::get_options (public) acs_sc::impl::get_options->db_list_of_lists ad_get_node_id_from_host_node_map ad_get_node_id_from_host_node_map (private) ad_get_node_id_from_host_node_map->db_list_of_lists apm::get_package_descendent_options apm::get_package_descendent_options (public) apm::get_package_descendent_options->db_list_of_lists

Testcases:
auth_authority_api, parameter__check_procs, db__caching, db__list_variants

db_list_of_ns_sets (public)

 db_list_of_ns_sets [ -dbn dbn ] [ -subst subst ] \
    [ -columns_var columns_var ] statement_name sql [ -bind bind ]
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
-subst (defaults to "all") (optional)
-columns_var (optional)
-bind (optional)
bind variables, passed either as an ns_set id, or via bind value list
Parameters:
statement_name - The name of the query.
sql - The SQL 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):
%3 test_db__caching db__caching (test acs-tcl) db_list_of_ns_sets db_list_of_ns_sets test_db__caching->db_list_of_ns_sets test_db__db_foreach db__db_foreach (test acs-tcl) test_db__db_foreach->db_list_of_ns_sets test_db__list_variants db__list_variants (test acs-tcl) test_db__list_variants->db_list_of_ns_sets test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_list_of_ns_sets acs_mail_lite::check_bounces acs_mail_lite::check_bounces (private) acs_mail_lite::check_bounces->db_list_of_ns_sets forum::list_forums forum::list_forums (public) forum::list_forums->db_list_of_ns_sets fs::get_folder_contents fs::get_folder_contents (public) fs::get_folder_contents->db_list_of_ns_sets notification::sweep::sweep_notifications notification::sweep::sweep_notifications (private) notification::sweep::sweep_notifications->db_list_of_ns_sets

Testcases:
db__db_foreach, db__caching, db__transaction_bug_3440, db__list_variants

db_load_sql_data (public)

 db_load_sql_data [ -dbn dbn ] [ -callback callback ] file

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 (defaults to "apm_ns_write_callback") (optional)
Parameters:
file - 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):
%3 apm_package_install_data_model apm_package_install_data_model (private) db_load_sql_data db_load_sql_data apm_package_install_data_model->db_load_sql_data ref_timezones::apm::after_upgrade ref_timezones::apm::after_upgrade (private) ref_timezones::apm::after_upgrade->db_load_sql_data

Testcases:
No testcase defined.

db_multirow (public)

 db_multirow [ -local ] [ -append ] [ -upvar_level upvar_level ] \
    [ -unclobber ] [ -extend extend ] [ -dbn dbn ] \
    [ -cache_key cache_key ] [ -cache_pool cache_pool ] \
    [ -subst subst ] var_name statement_name sql [ args... ]
Switches:
-local (boolean) (optional)
-append (boolean) (optional)
-upvar_level (defaults to "1") (optional)
-unclobber (boolean) (optional)
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. 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 ]

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.

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.

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]
    }
-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 (defaults to "db_cache_pool") (optional)
Override the default db_cache_pool
-subst (defaults to "all") (optional)
Perform Tcl substitution in xql-files. Possible values: all, none, vars, commands
Parameters:
var_name
statement_name
sql

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__caching db__caching (test acs-tcl) db_multirow db_multirow test_db__caching->db_multirow test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_multirow acs_user::demote_user acs_user::demote_user (public) acs_user::demote_user->db_multirow bm_folder_selection bm_folder_selection (public) bm_folder_selection->db_multirow bug_tracker::bug::get_multirow bug_tracker::bug::get_multirow (public) bug_tracker::bug::get_multirow->db_multirow category::get_mapped_categories_multirow category::get_mapped_categories_multirow (public) category::get_mapped_categories_multirow->db_multirow doc::func_multirow doc::func_multirow (private, deprecated) doc::func_multirow->db_multirow

Testcases:
db__caching, db__transaction_bug_3440

db_multirow_group_last_row_p (public)

 db_multirow_group_last_row_p -column column

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):
%3 bug_tracker::bug::get_multirow bug_tracker::bug::get_multirow (public) db_multirow_group_last_row_p db_multirow_group_last_row_p bug_tracker::bug::get_multirow->db_multirow_group_last_row_p

Testcases:
No testcase defined.

db_name (public)

 db_name [ -dbn dbn ]
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):
%3 test_acs_object_procs_test acs_object_procs_test (test acs-tcl) db_name db_name test_acs_object_procs_test->db_name test_cr_item_search_triggers cr_item_search_triggers (test acs-content-repository) test_cr_item_search_triggers->db_name test_datamodel__named_constraints datamodel__named_constraints (test acs-tcl) test_datamodel__named_constraints->db_name

Testcases:
cr_item_search_triggers, datamodel__named_constraints, acs_object_procs_test

db_nextval (public)

 db_nextval [ -dbn dbn ] sequence

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 - the name of an SQL sequence
Returns:
the next value for a sequence. This can utilize a pool of sequence values.

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_object_procs_test acs_object_procs_test (test acs-tcl) db_nextval db_nextval test_acs_object_procs_test->db_nextval test_ad_proc_permission_grant_and_revoke ad_proc_permission_grant_and_revoke (test acs-tcl) test_ad_proc_permission_grant_and_revoke->db_nextval test_ad_proc_permission_permission_p ad_proc_permission_permission_p (test acs-tcl) test_ad_proc_permission_permission_p->db_nextval acs_mail_lite::inbound_cache_hit_p acs_mail_lite::inbound_cache_hit_p (private) acs_mail_lite::inbound_cache_hit_p->db_nextval acs_mail_lite::inbound_queue_insert acs_mail_lite::inbound_queue_insert (private) acs_mail_lite::inbound_queue_insert->db_nextval acs_mail_lite::section_id_of acs_mail_lite::section_id_of (private) acs_mail_lite::section_id_of->db_nextval ad_form ad_form (public) ad_form->db_nextval application_data_link::new_from application_data_link::new_from (public) application_data_link::new_from->db_nextval

Testcases:
acs_object_procs_test, ad_proc_permission_grant_and_revoke, ad_proc_permission_permission_p

db_nth_pool_name (public)

 db_nth_pool_name [ -dbn dbn ] n
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
n
Returns:
the name of the pool used for the nth-nested selection (0-relative).

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

Testcases:
No testcase defined.

db_null (public, deprecated)

 db_null
Deprecated. Invoking this procedure generates a warning.

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):
%3

Testcases:
No testcase defined.

db_nullify_empty_string (public, deprecated)

 db_nullify_empty_string string
Deprecated. Invoking this procedure generates a warning.

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

Parameters:
string

See Also:
  • db_null

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

Testcases:
No testcase defined.

db_quote (public, deprecated)

 db_quote string
Deprecated. Invoking this procedure generates a warning.

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

See Also:

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

Testcases:
No testcase defined.

db_release_unused_handles (public)

 db_release_unused_handles [ -dbn dbn ]

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):
%3 test_db__caching db__caching (test acs-tcl) db_release_unused_handles db_release_unused_handles test_db__caching->db_release_unused_handles test_db__db_foreach db__db_foreach (test acs-tcl) test_db__db_foreach->db_release_unused_handles test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_release_unused_handles ad_change_password ad_change_password (public) ad_change_password->db_release_unused_handles ad_check_password ad_check_password (public) ad_check_password->db_release_unused_handles ad_progress_bar_begin ad_progress_bar_begin (public) ad_progress_bar_begin->db_release_unused_handles adp_parse_ad_conn_file adp_parse_ad_conn_file (public) adp_parse_ad_conn_file->db_release_unused_handles apm_bootstrap_load_libraries apm_bootstrap_load_libraries (private) apm_bootstrap_load_libraries->db_release_unused_handles

Testcases:
db__db_foreach, db__caching, db__transaction_bug_3440

db_resultrows (public)

 db_resultrows [ -dbn dbn ]
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):
%3 test_xowiki_test_cases xowiki_test_cases (test xowiki) db_resultrows db_resultrows test_xowiki_test_cases->db_resultrows acs_mail_lite::bounce_ministry acs_mail_lite::bounce_ministry (private) acs_mail_lite::bounce_ministry->db_resultrows acs_mail_lite::log_mail_sending acs_mail_lite::log_mail_sending (private) acs_mail_lite::log_mail_sending->db_resultrows acs_mail_lite::record_bounce acs_mail_lite::record_bounce (public, deprecated) acs_mail_lite::record_bounce->db_resultrows attribute::value_delete attribute::value_delete (public) attribute::value_delete->db_resultrows packages/acs-subsite/www/admin/attributes/enum-add-2.tcl packages/acs-subsite/ www/admin/attributes/enum-add-2.tcl packages/acs-subsite/www/admin/attributes/enum-add-2.tcl->db_resultrows

Testcases:
xowiki_test_cases

db_source_sql_file (public)

 db_source_sql_file [ -dbn dbn ] [ -callback callback ] file

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 (defaults to "apm_ns_write_callback") (optional)
Parameters:
file

Partial Call Graph (max 5 caller/called nodes):
%3 ad_acs_require_basic_schemata ad_acs_require_basic_schemata (private) db_source_sql_file db_source_sql_file ad_acs_require_basic_schemata->db_source_sql_file apm_package_delete apm_package_delete (public) apm_package_delete->db_source_sql_file apm_package_install_data_model apm_package_install_data_model (private) apm_package_install_data_model->db_source_sql_file install::xml::action::source install::xml::action::source (private) install::xml::action::source->db_source_sql_file packages/acs-admin/www/apm/bulk-install.tcl packages/acs-admin/ www/apm/bulk-install.tcl packages/acs-admin/www/apm/bulk-install.tcl->db_source_sql_file

Testcases:
No testcase defined.

db_source_sqlj_file (public)

 db_source_sqlj_file [ -dbn dbn ] [ -callback callback ] file

Oracle only.

Sources a SQLJ file using loadjava.

Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
-callback (defaults to "apm_ns_write_callback") (optional)
Parameters:
file

Partial Call Graph (max 5 caller/called nodes):
%3 apm_package_install_data_model apm_package_install_data_model (private) db_source_sqlj_file db_source_sqlj_file apm_package_install_data_model->db_source_sqlj_file packages/acs-admin/www/apm/bulk-install.tcl packages/acs-admin/ www/apm/bulk-install.tcl packages/acs-admin/www/apm/bulk-install.tcl->db_source_sqlj_file

Testcases:
No testcase defined.

db_string (public)

 db_string [ -dbn dbn ] [ -cache_key cache_key ] \
    [ -cache_pool cache_pool ] [ -subst subst ] statement_name sql \
    [ -default default ] [ -bind bind ]
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 (defaults to "db_cache_pool") (optional)
Override the default db_cache_pool
-subst (defaults to "all") (optional)
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
sql
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):
%3 test_db__caching db__caching (test acs-tcl) db_string db_string test_db__caching->db_string test_db__string db__string (test acs-tcl) test_db__string->db_string test_db__transaction db__transaction (test acs-tcl) test_db__transaction->db_string test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_string test_nullchar nullchar (test acs-tcl) test_nullchar->db_string acs_lookup_magic_object_no_cache acs_lookup_magic_object_no_cache (private) acs_lookup_magic_object_no_cache->db_string acs_mail_lite::sweeper acs_mail_lite::sweeper (private) acs_mail_lite::sweeper->db_string acs_object::object_p acs_object::object_p (public) acs_object::object_p->db_string acs_object::package_id_not_cached acs_object::package_id_not_cached (private) acs_object::package_id_not_cached->db_string acs_object_name acs_object_name (public) acs_object_name->db_string

Testcases:
db__caching, db__transaction, db__transaction_bug_3440, nullchar, db__string

db_table_exists (public)

 db_table_exists [ -dbn dbn ] table_name
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
table_name
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):
%3 test_datamodel__acs_object_type_check datamodel__acs_object_type_check (test acs-tcl) db_table_exists db_table_exists test_datamodel__acs_object_type_check->db_table_exists ad_verify_install ad_verify_install (public) ad_verify_install->db_table_exists group_type::delete group_type::delete (public) group_type::delete->db_table_exists group_type::new group_type::new (public) group_type::new->db_table_exists packages/acs-core-docs/www/index.tcl packages/acs-core-docs/ www/index.tcl packages/acs-core-docs/www/index.tcl->db_table_exists packages/acs-mail-lite/tcl/acs-mail-lite-init.tcl packages/acs-mail-lite/ tcl/acs-mail-lite-init.tcl packages/acs-mail-lite/tcl/acs-mail-lite-init.tcl->db_table_exists

Testcases:
datamodel__acs_object_type_check

db_tables (public)

 db_tables [ -pattern pattern ] [ -dbn dbn ]
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):
%3

Testcases:
No testcase defined.

db_transaction (public)

 db_transaction [ -dbn dbn ] transaction_code [ args... ]

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"
    }
    
Example 2:
In this example, the second command, "nonsense" triggers an error. There is no on_error block, so the transaction is immediately halted and aborted.
    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

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__transaction db__transaction (test acs-tcl) db_transaction db_transaction test_db__transaction->db_transaction test_db__transaction_bug_3440 db__transaction_bug_3440 (test acs-tcl) test_db__transaction_bug_3440->db_transaction aa_run_with_teardown aa_run_with_teardown (public) aa_run_with_teardown->db_transaction acs::test::auth::install acs::test::auth::install (private) acs::test::auth::install->db_transaction acs_mail_lite::after_upgrade acs_mail_lite::after_upgrade (private) acs_mail_lite::after_upgrade->db_transaction acs_mail_lite::imap_conn_set acs_mail_lite::imap_conn_set (private) acs_mail_lite::imap_conn_set->db_transaction acs_mail_lite::inbound_queue_insert acs_mail_lite::inbound_queue_insert (private) acs_mail_lite::inbound_queue_insert->db_transaction

Testcases:
db__transaction, db__transaction_bug_3440

db_type (public)

 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.

Partial Call Graph (max 5 caller/called nodes):
%3 test_db_bind_var_substitution db_bind_var_substitution (test acs-tcl) db_type db_type test_db_bind_var_substitution->db_type test_nullchar nullchar (test acs-tcl) test_nullchar->db_type test_sql_date sql_date (test acs-templating) test_sql_date->db_type apm_file_watchable_p apm_file_watchable_p (public) apm_file_watchable_p->db_type apm_load_queries apm_load_queries (private) apm_load_queries->db_type apm_package_supports_rdbms_p apm_package_supports_rdbms_p (public) apm_package_supports_rdbms_p->db_type apm_query_files_find apm_query_files_find (private) apm_query_files_find->db_type content::type::attribute::new content::type::attribute::new (public) content::type::attribute::new->db_type

Testcases:
db_bind_var_substitution, nullchar, sql_date

db_version (public)

 db_version
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):
%3 test_sql_date sql_date (test acs-templating) db_version db_version test_sql_date->db_version db_current_rdbms db_current_rdbms (public) db_current_rdbms->db_version packages/acs-api-browser/lib/search.tcl packages/acs-api-browser/ lib/search.tcl packages/acs-api-browser/lib/search.tcl->db_version template::util::date::get_property template::util::date::get_property (public) template::util::date::get_property->db_version tsearch2::build_query tsearch2::build_query (private) tsearch2::build_query->db_version

Testcases:
sql_date

db_with_handle (public)

 db_with_handle [ -dbn dbn ] db code_block

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 - Name of the handle variable used in the code block
code_block - code block to be executed with handle

Partial Call Graph (max 5 caller/called nodes):
%3 test_db__0or1row db__0or1row (test acs-tcl) db_with_handle db_with_handle test_db__0or1row->db_with_handle test_db__1row db__1row (test acs-tcl) test_db__1row->db_with_handle test_xowiki_test_cases xowiki_test_cases (test xowiki) test_xowiki_test_cases->db_with_handle db_0or1row db_0or1row (public) db_0or1row->db_with_handle db_abort_transaction db_abort_transaction (public) db_abort_transaction->db_with_handle db_abort_transaction_p db_abort_transaction_p (private) db_abort_transaction_p->db_with_handle db_blob_get db_blob_get (public) db_blob_get->db_with_handle db_blob_get_file db_blob_get_file (public) db_blob_get_file->db_with_handle

Testcases:
db__0or1row, db__1row, xowiki_test_cases

db_write_blob (public)

 db_write_blob [ -dbn dbn ] statement_name sql [ args... ]
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
statement_name
sql

Partial Call Graph (max 5 caller/called nodes):
%3 cr_write_content-lob cr_write_content-lob (private) db_write_blob db_write_blob cr_write_content-lob->db_write_blob

Testcases:
No testcase defined.

db_write_clob (public)

 db_write_clob [ -dbn dbn ] statement_name sql [ args... ]
Switches:
-dbn (optional)
The database name to use. If empty_string, uses the default database.
Parameters:
statement_name
sql

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

Testcases:
No testcase defined.
[ show source ]