Providing support for transactions
Benefits of EAServer’s transaction support
EAServer components that you develop in PowerBuilder can participate
in EAServer transactions. An EAServer transaction is
a transaction whose boundaries and outcome are determined by EAServer.
You can mark components to indicate that they will provide transaction
support. When a component provides transaction support, EAServer
ensures that the component’s database operations execute
as part of a transaction.
Multiple EAServer components can participate in a single EAServer transaction;
EAServer ensures that database changes performed by the participating
components are all committed or rolled back. By defining components
to use EAServer transactions, you can ensure that all work performed
by components that participate in a transaction occurs as intended.
Indicating how the component will support transactions
Each EAServer component has a transaction attribute that indicates
how the component participates in EAServer transactions. When you
develop an EAServer component in PowerBuilder, you can specify the
transaction attribute in the wizards. Here are the options:
| Transaction type | Description |
|---|---|
| Not supported | The component never executes as part of a transaction. If the component is activated by another component that is executing within a transaction, the new instance’s work is performed outside the existing transaction |
| Supports Transaction | The component can execute in the context of an EAServer transaction, but a transaction is not required to execute the component’s methods. If the component is instantiated directly by a client, EAServer does not begin a transaction. If component A is instantiated by component B and component B is executing within a transaction, component A executes in the same transaction |
| Requires Transaction | The component always executes in a transaction. When the component is instantiated directly by a client, a new transaction begins. If component A is activated by component B and B is executing within a transaction, A executes within the same transaction; if B is not executing in a transaction, A executes in a new transaction |
| Requires New Transaction | Whenever the component is instantiated, a new transaction begins. If component A is activated by component B, and B is executing within a transaction, then A begins a new transaction that is unaffected by the outcome of B’s transaction; if B is not executing in a transaction, A executes in a new transaction |
| Mandatory | Methods can be invoked only by a client that has an outstanding transaction. Calling this component when there is no outstanding transaction generates a runtime error |
| OTS Style | The component can manage transactions. It can inherit a client’s transaction. If called without a transaction, the component can explicitly begin, commit, and roll back transactions using an instance of the CORBACurrent context service object |
| Never | Methods cannot be invoked when there is an outstanding transaction. Calling this component when there is an outstanding transaction generates a runtime error |
Using the transaction service context object
Component methods can call EAServer’s transaction
state primitives to influence whether EAServer commits or aborts
the current transaction. To give you access to EAServer’s
transaction state primitives, PowerBuilder provides a transaction
service context object called TransactionServer.
To use the TransactionServer
context object, set the UseContextObject DBParm
parameter to Yes. This tells PowerBuilder that you will be using
the methods of the TransactionServer object rather than COMMIT and ROLLBACK
to indicate whether the component has completed its work for the current
transaction.
Before you can use the transaction context service, declare
a variable of type TransactionServer and call the GetContextService
function to create an instance of the service.
Example In the Activate (or Constructor) event for a component, you
can call GetContextService to instantiate the TransactionServer
service:
|
1 |
// Instance variable:<br /> // TransactionServer ts<br /> <br /> Integer li_rc<br /> li_rc = this.GetContextService("TransactionServer", &<br /> ts)<br /> IF li_rc <> 1 THEN<br /> // handle the error<br /> END IF |
In one of the component methods, you can then update the database
and call SetComplete if the update succeeds or SetAbort if it fails:
|
1 |
//Instance variable:<br /> //DataStore ids_datastore<br /> long ll_rv<br /> ...<br /> ...<br /> ll_rv = ids_datastore.Update()<br /> IF ll_rv = 1 THEN<br /> ts.SetComplete()<br /> ELSE<br /> ts.SetAbort()<br /> END IF |
The TransactionServer interface provides these methods to
allow you to access EAServer’s transaction primitives:
| Method | Description |
|---|---|
| DisableCommit | Indicates that the current transaction cannot be committed because the component’s work has not been completed; the instance remains active after the current method returns |
| EnableCommit | Indicates that the component should not be deactivated after the current method invocation; allows the current transaction to be committed if the component instance is deactivated |
| IsInTransaction | Determines whether the current method is executing in a transaction |
| IsTransactionAborted | Determines whether the current transaction has been aborted |
| SetAbort | Indicates that the component cannot complete its work for the current transaction and that the transaction should be rolled back. The component instance will be deactivated when the method returns |
| SetComplete | Indicates that the component has completed its work in the current transaction and that, as far it is concerned, the transaction can be committed and the component instance can be deactivated |
Automatic Demarcation/ Deactivation
If you want a component to be automatically deactivated after
each method invocation, you can enable Automatic Demarcation/Deactivation
for the component. This sets the component’s tx_vote
property to FALSE. When Automatic Demarcation/Deactivation
is enabled, you do not need to make explicit calls to SetComplete
to cause deactivation because SetComplete is assumed by default.
To roll back the transaction, you can call SetAbort.
If you do not want the component to be automatically deactivated
after each method invocation, disable the Automatic Demarcation/Deactivation
setting for the component. This sets the component’s tx_vote
property to TRUE. When you disable Automatic Demarcation/Deactivation,
EAServer waits for notification before completing transactions;
therefore, be sure to deactivate programmatically by making an explicit
call to SetComplete (or SetAbort).
COMMIT and ROLLBACK
You have the option to disable the TransactionServer context
object and use the COMMIT and ROLLBACK statements instead to specify
the EAServer transaction state for a component. This capability
is provided to allow you to migrate PowerBuilder 6 objects to EAServer
without modifying the code. To disable the TransactionServer context
object, set the UseContextObject DBParm parameter
to No. When you do this, COMMIT is equivalent to SetComplete and
ROLLBACK is equivalent to SetAbort.
COMMIT and ROLLBACK in nontransactional components In nontransactional components that disable the TransactionServer
context object, COMMIT does not invoke SetComplete and ROLLBACK
does not invoke SetAbort. For example, if you specify Not Supported
as the transaction type, disable Automatic Demarcation/Deactivation
(set tx_vote to TRUE), and set the UseContextObject parameter
to No, the PowerBuilder virtual machine does not
issue
a SetComplete when you execute a COMMIT (or a SetAbort when you
execute a ROLLBACK). In this case, EAServer never releases the component
because it is waiting for a call to SetComplete or SetAbort.
If you disable Automatic Demarcation/Deactivation
for a component that performs no database access whatsoever, then
you must use the TransactionServer object to call SetComplete (or
SetAbort) to deactivate the component. Otherwise, the component
will never be deactivated.
Transactions and the component lifecycle
EAServer’s transaction model and the component lifecycle
are tightly integrated. Component instances that participate in
a transaction are never deactivated until the transaction ends or
until the component indicates that its contribution to the transaction
is over (its work is done and ready for commit or its work must
be rolled back). An instance’s time in the active state corresponds
exactly to the beginning and end of its participation in a transaction.
For more information, see the EAServer documentation
.