db_transaction

db_transaction transaction_code [ args... ]

Defined in packages/acs-core/10-database-procs.tcl

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}. Any error generated in transaction_code will be caught automatically and process control will transfer to error_code 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 the transaction will be aborted. Alternatively, a command to continue the transaction db_continue_transaction can be issued. This command will commit any successful database commands when the transaction completes, assuming no further errors are raised. If you want to explicity 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_complaint "The DML failed."
    }
    

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)}
    } 
    

Example 3:
In this example, all of the dml statements are executed and committed. The call to db_abort_transaction signals that the transaction should be aborted which activates the higher level on_error block. That code issues a db_continue_transaction which commits the transaction. Had there not been an on_error block, none of the dml statements would have been committed.

    db_transaction {
	db_dml test {insert into footest values(1)}
	db_transaction {
	    db_dml test {insert into footest values(2) }
	    db_abort_transaction
	}
	db_dml test {insert into footest values(3) }
    } on_error {
	db_continue_transaction
    }
    

Parameters:

transaction_code