WebSphere Application Server diagnostic tools provide services
to help troubleshoot database connection problems. Additionally, the
IBM Web site provides flexible searching capabilities for finding
documented solutions to database-specific connection problems.
The following steps help you quickly isolate connectivity problems.
- Browse the log files of the application server for clues.
See Setting up the error log.
See Viewing JVM logs.
By default, these files are app_server_root/server_name/SystemErr.log and SystemOut.log.
- Browse the Helper Class property of the data source to verify
that it is correct and that it is on the WebSphere Application Server
class path. Mysterious errors or behavior might result from a missing
or misnamed Helper Class name. If WebSphere Application Server cannot
load the specified class, it uses a default helper class that might
not function correctly with your database manager.
- 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.
- 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.
For a comprehensive list of database-specific troubleshooting tips,
see the WebSphere Application Server product support page. (Find the
link at the end of this article.) In the Search Support field, type
a database vendor name among your search terms. Select Solve a
problem, then click Search.
Remember that you can always find Support references in the Troubleshooting help from IBM article
of this information center.
Currently this information center provides a limited number of
troubleshooting tips for the following databases:
General data access problems
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 the 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 an assembly tool.
- 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 WebSphere Application Server 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 you must 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:
- Click Resources>Manage JDBC Providers link in the administrative
console.
- Select the JDBC provider that supports the problem data source.
- Select Data Sources and then select the problem data source.
- Under Additional properties click Custom Properties.
- Select the databaseName property, or add one if it does
not exist, and enter the actual database name as the value.
- Click Apply or OK, and then click Save from
the action bar.
- 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 WebSphere Application Server
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 WebSphere Application Server is executed, or
by adding a statement in a .sh file which then executes the startServer program.
![[z/OS]](../../ngzos.gif)
Configure the java LIBPATH (java.library.path) property
with the
domain_region_libpath environment variable,
like control_region_libpath, server_region_libpath, adjunct_region_libpath.
See the topic on changing the values of variables referenced in BBOM0001I
messages for instructions on how to set the region libpath variables.
Avoid trouble: The path that contains the DBM vendor libraries
might vary by dbm. One way to find the files is to scan the directories
for the missing library that is specified in the error message. Then,
correct the LIBPATH variable to include the missing directory. Correct
the LIBPATH variable in the .profile of the account from which WebSphere
Application Server is executed, or you can add a statement in a .sh
file that executes the startServer program.
gotcha
"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 is missing or disabled. last participant
support allows a one-phase capable resource and a two-phase capable
resource to enlist within the same transaction.
Last participant
support is only available if the following are true:
- WebSphere Application Server Programming Model Extensions (PME)
is installed. PME is included in the Application Server Integration
Server product.
- The Additional Integration Server 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 last
participant support.
- The application enlisting the one-phase resource is deployed with
the Accept heuristic hazard option enabled. This
deployment is done with an assembly
tool.
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 WebSphere Application Server 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 WebSphere Application Server.
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 WebSphere Application Server is
not. If you choose DB2 Legacy CLI-based type 2 JDBC Driver
when defining a JDBC provider in WebSphere Application Server, then
you must 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 operating systems such as AIX or Linux, 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. Sometimes 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.
If you are
using a CLI driver or a Universal JDBC T2 driver, WebSphere Application
Server does support interaction with a DB2 UDB 64-bit server, but
it must be through a DB2 UDB 32-bit client. The WebSphere Application
Server environment (CLASSPATH and so on) must use the 32-bit client
code to ensure correct function.
With a Universal JDBC T4 driver,
you do not need the 32-bit DB2 client. You need only configure the
CLASSPATH to include db2jcc.jar and its license files in the WebSphere
Application Server environment.
"J2CA0114W: No container-managed authentication
alias found for connection factory or datasource datasource"
when attempting a database operation
This error might occur
in the SystemOut.log file when you run an application
to access a data source after creating the data source using JACL
script.
The error message occurs because the JACL script did
not set container-managed authentication alias for CMP connection
factory. The JACL is missing the following line:
$AdminConfig create MappingModule $cmpConnectorFactory "{mappingConfigAlias
DefaultPrincipalMapping} {authDataAlias $authDataAlias}
To
correct this problem, add the missing line to the JACL script and
run the script again. See Example: Creating a JDBC provider and data source using Java Management Extensions API and the scripting tool for a sample JACL script.
An error is thrown if you use the ws_ant
command to perform the database customization for Structured Query
Language in Java on HP platforms
If you use the
ws_ant command
to perform the database customization for Structured Query Language
in Java (SQLJ) on HP platforms, you can receive an error similar to
the following:
[java] [ibm][db2][jcc][sqlj]
[java] [ibm][db2][jcc][sqlj] Begin Customization
[java] [ibm][db2][jcc][sqlj] encoding not supported!!
The cause
of this error might be that your databases were created using the
HP default character set. The Java Common Client (JCC) driver depends
on the software development kit (SDK) to perform the codepage conversions.
The SDK shipped with this product, however, does not support the HP
default codepage.
You need to set your LANG to the ISO locale
before creating the databases. It should be similar to the following:
export LANG=en_US.iso88591
Refer
to the IBM support site for Information Management software to access
the latest technotes for DB2.
Container-managed persistence (CMP) cannot
successfully obtain the database access function as defined.
When
WebSphere Application Server is caching certain generated code that
is accessed in the database on the connection factory, and if any
changes in the Java archive (JAR) file require regeneration of the
database access, the changes are not effective until you stop and
restart the server.
Examples of when this failure might occur
include:
- Adding an enterprise bean custom finder method; a NullPointerException
exception is created.
- Updating an enterprise bean custom finder method; the new SQL
statement does not run.
- Changing schema mapping; the new SQL statement does not run.
In summary, if you add or update an enterprise bean that
contains a custom finder method, you must stop and then restart the
server.