CosTransactions Module

Current

The Current pseudo-object is used to handle transactions on the client side. This section describes CosTransactions::Current.

Listing 4-1 Definition for CosTransactions::Current Interface
interface Current  {
void begin () raises (SubtransactionsUnavailable);
void commit (in boolean report_heuristics)
raises (NoTransaction, HeuristicMixed, HeuristicHazard);
void rollback () raises (NoTransaction);
void rollback_only () raises (NoTransaction);
Status get_status ();
Control suspend ();
void resume(in Control tran) raises (InvalidControl);
void set_timeout (in unsigned long seconds);
}

The following code listing shows the methods of Current in Visual Basic syntax.

Listing 4-2 Methods for Current in Visual Basic Syntax
Public Sub begin(Optional ByRef exceptionInfo As VARIANT)
Public Sub commit( _
ByVal report_heuristics As Boolean, _
Optional ByRef exceptionInfo As VARIANT)
Public Sub rollback(Optional ByRef exceptionInfo As VARIANT)
Public Sub rollback_only(Optional ByRef exceptionInfo As VARIANT)
Public Function get_status(Optional ByRef exceptionInfo As VARIANT) As Integer
Public Function get_control (Optional ByRef exceptionInfo As VARIANT) As
DICosTransactions_Control
Public Function suspend(Optional ByRef exceptionInfo As VARIANT) As DICosTransactions_Control
Public Sub resume( _
ByVal tran As DICosTransactions_Control, _
Optional ByRef exceptionInfo As VARIANT)
Public Sub set_timeout(	 _
ByVal seconds As Long, _
Optional ByRef exceptionInfo As VARIANT)

The enumerated values that can be returned by get_control() are defined as matching constants for each OLE Automation controller ADE (for example, as Const in Visual Basic). The exceptions raised by methods of Current are returned using the optional exceptionInfo parameter.

Table 4-1 describes each operation of Current as implemented in the Active Expert.

Table 4-1 Active Expert Implementation of Current

Operation Description

begin

begin() is used to begin a new transaction. If there is a transaction already active, a SubtransactionsUnavailable exception is raised.

commit

By issuing commit(), an attempt is made to commit the active transaction using the two-phase commit protocol.

If the value of the report_heuristics_flag passed to commit() is true, the operation will return only after the second phase of the two-phase commit protocol has been completed.

If the value of the flag is false, the operation returns after the commit decision has been logged but before the second phase has been completed.

A HeuristicHazard exception is raised, if due to some failure, the work done on behalf of the transaction has been partially aborted.

A HeuristicMixed exception is raised when, due to a heuristic decision, the work done on behalf of the transaction was partially aborted and partially committed.

A NoTransaction exception is raised by the commit() operation if there is no active transaction.

rollback and rollback_only

The active transaction is aborted by using the rollback() operation.

rollback_only() has the exact same effect as rollback().

A NoTransaction exception is raised by rollback() and rollback_only() if there is no active transaction.

get_status

get_status() returns the state of the transaction: StatusNoTransaction, StatusActive, and StatusMarkedRolledBack.

suspend and resume

suspend() is used to suspend the current active transaction: all requests made after suspend() and before a subsequent resume() are not included in the active transaction.

suspend() returns a Control object if there is an active transaction, otherwise it returns a NULL object reference. The Control object returned by suspend() should be passed to resume(), otherwise an InvalidControl exception is raised.

If a NULL object reference is passed to resume(), the current transaction is suspended.

set_timeout

The operation set_timeout() sets the time-out period associated with subsequent transactions started with begin().

Control

The Control pseudo-object is used to explicitly manage the transaction as opposed to relying on the Transaction Manager. The only purpose of Control in the Active Expert is to act as a handle for the active transaction context for the suspend() and resume() operations of Current.