Adapter Logging and Exception Handling

Overview

The following sections describe message logging and Adapter for Tuxedo exception handling. A list of error codes and supporting information appears at the end of this chapter.

Adapter Logging Levels

The Adapter for Tuxedo uses the Integration Server logging mechanism to log messages. You can configure and view the Integration Server logs to monitor and troubleshoot the Adapter for Tuxedo. For detailed information about logging in the Integration Server, including instructions for configuring and viewing the different kinds of logs supported by the server, see the IBM webMethods Audit Logging Guide for your release.

Configuring Adapter Logging Levels

Beginning with Integration Server 7.1.1, you can configure different logging levels for the Adapter for Tuxedo. For complete information about specifying the amount and type of information to include in the log, see the IBM webMethods Audit Logging Guide for your release.

Accessing Logging Information

About this task

Perform the following to access an adapter's logging information.

To access the adapter's logging information

Procedure

From the Integration Server Administrator screen, select Settings > Logging.

The Logging Settings screen appears. The Loggers section has Adapters included in the Facility section.
Expand the Adapters tree to see a list of all installed adapters with their code number and adapter description, along with the logging level.

Changing Logging Settings

About this task

Perform the following to change an adapter's logging settings.

To change logging settings for the adapter

Procedure

Click Edit Logging Settings. Select the required Level of Logging for the Adapter for Tuxedo.
After making your changes, click Save Changes.

Adapter Message Logging

The Integration Server maintains several types of logs; however, the Adapter for Tuxedo logs messages only to the audit, error, and server logs. Because the Adapter for Tuxedo works in conjunction with the WmART package, the adapter's messages and exceptions typically appear within log messages for the WmART package.

The logging levels are different depending on which version of the Integration Server you are running the adapter on, as shown in the following table.

Integration Server	Log	Description
Integration Server 6.5	Audit Log	You can monitor individual adapter services using the audit log as you would audit any service in the Integration Server. The audit properties for an adapter service are available in the Adapter for Tuxedo service template on the Audit tab.
	Error Log	The Adapter for Tuxedo automatically posts critical-level and error-level log messages to the error log. These log messages appear as adapter run-time messages.
	Server Log	The Adapter for Tuxedo posts messages to the server log, depending on how the server log is configured. Critical-level through debug-level log messages appear as adapter run-time log messages. V1-Verbose1 or V4-Verbose4 log messages appear as Adapter for Tuxedo log messages.
Integration Server 7.1.1 or higher	Audit Log	You can monitor individual adapter services using the audit log as you would audit any service in the Integration Server. The audit properties for an adapter service are available in the Adapter for Tuxedo service template on the Audit tab.
	Error Log	The Adapter for Tuxedo automatically posts fatal-level and error-level log messages to the error log. These log messages appear as adapter run-time messages.
	Server Log	The Adapter for Tuxedo posts messages to the server log, depending on how the server log is configured. Fatal-level through debug-level log messages appear as adapter run-time log messages. Trace-level log messages appear as Adapter for Tuxedo log messages.

The Adapter for Tuxedo's log messages appear in the format, ADA.740.nnnnc, where:

ADA is the facility code that indicates the message is from an adapter.
740 is the Adapter for Tuxedo major error code, which indicates that the message is generated by the Adapter for Tuxedo.
nnnn represents the error's minor code. For detailed descriptions of the Adapter for Tuxedo's minor codes, see Adapter Error Codes.
c represents the message's severity level (optional).

To monitor the Adapter for Tuxedo's log messages in the server log, ensure that your server log's logging settings are configured to monitor the following facilities:

0113 Adapter Runtime (Managed Object)
0114 Adapter Runtime
0117 Adapter Runtime (Adapter Service)
0118 Adapter Runtime (Connection)
0121 Adapter Runtime (SCC Transaction Manager)
0126 Adapter Runtime (SCC Connection Manager)

Adapter Exception Handling

The Adapter for Tuxedo throws two kinds of exceptions that you should be aware of as you build integrations using the adapter:

AdapterException
AdapterConnectionException

When creating a flow or Java service that incorporates an adapter service, you might want to build logic into the wrapping service to catch and handle these types of exceptions.

AdapterException

The Adapter for Tuxedo throws an AdapterException to report an error related to the adapter's logic, such as a configuration error or a connection creation error.

To manage the AdapterException, you can catch the DetailedServiceException in a flow or Java service and then navigate through the nested exceptions to the AdapterException, which will contain the error code identifying the error.

AdapterConnectionException

The Adapter for Tuxedo throws an AdapterConnectionException to wrap a Jolt exception if the adapter interprets the code as a fatal error.

In this case, WmART drops the connection from the connection pool and tries to create a new connection. It then wraps the exception in com.wm.pkg.art.error.DetailedSystemException and throws it to the Integration Server.

Customizing the Adapter's List of Fatal Error Codes

About this task

The execution of a Adapter for Tuxedo service may sometimes result in a bea.jolt.JoltException being thrown. All the Jolt exceptions are distinguished by an error number. The list of these Jolt exception error numbers can be found on the web site of Oracle.

By default, a Jolt exception with the error number TPEJOLT is considered as a fatal exception, which results in an AdapterConnectionException being thrown. You can also add a specific Jolt error number to the list of fatal Jolt error numbers.

If a Jolt exception error number matches TPEJOLT or any of the error numbers in the fatal error number list, then the adapter throws an AdapterConnectionException. The Adapter Runtime then catches the AdapterConnectionException, and automatically refreshes the corresponding adapter connections.

If the Jolt exception error number does not match TPEJOLT or any of the error numbers in the fatal error number list, then the adapter throws an AdapterException.

To add JoltException error numbers to the list of fatal error numbers

Procedure

Start the Integration Server Administrator if it is not already running.
Under Settings in the left panel, select Extended.
Select Edit Extended Settings. In the edit box, type:
```
watt.tuxedoadapter.fatalErrors=+ErrorNumber_1, ErrorNumber_2, ErrorNumber_n
```
Example: To allow the Adapter for Tuxedo to refresh connections when encountering JoltException with error numbers TPESYSTEM, TPEIO, and TPEOS, type:
```
watt.tuxedoadapter.fatalErrors=+TPESYSTEM, TPEIO, TPEOS
```
Click Save Changes.
Restart the Adapter for Tuxedo.

Adapter Error Codes

The Adapter for Tuxedo categorizes its minor code numbers as follows:

Error Code	Description
3000-3016	Connection errors between the adapter and the Jolt server.
302`x`	Errors from a failed local transaction. These can occur at design time or at run time.
5000-5011	Cache look ups in the connection factory errors. These can occur at design time or at run time.
501`x`-502`x`	Errors from the introspection of the Jolt server's repository. This repository contains the names and input/output signatures of all remote Tuxedo services as well as all the associated data type information. During the introspection sequence, a connection is established, a list of all service names and their input/output metadata parameters is captured and placed in a cache in the connection factory object of the connection for access during adapter service creation (design time) or during adapter service execution (run time). 501`x` - Input Signature Creation Errors 502`x` - Output Signature Creation Errors
503`x`	Errors from executing the adapter services.

The following lists the Adapter for Tuxedo's minor codes and provides information about the error message, reason, and possible action for each error.

Error Code	Description
3001	`Can't instantiate JOLT Parameter Object. Check Jolt.jar file.`
	Explanation: The jolt.jar file is missing.
	Action: Verify that the jolt.jar file exists in the WmTuxedoAdapter/code/jars folder. If it does not exist, copy the jolt.jar file from the `Jolt_directory`\udataobj\jolt\java\lib directory where `Jolt_directory` is the directory where the Jolt server is running.
3002	`Failed to get Tuxedo6SyncConnectionFactory object from parent.`
	Explanation: The Tuxedo connection cannot retrieve a reference to the connection factory.
	Action: Check the error log for connection errors and reload/restart the adapter package.
3003	`TuxedoSyncConnection:JoltConnection open() error.`
	Explanation: The Tuxedo connection caught an exception from the Jolt API while attempting to connect.
	Action: Verify that the jolt.jar file exists in the WmTuxedoAdapter/code/jars folder. If it does not exist, copy the jolt.jar file from the `Jolt_directory`\udataobj\jolt\java\lib directory where `Jolt_directory` is the directory where the Jolt server is running.
3004	`TuxedoSyncConnection:Failed to open() Jolt Connection.`
	Explanation: The Tuxedo connection failed to successfully open a Jolt server connection.
	Action: Check that the connection parameters (hostname, port, login, etc.) are correct for the connection, and verify that the physical connection still exists.
3005	`TuxedoSyncConnection:registerResourceDomain() failed.`
	Explanation: The Tuxedo connection cannot register the adapter service templates for this connection.
	Action: Check the error log for connection errors and reload/restart the adapter package.
3010	`TuxedoSyncConnection:Failed to get JoltSession object: SessionException received.`
	Explanation: The Tuxedo connection was unable to establish a session with the Jolt server.
	Action: Verify that the jolt.jar file exists in the WmTuxedoAdapter/code/jars folder.If it does not exist, copy the jolt.jar file from the `Jolt_directory`\udataobj\jolt\java\lib directory where `Jolt_directory` is the directory where the Jolt server is running. Check that the connection parameters (hostname, port, login, etc) are correct for the connection, and verify that the physical connection still exists.
3011	`TuxedoSyncConnection:Failed to close a JoltSession in endSession().`
	Explanation: The Tuxedo connection was unable to end a session with the Jolt server.
	Action: Check the session timeout definition on the Jolt server. It should be set to infinite.
3012	`TuxedoSyncConnection:Failed to Get/Set JoltSessionAttributes in Connection open().`
	Explanation: The Jolt API is unable to return or set connection attributes.
	Action: Verify that the jolt.jar file exists in the WmTuxedoAdapter/code/jars folder. If it does not exist, copy the jolt.jar file from the `Jolt_directory`\udataobj\jolt\java\lib directory where `Jolt_directory` is the directory where the Jolt server is running. Verify that the parameters for the connection are correct.
3013	`TuxedoSyncConnection:AdapterCheckValue() Failed.`
	Explanation: The connection is unable to get the adapter service object for an adapter service name.
	Action: Check the adapter service. It may be deleted, corrupted, or renamed.
3014	`TuxedoSyncConnection:adapterResourceDomainLookup() Failed.`
	Explanation: The connection is unable to get the ResourceDomainValues for an adapter service name.
	Action: Check the adapter service. It may be deleted, corrupted, or renamed.
3015	`TuxedoSyncConnectionFactory:can't get the Repository Object.`
	Explanation: The Tuxedo connection factory cannot create a Jolt repository introspection object.
	Action: Check the error log for details. Verify that the parameters for the connection are correct.
3016	`TuxedoSyncConnectionFactory:initRepository() Failed.`
	Explanation: The Tuxedo connection factory received an exception from the Jolt interface while attempting to create a Jolt Repository introspection object.
	Action: Check the error log for details. Verify that the parameters for the connection are correct.
3020	`TuxedoLocalTransaction:Failed to begin Jolt Transaction.`
	Explanation: The LOCAL TRANSACTION is unable to create a Jolt server transaction object.
	Action: Check the error log for details. Also verify that the Tuxedo connection status is enabled and that the parameters for this connection are correct.
3021	`TuxedoLocalTransaction:Failed to commit Jolt Transaction.`
	Explanation: The LOCAL TRANSACTION is unable to commit a Jolt server transaction object.
	Action: Check the error log for details. Also verify that the Tuxedo connection status is enabled and that the parameters for this connection are correct.
3022	`TuxedoLocalTransaction:Failed to rollback Jolt Transaction.`
	Explanation: The LOCAL TRANSACTION is unable to rollback a Jolt server transaction object.
	Action: Check the error log for details. Also verify that the Tuxedo connection status is enabled and that the parameters for this connection are correct.
5001	`TuxedoAdapter:MetadataCommon can't find Service Descriptor, Cache Null.`
	Explanation: Unable to look up a Tuxedo service in the connection factory. The cache pointer is NULL.
	Action: Check the error log for details and make sure the Tuxedo connection is enabled and has no connection failures.
5002	`TuxedoAdapter:MetadataCommon can't find Service Descriptor in Cache.`
	Explanation: Unable to lookup a Tuxedo service in the connection factory. Name is not in the cache.
	Action: Check the error log for details and make sure the Tuxedo connection is enabled and has no connection failures.
5010	`TuxedoAdapter:TuxRepoLookupName can't get factory from connection.`
	Explanation: The Tuxedo connection is unable to get the reference to the parent connection factory.
	Action: Check the error log for details. Reload/restart the Adapter for Tuxedo package.
5011	`TuxedoAdapter:TuxRepoLookupName can't get Repository Cache from Factory.`
	Explanation: The Tuxedo connection factory is unable to return the pointer to the repository cache.
	Action: Check the connection status and look in the error log for connection errors.
5012	`TuxedoAdapter:TuxInputSignature can't get factory from connection.`
	Explanation: The Tuxedo connection is unable to get the reference to the parent connection factory.
	Action: Check the error logs for connection errors. Reload/restart the Adapter for Tuxedo package.
5013	`TuxedoAdapter:TuxInputSignature can't get Repository Cache from Factory.`
	Explanation: The Tuxedo connection factory is unable to return the pointer to the repository cache.
	Action: Check the connection status and look in the error log for connection errors.
5014	`TuxedoAdapter:TuxInputSignature No Service Descriptors in Repository.`
	Explanation: The repository cache in the connection factory is empty.
	Action: Check the connection status and verify that the connection attributes (Application Name, Application Password, User Role, etc.) are correct.
5015	`TuxedoAdapter:TuxInputSignature Service Name is NULL.`
	Explanation: The service name passed for look ups in the repository cache is NULL.
	Action: The adapter service is corrupt, deleted, renamed, or out of sync with the repository.
5016	`TuxedoAdapter:TuxInputSignature can't Find Service Descriptor in Repository.`
	Explanation: The service name passed for look ups in the repository cache cannot be found.
	Action: The cache in the connection factory is not synchronized with the repository. Reload/restart the adapter.
5017	`TuxedoAdapter:TuxInputSignature Input Signature in Descriptor is NULL.`
	Explanation: The Tuxedo service descriptor in the repository cache has no input signature.
	Action: Check the input signature definition on the Jolt server for this service.
5018	`TuxedoAdapter:TuxInputSignature No Parameters in Input Signature Descriptor.`
	Explanation: The input signature in the repository cache has no parameters.
	Action: Check the input signature definition on the Jolt server for this service.
5022	`TuxedoAdapter:TuxOutputSignature can't get factory from connection.`
	Explanation: The Tuxedo connection is unable to get the reference to the parent connection factory.
	Action: Check the error log for details. Reload/restart the Adapter for Tuxedo package.
5023	`TuxedoAdapter:TuxOutputSignature can't get Repository Cache from Factory.`
	Explanation: The Tuxedo connection factory is unable to return the pointer to the repository cache.
	Action: Check the connection status and look in the error log for connection errors.
5024	`TuxedoAdapter:TuxOutputSignature No Service Descriptors in Repository.`
	Explanation: The repository cache in the connection factory is empty.
	Action: Check the connection status and verify that the connection attributes (Application Name, Application Password, User Role, etc.) are correct.
5025	`TuxedoAdapter:TuxOutputSignature Service Name is NULL.`
	Explanation: The service name passed for look ups in the repository cache is NULL.
	Action: The adapter service is corrupt, deleted, renamed, or not synchronized with the repository.
5026	`TuxedoAdapter:TuxOutputSignature can't find Service Descriptor in Repository.`
	Explanation: The service name passed for look ups in the repository cache cannot be found.
	Action: The cache in the connection factory is not synchronized with the repository. Reload/restart the adapter.
5027	`TuxedoAdapter:TuxOutputSignature Output Signature in Descriptor is NULL.`
	Explanation: The Tuxedo service descriptor in the repository cache has no output signature.
	Action: Check the output signature definition on the Jolt server for this service.
5028	`TuxedoAdapter:TuxOutputSignature No Parameters in Output Signature Descriptor.`
	Explanation: The output signature in the repository cache has no parameters.
	Action: Check the output signature definition on the Jolt server for this service.
5030	`TuxedoAdapter:Tux Synch Service, execute:Input WmRecord is NULL.`
	Explanation: The input signature record passed into the adapter service is NULL.
	Action: Check the error log for details. Reload/restart the adapter package.
5031	`TuxedoAdapter:Tux Synch Service, execute:can't create JoltRemoteService Object.`
	Explanation: Unable to create a Jolt service with the name given in the adapter service. Adapter service is not synchronized with the Jolt server repository.
	Action: Reload or restart the adapter.
5032	`TuxedoAdapter:Tux Synch Service, execute:JoltRemoteService.call() failed.`
	Explanation: The call() to execute the remote service on the Jolt server failed. Check the error log for details.
	Action: Check the connection status and the adapter service. Ensure that the adapter service is synchronized with the Tuxedo service.
5033	`TuxedoAdapter:Tux Synch Service, execute:Input Field: can't cast from Java-type to Jolt-Type.`
	Explanation: The input field data type for Java cannot be translated to a Jolt server data type.
	Action: Check the data type definitions in the adapter service in Designer.
5034	`TuxedoAdapter:Tux Synch Service, execute:Input Fields: No Service Input Values.`
	Explanation: There are no input signature values to pass to the Jolt remote service.
	Action: Check the input signature definition in Designer.
5035	`TuxedoAdapter:Tux Synch Service, execute:WmManagedConnection is not Tuxedo6SyncConnection.`
	Explanation: The adapter service template does not match the connection type. Check the error log for details.
	Action: Reload/restart the adapter package.
5036	`TuxedoAdapter:Tux Synch Service, execute:Error while adding Values to RemoteService.`
	Explanation: The adapter service cannot add the input signature values to the Jolt remote service object.
	Action: Compare the adapter service signature to the Jolt server repository signature.
5037	`TuxedoAdapter:Tux Synch Service, execute:Error reading response data from JoltRemoteService.`
	Explanation: Data defined in the adapter service output signature was not returned by the Jolt remote service.
	Action: Compare the adapter service signature to the Jolt server repository signature.
5038	`TuxedoAdapter:Tux Synch Service, execute:can't translate IS datatype for input field to Tuxedo datatype.`
	Explanation: A data type in the adapter service input signature cannot be translated to a Jolt remote service data type.
	Action: Compare the adapter service signature to the Jolt server repository signature.
5039	`TuxedoAdapter:Tux Synch Service, execute:can't translate Tux datatype to IS datatype for output field.`
	Explanation: The data returned by the Jolt remote service contains a data type that cannot be translated to a Java data type.
	Action: Compare the adapter service signature to the Jolt server repository signature.