Using XMLink

Appendix A. Troubleshooting

Configuration Issues

Older Versions of JAR Files

If you are upgrading from an older version of WebSphere, check that the older versions of connector.jar, jca.jar, or connector-1_0-pfd2-classes.jar are not in the CLASSPATH.

Tuxedo 7.1 for Windows

For Tuxedo 7.1 for Windows, XMLink needs the Tuxedo 7.1 Rolling Patch from Oracle to work within WebSphere. The Rolling Patch must include the fix for "CR034485 stack overflow when loading a DLL on NT (S-05377)."

Specifying the Native Path and Archive Path

When configuring an XMLink resource adapter in WebSphere 6, make sure that the native path is set to the same location as the archive path. The Class Path should contain the path to tconn.jar. For TConn.rar, this would typically be ${CONNECTOR_INSTALL_ROOT}/TConn.rar/tconn.jar.

Starting WebSphere as a Windows Service

Windows users who install WebSphere so that it is started as a Windows service (the default for WAS 6) should be aware this affects the use of operating system environment variables that can be used with the Oracle Tuxedo client within the WebSphere Application Server. If the operating system environment is changed in the control panel application, it does not effect the environment used by the process that starts Windows services. That process continues to pass the old environment to services it starts, until Windows is rebooted.

Determining Your XMLink Resource Adapter Version

As before, XMLink 3.0 provides two resource adapters TConn.rar and TConn6.rar. It is intended that TConn.rar should support all version of Oracle Tuxedo later than 6. However, on some platforms a version incompatibility may exist. In such cases additional resource adapter archives may be provided with XMLink for specific versions of Oracle Tuxedo. In those cases, it may be necessary to use the System property XMLink.tconn, rather than the new ConnectionType connection factory property setting.

XMLink Resource Adapter Files in a Managed Environment

As of WebSphere 4.0, using a resource adapter in a managed environment installs its files in a central location. For XMLink, this is:

$WAS_HOME\InstalledConnectors\TConn.rar\...

System settings for CLASSPATH, PATH or LD_LIBRARY_PATH (LIBPATH) should not reference alternate versions of these files.

A problem can occur if you previously ran XMLink in a non-managed environment which would specify these variables.

For more information on managed environments, refer to "Managed and Non-Managed Environments."

Tuxedo Error Messages

Note: XMLink throws a Tuxedo exception and sets the Tuxedo error code to TPEBLOCK when a transaction is attempted with Tuxedo 6 versions. Transaction support is only available on Tuxedo 6.x when a Tuxedo 7.1 workstation client is used in conjunction with a Tuxedo 6.4+ server. In this case, the patch for the Tuxedo 7.1 client is required.

Using the TuxedoException Class

CCI interface methods are often declared to throw a ResourceException. The Connector Architecture specification defines several extensions of ResourceException, which XMLink may use where appropriate. XMLink also defines the TuxedoException class, which extends ResourceException, for use mainly with Tuxedo generated errors.

The TuxedoException class defines five public methods that can be used to access information about the error. They are:

public int getError()
public int getErrorDetail()
public String getStrError()
public String getStrErrorDetail()
public String toString()

getError() returns the Tuxedo error code associated with tperrno.
getErrorDetail() returns the code returned by tperrordetail().
getStrError() returns the string returned by tpstrerror().
getStrErrorDetail() returns the string returned by tpstrerrordetail().
toString() returns a String containing an XMLink generated error message, plus all of the information provided by the other methods. Its format is:
```
message: tpstrerror (tpstrerrordetail) : tperrno (tperrordetail)
```

The TuxedoException class defines several public static final variables whose names correspond to the names of Tuxedo error codes associated with tperrno and tperrordetail(). These may be used to test for specific errors. For example:

try {
	outputRecord = interaction.execute(myTuxInteractionSpec, inputRecord);
} catch (TuxedoException te) {
	if (te.getError() == TuxedoException.TPESVCFAIL)
	{
		// handle the service failure
	}
	// handle additional error codes that may be returned
}

The application may write information to the Tuxedo client log file using the static method Tuxedo.userlog(), which takes a single String parameter. XMLink provides several native methods which correspond roughly to Tuxedo ATMI methods. These methods should be used with caution. They are intended primarily for internal use by XMLink. Tuxedo.tperrno(), for example, may not return the same error code contained in the TuxedoException. That is because XMLink saves the error code right after the error occurs. This code may be changed by other ATMI calls made by XMLink before a CCI method returns to the application. Other methods of the Tuxedo class may have names which match Tuxedo ATMI methods, but parameters which do not.

In the managed environment, CCI methods may throw a ResourceException, which contains a chain of linked exceptions. Often the root cause is at the end of the chain, and may be a TuxedoException. The getLinkedException() method of ResourceException may be used in a loop until it returns null. The ReourceException at the end of the chain may then be tested to see if it is an instance of TuxedoException. If it is, it may be handled as previously described.

In addition to Tuxedo generated errors, XMLink occasionally generates a TuxedoException for other errors related to use of its native interface to access Tuxedo ATMI functions. In such cases, only the message portion of the exception, as returned by toString(), will be relevant. The getStrError() method of the TuxedoException may return the String TPENONE, which does not represent a real Tuxedo error code, and the getStrErrorDetail() method may return the String "none", which does not come from Tuxedo. These strings are used when the TuxedoException is not caused by a Tuxedo generated error.

Using the TuxedoReturnCodeWarning Class

XMLink provides the TuxedoReturnCodeWarning class to hold the user return code returned by a Tuxedo service. TuxedoReturnCodeWarning extends the ResourceWarning class provided by the connector architecture, which further extends ResourceException. As such, several TuxedoReturnCodeWarning objects may be chained, just like ResourceException objects, but they are not thrown as exceptions. The application code uses standard CCI methods to access any TuxedoReturnCodeWarning objects associated with an Interaction.

The user return code is the second argument to tpreturn(). Typically, it is used to provide additional information to the Tuxedo client about a service that failed. In this case, a Tuxedo client error code of TPESVCFAIL is associated with a Tuxedo service that returns TPFAIL as its return value. The return value is specified by the service in the first argument to tpreturn(). Even though this is a typical use, an application may use the user return code for some other purpose, since the client can access it even if the Tuxedo service returns TPSUCCESS as its return value.

Whenever a non-zero user return code is returned by a Tuxedo service, XMLink generates a TuxedoReturnCodeWarning, and adds it to the head of a linked list of them associated with the Interaction. (Note that if a user return code of zero has some special meaning for the application, application client code may call Tuxedo.tpurcode() directly.) The getWarnings() method of the Interaction class may be used to retrieve the ResourceWarning at the head of the linked list, typically a TuxedoReturnCodeWarning. Often there will be just one ResourceWarning if the execute() method of the Interaction was called just once, or if application code clears the list before successive calls to execute(). The ResourceWarning list can be cleared by calling the clearWarnings() method of the Interaction. The list is also cleared when the close() method of the Interaction is called. When the list is cleared, the getWarning() method returns null.

TuxedoReturnCodeWarning implements getReturnCode(), which returns a long, and getInteractionSpec(), which returns the InteractionSpec instance associated with the service call that generated the return code. toString() can be used to generate a String of the form "<function-name> returned <code>." Note that a TuxedoReturnCodeWarning will be generated for a non-zero user return code, regardless of whether TPSUCCESS or TPFAIL is returned by the service. Thus getWarnings() can be used directly after execute() is called, as well as in an exception handler block.

Using XMLink with Tuxedo 6.5

When using XMLink with Tuxedo 6.5, you need to be aware of the following issues:

XMLink does not support transactions when used with Tuxedo 6.5. XMLink throws a TPEBLOCK exception if an attempt is made to begin a transaction using XMLink with Tuxedo 6.5.

Tuxedo 6.5 allows only one client/server association (connection) per client process. If one client begins a transaction on the connection, and another client makes a service call, that service call would become part of the transaction begun by the first client. Since this cannot be permitted, an exception is thrown.
XMLink used as a Tuxedo 7.1 /WS client can be used with a Tuxedo 6.5 server. This can work around the lack of transaction support when used with Tuxedo 6.5. The Tuxedo 7.1 Rolling Patch is required for this to work.
XMLink achieves support for its multithreaded client for Tuxedo 6.5 by serializing calls to Tuxedo API functions. This is necessary since Tuxedo 6.5 libraries are not thread-safe. tpacall(), rather than tpcall(), is used to reduce most of the overhead introduced by the serialization.
XMLink does not support Tuxedo 6.5 CTS, a special "Client Threads Supplement" version of Tuxedo in which partial support for multithreaded native clients is provided.