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 C

To end a global transaction, call tpcommit(3c) to commit the current transaction, or tpabort(3c) to abort the transaction and roll back all operations.

Note: If tpcall(), tpacall(), or tpconnect() is called by a process that has explicitly set the flags argument to TPNOTRAN, the operations performed by the called service do not become part of the current transaction. In other words, when you call the tpabort() function, the operations performed by these services are not rolled back.

The tpcommit(3c) function 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() function.

int
tpcommit(long flags)

Although the flags argument is not used currently, you must set it to zero to ensure compatibility with future releases.

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 tperrno(5) is set to TPEPROTO, indicating a protocol error. If the second or third condition is false, the call fails and tperrno() 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 function cancels the transaction, returns -1, and sets tperrno(5) to TPEABORT. The results are the same if tpcommit() is called for a transaction that has already timed out: tpcommit() returns -1 and sets tperrno() to TPEABORT. Refer to Managing Errors for more information on transaction errors.

When the tpcommit() function 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() function. 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 tperrno(5) 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 tpcommit(), 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(3c) function 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() function.

int
tpabort(long flags)

Although the flags argument is not used currently, you must set it to zero to ensure compatibility with future releases.

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 18). Then the code checks for participant failures by testing for errors that can be returned on a communication call (lines 19-34).

001    #include <stdio.h>
002    #include "atmi.h"
003
004    main()
005    {
006    char *sbuf, *rbuf;
007    long slen, rlen;
008    if (tpinit((TPINIT *) NULL) == -1)
009        error message, exit program;
010    if (tpbegin(30, 0) == -1)
011        error message, tpterm, exit program;
012    if ((sbuf=tpalloc("STRING", NULL, 100)) == NULL)
013        error message, tpabort, tpterm, exit program;
014    if ((rbuf=tpalloc("STRING", NULL, 2000)) == NULL)
015        error message, tpfree sbuf, tpabort, tpterm, exit program;
016    (void)strcpy(sbuf, "REPORT=accrcv DBNAME=accounts");
017    slen=strlen(sbuf);
018    if (tpcall("REPORT", sbuf, slen, &rbuf, &rlen, 0) == -1) {
019        switch(tperrno) {
020        case TPESVCERR:
021            fprintf(stderr,
022                "REPORT service's tpreturn encountered problems\n");
023            break;
024        case TPESVCFAIL:
025            fprintf(stderr,
026                "REPORT service TPFAILED with return code of %d\n", tpurcode);
027            break;
028        case TPEOTYPE:
029            fprintf(stderr,
030                "REPORT service's reply is not of any known data type\n");
031            break;
032        default:
033            fprintf(stderr,
034                "REPORT service failed with error %d\n", tperrno);
035            break;
036        }
037        if (tpabort(0) == -1){
038            check for errors;
039        }
040    }
041    else
042        if (tpcommit(0) == -1)
043            fprintf(stderr, "Transaction failed at commit time\n");
044    tpfree(rbuf);
045    tpfree(sbuf);
046    tpterm();
047    exit(0);
048    }