db_transaction (public)

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

Defined in packages/acs-tcl/tcl/01-database-procs.tcl

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 db_abort_transaction db_abort_transaction (public) db_transaction->db_abort_transaction db_abort_transaction_p db_abort_transaction_p (private) db_transaction->db_abort_transaction_p db_release_unused_handles db_release_unused_handles (public) db_transaction->db_release_unused_handles db_state_array_name_is db_state_array_name_is (private) db_transaction->db_state_array_name_is db_type db_type (public) db_transaction->db_type Class ::xo::Authorize Class ::xo::Authorize (public) Class ::xo::Authorize->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

Testcases:
db__transaction, db__transaction_bug_3440
[ show source ]
Show another procedure: