Exceptions and warnings under the IBM Data Server Driver for JDBC and SQLJ

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 information specific to DB2®. The information specific to DB2, for an SQLWarning object, is the same as the information for an SQLException object.