Cannot access a data source

What kind of database are you trying to access?

• Problems accessing an Oracle data source

• Problems accessing a DB2 database

• Problems accessing a SQL server data source

• Problems accessing a Cloudscape database

• Problems accessing a Sybase data source

• General data access problems

If the errors described in the previous articles do not match the errors you see...

1. Browse the log files of the appserver that contains the application, for clues. By default these files are $WAS_HOME/server_name/SystemErr.log and SystemOut.log.

2. Browse the Helper Class property of the data source to verify that it is correct and that it is on the WAS class path. Mysterious errors or behavior might result from a missing or misnamed Helper Class name. If WAS cannot load the specified class, it uses a default helper class that might not function correctly with your database manager.

3. Verify that the Java Naming and Directory Interface (JNDI) name of the data source matches the name used by the client attempting to access it. If error messages indicate that the problem might be naming-related, such as referring to the name server or naming service, or including error IDs beginning with NMSV, look at the Naming related problems and Troubleshooting the naming service component topics.

4. Enable tracing for the resource adapter using the trace specification, RRA=all=enabled. Follow the instructions for dumping and browsing the trace output, to narrow the origin of the problem.

If none of these steps fixes your problem, see if the problem is identified and documented in available online support (hints and tips, technotes, and fixes). If none of the online resources listed in the topic describes your problem, see Obtaining help from IBM.

 

General data access problems

• An exception "IllegalConnectionUseException" occurs

• WTRN0062E: An illegal attempt to enlist multiple one phase capable resources has occurred.

• ConnectionWaitTimeoutException.

• com.ibm.websphere.ce.cm.StaleConnectionException... [IBM][CLI Driver] SQL1013N The database alias name or database name "NULL" could not be found. SQLSTATE=42705

• java.sql.SQLException: java.lang.UnsatisfiedLinkError:

• "J2CA0030E: Method enlist caught java.lang.IllegalStateException" wrapped in error "WTRN0063E: An illegal attempt to enlist a one phase capable resource with existing two phase capable resources has occurred" when attempting to execute a transaction.

• java.lang.UnsatisfiedLinkError:xaConnect exception when attempting a database operation

 

IllegalConnectionUseException

This error can occur because a connection obtained from a WAS40DataSource is being used on more than one thread. This usage violates the J2EE 1.3 programming model, and an exception generates when it is detected on the server. This problem occurs for users accessing a data source through servlets or bean-managed persistence (BMP) enterprise beans.

To confirm this problem, examine the code for connection sharing. Code can inadvertently cause sharing by not following the programming model recommendations, for example by storing a connection in an instance variable in a servlet, which can cause use of the connection on multiple threads at the same time.

 

WTRN0062E: An illegal attempt to enlist multiple one phase capable resources has occurred

This error can occur because...

• An attempt was made to share a single-phase connection, when each getConnection method has different connection properties; such as the AccessIntent. This attempt causes a non-shareable connection to be created.

• An attempt was made to have more than one unshareable connection participate in a global transaction, when the data source is not an XA resource.

• An attempt was made to have a one-phase resource participate in a global transaction while an XA resource or another one-phase resource already participated in this global transaction.

  • Within the scope of a global transaction you try to get a connection more than once and at least one of the resource-refs you use specifies that the connection is unshareable, and the data source is not configured to support two-phase commit transactions. It does not support an XAResource. If you do not use a resource-ref, you default to unshareable connections.

  • Within the scope of a global transaction you try to get a connection more than once and at least one of the resource-refs you use specifies that the connection is shareable and the data source is not configured to support two-phase commit transactions. That is, it does not support an XAResource. In addition, even though you specify that connections are shareable, each getConnection request is made with different connection properties (such as IsolationLevel or AccessIntent). In this case, the connections are not shareable, and multiple connections are handed back.

  • Multiple components (servlets, session beans, BMP entity beans, or CMP entity beans) are accessed within a global transaction. All use the same data source, all specify shareable connections on their resource-refs, and you expect them to all share the same connection. If the properties are different, you get multiple connections. AccessIntent settings on CMP beans change their properties. To share a connection, the AccessIntent setting must be the same. For more information about CMP beans sharing a connection with non-CMP components, see Data access application programming interface support and Example... Accessing data using IBM extended APIs to share connections between container-managed and bean-managed persistence beans topics in the DataAccess section of the information center.

To correct this error...

• Check what your client code passes in with its getConnection requests, to ensure they are consistent with each other.

• Check the connection sharing scope from the resource binding, using the Assembly Toolkit.

  • If you are running an unshareable connection scope, verify that your data source is an XA data source.

  • If you are running a shareable connection scope, verify that all connection properties, including AccessIntent, are sharable.

• Check the JDBC provider implementation class from the Manage JDBC resource panel of the administrative console to ensure that it is a class that supports XA-type transactions.

 

ConnectionWaitTimeoutException accessing a data source or resource adapter

If your application receives exceptions like a com.ibm.websphere.ce.cm.ConnectionWaitTimeoutException or com.ibm.websphere.ce.j2c.ConnectionWaitTimeoutException when attempting to access a WAS data source or JCA-compliant resource adapter, respectively, some possible causes are...

• The maximum number of connections for a given pool is set too low. The demand for concurrent use of connections is greater then the configured maximum value for the connection pool. One indication that this situation is the problem is that you receive these exceptions regularly, but your CPU utilization is not high. This exception indicates that there are too few connections available to keep the threads in the server busy.

• Connection Wait Time is set too low. Current demand for connections is high enough such that sometimes there is not an available connection for short periods of time. If your connection wait timeout value is too low, you might timeout shortly before a user returns a connection back to the pool. Adjusting the connection wait time can give you some relief. One indication of this problem is that you use close to the maximum number of connections for an extended period and receiving this error regularly.

• You are not closing some connections or you are returning connections back to the pool at a very slow rate. This situation can happen when using unshareable connections, when you forget to close them, or you close them long after you are finished using them, keeping the connection from returning to the pool for reuse. The pool soon becomes empty and all applications get ConnectionWaitTimeoutExceptions. One indication of this problem is you run out of connections in the connection pool and you receive this error on most requests.

• You are driving more load than the server or backend system have resources to handle. In this case determine which resources you need more of and upgrade configurations or hardware to address the need. One indication of this problem is that the application or database server CPU is nearly 100% busy.

To correct these problems, either...

• Modify an application to use fewer connections

• Properly close the connections.

• Change the pool settings of MaxConnections or ConnnectionWaitTimeout.

• Adjust resources and their configurations.

 

com.ibm.websphere.ce.cm.StaleConnectionException... [IBM][CLI Driver] SQL1013N The database alias name or database name "NULL" could not be found. SQLSTATE=42705

This error occurs when a data source is defined but the databaseName attribute and the corresponding value are not added to the custom properties panel.

To add the databaseName property...

1. Click Resources>Manage JDBC Providers link in the administrative console.

2. Select the JDBC provider that supports the problem data source.

3. Select Data Sources and then select the problem data source.

4. Under Additional properties click Custom Properties.

5. Select the databaseName property, or add one if it does not exist, and enter the actual database name as the value.

6. Click Apply or OK, and then click Save from the action bar.

7. Access the data source again.

 

java.sql.SQLException: java.lang.UnsatisfiedLinkError:

This error indicates that the directory containing the binary libraries which support a database are not included in the LIBPATH environment variable for the environment in which the WAS starts.

The path containing the DBM vendor libraries vary by dbm. One way to find them is by scanning for the missing library specified in the error message. Then you can correct the LIBPATH variable to include the missing directory, either in the .profile of the account from which WAS is executed, or by adding a statement in a .sh file which then executes the startServer program.

 

"J2CA0030E: Method enlist caught java.lang.IllegalStateException" wrapped in error "WTRN0063E: An illegal attempt to enlist a one phase capable resource with existing two phase capable resources has occurred" when attempting to execute a transaction.

This error can occur when last participant support (LPS) is missing or disabled. LPS allows a one-phase capable resource and a two-phase capable resource to enlist within the same transaction.

LPS is only available if the following are true...

• WAS Programming Model Extensions (PME), which is included in the Application Server Enterprise product is installed.

• The Additional Enterprise Extensions option is enabled when PME is installed. If you perform a typical installation, this function is enabled by default. If you perform a custom installation, you have the option to disable this function, which disables LPS.

• The application enlisting the one-phase resource is deployed with the Accept heuristic hazard option enabled. This deployment is done through the Assembly Toolkit. To enable this option in the Application Assembly Tool:

  1. Load the EAR file into the Assembly Toolkit.

  2. If the EAR file is actually a JTEE1.2 EAR then it must be upgraded to a JTEE1.3 EAR by clicking File> Convert EAR from the Assembly Toolkit.

  3. Select the EAR file in the left-hand panel of the Application Assembly Tool.

  4. Select the WAS Enterprise tab in the bottom right window panel of the Assembly Toolkit.

  5. Ensure that the Accept heuristic hazard option is selected.

  6. Save the EAR file.

 

java.lang.UnsatisfiedLinkError:xaConnect exception when attempting a database operation

This problem has two main causes:

• The most common cause is that the jdbc driver which supports connectivity to the database is missing, or is not the correct version, or that native libraries which support the driver are on the system's path.

  • To resolve this problem on a Windows platform, verify that the JDBC driver jar file is on the system PATH environment variable...

    • If you are using DB2,verify that at least the DB2 client product has been installed on the WebSphere host

      • On DB2 version 7.2 or earlier, the file where the client product is installed on the WAS is db2java.zip. Verify that the usejdbc2.bat program has been executed after the database install and after any upgrade to the database product.

      • On DB2 version 8.1 or later, use the DB2 Universal JDBC Provider Driver when defining a JDBC provider in WAS. The driver file is db2jcc.jar. If you use the type 2 (default) option, verify that at least the DB2 client product is installed on the WebSphere Application Server host. If you specify the type 4 option, the DB2 client does not need to be installed, but the file db2jcc.jar still must be present.

        When specifying the location of the driver file, it is recommended to that you specify the path and file name of the target DB2 installation, rather than simply copying the file to a local directory, if possible. Otherwise, you may be exposed to problems if the target DB2 installation is upgraded and the driver used by WAS is not. If you choose DB2 Legacy CLI-based type 2 JDBC Driver when defining a JDBC provider in WAS, then still follow the steps to ensure that you have the correct version of the db2java.zip file (see instructions for DB2 7.2 or earlier).

  • On a Unix platform, ensure that any native libraries required to support the database client of your database product are specified in the LD_LIBRARY_PATH environment variable in the profile of the account under which WebSphere Application Server executes.

    If you are using DB2 The native library is libdb2jdbc.so. The best way to ensure that this library is accessed correctly by WebSphere is to call the db2profile script supplied with DB2 from the .profile script of the account (such as "root") under which WebSphere runs.

    • If you are using DB2 version 7.2 or earlier, ensure that the usejdbc2,script provided with DB2 is called from the profile of the account under which WebSphere Application server is launched.

    • If you are using DB2 version 8.1 or later, see the previous instructions for the Windows operating system.

• If the database manager is DB2, you may have chosen the option to create a 64-bit instance.  A 64-bit configuration is not supported. If this has happened, remove the database instance and create a new one with the default 32-bit setting.

  Note that For general help in configuring JDBC drivers and data sources in WAS, see the topic Accessing data from applications.

 

See Also

Troubleshooting by component: What is not working?
Example: Accessing data using IBM extended APIs to share connections between container-managed and bean-managed persistence beans
Data access application programming interface support
Problems accessing an Oracle data source
Problems accessing a DB2 database
Problems accessing a SQL server data source
Problems accessing a Cloudscape database
Problems accessing a Sybase data source

 

---