Managing heuristic decisions

This chapter provides information about the heuristic decisions that you must manage for your transactional applications.

What is a heuristic decision?

A heuristic decision is a unilateral decision made by one or more transaction participants to commit or rollback updates without first obtaining the consensus outcome determined by the VisiTransact Transaction Service. Heuristic decisions are typically made in unusual circumstances, such as communication failures, that prevent normal processing. When a heuristic decision is made, there is a risk that the decision will differ from the consensus outcome, resulting in a loss of data integrity.

The types of heuristic outcome exceptions that can be returned are:

•	HeuristicRollback. The participant rolled back all relevant updates.

•	HeuristicCommit. The participant committed all relevant updates.

•	HeuristicMixed. The participant has committed some relevant updates, and rolled back others.

•	HeuristicHazard. The participant does not know the result of at least one relevant update.

For more information about heuristic decisions and exceptions, see “Transaction completion”.

What is the heuristic.log file?

VisiBroker VisiTransact produces one heuristic log per instance of the VisiTransact Transaction Service, located by default in <VBROKER_ADM>/its/transaction_service/<transaction_service_name>/heuristic.log. This log is saved in text format and can be viewed, but should not be edited. The heuristic log contains records for any heuristically-completed transaction associated with the VisiTransact Transaction Service instance.

A heuristic log record contains information which is global to the transaction:

•	Exception. The exception that was reported back to the transaction originator, if requested. This appears before the Transaction Info portion of the log record; for example: CosTransactions::HeuristicHazard Exception.

•	Transaction Name. The name of the transaction (either user-defined, or assigned by the VisiTransact Transaction Service). This appears in the name field of the Transaction Info portion of the log record; for example, Update_Inventory_Database.

•	Transaction Identifier. The ASCII version of the transaction identifier (otid). This appears in the id field of the Transaction Info portion of the log record.

•	Host of Transaction Originator. The IP address of the host machine where the transaction originator is located. This appears in the host field of the Originator Info portion of the log record.

The heuristic log also contains the following information for each Resource in the Participant Info sections of the log record:

•	Resource Name. The name of the Resource object registered with the VisiTransact Transaction Service instance that made the heuristic decision. This appears in the name field.

•	Resource Host. The IP address of the host on which the Resource is located. This appears in the host field.

•	Resource IOR. The interoperable object reference (IOR) of the Resource. This appears in the ior field.

•	Resource Vote. The vote sent by the Resource when asked to prepare to commit. This appears in the voteForPrepare field.

•	Resource Decision. The heuristic decision made by the Resource (for example, OutcomeHeuristicHazard or OutcomeHeuristicMixed). This appears in the outcome field.

You can archive the heuristic log file by moving it to a different location, if you have the appropriate file permissions. If you do this, the next time a heuristic occurs, the VisiTransact Transaction Service instance will recreate the heuristic log file. You can also make backup copies of the log by copying the log file to an alternate location. This is useful if you want to keep a daily backup of the heuristic log for your records.

Caution

Do not edit the heuristic.log file.

Interpreting the heuristic log

Assume that a transaction named Update_Inventory_Database has begun. Two Resources are registered with this transaction—inventory and customer. As part of the transaction completion, these Resources are asked to prepare to commit the transaction, and both Resources return a vote of VoteCommit. The VisiTransact Transaction Service then requests that the Resources commit the transaction. The customer Resource commits successfully and returns, but the inventory Resource makes a heuristic decision and returns with an exception of HeuristicHazard.

The following heuristic log shows what would appear in the heuristic log for this transaction. Notice that the exception returned to the transaction originator is CosTransactions::HeuristicHazard. The boldface type marks the location of the information described in “What is the heuristic.log file?”. Extra white space has been added to the example heuristic log entry for easier viewing.

06/02/98, 14:43:43.587, gemini, /net/gemini/vsi2/its/dev/jmitra/vbroker/adm/../bin/ots,
>None, 0, 0, Error, TransactionService, 4004,
at 0X000001, 0X04110FA4, 896823823, >587
CosTransactions::HeuristicHazard Exception:

Transaction Info:
name = Update_Inventory_Database
Id = _56495349_01000000_ce400ff2_0000cac1_67656d69_6e695f6f_74730000_00000000_000
00000_00000000_00000000_00000000_3574720f_0000e845_00000000_00000000

Originator Info:
host = 206.64.15.75

Participant Info:
name = inventory
host = 206.64.15.75
ior = IOR:002020200000002549444c3a73797374656d5f746573742f44756d6d7950617274696369
70656e743a312e3000202020000000010000000000000062000100000000000d3230362e3634
2e31352e373500000f730000004600504d43000000000000002549444c3a73797374656d5f74
6573742f44756d6d795061727469636970656e743a312e30000000000000000e746573745265
736f757263653100
voteForPrepare = VoteCommit
outcome = OutcomeHeuristicHazard

Participant Info:
name = customer
host = 206.64.15.75
ior = IOR:002020200000002549444c3a73797374656d5f746573742f44756d6d7950617274696369
70656e743a312e3000202020000000010000000000000062000100000000000d3230362e3634
2e31352e373500000f730000004600504d43000000000000002549444c3a73797374656d5f74
6573742f44756d6d795061727469636970656e743a312e30000000000000000e746573745265
736f757263653200
voteForPrepare = VoteCommit
outcome = OutcomeNone

What to do once the problem has been isolated

Once you have determined the nature of the problem by looking through the heuristic log, you can do several things to correct the problem.

The first thing to do is to match the transaction name and transaction identifier found in the heuristic log with the transaction identifier in the log on the Resource side (that is, the database log). Once you've located the problem, you can correct it manually on the Resource side. For example, as described in “Interpreting the heuristic log” you would locate Update_Inventory_Database in the Resource log, and take steps to manually commit the changes to the inventory Resource.