transaction, abortTxn and commitTxn

$session->transaction( [ $flag ] );
$session->abortTxn( );
$session->commitTxn( );

These functions start, commit, and stop transactions.

Using transactions, you can commit many changes to the objects in a Domain Manager as a single atomic transaction, or choose to stop all of them. Use the following syntax to create a transaction:

 $session->transaction();

After initiating the transaction, every change made to an object does not affect the object until you commit the transaction. If the transaction is stopped, any changes made will not affect the object. Use the following syntax to either commit or stop a transaction.

 $session->commitTxn( );

or

 $session->abortTxn( );

The changes made with a transaction are not visible outside of the script until the changes are committed. Within a transaction, the same script can see the proposed changes. Transactions also can control how other applications see objects before changes are committed or stopped by adding a single keyword.

The syntax of a transaction with a keyword is:

 $session->
  transaction(["WRITE_LOCK"|"READ_LOCK"|"NO_LOCK"]);

A keyword can be any one of those described in Transaction lock options.

Table 1. Transaction lock options

Keyword	Description
WRITE_LOCK	While the transaction is open, no other process can modify or access information in the repository.
READ_LOCK	The behavior of READ_LOCK is the same as WRITE_LOCK.
NO_LOCK	This is the default behavior. No locks exist until the script commits the transaction.

Transactions may be nested. When you nest a transaction, you must commit or stop the nested transaction before you commit or stop the previous transaction.

The API stops any open transactions when the script terminates.

Example:

 #! /usr/local/bin/Perl
 $session = InCharge::session->init( );
 $delthis = shift @ARGV;
 $delthisObj = $session->object($delthis);
 @relObj = @{ $delthisObj->{ComposedOf} };
 $session->transaction();
 $x = $delthisObj->delete();
 foreach $mem (@relObj) {
  $mem->delete();
 }
 $session->commitTxn();
 print("Deleted ".delthis." and related ports\n”);

In the example, the script deletes a card and its related ports. The script is invoked with an argument that specifies the card to delete. Using the ComposedOf relationship, the script creates a list of port objects to delete. The script deletes the card and its related ports at the same time through a transaction that ensures that no other script can see the intermediate stage with an incompletely deleted suite of objects.