bdfp1m0hProgramming Concepts and Reference


Transaction Manager

TPFDF product support of the TPF transaction manager (TM) ensures a consistent view of a database in an application program. This consistent view of the database ensures that either all or none of the file changes have been completed; there is no such thing as a partially updated database.

The TM verifies a consistent database view by using a set of application programming interfaces (APIs) for the application program to define both the scope of a file transaction as well as actions to be taken for the file transaction.

The TM provides a subset of the TX functions (defined by the X/Open TX interface) to the application to begin and end (that is, commit or roll back) a transaction:

Table 1. Begin and End Transactions

C Function Assembler Macro
tx_begin TXBGC
tx_commit TXCMC
tx_rollback TXRBC

Additionally, the TM provides the following extension (to X/Open) functions to the application to suspend or resume a transaction:

Table 2. Suspend and Resume Transactions

C Function Assembler Macro
tx_suspend_tpf TXSPC
tx_resume_tpf TXRSC

ALCS Support

The ALCS environment does not support the TM.

Commit Scopes

The TM groups all database updates into a unit of work called a commit scope. A current commit scope is defined by a file transaction.

A file transaction refers to all macros, instructions, and functions that are issued on a file. When a file transaction is completed, you can save (commit) or discard (roll back) the file updates.

Root Commit Scopes

The first commit scope that is created by the application is a root commit scope.

Nested Commit Scopes

A commit scope that is created after the root scope has been activated is a nested commit scope. A root commit scope can have many nested commit scopes.

In a commit scope, all database requests are satisfied back through the chain of nested scopes to the root commit scope. Therefore, none of the nested commit scopes are satisfied until the root commit scope is satisfied.

Suspended Commit Scopes

You can temporarily suspend a commit scope to make database updates outside the current commit scope. However, when a commit scope is suspended, you cannot reference a file that is already referenced in the current commit scope.

See the following for more information about the transaction manager or commit scopes:

Programming Conventions

The TM APIs can be used with TPFDF macros in an application program to ensure that all file updates are complete before being committed (saved) to the database. All updates are filed to DASD as one update; that is, all or none of the updates take effect. TPFDF macros that update the database do not take effect on DASD until a commit is issued for the root commit scope. If a rollback is issued for the root commit scope, all updates made by TPFDF macro calls in the commit scope are discarded.

The following programming conventions provide you with safe and simple use of commits scopes with TPFDF macros:

The following shows an example of a basic TPFDF transaction that is contained in a commit scope. The TXBGC macro begins the commit scope that contains the DBOPN, DBADD, and DBCLS macros issued on FILE1. The TXCMC macro ends the commit scope and commits FILE1 to the database.

TXBGC
 
DBOPN REF=FILE1
 
DBADD REF=FILE1
 
DBCLS REF=FILE1
 
TXCMC

The following shows an example of TPFDF transactions contained in a root commit scope and a nested commit scope. The first TXBGC macro begins the root commit scope that contains the DBOPN and DBRED macros issued on FILE1. The second TXBGC macro begins the nested commit scope that contains the DBOPN, DBADD, and DBCLS macros issued on FILE2 and FILE3. Although the nested commit scope ends with the subsequent TXCMC macro, it is not until the root commit scope is ended with the TXCMC macro that FILE1, FILE2, and FILE3 are committed to the database because nested commit scopes are not satisfied until the root commit scope is satisfied. Additionally, a file that is outside a nested commit scope cannot be referenced from within a nested commit scope. If FILE1 is accessed within the nested commit scope, an error would occur.

TXBGC
 
DBOPN REF=FILE1
 
DBRED REF=FILE1
 
TXBGC
 
DBOPN REF=FILE2
 
DBOPN REF=FILE3
 
DBADD REF=FILE2
 
DBADD REF=FILE3
 
DBCLS REF=FILE2
 
DBCLS REF=FILE3
 
TXCMC
 
DBCLS REF=FILE1
 
TXCMC

Internal Use of Commit Scopes

To provide added security against database corruption that results from unplanned system outages, the TM support of TPFDF transactions includes an option to use commit scopes internally. This option is valuable when many files are to be filed out during checkpoint and close processing (for example, detac mode, extensive B+Tree indexing updates, and requests to pack indexes).

Checkpoint and Close Processing

You can control the use of commit scopes internally by specifying the optional parameters for the TPFDF macros that use checkpoint and close processing. These optional parameters can override the database definition (DBDEF) default setting to enable or disable the internal use of commit scopes. Using commit scopes provides protection against database corruption, such as when system outages occur during the large filing of updates.

See the following for additional information about the option to manage TPFDF macros with commit scopes:

See TPFDF Database Administration for additional information about the DBDEF option to manage TPFDF macros with commit scopes.

Benefits of Using Commit Scopes

Using commit scopes with TPFDF macros provides the following benefits: