Programming Guide

The transaction manager accesses two layers of transaction models: the common model and a database-specific model. The common transaction model contains the functionality common to all of the database engines; the database-specific model contains processing necessary for a specific database engine.

The source code for the database-specific transaction models is provided in the distribution and can be modified to make global changes in transaction manager functionality. The common model should not be modified; however, the source code is available for reference.

• Common Transaction Model

• Database-Specific Transaction Models

For more information, refer to Application Development Guide—Chapter 35, "Generating Transaction Manager Events," for how the transaction manager uses the transaction model and to Chapter 32, "Writing Transaction Event Functions," for an explanation of the return codes.

Common Transaction Model

Table 9-1lists the events generated for each transaction manager command in the common model. The events are listed in the table in the order in which they are processed. Error and diagnostic events are indicated for the events which might generate them, although many of the error events shown are unlikely to be encountered. The error checking events are done after the events that give rise to them, and before any other event processing.

The transaction manager command documentation contains a description of the processing for each event; refer to Chapter 8, "Transaction Manager Commands."

Reading the Event Table

For compactness, whenever it is possible, the lower level events are shown on the same line as the higher level events that give rise to them. Thus, the entry for the FETCH command compresses the information about six events into the following two lines:

• The FETCH command generates only one request, TM_FETCH.

• TM_FETCH in its own right can cause a TM_TEST_ERROR event to be generated by the transaction manager (by returning TM_CHECK).

• The TM_TEST_ERROR event can cause a TM_NOTE_FAILURE event to generated by transaction manager (by returning TM_FAILURE).

• TM_FETCH also has a slice that it generates, TM_SEL_CHECK.

• TM_SEL_CHECK can cause a TM_TEST_ERROR event to be generated by the transaction manager (by returning TM_CHECK).

• The TM_TEST_ERROR event can cause a TM_NOTE_FAILURE event to be generated by transaction manager (by returning TM_FAILURE).

For a description of the error events, refer to "Error and Diagnostic Events."

Error and Diagnostic Events

The transaction error and diagnostic events are generated as a result of return values for other events. The most common error and diagnostic events are shown in the Error columns in Table 63. They are: TM_TEST_ERROR, TM_TEST_ONE_ROW and TM_NOTE_FAILURE.

The slice event TM_SEL_BUILD_PERFORM in all the CONTINUE commands has two events (E and F) in the first Error column, because TM_SEL_BUILD_PERFORM can return TM_CHECK, in addition to TM_FAILURE and TM_OK. In this table, the second F is associated with the E, not with the first F. It is the TM_TEST_ERROR event from TM_SEL_CHECK that can give rise to a further TM_NOTE_FAILURE event.

Database-Specific Transaction Models

Panther transaction models perform specialized processing for their respective databases. Table 9-2 lists the supported databases, the corresponding model name, and the type of non-trivial processing performed by each model.

INITIAL Mode Handling

For TM_SAVE_SET_MODE, the model sets TM_VALUE to TM_INITIAL_MODE. This means that when a COMMIT has been done in the course of a SAVE command, the model suggests that the mode be set to INITIAL. (Such a suggestion of a mode change can be ignored, particularly in a web application context.)

BEGIN Command Processing

For TM_SAVE_BEGIN, the transaction model does a BEGIN command.

Special Processing

The following models perform specialized processing:

• tminf1.c—INITIAL mode processing is done only if the special subroutine dm_inf_static_cursors so specifies.

• tmjdb1.c—If rows are inserted into the database during SAVE processing, a special check (optional) for duplication rows in that table after the insertion. (This entails cursor name generation and giving up the cursor used for this test, so there are several slices beyond those obviously needed for the test.)

• tmora1.c—For TM_SAVE_BEGIN, the model performs a DBMS SAVE command; in the event that a ROLLBACK is necessary, the DBMS ROLLBACK uses the same name. For Oracle Tuxedo applications, if in an XA context, XA processing is done rather than the corresponding DBMS operations for BEGIN, COMMIT and ROLLBACK; the timing of the XA operations can also be somewhat different from the timing of the DBMS operations.

• tmsyb1.c—There is specialized cursor management. This includes reusing cursors, rather than closing cursors that are given up. It also entails flushing cursors that are used for SELECT operations, and giving up select cursors before inserting, updating, or deleting tables on which they were used. commit and ROLLBACK are performed on the save cursor.