In JDBC applications, SQL errors throw exceptions, which
you handle using try/catch blocks. SQL warnings do
not throw exceptions, so you need to invoke methods to check whether
warnings occurred after you execute SQL statements.
The IBM® Data Server Driver for JDBC and SQLJ provides
the following classes and interfaces, which provide information about
errors and warnings.
SQLException
The
SQLException class
for handling errors. All JDBC methods throw an instance of
SQLException when
an error occurs during their execution. According to the JDBC specification,
an
SQLException object contains the following information:
- An int value that contains an error code. SQLException.getErrorCode retrieves
this value.
- A String object that contains the SQLSTATE,
or null. SQLException.getSQLState retrieves this
value.
- A String object that contains a description
of the error, or null. SQLException.getMessage retrieves
this value.
- A pointer to the next SQLException, or null. SQLException.getNextException retrieves
this value.
When a JDBC
method throws a single SQLException, that SQLException might
be caused by an underlying Java™ exception
that occurred when the IBM Data Server Driver for JDBC and SQLJ processed
the method. In this case, the SQLException wraps
the underlying exception, and you can use the SQLException.getCause method
to retrieve information about the error.
DB2Diagnosable
The
IBM Data Server Driver for JDBC and SQLJ-only
interface
com.ibm.db2.jcc.DB2Diagnosable extends
the
SQLException class. The
DB2Diagnosable interface
gives you more information about errors that occur when the data source
is accessed. If the JDBC driver detects an error,
DB2Diagnosable gives
you the same information as the standard
SQLException class.
However, if the database server detects the error,
DB2Diagnosable adds
the following methods, which give you additional information about
the error:
- getSqlca
- Returns an DB2Sqlca object with the following
information:
- An SQL error code
- The SQLERRMC values
- The SQLERRP value
- The SQLERRD values
- The SQLWARN values
- The SQLSTATE
- getThrowable
- Returns a java.lang.Throwable object that caused
the SQLException, or null, if no such object exists.
- printTrace
- Prints diagnostic information.
SQLException subclasses
If you are using JDBC
4.0 or later, you can obtain more specific information than an
SQLException provides
by catching the following exception classes:
- SQLNonTransientException
An SQLNonTransientException is
thrown when an SQL operation that failed previously cannot succeed
when the operation is retried, unless some corrective action is taken.
The SQLNonTransientException class has these subclasses:
- SQLFeatureNotSupportedException
- SQLNonTransientConnectionException
- SQLDataException
- SQLIntegrityConstraintViolationException
- SQLInvalidAuthorizationSpecException
- SQLSyntaxException
- SQLTransientException
An SQLTransientException is
thrown when an SQL operation that failed previously might succeed
when the operation is retried, without intervention from the application.
A connection is still valid after an SQLTransientException is
thrown. The SQLTransientException class has these
subclasses:
- SQLTransientConnectionException
- SQLTransientRollbackException
- SQLTimeoutException
- SQLRecoverableException
An SQLRecoverableException is
thrown when an operation that failed previously might succeed if the
application performs some recovery steps, and retries the transaction.
A connection is no longer valid after an SQLRecoverableException is
thrown.
- SQLClientInfoException
A SQLClientInfoException is
thrown by the Connection.setClientInfo method when
one or more client properties cannot be set. The SQLClientInfoException indicates
which properties cannot be set.
BatchUpdateException
A BatchUpdateException object
contains the following items about an error that occurs during execution
of a batch of SQL statements:
- A String object that contains a description
of the error, or null.
- A String object that contains the SQLSTATE
for the failing SQL statement, or null
- An integer value that contains the error code, or zero
- An integer array of update counts for SQL statements in the batch,
or null
- A pointer to an SQLException object, or null
One
BatchUpdateException is thrown for
the entire batch. At least one
SQLException object
is chained to the
BatchUpdateException object.
The
SQLException objects are chained in the same
order as the corresponding statements were added to the batch. To
help you match
SQLException objects to statements
in the batch, the error description field for each
SQLException object
begins with this string:
Error for batch element #n:
n is
the number of the statement in the batch.
SQL warnings during
batch execution do not throw BatchUpdateExceptions.
To obtain information about warnings, use the Statement.getWarnings method
on the object on which you ran the executeBatch method.
You can then retrieve an error description, SQLSTATE, and error code
for each SQLWarning object.
SQLWarning
The IBM Data Server Driver for JDBC and SQLJ accumulates
warnings when SQL statements return positive SQLCODEs, and when SQL
statements return 0 SQLCODEs with non-zero SQLSTATEs.
Calling getWarnings retrieves
an SQLWarning object.
Important: When
a call to Statement.executeUpdate or PreparedStatement.executeUpdate affects
no rows, the IBM Data Server Driver for JDBC and SQLJ generates
an SQLWarning with error code +100.
When
a call to ResultSet.next returns no rows, the IBM Data Server Driver for JDBC and SQLJ does
not generate an SQLWarning.
A generic SQLWarning object
contains the following information:
- A String object that contains a description
of the warning, or null
- A String object that contains the SQLSTATE,
or null
- An int value that contains an error code
- A pointer to the next SQLWarning, or null
Under the IBM Data Server Driver for JDBC and SQLJ,
like an SQLException object, an SQLWarning object
can also contain DB2-specific
information. The DB2-specific
information for an SQLWarning object is the same
as the DB2-specific
information for an SQLException object.