Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Programming a BEA Tuxedo Application Using COBOL

To end a global transaction, call TPCOMMIT(3cbl) to commit the current transaction, or TPABORT(3cbl) to abort the transaction and roll back all operations.

Note: If TPCALL, TPACALL, or TPCONNECT is called by a process that has explicitly set TPNOTRAN, the operations performed by the called service do not become part of the current transaction. In other words, when you call the TPABORT routine, the operations performed by these services are not rolled back.

The TPCOMMIT(3cbl) routine commits the current transaction. When TPCOMMIT returns successfully, all changes to resources as a result of the current transaction become permanent.

Use the following signature to call the TPCOMMIT routine.

*
  01 TPTRXDEF-REC.
     COPY TPTRXDEF.
*
  01 TPSTATUS-REC.
     COPY TPSTATUS.
*
   CALL "TPCOMMIT" USING TPTRXDEF-REC TPSTATUS-REC.

Refer to Starting the Transaction for a description of the TPTRXDEF-REC structure.

For TPCOMMIT to succeed, the following conditions must be true:

• The calling process must be the same one that initiated the transaction with a call to TPBEGIN.

• The calling process must have no transactional replies (calls made without the TPNOTRAN flag) outstanding.

• The transaction must not be in a rollback-only state and must not be timed out.

If the first condition is false, the call fails and TP-STATUS is set to TPEPROTO, indicating a protocol error. If the second or third condition is false, the call fails and TP-STATUS is set to TPEABORT, indicating that the transaction has been rolled back. If TPCOMMIT is called by the initiator with outstanding transaction replies, the transaction is aborted and those reply descriptors associated with the transaction become invalid. If a participant calls TPCOMMIT or TPABORT, the transaction is unaffected.

A transaction is placed in a rollback-only state if any service call returns TPFAIL or indicates a service error. If TPCOMMIT is called for a rollback-only transaction, the routine cancels the transaction, returns -1, and sets TP-STATUS to TPEABORT. The results are the same if TPCOMMIT is called for a transaction that has already timed out: TPCOMMIT returns -1 and sets TP-STATUS to TPEABORT. Refer to Managing Errors for more information on transaction errors.

When the TPCOMMIT routine is called, it initiates the two-phase commit protocol. This protocol, as the name suggests, consists of two steps:

1. Each participating resource manager indicates a readiness to commit.

2. The initiator of the transaction gives permission to commit to each participating resource manager.

The commit sequence begins when the transaction initiator calls the TPCOMMIT routine. The BEA Tuxedo TMS server process in the designated coordinator group contacts the TMS in each participant group that is to perform the first phase of the commit protocol. The TMS in each group then instructs the resource manager (RM) in that group to commit using the XA protocol that is defined for communications between the Transaction Managers and RMs. The RM writes, to stable storage, the states of the transaction before and after the commit sequence, and indicates success or failure to the TMS. The TMS then passes the response back to the coordinating TMS.

When the coordinating TMS has received a success indication from all groups, it logs a statement to the effect that a transaction is being committed and sends second-phase commit notifications to all participant groups. The RM in each group then finalizes the transaction updates.

If the coordinator TMS is notified of a first-phase commit failure from any group, or if it fails to receive a reply from any group, it sends a rollback notification to each RM and the RMs back out all transaction updates. TPCOMMIT then fails and sets TP-STATUS to TPEABORT.

When more than one group is involved in a transaction, you can specify which of two criteria must be met for TPCOMMIT to return successfully:

• When all participants have indicated a readiness to commit (that is, when all participants have reported that phase 1 of the two-phase commit has been logged as complete and the coordinating TMS has written its decision to commit to stable storage)

• When all participants have finished phase 2 of the two-phase commit

To specify one of these prerequisites, set the CMTRET parameter in the RESOURCES section of the configuration file to one of the following values:

• LOGGED - to require completion of phase 1

• COMPLETE - to require completion of phase 2

By default, CMTRET is set to COMPLETE.

In most cases, when all participants in a global transaction have logged successful completion of phase 1, they do not fail to complete phase 2. By setting CMTRET to LOGGED, you allow a slightly faster return of calls to TCOMMIT, but you run the slight risk that a participant may heuristically complete its part of the transaction in a way that is not consistent with the commit decision.

Whether it is prudent to accept the risk depends to a large extent on the nature of your application. If your application demands complete accuracy (for example, if you are running a financial application), you should probably wait until all participants fully complete the two-phase commit process before returning. If your application is more time-sensitive, you may prefer to have the application execute faster at the expense of accuracy.

Use the TPABORT(3cbl) routine to indicate an abnormal condition and explicitly abort a transaction. This function invalidates the call descriptors of any outstanding transactional replies. None of the changes produced by the transaction are applied to the resource. Use the following signature to call the TPABORT routine.

*
  01 TPTRXDEF-REC.
     COPY TPTRXDEF.
*
  01 TPSTATUS-REC.
     COPY TPSTATUS.
*
   CALL "TPABORT" USING TPTRXDEF-REC TPSTATUS-REC.

Refer to Starting the Transaction for a description of the TPTRXDEF-REC structure.

The following figure illustrates a conversational connection hierarchy that includes a global transaction.

The connection hierarchy is created through the following process:

1. A client (process A) initiates a connection in transaction mode by calling TPBEGIN and TPCONNECT.

2. The client calls subsidiary services, which are executed.

3. As each subordinate service completes, it sends a reply indicating success or failure (TPEV_SVCSUCC or TPEV_SVCFAIL, respectively) back up through the hierarchy to the process that initiated the transaction. In this example the process that initiated the transaction is the client (process A). When a subordinate service has completed sending replies (that is, when no more replies are outstanding), it must call TPRETURN.

4. The client (process A) determines whether all subordinate services have returned successfully.

   • If so, the client commits the changes made by those services, by calling TPCOMMIT, and completes the transaction.

   • If not, the client calls TPABORT, since it knows that TPCOMMIT could not be successful.

In the following sample code, a client makes a synchronous call to the fictitious REPORT service (line 24). Then the code checks for participant failures by testing for errors that can be returned on a communication call (lines 30-42).

01   . . .
02   CALL "TPINITIALIZE" USING TPINFDEF-REC
03   USR-DATA-REC
04   TPSTATUS-REC.
05   IF  NOT TPOK
06       error message,
07       EXIT PROGRAM .
08   MOVE 30 TO T-OUT.
09   CALL "TPBEGIN" USING TPTRXDEF-REC TPSTATUS-REC.
10   IF  NOT TPOK
11       error message,
12       PERFORM DO-TPTERM.
13  * Set up record
14   MOVE "REPORT=accrcv DBNAME=accounts" TP-RECORD.
15   MOVE 27 TO LEN.
16   MOVE "REPORTS" TO SERVICE-NAME.
17   MOVE "STRING" TO REC-TYPE.
18   SET TPBLOCK TO TRUE.
19   SET TPTRAN IN TPSVCDEF-REC TO TRUE.
20   SET TPNOTIME TO TRUE.
21   SET TPSIGRSTRT TO TRUE.
22 SET TPCHANGE TO TRUE.
23  *
24   CALL "TPCALL" USING TPSVCDEF-REC
25                 TPTYPE-REC
26                 TP-RECORD
27                 TPTYPE-REC
28                 TP-RECORD
29                 TPSTATUS-REC.
30   IF  TPOK
31        PERFORM DO-TPCOMMIT
32        PERFORM DO-TPTERM.
33  * Check return status
34    IF  TPESVCERR
35    DISPLAY "REPORT service's TPRETURN encountered problems"
36    ELSE IF  TPESVCFAIL
37    DISPLAY "REPORT service FAILED with return code=" APPL-RETURN-CODE
38    ELSE IF  TPEOTYPE
39    DISPLAY "REPORT service's reply is not of any known REC-TYPE"
40  *
41    PERFORM DO-TPABORT
42    PERFORM DO-TPTERM.
43  * Commit global transaction
44   DO-TPCOMMIT.
45    CALL "TPCOMMIT" USING TPTRXDEF-REC
46                    TPSTATUS-REC
47    IF  NOT TPOK
48        error message
49  * Abort the transaction
50   DO-TPABORT.
51    CALL "TPABORT" USING TPTRXDEF-REC
52                   TPSTATUS-REC
53    IF  NOT TPOK
54        error message
55  * Leave the application
56   DO-TPTERM.
57    CALL "TPTERM" USING TPSTATUS-REC.
58    IF  NOT TPOK
59        error message
60    EXIT PROGRAM.