Transaction Service Interfaces and Classes

This document describes the VisiBroker VisiTransact Transaction Service interfaces and classes. It contains the following sections:

• CosTransactions and VISTransactions modules
• Current interface
• TransactionalObject interface
• TransactionFactory interface
• Control interface
• Terminator interface
• Coordinator interface
• RecoveryCoordinator interface
• Resource interface
• Synchronization interface
• VISTransactionService class
• Commands and arguments
• Error codes

CosTransactions and VISTransactions modules

This section introduces the CosTransactions and VisTransactions modules, and describes the data types, structures, and exceptions for the CosTransactions module.

Looking at the CosTransactions module

The CosTransactions module is the Transaction Service IDL that conforms to the final OMG Transaction Service document. This is the module to use to restrict yourself strictly to CORBA-compliant methods. The IDL for this module is contained in the file CosTransactions.idl.

You might also consider using the VISTransactions module, which contains the IDL for some VisiBroker VisiTransact extensions to the standard. The IDL for the VISTransactions module is contained in the file VISTransactions.idl. You can use VISTransactions.idl in your code to obtain both the CosTransactions and VISTransactions modules. For more information, see "Looking at the VISTransactions module."

Data types

The CosTransactions module defines the data types enum Status and enum Vote.

The definition for the enum Status data type is:

enum Status

{

  StatusActive,

  StatusMarkedRollback,

  StatusPrepared,

  StatusCommitted,

  StatusRolledBack,

  StatusUnknown,

  StatusNoTransaction

  StatusPreparing,

  StatusCommitting,

  StatusRollingBack,

};

For a description of each Status value, see "Status value definitions."

The enum Vote data type is used only by implementations of the CosTransactions::Resource interface. It is used to indicate the result of a Resource's attempt to prepare a transaction.

The definition for the enum Vote data type is:

enum Vote

{

  VoteCommit,

  VoteRollback,

  VoteReadOnly

};

The Vote values are described in the following table.

Structures

The CosTransactions module defines these structures, which are used to save the transaction context.

• otid_t contains an object transaction ID (or otid), which is a globally unique ID for a transaction. The otid_t structure is a more efficient OMG IDL version of the X/Open-defined transaction identifier (XID). The otid_t can be transformed to an X/Open XID and vice versa.
• TransIdentity contains certain key information for a transaction: its Coordinator, its Terminator (optionally), and its otid.
• PropagationContext contains a transaction's TransIdentity and its time-out. In addition, it contains a TransIdentity for the parent and each ancestor transaction, up to the top-level transaction, formatted as a sequence (or array). Because nested transactions are not implemented in VisiTransact, every transaction is a top-level transaction, and the parents sequence will always be empty.

For the most part, these structures are used behind the scenes; you won't reference them directly.

struct otid_t

{

  long formatID;

  long bqual_length;

  sequence <octet> tid;

};

struct TransIdentity

{

  Coordinator coordinator;

  Terminator terminator;

  otid_t otid;

};

struct PropagationContext 

{

  unsigned long timeout;

  TransIdentity current;

  sequence <TransIdentity> parents;

  any implementation_specific_data;

};

When the transaction context is passed from one object to another object, usually a TransactionalObject, it is commonly passed as a PropagationContext. The implementation_specific_data field is reserved for the VisiTransact Transaction Service.

For the most part, these structures are used behind the scenes; you won't reference them directly. Certain methods, however, work explicitly with PropagationContext.

• Coordinator::get_txcontext() extracts a PropagationContext.
• TransactionFactory::recreate() uses a PropagationContext to create a new Control object.

The transaction context is always passed to a transactional object implicitly. In addition, a program may be passed a transaction context explicitly, as a parameter. You can use Coordinator::get_txcontext() to get the PropagationContext. For more information on propagation of transaction context, see "TransactionalObject interface."

Another method that obtains information from these structures is the VISTransactions::Current::get_otid() method, which extracts the otid from the PropagationContext.

Exceptions

Exceptions are divided into three categories: Standard, Heuristic, and Method-specific.

Standard exceptions in the CosTransactions module

Heuristic exceptions in the CosTransactions module

Method-specific exceptions in the CosTransactions module

Looking at the VISTransactions module

Interfaces in the VISTransactions module inherit from and extend the CosTransactions interfaces. The VISTransactions module defines no new data types, structures, or exceptions over those in CosTransactions. For example, the Current interface includes VisiBroker VisiTransact methods that make certain programming operations shorter and more convenient. The IDL for this module is contained in the file VISTransactions.idl.

For related information see "Choosing a Current interface" and "Obtaining a Current object reference."

Current interface

The Current interface defines methods to:

• Enable a program to manage transactions.
• Use implicit transaction propagation.
• Obtain information about the current transaction.
• Register Resources and Synchronization objects.

VisiBroker VisiTransact supports a number of extensions to the OMG Transaction Service specification—additional methods for added convenience. VisiBroker VisiTransact methods on the Current interface can simplify the use of the VisiTransact Transaction Service for most programs. These methods are flagged by the icon where described or cross-referenced.

Choosing a Current interface

The VisiTransact Transaction Service provides the Current interface in the following IDL files:

• CosTransactions.idl contains the Transaction Service IDL that conforms to the final OMG Transaction Service document.
• VISTransactions.idl provides both the CosTransactions interface and the VISTransactions interface, which inherits and extends the CosTransactions::Current interface. This interface includes VisiBroker VisiTransact extensions such as begin_with_name(), register_resource(), and others.

You should use one of these IDL files. To restrict yourself strictly to CORBA-compliant methods, use the CosTransactions.idl. If you decide to use any of the VisiTransact extensions, use VISTransactions.idl.

The following example shows the CosTransactions interface for Current.

...

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();

  string get_transaction_name();

  void set_timeout(in unsigned long seconds);

  Control get_control();

  Control suspend();

  void resume(in Control which)

    raises(InvalidControl);

};

...

The next example shows the VISTransactions interface for Current.

interface Current : CosTransactions::Current

{

  void   begin_with_name(in string user_transaction_name)

         raises(CosTransactions::SubtransactionsUnavailable);

  CosTransactions::RecoveryCoordinator

    register_resource(in CosTransactions::Resource resource)

         raises(CosTransactions::Inactive);

  void   register_synchronization(in CosTransactions::Synchronization synch)

         raises(CosTransactions::NoTransaction,

                CosTransactions::Inactive,

                CosTransactions::SynchronizationUnavailable

                CosTransactions::Unavailable);

  CosTransactions::otid_t get_otid();

         raises(CosTransactions::NoTransaction,

                CosTransactions::Unavailable);

  CosTransactions::PropagationContext get_txcontext()

         raises(CosTransactions::Unavailable,

                CosTransactions::NoTransaction);

  attribute string ots_name;

  attribute string ots_host;

  attribute string ots_factory;

};

Obtaining a Current object reference

To gain access to a VisiTransact-managed transaction, you must obtain an object reference to the Current object. The Current object reference is valid throughout the process.

The example below shows how a reference to the Current object is obtained using the resolve_initial_references() method, and then how the object returned by that method is narrowed to a CosTransactions::Current object.

int main(....)

{

  try

  {

           ... ...

    // ORB related initialization

   // get reference to a CosTransactions::Current instance

  CORBA::Object_var

      obj = orb->resolve_initial_references("TransactionCurrent");

    CosTransactions::Current_var

      current = CosTransactions::Current::_narrow(obj);

  ...

  }

  catch(...) { }  // catch all exceptions or exceptions you care about,

}

VisiBroker VisiTransact offers extensions to the Current interface to simplify certain operations. To take advantage of these extensions, narrow to a VISTransactions::Current object.

VISTransactions::Current::_narrow(obj)

Using the Current object reference

The Current object reference is valid for the entire process under which you create it; you can use it in any thread. You can either make multiple calls to obtain references to the Current object or use just one reference throughout the entire process. Typically, you would obtain one reference to avoid multiple invocations of resolve_initial_references().

The C++ header files that you include must also correspond to your choice of interfaces.

• For VISTransactions, use #include <VISTransactions_c.hh>.
• For CosTransactions, use #include <CosTransactions_c.hh>.

For more information, see the VisiBroker VisiTransact Guide.

Is your VisiTransact Transaction Service instance available?

You can issue begin() or begin_with_name() to determine if the instance of your VisiTransact Transaction Service is available. The method will raise CORBA:NO_IMPLEMENT exception if the instance is not available.

Calling get_status() when there is no available instance of the VisiTransact Transaction Service will return the current transaction state, and cannot be used to determine if the instance of the VisiTransact Transaction Service is available.

Checked behavior

Checked behavior is supported by the VisiTransact Transaction Service to provide an extra level of transaction integrity. Specifically, checked behavior is supported for transactions originated with Current::begin(). The purpose of the checks is to ensure that all transactional requests made by the application have completed their processing before the transaction is committed. This guarantees that a commit will not succeed unless all transactional objects involved in the transaction have completed the processing of their transactional requests. For checks that are part of the commit process, see "commit()". For more information about checked behavior, see the VisiBroker VisiTransact Guide.

Current methods

begin()

void begin()

raises SubtransactionsUnavailable;

This method creates a new transaction. Because nested transactions are not supported in VisiBroker VisiTransact, this is always a top-level transaction.

The transaction context of the client thread is modified so that the thread is associated with the new transaction. If the client thread is already associated with a transaction, the SubtransactionsUnavailable exception is raised.

Included in the Current interface in CosTransactions.idl

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

begin_with_name()

void begin_with_name(in string user_transaction_name)

raises(CosTransactions::SubtransactionsUnavailable);

This VisiBroker VisiTransact method is a begin() method that enables its caller to pass a user-defined informational transaction name. For example, this helps with diagnostics because the user-defined transaction name is included in the value returned by the get_transaction_name() method. The name also helps with administration, because the Console will report the name in the detailed information about an outstanding transaction.

To use this method, narrow the object returned from resolve_initial_references() to VISTransactions::Current. For more information, see "Obtaining a Current object reference".

Included in the Current interface in VISTransactions.idl

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

commit()

void commit(in boolean report_heuristics)

raises(NoTransaction,

       HeuristicMixed,

       HeuristicHazard

);

This method commits the transaction associated with the client thread. The effect of this method is equivalent to calling the commit() method on the corresponding Terminator object.

If this transaction has been marked for rollback, or any Resource votes for rollback, this call raises CORBA::TRANSACTION_ROLLEDBACK. If there is no current transaction, a CosTransactions::NoTransaction exception is raised. If the caller is not the transaction originator, commit() raises the exception CORBA::NO_PERMISSION.

Checks are made to ensure checked behavior. See the VisiBroker VisiTransact Guide for more information.

On return from this method, the client thread is no longer associated with a transaction. Any attempt to use Current, as if there were a transaction, will raise an exception, such as NoTransaction or CORBA::TRANSACTION_REQUIRED, or will return a null object reference.

This method does not return until the transaction is complete, and all related Synchronization objects have been notified.

Included in the Current interface in CosTransactions.idl

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information on the heuristic log, see the VisiBroker VisiTransact Guide.

get_control()

Control get_control();

This method returns a Control object reference that represents the transaction context currently associated with the client thread.

If the client thread is not associated with a transaction, a null object reference is returned.

Caution: See the VisiBroker VisiTransact Guide for details on checked behavior and the implications of using this method.

Included in the Current interface in CosTransactions.idl.

No user exceptions are raised.

For related material, see "Control interface" and "Terminator interface." For more information see the VisiBroker VisiTransact Guide.

get_otid()

CosTransactions::otid_t get_otid()

raises(CosTransactions::NoTransaction,

       CosTransactions::Unavailable);

Most applications will not normally call this method.

This VISTransactions::Current method provides the object transaction ID (otid) through the Current interface as a convenience. This avoids going to the Coordinator and looking through a PropagationContext. The otid is used to identify a transaction to a recoverable object. This method raises CosTransactions::NoTransaction if no transaction is associated with the client thread.

To use this method, narrow the object returned from resolve_initial_references() to VISTransactions::Current. For more information, see "Obtaining a Current object reference".

Included in the Current interface in VISTransactions.idl.

The following exceptions may be raised when calling this method.

For related material, see "Coordinator interface" and "Terminator interface."

get_status()

Status get_status();

This method returns an enumerated value (enum Status) that represents the status of the transaction associated with the client thread.

Calling this method is equivalent to calling the get_status() method on the corresponding Coordinator object. If there is no transaction associated with the current thread, then the method returns CosTransactions::StatusNoTransaction.

The possible return values are:

• StatusActive
• StatusMarkedRollback
• StatusPrepared
• StatusCommitted
• StatusRolledBack
• StatusUnknown
• StatusNoTransaction
• StatusPreparing
• StatusCommitting
• StatusRollingBack

Included in the Current interface in CosTransactions.idl.

No user exceptions are raised.

Status value definitions

Some implications of the enum Status values are:

• StatusActive—A transaction is associated with the target object and it is in the active state. The VisiTransact Transaction Service returns this status after a transaction has been started and prior to a Coordinator issuing any prepare statements--unless the transaction has been marked for rollback or timed out.
• StatusMarkedRollback—A transaction is associated with the target object and has been marked for rollback, perhaps as the result of the rollback_only() method.
• StatusPrepared—A transaction is associated with the target object and has been prepared.
• StatusCommitted—A transaction is associated with the target object and has been committed. It is likely that heuristics exist, otherwise the transaction would have been quickly destroyed and StatusNoTransaction returned.
• StatusRolledBack—A transaction is associated with the target object and the outcome has been determined as rollback. It is likely that heuristics exist, otherwise the transaction would have been quickly destroyed and StatusNoTransaction returned.
• StatusUnknown—A transaction is associated with the target object, but the VisiTransact Transaction Service cannot determine its current status. This is a transient condition, and a subsequent invocation will ultimately return a different status.
• StatusNoTransaction—No transaction is currently associated with the target object. This will occur after a transaction has completed.
• StatusPreparing—A transaction is associated with the target object and it is in the process of preparing. The VisiTransact Transaction Service returns this status if the transaction has started preparing, but has not yet completed the process—perhaps because it is waiting for responses to prepare from one or more Resources.
• StatusCommitting—A transaction is associated with the target object and is in the process of committing. The VisiTransact Transaction Service returns this status if the transaction has begun to commit, but has not yet completed the process--perhaps because it is waiting for responses from one or more Resources.
• StatusRollingBack—A transaction is associated with the target object and it is in the process of rolling back. The VisiTransact Transaction Service returns this status if the transaction is being rolled back, but has not yet completed the process--perhaps because it is waiting for responses from one or more Resources.

get_transaction_name()

string get_transaction_name();

This method returns a printable string that is a descriptive name for the transaction. This method is intended to assist in diagnostics and debugging. If the transaction was created by the begin_with_name() method, the returned string is the user-defined name assigned to the transaction, rather than the VisiTransact Transaction Service-generated name.

The effect of this method is equivalent to calling the get_transaction_name() method on the corresponding Coordinator object. If there is no transaction associated with the client thread, an empty string is returned.

Included in the Current interface in CosTransactions.idl.

No user exceptions are raised.

get_txcontext()

CosTransactions::PropagationContext get_txcontext()

raises(CosTransactions::Unavailable,

       CosTransactions::NoTransaction);

Most applications will not normally call this method.

This VISTransactions::Current method returns a PropagationContext, which can be used by one VisiTransact Transaction Service domain to export a transaction to a new VisiTransact Transaction Service domain.

To use this method, narrow the object returned from resolve_initial_references() to VISTransactions::Current. For more information, see "Obtaining a Current object reference".

Included in the Current interface in VISTransactions.idl.

The following exceptions may be raised when calling this method.

For related material, see "Coordinator interface," and "Terminator interface."

ots_factory

attribute string ots_factory;

If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call VISTransactions::Current::begin(). Subsequent calls to the begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again.

This attribute specifies the VisiTransact Transaction Service instance by IOR. VisiTransact uses the specified IOR (CosTransactions::TransactionFactory) to locate the desired instance of a VisiTransact Transaction Service instance on the network. This argument enables VisiTransact to operate without the use of a Smart Agent (osagent).

If you specify the IOR with either the Host Name or VisiTransact Transaction Service Name attributes, the Smart Agent will find the VisiTransact Transaction Service instance by IOR only--it ignores the other attributes. If you leave all three attributes null, the ORB chooses a VisiTransact Transaction Service instance using the VisiBroker Smart Agent.

Included in the Current interface in VISTransactions.idl.

To set this attribute, use the appropriate method generated automatically for the language you are using.

For more information, see the VisiBroker VisiTransact Guide.

ots_host

attribute string ots_host;

If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call VISTransactions::Current::begin(). Subsequent calls to the begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again. To return this attribute to the default VisiTransact instance, set it to an empty or null string.

This attribute specifies the VisiTransact Transaction Service instance by host name. The Smart Agent will find any available VisiTransact Transaction Service instance that is located on the specified host.

If you specify a combination of Host Name and VisiTransact Transaction Service Name attributes, the Smart Agent will find the named VisiTransact Transaction Service instance on the named host. If you leave all three attributes null, the ORB chooses a VisiTransact Transaction Service instance using the VisiBroker Smart Agent.

Included in the Current interface in VISTransactions.idl.

To set this attribute, use the appropriate method generated automatically for the language you are using.

For more information, see the VisiBroker VisiTransact Guide.

ots_name

attribute string ots_name;

If you are using VISTransactions.idl, you can control the instance of the VisiTransact Transaction Service used to create a transaction by setting this attribute before you call VISTransactions::Current::begin(). Subsequent calls to the begin() method create transactions on the specified VisiTransact Transaction Service. This attribute applies to all the threads in your program. When the attribute is set, it retains its value until set again. To return this attribute to the default VisiTransact instance, set it to an empty or null string.

This attribute specifies the VisiTransact Transaction Service instance by name. The Smart Agent will find the named VisiTransact Transaction Service instance anywhere on the network.

If you specify a combination of Host Name and VisiTransact Transaction Service Name attributes, the Smart Agent will find the named VisiTransact Transaction Service instance on the named host. If you leave all three attributes null, the ORB chooses a VisiTransact Transaction Service instance using the VisiBroker Smart Agent.

Included in the Current interface in VISTransactions.idl.

To set this attribute, use the appropriate method generated automatically for the language you are using.

For more information, see the VisiBroker VisiTransact Guide.

register_resource()

CosTransactions::RecoveryCoordinator

     register_resource(in CosTransactions::Resource resource)

raises(CosTransactions::Inactive);

Most applications will not normally call this method.

This VISTransactions::Current method registers a Resource for a recoverable object. This method is a shortcut for using the Control and Coordinator objects to register a Resource for a recoverable object. It returns a Recovery Coordinator object that can be used to help coordinate recovery. If this method is invoked when there is no transaction associated with the client thread, the CORBA::TRANSACTION_REQUIRED exception is thrown.

To use this method, narrow the object returned from resolve_initial_references() to VISTransactions::Current. For more information, see "Obtaining a Current object reference".

Included in the Current interface in VISTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For related material, see "Coordinator interface."

register_synchronization()

void register_synchronization(in CosTransactions::Synchronization synch)

raises(CosTransactions::NoTransaction,

       CosTransactions::Inactive,

       CosTransactions::SynchronizationUnavailable

       CosTransactions::Unavailable);

This VISTransactions::Current method registers a Synchronization object. This method is a short-cut for using the Control and Coordinator object to register a Synchronization object. To use this method, narrow the object returned from resolve_initial_references() to VISTransactions::Current. For more information, see "Obtaining a Current object reference".

Included in the Current interface in VISTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

resume()

void resume(in Control which)

raises(InvalidControl);

Associates the client thread with the specified transaction. Typically, this is used to either

• Associate a transaction context with a thread for use in implicit transaction propagation, or
• Resume a transaction that was previously suspended by a suspend() method.

The client thread becomes associated with the specified transaction. If the client thread was already associated with a transaction, the previous transaction context is forgotten. If resume() is invoked with a NULL control, no transaction is associated with the current thread, and the transaction context is forgotten.

Caution: Any transaction context you set via resume() is propagated back to the invoking object.

Included in the Current interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

rollback()

void rollback()

raises(NoTransaction);

Rolls back the transaction associated with the client thread. This is equivalent to calling the rollback() method on the corresponding Terminator object. This method does not return until the transaction is complete, and all related Synchronization objects have been notified. On return from this method, the client thread is no longer associated with a transaction. Any attempt to use Current, as if there were a transaction, will raise an exception, such as CosTransactions::NoTransaction or CORBA::TRANSACTION_REQUIRED, or return a null object reference. If a heuristic occurs, this method will not throw a heuristic-related exception.

If the caller is not the transaction originator, rollback() raises the exception CORBA::NO_PERMISSION.

Included in the Current interface in CosTransactions.idl.

For more information, see the VisiBroker VisiTransact Guide.

rollback_only()

void rollback_only()

raises(NoTransaction);

The method modifies the transaction associated with the client thread so that rollback is the only possible transaction outcome. The effect of this request is equivalent to calling the rollback_only() method on the corresponding Coordinator object. A client that is restricted from performing the rollback() operation, can nonetheless call rollback_only().

Included in the Current interface in CosTransactions.idl.

Exceptions

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

set_timeout()

void set_timeout(in unsigned long seconds);

This method establishes a new timeout for transactions started by subsequent calls to the Current::begin() method in all threads within this program.

To establish a new timeout, use these values of the seconds parameter:

Note: When a transaction, created by a subsequent call to begin() in any thread in the process, takes longer to start transaction completion than the established timeout, it will be rolled back. If the timeout occurs before the transaction enters the completion stage (begins two-phase or one-phase processing) the transaction will be rolled back. Otherwise, the timeout is ignored.

Included in the Current interface in CosTransactions.idl.

The following parameters are used by this method.

No user exceptions are raised.

For more information see the description of set_timeout() in the VisiBroker VisiTransact Guide.

suspend()

Control suspend();

This method suspends the transaction currently associated with the client thread and returns a Control object for that transaction. If the client thread is not associated with a transaction, a null object reference is returned.

The Control object can be passed to the resume() method to reestablish this context in the same thread or a different thread.

After the call to suspend(), no transaction is associated with the client thread. Any attempt to use Current, as if there were a transaction, will raise an exception, such as CosTransactions::NoTransaction or CORBA::TRANSACTION_REQUIRED, or return a null object reference.

Included in the Current interface in CosTransactions.idl.

No user exceptions are raised.

TransactionalObject interface

The TransactionalObject interface provides for the automatic propagation of transaction context on method calls of transactional objects. The TransactionalObject interface defines no methods.

Methods that work on transactions must have access to the transaction context. The transaction context can be made available to such methods in two ways:

• Explicit propagation. A method receives and passes the transaction context as a Terminator, Control, Coordinator, or PropagationContext structure. For further information, see the VisiBroker VisiTransact Guide.
• Implicit propagation. The transaction context is passed automatically (and implicitly) on method calls. For further information, see the VisiBroker VisiTransact Guide.

Implicit propagation is the typical, and easiest, way. This is the capability that the TransactionalObject interface provides to your transactional objects.

For information about the details of what information is in the transaction context, see "Structures."

An instance of TransactionalObject can participate in implicit propagation. Implicit propagation is where the transaction context associated with the client thread is automatically propagated to TransactionalObject instances through method calls.

To use VisiTransact-managed transactions, all of your transactional objects must inherit from TransactionalObject. By using VisiTransact-managed transactions, you benefit from checked behavior.

The following example shows the TransactionalObject interface in the CosTransactions.idl file.

interface TransactionalObject 

{

};

The transaction context is always passed implicitly to an object that inherits from CosTransactions::TransactionalObject. In addition, a program may be passed a transaction context explicitly, as a parameter.

TransactionFactory interface

As described in "Current interface" the Current interface enables a program to initiate VisiTransact-managed transactions. This chapter, by contrast, describes the TransactionFactory interface, which defines methods that enable a program to initiate non-VisiTransact-managed transactions. The TransactionFactory interface gives programs direct control over the propagation of transaction context.

In the CosTransactions module, the TransactionFactory interface provides three methods.

For further information about using different IDL files, see "Choosing a Current interface."

Note: You acquire a TransactionFactory object the way you do any CORBA object; for example, by binding.

Methods that are VisiBroker VisiTransact extensions are flagged by the icon where described or cross-referenced.

The following example shows the CosTransactions IDL for TransactionFactory.

...

interface TransactionFactory 

{

  Control create(in unsigned long time_out);

  Control recreate(in PropagationContext ctx);

};

...

The next example shows the VISTransactions IDL for TransactionFactory.

...

interface TransactionFactory : CosTransactions::TransactionFactory 

{

  CosTransactions::Control 

    create_with_name(in unsigned long time_out, 

               in string user_transaction_name);

};...

...

TransactionFactory methods

create()

CosTransactions::Control create(in unsigned long time_out);

This method accepts a timeout parameter (time_out) and creates a new transaction. It returns a Control object. The Control object can be used to manage or to control participation in the new transaction. The Control object can be used by any thread and passed around explicitly, just like any other CORBA object.

Note: Checked behavior cannot be provided for transactions that use this method.

Included in the TransactionFactory interface in CosTransactions.idl.

The following parameters are used by this method.

To establish a new timeout, use the following values of the time_out parameter.

Note: If a transaction does not start transaction completion (begin two-phase or one-phase processing) before the timeout expires, it will be rolled back.

The new timeout applies only to the transaction created on this call.

See the description of set_timeout() in the VisiBroker VisiTransact Guide.

No user exceptions are raised.

create_with_name()

CosTransactions::Control 

create_with_name(in unsigned long time_out, 

                 in string user_transaction_name);

This VISTransactions method extends the CosTransactions::
TransactionFactory::create() method by enabling you to create a new transaction and assign it an informational transaction name that can be used for debugging and error reporting. The user-defined transaction name is included in the value returned by get_transaction_name().

Note: Checked behavior cannot be provided for transactions that use this method.

This method returns a Control object. The Control object can be used to manage or to control participation in the new transaction. The Control object can be used by any thread and passed around explicitly, just like any other CORBA object.

Included in the TransactionFactory interface in VISTransactions.idl.

The following parameters are used by this method.

To establish a new timeout, use these values of the time_out parameter.

Note: If a transaction does not start transaction completion (begin two-phase or one-phase processing) before the timeout expires, it will be rolled back.

The new timeout applies only to the transaction created on this call.

See the description of set_timeout() in the VisiBroker VisiTransact Guide.

No user exceptions are raised.

For more information, see the VisiBroker VisiTransact Guide.

recreate()

Control recreate(in PropagationContext context);

Most applications will not normally call this method.

This method creates a new Control object using its PropagationContext parameter. The Control object can be used to manage or to control participation in the transaction.

To get a transaction's PropagationContext, invoke the get_txcontext() method on the transaction's Coordinator object.

Included in the TransactionFactory interface in CosTransactions.idl.

The following parameters are used by this method.

No user exceptions are raised.

The following example shows the way get_txcontext() and recreate() work together to recreate a transaction.

...

CosTransactions::Coordinator_var coord;

CosTransactions::TransactionFactory_var newDomainFactory;

...

propxtxt = coord->get_txcontext();

CosTransactions::Control_var control = newDomainFactory->recreate(propctxt);

...

Control interface

The Control interface enables a program to explicitly manage or propagate a transaction context. A Control object is implicitly associated with one specific transaction.

The Control interface defines two methods:

• get_coordinator()
• get_terminator()

The get_coordinator() method returns a Coordinator object, which supports methods used by participants in the transaction. The get_terminator() method returns a Terminator object, which supports methods to complete the transaction. The Terminator and Coordinator objects support methods that are typically performed by different parties. Providing two objects enables each set of methods to be made available only to the parties that require those methods.

The example below contains the IDL for the Control interface, an excerpt from the CosTransactions.idl file.

...

interface Control 

{

  Terminator get_terminator()

    raises(Unavailable);

  Coordinator get_coordinator()

    raises(Unavailable);

};

...

You can obtain a Control object by using one of the methods of the TransactionFactory. See "TransactionFactory interface." You can also obtain a Control object for the current transaction (associated with a thread) through methods of the Current object. See "get_control()" or "suspend()" in "Current interface."

Control methods

get_coordinator()

Coordinator get_coordinator()

raises(Unavailable);

This method returns a Coordinator object. The Coordinator provides methods that are called by participants in a transaction. These participants are typically either recoverable objects or agents of recoverable objects.

Included in the Control interface in CosTransactions.idl.

The following exceptions may be raised when calling this method.

For more information, see "Coordinator interface" for details on methods you can use once you obtain the Coordinator object.

get_terminator()

Terminator get_terminator()

raises(Unavailable);

This method returns a Terminator object. The Terminator can be used to rollback or commit the transaction associated with the Control. The Unavailable exception is raised if the Control cannot provide the requested object due to the inability of the Terminator object to be transmitted to or be used in other execution environments.

Included in the Control interface in CosTransactions.idl.

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

Terminator interface

The Terminator interface supports methods to commit or rollback a transaction. Typically, these methods are used by the transaction originator, but any program that has access to a Terminator object for that transaction can commit or rollback the transaction.

The following example contains the IDL for the Terminator interface, an excerpt from the CosTransactions.idl file.

...

interface Terminator 

{

  void commit(in boolean report_heuristics)

    raises (HeuristicMixed,

            HeuristicHazard);

  void rollback();

};

...

Terminator methods

commit()

void commit(in boolean report_heuristics)

raises(HeuristicMixed,

       HeuristicHazard);

Before committing the transaction, this method performs some checks. If the transaction has not been marked rollback only, and all of the participants in the transaction agree to commit, the transaction is committed and the operation terminates normally. Otherwise, the transaction is rolled back and the CORBA::TRANSACTION_ROLLEDBACK standard exception is raised.

If the report_heuristics parameter is true, the VisiTransact Transaction Service will report inconsistent or possibly inconsistent outcomes using the CosTransactions::HeuristicMixed and CosTransactions::HeuristicHazard exceptions when appropriate. Information about the Resources involved in a heuristic outcome will be written to a heuristic log file corresponding to the instance of the VisiTransact Transaction Service. For more information on heuristics, see the VisiBroker VisiTransact Guide.

When a transaction is committed, all changes to recoverable objects made in the scope of this transaction are made permanent and visible to other transactions or clients.

Included in the Terminator interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

The example below shows how to use the commit() method with and without heuristics.

// Using commit() without heuristics.

try

{

   terminator->commit(0);

}

catch(CORBA::TRANSACTION_ROLLEDBACK&)

{

   cerr << "Transaction failed" << endl;

}

...

// Using commit() with heuristics.

try

{

   terminator->commit(1);

}

catch(CORBA::TRANSACTION_ROLLEDBACK&)

{

   cerr << "Transaction failed" << endl;

}

catch(CosTransactions::HeuristicMixed&)

{

   cerr << "HeuristicMixed exception was raised" << endl;

}

catch(CosTransactions::HeuristicHazard&)

{

   cerr << "HeuristicHazard exception was raised" << endl;

}

catch(CORBA::OBJECT_NOT_EXIST&)

{

   cerr << "Transaction no longer exists" << endl;

}

For more information, see the VisiBroker VisiTransact Guide.

rollback()

void rollback();

This method rolls back the transaction. When a transaction is rolled back, all changes to recoverable objects made in the scope of this transaction are rolled back. All Resources locked by the transaction are made available to other transactions as appropriate to the degree of isolation enforced by the Resources.

This method does not return until the transaction is complete and all related Synchronization objects have been notified. Any heuristic outcome that may occur will be provided through the Console.

Included in the Terminator interface in CosTransactions.idl.

The following exceptions may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

Coordinator interface

The Coordinator interface provides methods that are used by participants in a transaction. These participants are typically either recoverable objects or agents of recoverable objects. Each Coordinator is implicitly associated with a single transaction.

The following example shows the CosTransactions IDL for the Coordinator interface.

...

interface Coordinator

{

  Status get_status();

  Status get_parent_status();

  Status get_top_level_status();



  boolean is_same_transaction(in Coordinator coord);

  boolean is_related_transaction(in Coordinator coord);

  boolean is_ancestor_transaction(in Coordinator coord);

  boolean is_descendant_transaction(in Coordinator coord);

  boolean is_top_level_transaction();



  unsigned long hash_transaction();

  unsigned long hash_top_level_tran();



  RecoveryCoordinator register_resource(in Resource resource)

    raises(Inactive);



  void register_synchronization(in Synchronization synch)

    raises(Inactive, SynchronizationUnavailable);



  void register_subtran_aware(in SubtransactionAwareResource resource)

    raises(Inactive, NotSubtransaction);



  void rollback_only()

    raises(Inactive);



  string get_transaction_name();



  Control create_subtransaction()

    raises(SubtransactionsUnavailable, Inactive);



  PropagationContext get_txcontext()

    raises(Unavailable);

};

Because VisiTransact does not support nested transactions, several of the Coordinator methods have become equivalent—that is, they return the same result. More information is provided later in the chapter with the method descriptions.

The following methods are equivalent:

• get_status()
• get_top_level_status()
• get_parent_status()

Similarly, certain methods return true only when the target object and the parameter refer to the same Coordinator object. Therefore, the following methods are also equivalent:

• is_same_transaction()
• is_related_transaction()
• is_ancestor_transaction()
• is_descendant_transaction()

And, the following methods are equivalent:

• hash_transaction()
• hash_top_level_tran()

Finally, without nested transactions, the create_subtransaction() method is not useful and is therefore excluded from this version of VisiTransact (and this documentation), although it is described in the OMG specification.

Coordinator methods

get_parent_status()

Status get_parent_status();

Because VisiTransact does not support nested transactions, every transaction is top-level, and get_parent_status() of a top-level transaction is equivalent to get_status(), by OMG definition. For further information, see "get_status()".

Included in the Coordinator interface in CosTransactions.idl.

get_status()

Status get_status();

This method returns the status of the transaction associated with the target object, as an enumerated value (enum Status). If there is no transaction associated with the target object, then the method returns the value StatusNoTransaction.

The following are the possible return values, as defined in CosTransactions.idl:

• StatusActive
• StatusMarkedRollback
• StatusPrepared
• StatusCommitted
• StatusRolledBack
• StatusUnknown
• StatusNoTransaction
• StatusPreparing
• StatusCommitting
• StatusRollingBack

For information about each Status value, see "Status value definitions."

Included in the Coordinator interface in CosTransactions.idl.

For more information, see the VisiBroker VisiTransact Guide.

get_top_level_status()

Status get_top_level_status();

Because VisiTransact does not support nested transactions, every transaction is top-level. Therefore, this method is equivalent to the get_status() method. See "get_status()".

Included in the Coordinator interface in CosTransactions.idl.

get_transaction_name()

string get_transaction_name();

This method returns a printable string that is a descriptive name for the transaction. This method is intended to assist with diagnostics and debugging. If the transaction was created by the VISTransactions::TransactionFactory::create_with_name() method, the return string is the user-defined descriptive transaction name rather than the VisiTransact Transaction Service-generated name. If there is no transaction associated with the client thread, an empty string is returned.

Included in the Coordinator interface in CosTransactions.idl.

For more information, see the VisiBroker VisiTransact Guide.

get_txcontext()

PropagationContext get_txcontext()

raises(Unavailable);

Most applications will not normally call this method.

The get_txcontext() method returns a PropagationContext, which can be used by one VisiTransact Transaction Service domain to export a transaction to a new VisiTransact Transaction Service domain.

Included in the Coordinator interface in CosTransactions.idl.

The following exceptions may be raised when calling this method.

hash_top_level_tran()

unsigned long hash_top_level_tran();

Most applications will not normally call this method.

Because VisiTransact does not support nested transactions, every transaction is a top-level transaction. Therefore, this method is equivalent to the hash_transaction() method.

This method returns a hash code for the transaction associated with the target object. Each transaction has a single hash code. The hash code can be used to efficiently compare Coordinators for inequality against the hash codes of other transactions. If the hash codes of two Coordinators are not equal, then they represent different transactions. If two hash codes are equal, then Coordinator::is_same_transaction() must be used to guarantee equality or inequality, because two Coordinators might have the same hash code but, in fact, represent two different transactions.

Included in the Coordinator interface in CosTransactions.idl.

For more information, see the VisiBroker VisiTransact Guide.

hash_transaction()

unsigned long hash_transaction();

Most applications will not normally call this method.

This method returns a hash code for the transaction associated with the target object. Each transaction has a single hash code. The hash code can be used to efficiently compare Coordinators for inequality against the hash codes of other transactions. If the hash codes of two Coordinators are not equal, then they represent different transactions. If two hash codes are equal, then Coordinator::is_same_transaction() must be used to guarantee equality or inequality, because two Coordinators might have the same hash code but, in fact, represent two different transactions.

Included in the Coordinator interface in CosTransactions.idl.

The example below shows a method that uses hash_transaction() to efficiently reject unequal Coordinators.

CORBA::Boolean are_same(Coord1, Coord2)

{

  CORBA::ULong hash1 = Coord1->hash_transaction();

  CORBA::ULong hash2 = Coord2->hash_transaction();

  if(hash1 != hash2)

  {

    return 0;

  }

  else

  {

    return Coord1->is_same_transaction(Coord2);

  }

}

For more information, see the VisiBroker VisiTransact Guide.

is_ancestor_transaction()

boolean is_ancestor_transaction(in Coordinator coord);

Because VisiTransact does not support nested transactions, this method returns true if, and only if, the target object and the parameter object refer to the same transaction.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

is_descendant_transaction()

boolean is_descendant_transaction(in Coordinator coord);

Because VisiTransact does not support nested transactions, this method returns true if, and only if, the target object and the parameter object refer to the same transaction.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

is_related_transaction()

boolean is_related_transaction(in Coordinator coord);

Because VisiTransact does not support nested transactions, this method returns true if, and only if, the target object and the parameter object refer to the same transaction.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

is_same_transaction()

boolean is_same_transaction(in Coordinator coord);

This method returns true if, and only if, the target object and the parameter object both refer to the same transaction.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

For more information, see the VisiBroker VisiTransact Guide.

is_top_level_transaction()

boolean is_top_level_transaction(in Coordinator coord);

Because VisiTransact does not support nested transactions, this method always returns true.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

For more information, see the VisiBroker VisiTransact Guide.

register_resource()

RecoveryCoordinator register_resource(in Resource resource)

raises(Inactive);

This method registers the specified Resource as a participant in the transaction associated with the target object. When the transaction is terminated, the Resource will receive requests to prepare, commit, or rollback the updates performed as part of the transaction. For information on Resource methods, see "Resource interface."

This method returns a RecoveryCoordinator that can be used by this Resource during recovery.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information, see "RecoveryCoordinator interface" and "Resource interface".

register_synchronization()

void register_synchronization(in Synchronization synch)

raises(Inactive, SynchronizationUnavailable);

This method registers the specified Synchronization object so that it will be notified to perform the necessary processing before and after completion of the transaction. Such methods are described in the description of the Synchronization interface; see "Synchronization interface."

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information, see "Resource interface," "Synchronization interface," and see the VisiBroker VisiTransact Guide.

register_subtran_aware()

void register_subtran_aware(in SubtransactionAwareResource resource)

raises(Inactive, SubtransactionsUnavailable);

Because VisiTransact does not support nested transactions, this method always raises CosTransactions::SubtransactionsUnavailable.

Included in the Coordinator interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

rollback_only()

void rollback_only()

raises (Inactive);

This method modifies the transaction associated with the Coordinator so that rollback is the only possible transaction outcome.

Included in the Coordinator interface in CosTransactions.idl.

The following exceptions may be raised when calling this method.

For more information about invoking rollback_only(), see the VisiBroker VisiTransact Guide.

RecoveryCoordinator interface

When a Resource is registered with the Coordinator, a RecoveryCoordinator is returned. The RecoveryCoordinator is implicitly associated with a single Resource registration request and can only be used by that Resource. In case recovery is necessary, the Resource can use the RecoveryCoordinator during the recovery process.

Also, the Resource can use the RecoveryCoordinator if it needs to know the current status of the transaction. For example, the Resource can set its own timeout, and if commit or rollback does not occur within the timeout, the Resource can invoke replay_completion() to determine the status of the transaction.

The following example shows the RecoveryCoordinator interface in the CosTransactions.idl file.

...

interface RecoveryCoordinator

{

  Status replay_completion(in Resource resource)

    raises(NotPrepared);

};

...

RecoveryCoordinator methods

replay_completion()

Status replay_completion(Resource resource)

raises(NotPrepared);

This method notifies the VisiTransact Transaction Service that the Resource is available. This method is typically used during recovery, and can be used by the Resource to determine the status of the transaction.

Note: This method does not initiate completion.

Included in the RecoveryCoordinator interface in CosTransactions.idl.

The following parameters are used by this method.

The following exceptions may be raised when calling this method.

For more information on Status values, see "Status value definitions" in "Current interface."

Resource interface

VisiBroker VisiTransact uses a two-phase commit protocol to complete a top-level transaction with each Resource registered with it—that is, with each Resource that might change during the transaction. The Resource interface defines the methods invoked by the VisiTransact Transaction Service on each Resource. Each object supporting the Resource interface is implicitly associated with a single top-level transaction.

The following example shows the Resource interface in the CosTransactions.idl file.

...

interface Resource 

{

  Vote prepare()

    raises(

        HeuristicMixed,

        HeuristicHazard

    );

  void rollback()

    raises(

        HeuristicCommit,

        HeuristicMixed,

        HeuristicHazard

    );

  void commit()

    raises(

        NotPrepared,

        HeuristicRollback,

        HeuristicMixed,

        HeuristicHazard

    );

  void commit_one_phase()

    raises(

        HeuristicHazard

    );

  void forget();

};

...

VisiBroker VisiTransact provides this interface, but you must provide the implementation in your Resource. A typical application does not implement a Resource.

Resource methods

commit()

void commit()

raises(NotPrepared

       HeuristicRollback

       HeuristicMixed

       HeuristicHazard

  );

This method attempts to commit all changes associated with the Resource. If a heuristic outcome exception is raised, the Resource must keep the heuristic decision in persistent storage until the forget() method is performed so that it can return the same outcome in case commit() is invoked again during recovery. Otherwise, the Resource can immediately forget all knowledge of the transaction.

Included in the Resource interface in CosTransactions.idl.

The following exceptions may be thrown when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

commit_one_phase()

void commit_one_phase()

raises (HeuristicHazard);

The commit_one_phase() method requests the Resource to commit all changes made as part of the transaction. This method is an optimization for use when a transaction has only one participating Resource. The commit_one_phase() method can be called on the Resource, instead of first calling prepare() and then commit() or rollback().

If a heuristic outcome exception is raised, the Resource must keep the heuristic decision in persistent storage until the forget() method is performed. This enables the Resource to return the same outcome in case commit_one_phase() is performed again during recovery. Otherwise, the Resource immediately forgets all knowledge of the transaction.

Included in the Resource interface in CosTransactions.idl.

If a failure occurs during commit_one_phase(), it is called again when the failure is repaired. Since there is only a single Resource, the HeuristicHazard exception is used to report heuristic decisions related to that Resource.

The following exceptions may be thrown when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

forget()

void forget();

When VisiBroker VisiTransact receives a heuristic exception, it records the exception. The VisiTransact Transaction Service will ultimately call forget() on the Resource. This means that the Resource can discard all information about the transaction that raised the heuristic exception. This method is called only if a heuristic exception was raised from rollback(), commit(), or commit_one_phase().

Included in the Resource interface in CosTransactions.idl.

For more information, see the VisiBroker VisiTransact Guide.

prepare()

Vote prepare()

raises(HeuristicMixed

       HeuristicHazard

);

This method performs the prepare operation—the first step in the two-phase commit protocol for a Resource object. When finished, the method returns one of these Vote values.

After returning VoteReadOnly or VoteRollback, the Resource can forget all knowledge of the transaction.

If a heuristic outcome exception is raised, the Resource must save the heuristic decision in persistent storage until the forget() method is called so that it can return the same outcome in case prepare() is called again.

Included in the Resource interface in CosTransactions.idl.

The following exceptions may be thrown when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

rollback()

void rollback()

raises(HeuristicCommit

       HeuristicMixed

       HeuristicHazard

);

This method rolls back all updates associated with the Resource object.

If a heuristic outcome exception is raised, the Resource must save the heuristic decision in persistent storage until the forget() method is invoked. This enables the Resource to return the same outcome in case rollback() is called again during recovery. Otherwise, the Resource immediately forgets all knowledge of the transaction.

Included in the Resource interface in CosTransactions.idl.

The following exceptions that may be raised when calling this method.

For more information, see the VisiBroker VisiTransact Guide.

Synchronization interface

The Synchronization interface defines methods that enable a transactional object to be notified before the start of the two and one-phase commit protocol, and after its completion, as described in the VisiBroker VisiTransact Guide.

In the CosTransactions module, the Synchronization interface provides two methods:

Here are two limitations you should be aware of:

• If the VisiTransact Transaction Service cannot contact your Synchronization object while trying to call before_completion(), then the transaction will be rolled back. If a Synchronization object is unavailable after completion, it will be ignored.
• When the VisiTransact Transaction Service instance recovers from a failure, it does not remember Synchronization objects, and will only replay completion and not Synchronization objects. If a failure occurs, the Synchronization object will not be notified of how the transaction was completed by the VisiTransact Transaction Service.

Note: In certain cases, after_completion() is called when before_completion() was not called. before_completion() is called only if a transaction is still continuing towards a commit at the outset of completion. after_completion() is always called (unless the VisiTransact Transaction Service crashes before the transaction completes).

Synchronization objects are not recoverable. If an instance of a VisiTransact Transaction Service fails, any transactions that are completed will not involve Synchronization objects.

Note: Although the signatures of these methods are fixed by the Synchronization interface, their implementations are user-defined. This enables an application to do custom processing at key points in a transaction--before and after transaction completion.

The following example shows the CosTransactions IDL for the Synchronization interface.

...

interface Synchronization : TransactionalObject

  {

    void before_completion();

    void after_completion(in Status status);

  };

...

Synchronization methods

after_completion()

void after_completion(in Status status);

This is a method that you write that performs customized processing after the completion of the transaction. It is essentially a callback.

Note: The after_completion() method is always invoked during normal processing.

As shown above, IDL for the Synchronization interface inherits from the TransactionalObject interface. As a programmer, you are responsible for writing the implementation of an after_completion() method that conforms to the IDL.

If after_completion() is to be called in processing a particular transaction, the following actions must be taken:

• A Synchronization object must be created--by the transaction originator or some other transaction participant.
• The Synchronization object must be registered--by getting the transaction's Coordinator, and calling the register_synchronization() method in Coordinator and Current. See "register_synchronization()" in "Coordinator interface." Registration must be done after the transaction is created and before the start of the two-phase commit.

Multiple Synchronization objects can be created and registered for a single transaction.

The VisiTransact Transaction Service calls this method after the two-phase commit protocol completes. As an example of its use, after_completion() can be used by a transactional object to discover the outcome of the transaction. This is particularly useful for transactional objects that are not also recoverable objects, and so are not automatically notified of the outcome.

You can call get_status() to see whether or not the transaction has been marked for rollback.

Notice that because Synchronization inherits from TransactionalObject, the transaction context will be available through the Current object.

Included in the Synchronization interface in CosTransactions.idl.

The following parameters are used by this method.

All exceptions will be ignored.

For more information see the VisiBroker VisiTransact Guide.

before_completion()

void before_completion();

This is a method that you write to perform customized processing at the onset of the completion of a transaction. It is called only if the transaction is still continuing towards successful completion. It is essentially a callback.

Note: The before_completion() method is invoked after the application invokes commit(), but before the VisiTransact Transaction Service begins transaction completion. The before_completion() method is not invoked for a rollback request.

As shown in the beginning of this section the IDL for the Synchronization interface inherits from the TransactionalObject interface. As a programmer, you are responsible for writing the implementation of a before_completion() method that conforms to the IDL.

If before_completion() is to be called when processing a particular transaction, the Synchronization object must be registered using the register_synchronization() method in the Coordinator interface. Register the Synchronization object from your transactional object or recoverable server. See "register_synchronization()" in "Coordinator interface". Registration must be done after the transaction is created and before the start of the two-phase commit.

Multiple Synchronization objects can be created and registered for a single transaction.

The VisiTransact Transaction Service calls this method after the transaction work has been done but before the two-phase commit protocol starts; that is, before prepare() is called on the participating Resource. VisiBroker VisiTransact calls before_completion() only if a transaction is still continuing towards a commit at the outset of completion. This means that Terminator->commit() was called and the transaction has not been marked for rollback. If Terminator->rollback() was called, or the first of several Synchronization objects marked the transaction for rollback, or the transaction was already marked for rollback, before_completion() calls will not be called again for this transaction.

Within this method, you can ensure the transaction will be rolled back by calling the rollback_only() method. You can also call get_status() to see whether or not the transaction has been marked for rollback. At the time the method is called, however, you cannot rely upon the status to indicate whether or not the transaction will actually be committed.

Notice that because the Synchronization interface inherits from TransactionalObject, the transaction context will be available through the Current object. This means that before_completion() can use all objects on the Current object, such as get_status() and get_control().

Included in the Synchronization interface in CosTransactions.idl.

All CORBA exceptions raised by your Synchronization objects will result in the transaction being rolled back.

For more information see the VisiBroker VisiTransact Guide.

VISTransactionService class

The VISTransactionService class is provided to help you link an instance of the VisiTransact Transaction Service with your application process.

Its methods, in the visits.h file, include:

• init()
• terminate()

VISTransactionService methods

init()

static void init(int &argc, char* const* argv);

This method initializes all the instances of the VisiTransact Transaction Service that are linked in your application process. It must be invoked to activate an instance of the VisiTransact Transaction Service that you have linked into your process by adding the ots_r library and the otsinit object file to the link line.

If you want to initialize the embedded instance of the VisiTransact Transaction Service, the init() method must be called. After ORB_init() has been invoked, all the recognized VisiTransact arguments will be stripped from the original parameter list so that they will not interfere with any other argument processing that your client program requires.

Caution: If the in-process VisiTransact Transaction Service instance has been de-activated using terminate(), vshutdown, or the Console, do not invoke init() again.

Included in the VISTransactionService interface in visits.h.

The following parameters are used by this method.

Note: The argc and argv parameters should be argc and argv from the main function.

For more information, see the VisiBroker VisiTransact Guide.

terminate()

static void terminate();

This method will cleanup all the instances of the VisiTransact Transaction Service that have been initialized by a call to init(). This method will not bring down your application process unless the command line option OTSexit_on_shutdown is set to 1.

If this option is either not set, or set to 0, it will deactivate the VisiTransact Transaction Service objects registered with the Smart Agent but will NOT bring down your application process.

Included in the VISTransactionService interface in visits.h.

For more information, see the VisiBroker VisiTransact Guide.

Commands and arguments

This section provides information about arguments for VisiTransact Transaction Manager commands and ORB_init().

Overview of VisiTransact commands

The commands in the next few sections relate to one another as described in the following table.

Overview of VisiTransact commands

vbconsolew

This command invokes the VisiBroker Console, and can be run on any node that has the executable for the Console installed. The Console does not have to be local to the VisiTransact Transaction Service instances that it administers. However, to administer these instances, they must be running when the Console is started.

Syntax

prompt>vbconsolew

Arguments

None.

ots

This command starts an instance of the VisiTransact Transaction Service.

Syntax

prompt>ots [-Dvbroker.ots.defaultTimeout=<seconds>] 

              [-Dvbroker.ots.defaultMaxTimeout=<seconds>] 

              [-Dvbroker.ots.name=<transaction_service_name>]

              [-Dvbroker.ots.logDir=<directory_name>]

              [-Dvbroker.ots.iorFile=<ior_file_name>]

Example

prompt>ots -Dvbroker.ots.defaultTimeout=60 -Dvbroker.ots.defaultMaxTimeout=120 -Dvbroker.ots.name=Sales

Arguments

The following arguments can be used with this command.