bdfp1m0h | Programming Concepts and Reference |
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 |
The ALCS environment does not support the TM.
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.
The first commit scope that is created by the application is a root commit scope.
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.
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:
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:
Attention: A rollback has no effect on any updates (nonfile updates) issued outside of the TPFDF macros; for example, application use of the data levels, registers, and local variables.
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
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).
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.
Using commit scopes with TPFDF macros provides the following benefits:
Using commit scopes ensures either all or none of the files updated in a database are written to DASD. There is no such thing as a partially updated database when updates are all made in commit scopes.
Commit scopes support both TPFDF and traditional files, including critical and internal files; that is, a commit scope can contain updates to both TPFDF and traditional files.
Using commit scopes simplifies your application program designs with a reduced need for error recovery routines, and shortens your coding and testing phases. The reliability of your application program is increased because the order of updates is no longer of paramount importance. At any time, the application program could stop processing and request that the TPF system ignore all of its previous updates. Additionally, knowing that you always have a consistent view of the database affects your application development cycle time. Either all of your file changes have been completed or none of them have; it is that simple.
The order of updates is no longer of paramount importance. At any time, the application program could stop processing and request that the TPF system ignore all of its previous updates.