Using Transactions in Your Client Application

Using Transactions

Transactions enable an application to perform operations on multiple objects as if they were run simultaneously. This guarantees the integrity of the data when related changes need to be made to a set of objects.

In your application, you can call PCM_OP_TRANS_OPEN before calling an opcode and PCM_OP_TRANS_ABORT or PCM_OP_TRANS_COMMIT after the opcode calls.

Only one transaction at a time can be opened on a PCM context. A transaction is opened on a specific database schema specified by the POID database number in the input flist. All operations performed in an open transaction must manipulate data within the same database.

Any changes made within an open transaction can be cancelled at any time and all changes are completely erased. These actions cancel an open transaction:

You use the PCM_OP_TRANS_ABORT opcode.
The application exits or closes the PCM context.
A system error occurs and connectivity is lost between the application and the database.

The system tracks the transaction along with the context argument used by most of the PCM Library macros. If the context pointer passed has an outstanding transaction, it is used automatically.

Keeping a transaction open for a long time can affect performance because the system maintains a frozen view of the data while changes are made by other applications. It is not recommended that you leave transactions open while long-latency tasks, such as prompting a user for input, are performed.

In general, any PCM opcode can be run within an open transaction, and its effect follows the transactional rules. However, some Facilities Module opcodes that interface to legacy systems or external systems do not follow the transactional rules (that is, they can't be undone). Opcodes with this limitation must check for an open transaction and return an error if an application attempts to run the opcode within the open transaction.

Types of Transactions

When you use the PCM_OP_TRANS_OPEN opcode to open a transaction, you can use the following flags to open different types of transactions:

PCM_TRANS_OPEN_READONLY. See "Read-Only Transactions".
PCM_TRANS_OPEN_READWRITE. See "Read-Write Transactions".
PCM_TRANS_OPEN_LOCK_OBJ. See "Transaction with a Locked Objects".
PCM_TRANS_OPEN_LOCK_DEFAULT. See "Transaction with a Locked Default Balance Group".

Note:

For J2EE-compliant applications, use JCA Resource Adapter to open extended architecture (XA) transactions through the XAResource interface. For more information, see "About BRM JCA Resource Adapter Transaction Management" see in BRM JCA Resource Adapter.

Read-Only Transactions

Use the PCM_TRANS_OPEN_READONLY flag to open a read-only transaction.

Use this type if operations will not change any data in the transaction.

From the application's point of view, a read-only transaction freezes the data in the database. The application does not see any changes to data made by other applications while the transaction is open. This allows data to be examined in a series of operations without being changed in mid-process.

Read-only transactions are more efficient and should be used when possible. Any number of read-only transactions can be open against a database at once.

Read-Write Transactions

Use the PCM_TRANS_OPEN_READWRITE flag to open a read-write transaction.

A read-write transaction freezes the data in the database from the application's point of view, and allows changes to be made to the data set. These changes are not seen by any other application until the transaction is committed. This allows the effects of a series of operations performed on objects to occur simultaneously when the transaction is committed.

Any number of read-write transactions can be open against a database at once.

Transaction with a Locked Objects

Use the PCM_TRANS_OPEN_LOCK_OBJ flag to open a transaction and lock an object as part of the transaction.

A lock-object transaction is useful when two applications must synchronize the operations they perform on the same object. Lock-object transactions are the same as read-write transactions, with the addition of the object lock. If you use a lock-object transaction, you must specify the PCM_TRANS_OPEN_READWRITE flag.

If an application tries to open a lock-object transaction on an object that is already locked by another application, it will be held off until the application that currently holds the object finishes its transaction and unlocks the object.

Transaction with a Locked Default Balance Group

Use the PCM_TRANS_OPEN_LOCK_DEFAULT flag to open a transaction and lock the default balance group object only as part of the transaction.

Most opcode transactions lock the account object, if used, at the beginning of a transaction. This provides reliable data consistency but in systems that use account hierarchies, it can also cause a lot of serialization which decreases the throughput of the system. You can use the PCM_TRANS_OPEN_LOCK_DEFAULT flag to open a transaction that locks only the default balance group for the account instead of the sum of all the account objects in the hierarchy. See "Locking Specific Objects".

If you use a lock default balance group transaction, you must specify the PCM_TRANS_OPEN_READWRITE flag and not specify the PCM_TRANS_OPEN_LOCK_OBJ flag.

If an application tries to open a transaction on a balance group that is already locked by another application, it will be held off until the application that currently holds the object finishes its transaction and unlocks the object.

About Committing Transactions

Changes made within an open transaction are not permanent or visible to other applications until the transaction has been successfully committed.

Committing a transaction has these effects:

The transaction is closed and all data changes made within the open transaction take effect in the data set. The changes become visible to all other applications (subject to their open transactions).
The application's view of the data set is no longer frozen in time, so changes made by other applications are now visible to the application.
If an object was locked, it is unlocked.
The application is free to open another transaction. Subsequent operations on the PCM context are unrelated to the closed transaction.

Note:

For J2EE-compliant applications, use JCA Resource Adapter to commit XA transactions through the XAResource interface. The adapter supports both single-phase and two-phase commits. For more information, see "About BRM JCA Resource Adapter Transaction Management" in BRM JCA Resource Adapter.

About Cancelling Transactions

Cancelling a transaction has the following effects:

All data changes made within the open transaction are discarded, so no data is changed by operations related to the transaction.
If an object was locked, it is unlocked.
The transaction is closed, and subsequent operations on the PCM context are unrelated to the closed transaction. The application is free to open another transaction.
The application's view of the data set is no longer frozen in time, so changes made by other applications are visible to the application.

Note:

For J2EE-compliant applications, use JCA Resource Adapter to roll back XA transactions through the XAResource interface. For more information, see "About BRM JCA Resource Adapter Transaction Management" in BRM JCA Resource Adapter.

About the Transaction Base Opcodes

Use the following opcodes to manage transactions:

To open transactions, use PCM_OP_TRANS_OPEN.
To commit transaction, use PCM_OP_TRANS_COMMIT.
To cancel transactions, use PCM_OP_TRANS_ABORT.

Customizing How to Open Transactions

To customize how to open transactions, use PCM_OP_TRANS_POL_OPEN.

This opcode gets the same flist that PCM_OP_TRANS_OPEN does. The return flist then becomes the transaction ID flist; it can contain whatever you want to put in it. That flist then becomes the input to PCM_OP_TRANS_POL_COMMIT and PCM_OP_TRANS_POL_ABORT. The return flists from those opcodes are ignored.

Customizing the Verification Process for Committing a Transaction Opcode

To customize how to verify the readiness of an external system to commit a transaction opcode, use PCM_OP_TRANS_POL_PREP_COMMIT.

This opcode provides BRM with preparatory notice of a pending commit process for transaction policies working with an external system. This is its overall process:

Open a transaction in each system.
Do the work authorized by the transaction.
Verify that the external system will be able to commit the transaction.
Commit the transaction in BRM.
Commit the transaction in the external system.

PCM_OP_TRANS_POL_PREP_COMMIT verifies that the external system will be able to commit the transaction. If the transaction is successfully committed, the CM calls PCM_OP_TRANS_COMMIT, and upon a successful commit transaction of that opcode it calls PCM_OP_TRANS_POL_COMMIT.

If PCM_OP_TRANS_POL_PREP_COMMIT fails, the CM automatically cancels the transaction using PCM_OP_TRANS_ABORT and PCM_OP_TRANS_POL_ABORT.

Customizing How to Commit a Transaction

To customize how to commit a transaction, use PCM_OP_TRANS_POL_COMMIT.

The return flist from PCM_OP_TRANS_POL_OPEN becomes the transaction ID flist; it can contain whatever you want to put in it. That flist then becomes the input to PCM_OP_TRANS_POL_COMMIT. The return flist from this opcode is ignored.

Customizing How to Cancel Transactions

To customize how to cancel transactions, use PCM_OP_TRANS_POL_ABORT.

The return flist from PCM_OP_TRANS_POL_OPEN becomes the transaction ID flist; it can contain whatever you want to put in it. That flist then becomes the input to PCM_OP_TRANS_POL_ABORT. The return flist from this opcode is ignored.