A set of APIs is provided for tool writers to perform heuristic functions on indoubt transactions when the resource owner (such as the database administrator) cannot wait for the Transaction Manager (TM) to perform the re-sync action. This condition may occur if, for example, the communication line is broken, and an indoubt transaction is tying up needed resources. For the database manager, these resources include locks on tables and indexes, log space, and storage used by the transaction. Each indoubt transaction also decreases, by one, the maximum number of concurrent transactions that could be processed by the database manager.
The heuristic APIs have the capability to query, commit, and roll back indoubt transactions, and to cancel transactions that have been heuristically committed or rolled back, by removing the log records and releasing log pages.
Attention: The heuristic APIs should be used with caution and only as a last resort. The TM should drive the re-sync events. If the TM has an operator command to start the re-sync action, it should be used. If the user cannot wait for a TM-initiated re-sync, heuristic actions are necessary.
Although there is no set way to perform these actions, the following guidelines may be helpful:
If the transaction manager is available, and the indoubt transaction is due to the RM not being available in the second phase, or in an earlier re-sync, the DBA should determine from the TM's log what action has been taken against the other RMs, and then do the same. The gtrid is the matching key between the TM and the RMs.
Do not execute sqlxhfrg - Forget Transaction Status unless a heuristically committed or rolled back transaction happens to cause a log full condition. The forget function releases the log space occupied by this indoubt transaction. If a transaction manager eventually performs a re-sync action for this indoubt transaction, the TM could make the wrong decision to commit or to roll back other RMs, because no record was found in this RM. In general, a missing record implies that the RM has rolled back.
Permits the RM to erase knowledge of a heuristically completed transaction (that is, one that has been committed or rolled back heuristically).
Authorization
One of the following:
Required Connection
Database
API Include File
sqlxa.h
C API Syntax
/* File: sqlxa.h */ /* API: Forget Transaction Status */ /* ... */ extern int SQL_API_FN sqlxhfrg( SQLXA_XID *pTransId, struct sqlca *pSqlca ); /* ... */ |
API Parameters
Usage Notes
Only transactions with a status of heuristically committed or rolled back can have the FORGET operation applied to them.
For information about the SQLXA_XID structure, see SQLXA-XID.
Commits an indoubt transaction (that is, a transaction that is prepared to be committed). If the operation succeeds, the transaction's state becomes heuristically committed.
Scope
This API only affects the node on which it is issued.
Authorization
One of the following:
Required Connection
Database
API Include File
sqlxa.h
C API Syntax
/* File: sqlxa.h */ /* API: Commit an Indoubt Transaction */ /* ... */ extern int SQL_API_FN sqlxphcm( int exe_type, SQLXA_XID *pTransId, struct sqlca *pSqlca ); /* ... */ |
API Parameters
Usage Notes
Only transactions with a status of prepared can be committed. Once heuristically committed, the database manager remembers the state of the transaction until sqlxhfrg - Forget Transaction Status is issued.
For information about the SQLXA_XID structure, see SQLXA-XID.
Gets a list of all indoubt transactions for the currently connected database.
Scope
This API only affects the node on which it is issued.
Authorization
One of the following:
Required Connection
Database
API Include File
sqlxa.h
C API Syntax
/* File: sqlxa.h */ /* API: List Indoubt Transactions */ /* ... */ extern int SQL_API_FN sqlxphqr( int exe_type, SQLXA_RECOVER **ppIndoubtData, long *pNumIndoubts, struct sqlca *pSqlca ); /* ... */ |
API Parameters
Rolls back an indoubt transaction (that is, a transaction that has been prepared). If the operation succeeds, the transaction's state becomes heuristically rolled back.
Scope
This API only affects the node on which it is issued.
Authorization
One of the following:
Required Connection
Database
API Include File
sqlxa.h
C API Syntax
/* File: sqlxa.h */ /* API: Roll Back an Indoubt Transaction */ /* ... */ extern int SQL_API_FN sqlxphrl( int exe_type, SQLXA_XID *pTransId, struct sqlca *pSqlca ); /* ... */ |
API Parameters
Usage Notes
Only transactions with a status of prepared or idle can be rolled back. Once heuristically rolled back, the database manager remembers the state of the transaction until sqlxhfrg - Forget Transaction Status is issued.
For information about the SQLXA_XID structure, see SQLXA-XID.