High Availability Guide : Using HotStandby with applications : Transparent Connectivity : Failure transparency in Transparent Connectivity
  
Failure transparency in Transparent Connectivity
Failure transparency handles the masking of failures. The failure transparency level is set with the TF_LEVEL attribute.
Three failure transparency levels are available:
TF_LEVEL=NONE
Failure transparency is disabled (default).
TF_LEVEL=CONNECTION
The server connection is preserved, that is, it is unnecessary to reconnect in the case of failover or switchover.
TF_LEVEL=SESSION
Most non‑default session level settings are preserved. Additionally, prepared statements are preserved. However, open cursors are closed, and ongoing transactions are aborted.
Principles of connection switch handling
A connection switch refers to a situation where the driver changes the active server connection. Generally, the reason for a connection switch is a failover to the Secondary server or a switchover between the servers.
More specifically, a need for a connection switch is detected from one of the following events:
Event from the Secondary server about the state change to PRIMARY ALONE (failover) or PRIMARY ACTIVE (switchover). This is the main (and the fastest) mode of performing the connection switch.
Indication of the state change at Primary.
Link failure on the active connection.
Connection timeout on the active connection.
The driver executes the connection switch in two steps:
1 The need for the connection switch is detected. The driver returns the following connection switch error on a pending request, or the following request:
SQLSTATE
Native code
Message text and description
HY000
25216
Connection switch, some session context may be lost.
Description: The driver has discovered the need of the connection switch. The client is expected to issue a transaction rollback call to finalize the connection switch. This error code and message will be received at each consecutive network request call until the rollback call is issued
2 The Client program issues a rollback command (ODBC: SQLEndTran() with SQL_ROLLBACK; JDBC: Connection.rollback()). If the rollback is successful, a new active connection has been mapped to the TC connection that may be used.
Note The connection switch error may be returned on a few consecutive ODBC calls. Therefore, a provision must be made to always respond with a rollback to this error, on any ODBC network request. If this happens in the middle of a transaction, the transaction must be re-executed.
On the other hand, if a new active connection cannot be established, the following error code is returned:
SQLSTATE
Native code
Message text and description
08S01
14503
Communication link failure
Description: The driver has failed to establish a new active connection. The TF connection is lost and the Client has to reconnect (using a Data Source Info) in order to continue.
After receiving the rollback call, the driver will use a few alternative ways of finding the new active connection. In the simplest case, it will use the standby connection for the purpose. If that connection is not in the right state, the driver will wait for two seconds for the proper event to arrive. If the event does not arrive, and in other cases, the driver will fall back to the address list in the TC connect info and will repeat the connect sequence iteratively for a maximum time of 10 seconds. If all the efforts fail, the driver returns the above error.
The effect of the error is that the connection is lost, as seen by the application. Any further request issued on that connection will result in the same error.
Preservation of session state
When the connection switch is executed by the driver, some of the session context can be lost and the application must reconstruct it. The amount of the preserved state is dictated by the Transparent Failover level, expressed with the TC Info attribute TF_LEVEL.
With the TF level CONNECTION, no state is preserved. With the SESSION level, most of the session state is preserved. The preservation of the session state is implemented by caching the necessary data in the driver. The higher transparency level is achieved at the expense of the response time of the requests requiring caching, as well as increased memory usage in the driver.
Regardless of the TF level, the following applies in the case of failovers:
The updates of the current transactions are lost (because of the transaction rollback).
Open cursors and their positions are lost.
TF_LEVEL
Preserved state
CONNECTION
No session state is preserved.
SESSION
Prepared statements
The prepared states are preserved.
The effects of the following statements are preserved:
SET CATALOG
SET SQL INFO
SET SQL SORTARRAYSIZE
SET SQL CONVERTORSTOUNIONS
SET SQL JOINPATHSPAN
SET LOCK TIMEOUT <seconds>
SET IDLE TIMEOUT
SET OPTIMISTIC LOCK TIMEOUT
SET STATEMENT MAXTIME
SET ISOLATION LEVEL
SET DURABILITY
SET SAFENESS
SET SCHEMA
SET SYNC USER
SET SYNC MODE
The following standard ODBC attributes are preserved
SQL_ATTR_ACCESS_MODE
(SET READ ONLY, SET READ WRITE)
SQL_ATTR_CURRENT_CATALOG
(duplicates SET CATALOG above)
SQL_ATTR_AUTOCOMMIT
See also
Transparent Connectivity