WebSphere® Application Server diagnostic
tools provide services to help troubleshoot database connection problems.
Additionally, the IBM® website provides flexible searching
capabilities for finding documented solutions to database-specific
connection problems.
New feature: This topic
references one or more of the application server log files. Beginning
in WebSphere Application Server Version 8.0 you can configure the
server to use the High Performance Extensible Logging (HPEL) log and
trace infrastructure instead of using
SystemOut.log ,
SystemErr.log,
trace.log,
and
activity.log files or native z/OS logging
facilities. If you are using HPEL, you can access all of your log
and trace information using the LogViewer command-line tool from your
server profile bin directory. See the information about using HPEL
to troubleshoot applications for more information on using HPEL.
newfeat
The following steps help you quickly isolate connectivity problems.
- Browse the log files of the application server for clues.
See the topic, Setting up the error log.
See the topic, Viewing JVM logs. By default,
these files are
app_server_root/server_name/SystemErr.log and
SystemOut.log.
New feature: This topic
references one or more of the application server log files. Beginning
in WebSphere Application Server Version 8.0 you can configure the
server to use the High Performance Extensible Logging (HPEL) log and
trace infrastructure instead of using
SystemOut.log ,
SystemErr.log,
trace.log,
and
activity.log files or native z/OS logging
facilities. If you are using HPEL, you can access all of your log
and trace information using the LogViewer command-line tool from your
server profile bin directory. See the information about using HPEL
to troubleshoot applications for more information on using HPEL.
newfeat
- 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 topics, Naming related problems, and Troubleshooting the naming
service component.
- 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. See the topic,
Enabling tracing.
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 topic,
Troubleshooting help from IBM, in 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 one-phase connection but the getConnection
calls do not all use the same connection properties; such as the AccessIntent
property.
- 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
has already participated in this global transaction. The following
information might help identify why the error condition is occurring:
- If you are using a non-XA data source and you are expecting to
share a connection, set all of the relevant resource-refs to shareable.
If you do not use a resource-ref, the default is set to unshareable
connections.
- Your connection is not shared if you do not use the same connection
properties, such as IsolationLevel or AccessIntent, on each connection
request.
- Your connections might not be shared if you are using CMP beans
that might be using different AccessIntent settings. To learn more
about CMP beans sharing a connection with non-CMP components, see
theinformation on extensions to data access APIs.
To correct this error:
- Check what your client code passes in with its getConnection requests,
to ensure that they are consistent with each other.
- Check the connection sharing scope from the resource binding,
using an assembly tool. See the topic, Assembly tools.
- 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 shareable.
- 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, 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 than
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 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 with 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
server or the database server processor 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 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 started, or by adding a statement in a .sh file
which then starts the startServer program.
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.
"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 supports 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 can 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.
This problem has two
main causes:
- The most common cause is that the JDBC driver that supports connectivity
to the database is missing, or is not the correct version. Another
common cause is the native libraries which support the driver are
on the system 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 copying the file
to a local directory, if possible. Otherwise, you might be exposed
to problems if the target DB2 installation is upgraded and
the driver used by WebSphere Application Server
is not.
- 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 starts.
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
can choose 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 one with the default 32-bit setting.
If
you are using the 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 class path to include db2jcc.jar and its license files in the WebSphere Application Server environment.
Note: For
general help in configuring JDBC drivers and data sources in WebSphere Application Server, see the topic,
Accessing data from applications.
"J2CA0114W: No container-managed authentication
alias found for connection factory or data source 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 the topic, 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 code page conversions. The SDK shipped with this product,
however, does not support the HP default code page.
You must
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.