1. C Developer's Guide
  2. Working With TimesTen Databases in ODBC
  3. Error Handling

Error Handling

There are methods to check and handle different types of errors.

This section includes the following topics:

Checking for Errors

An application should check for errors and warnings on every call. This saves considerable time and effort during development and debugging. The sample applications provided with TimesTen show examples of error checking.

See About TimesTen Quick Start and Sample Applications.

Errors can be checked using either the TimesTen error code (error number) or error string, as defined in the installation_dir/include/tt_errCode.h file. Entries are in the following format: 

#define tt_ErrMemoryLock             712

See List of Errors and Warnings in Oracle TimesTen In-Memory Database Error Messages and SNMP Traps.

After calling an ODBC function, check the return code. If the return code is not SQL_SUCCESS, use an error-handling routine that calls the ODBC function SQLError to retrieve the errors on the relevant ODBC handle. A single ODBC call may return multiple errors. The application should be written to return all errors by repeatedly calling the SQLError function until all errors are read from the error stack. Continue calling SQLError until the return code is SQL_NO_DATA_FOUND. (SQL_NO_DATA_FOUND is defined in sqlext.h, which is included by timesten.h.)

The following example shows that after a call to SQLAllocConnect, you can check for an error condition. If one is found, an error message is displayed and program execution is terminated. 

rc = SQLAllocConnect(henv, &hdbc);

if (rc != SQL_SUCCESS) {
  handleError(rc, henv, hdbc, hstmt, err_buf, &native_error);
  fprintf(stderr,
          "Unable to allocate a connection handle:\n%s\n",
          err_buf);
  exit(-1);
}

Refer to ODBC API reference documentation for details about the SQLError function and its arguments.

See Retrieving Errors and Warnings in Oracle TimesTen In-Memory Database Error Messages and SNMP Traps.

Error and Warning Levels

When operations are not completely successful, TimesTen can return certain types of errors.

Note:

In some cases of an unusual termination, such as process failure, no error is returned, but TimesTen automatically rolls back the transactions of the failed process.

Fatal Errors

Fatal errors are those that make the database inaccessible until after error recovery.

When a fatal error occurs, all database connections are required to disconnect. No further operations may complete. Fatal errors are indicated by TimesTen error codes 846 and 994. Error handling for these errors should be different from standard error handling. In particular, the application error-handling code should roll back the current transaction and disconnect from the database.

Also see Recovery After Fatal Errors.

Non-Fatal Errors

Non-fatal errors include errors such as an INSERT statement that violates unique constraints. This category also includes some classes of application and process failures.

TimesTen returns non-fatal errors through the standard error-handling process. Applications should check for errors and appropriately handle them.

When a database is affected by a non-fatal error, an error may be returned and the application should take appropriate action.

An application can handle non-fatal errors by modifying its actions or, in some cases, rolling back one or more offending transactions.

Warnings

TimesTen returns warnings when something unexpected occurs that you may want to know about.

Here are some events that cause TimesTen to issue a warning:

  • Checkpoint failure

  • Use of a deprecated feature

  • Truncation of some data

  • Execution of a recovery process upon connect

  • Replication return receipt timeout

Application developers should have code that checks for warnings, as they can indicate application problems.

Recovery After Fatal Errors

When fatal errors occur, TimesTen performs a full cleanup and recovery procedure.

  • Every connection to the database is invalidated. To avoid out-of-memory conditions in the server, applications are required to disconnect from the invalidated database. Shared memory from the old TimesTen instance is not freed until all active connections at the time of the error have disconnected. Inactive applications still connected to the old TimesTen instance may have to be manually terminated.

  • The database is recovered from the checkpoint and transaction log files upon the first subsequent initial connection.

  • The recovered database reflects the state of all durably committed transactions and possibly some transactions that were committed non-durably.

  • No uncommitted or rolled back transactions are reflected.

Transient Errors (ODBC)

TimesTen automatically resolves most transient errors (which is particularly important for TimesTen Scaleout), but if your application detects the following SQLSTATE value, it is suggested to retry the current transaction.

  • TT005: Transient transaction failure due to unavailability of resource. Roll back the transaction and try it again.

Note:

In ODBC 3.5, SQLSTATE is returned by the SQLGetDiagRec function or indicated in the SQL_DIAG_SQLSTATE field of the SQLGetDiagField function. In ODBC 2.5, SQLSTATE is returned by the SQLError function. This SQLSTATE may be encountered by any of the following functions. Unless indicated otherwise, these functions apply to either ODBC 2.5 or ODBC 3.5.

  • Catalog functions (such as SQLTables and SQLColumns)

  • SQLCancel

  • SQLCloseCursor (ODBC 3.5)

  • SQLDisconnect

  • SQLExecDirect

  • SQLExecute

  • SQLFetch

  • SQLFetchScroll (ODBC 3.5)

  • SQLFreeStmt (ODBC 2.5)

  • SQLGetData

  • SQLGetInfo

  • SQLPrepare

  • SQLPutData

  • SQLEndTran (ODBC 3.5)

  • SQLTransact (ODBC 2.5)