bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

WebLogic Tuxedo Connector Programmer's Guide

Application Error Management

The following sections provide mechanisms to manage and interpret error conditions in your applications:

- Testing for Application Errors

- WebLogic Tuxedo Connector Time-Out Conditions

- Guidelines for Tracking Application Events

Testing for Application Errors

Note: To view an example that demonstrates how to test for error conditions, see Example Transaction Code.

Your application logic should test for error conditions after the calls that have return values and take suitable steps based on those conditions. In the event that a function returned a value, you may invoke a functions that tests for specific values and performs the appropriate application logic for each condition.

Exception Classes

The WebLogic Tuxedo Connector throws the following exception classes:

- Ferror: Exception thrown for errors occurring while manipulating FML.

- TPException: Exception thrown that represents a TPException failure.

- TPReplyException: Exception thrown that represents a TPException failure when user data is associated with the exception thrown.

Fatal Transaction Errors

In managing transactions, it is important to understand which errors prove fatal to transactions. When these errors are encountered, transactions should be explicitly aborted on the application level by having the initiator of the transaction call commit(). Transactions fail for the following reasons:

- The initiator or participant of the transaction caused it to be marked for rollback.

- The transaction timed out.

- A commit() was called by a participant rather than by the originator of a transaction.

WebLogic Tuxedo Connector Time-Out Conditions

There are two types of time-out which can occur when using the WebLogic Tuxedo Connector:

- Blocking time-out.

- Transaction time-out.

Blocking vs. Transaction Time-out

Blocking time-out is exceeding the amount of time a call can wait for a blocking condition to clear up. Transaction time-out occurs when a transaction takes longer than the amount of timed defined for it in setTransactionTimeout(). By default, if a process is not in transaction mode, blocking time-outs are performed. When the flags parameter of a a communication call is set to TPNOTIME, it applies to blocking time-outs only. If a process is in transaction mode, blocking time-out and the TPNOTIME flag are not relevant. The process is sensitive to transaction time-out only as it has been defined for it when the transaction was started. The implications of the two different types of time-out follow:

- If a process is not in transaction mode and a blocking time-out occurs on an asynchronous call, the communication call that blocked will fail, but the call descriptor is still valid and may be used on a re-issue call. Further communication in general is unaffected.

- In the case of transaction time-out, the call descriptor to an asynchronous transaction reply (done without the TPNOTRAN flag) becomes stale and may no longer be referenced. The only further communication allowed is the one case described earlier of no reply, no blocking, and no transaction.

Effect on commit()

The state of a transaction if time-out occurs after the call to commit() is undetermined. If the transaction timed out and the system knows that it was aborted, setRollbackOnly() returns with an error.

If the state of the transaction is in doubt, you must query the resource to determine if any of the changes that were part of that transaction have been applied to it in order to discover whether the transaction committed or aborted.

Effect of TPNOTRAN

Note: A transaction can time-out while waiting for a reply that is due from a service that is not part of that transaction.

When a process is in transaction and makes a communications call with flags set to TPNOTRAN, it prohibits the called service from becoming a participant of that transaction. The success or failure of the service does not influence the outcome of that transaction.

Guidelines for Tracking Application Events

You can track the execution of your applications by using System.out.println() to write messages to the WebLogic Server trace log. Create a log() method that takes a variable of type String and use the variable name as the argument to the call, or include the message as a literal within quotation marks as the argument to the call. In the following example, a series of messages are used to track the progress of a tpcall().

Listing 8-1 Example Event Logging

>     .

>     .

>     .

>     log("About to call tpcall");
>     	try {
>     		myRtn = myTux.tpcall("TOUPPER", myData, 0);
>     	}
>     	catch (TPReplyException tre) {
>     		log("tpcall threw TPReplyExcption " + tre);
>     		throw tre;
>     	}
>     	catch (TPException te) {
>     		log("tpcall threw TPException " + te);
>     		throw te;
>     	}
>     	catch (Exception ee) {
>     		log("tpcall threw exception: " + ee);
>     		throw new TPException(TPException.TPESYSTEM, "Exception: " + ee);
>     	}
>     	log("tpcall successfull!");
>     .

>     .

>     .

>     private static void

>     log(String s)

>     {	System.out.println(s);}

>     .

>     .

>     .