%META:TOPICPARENT{name="ConfigureUDAFeatures"}%
=Oracle Real Application Clustering

%TOC%

==What is Real Application Clustering?==

Oracle Real Application Clustering (RAC) uses  Transparent Application Failover (TAF) which is a protocol within Oracle whereby, if a connection to a database node fails, it can be re-established against an alternative node.

%BR%%BR%<img src="%ATTACHURLPATH%/ora_rac.png" style="wikiautogen"/>%BR%%BR%

Once a broken connection has failed-over, an application can continue without any special action on its part. However, TAF does not restore all facets of a connection. For instance, TAF does not:

* restore active transactions - any active transactions are rolled back at the time of failure because TAF cannot preserve active transactions after failover: the application instead receives an error message until a {{{ROLLBACK}}} is submitted
* restore session properties set using '{{{ALTER SESSION}}}'
* maintain the state of server-side program variables, such as PL/SQL package states

If any of these situations apply to a failed connection, an application may need to take action following failover to return the connection fully to the desired state. In order to do this, the application may request to be notified when failover has occurred. Both the "Lite" Edition and the "Enterprise" Edition Generic Client provide this facility through TAF event notifications.

The "Lite" Edition ODBC Driver and the "Enterprise" Edition Database Agent both enable configuration of the failover retry interval and the maximum number of failover retries, in the event that failover is not successful on the first attempt.

== How to Configure UDA to use Oracle Real Application Clustering ==

===Single-Tier "Lite" Edition on Unix-like OS ===

# Log in to the machine that hosts the Single-Tier (Lite) drivers.
# Use a text editor to open the {{{openlink.ini}}} ({{{$OPENLINKINI}}}) file that resides in the bin sub-directory of the Single-Tier installation.
# Locate the {{{[Environment Oracle 10.x]}}} section.
# Create and set the following two variables:
{{{
OPL_TAF_MAX_RETRIES    = 10    ; This is the maximum number of times that the driver will retry the connection.
OPL_TAF_RETRY_INTERVAL = 5     ; This is the number of seconds that the driver will wait between connection attempts.
}}}
# Save your changes and exit the file.


===Single-Tier "Lite" Edition on Windows ===


# Log in to the machine that hosts the Single-Tier "Lite" Edition drivers.
# Launch your ODBC Data Sources Administrator.
# Locate the relevant DSN.
# Click the Configure button.
# Scroll through the configuration screens until you find the "Enable TAF" checkbox.
# Check the TAF checkbox to prompt the driver to attempt multiple failover connections to alternative DBMS nodes. 
# Configure the rest of the fields related to TAF:
#* **Maximum Retries** - This is the maximum number of times that the driver will retry the connection.
#* **Retry Interval (secs)** - This is the number of seconds that the driver will wait between connection attempts.


=== Multi-Tier "Enterprise" Edition on any OS ===

# Log in to the machine that hosts the Multi-Tier server components installation.
# Use a text editor to open the {{{oplrqb.ini}}} file that resides in the bin sub-directory of the Multi-Tier installation.
# Locate the {{{[Environment ORACLE10]}}} section.
# Create and set the following two variables:
{{{
OPL_TAF_MAX_RETRIES    = 10    ; This is the maximum number of times that the driver will retry the connection.
OPL_TAF_RETRY_INTERVAL = 5     ; This is the number of seconds that the driver will wait between connection attempts.
}}}
# Save your changes and exit the file.
# Restart the Request Broker.


== Programmatic Considerations ==

Our ODBC drivers notify ODBC applications that failover has occurred using two mechanisms: event call-backs and SQLSTATEs.

=== TAF Event Notification: Call-backs ===

An application can register a failover call-back routine by setting the proprietary connection attribute {{{SQL_ATTR_EVENT_CALL-BACK (1280)}}} on an open connection. The routine's address is supplied as the value of {{{SQLSetConnectAttr}}}'s {{{ValuePtr}}} argument. The same call-back routine can be registered for more than one connection. The call-back routine's signature must take the form:
{{{
void (*call-back) (oplevent_t   oplEvent, 
                   SQLHANDLE    handle, 
                   SQLUSMALLINT eventInfo) 
}}}

where:

* **{{{oplEvent}}}** is an integer indicating the type of event which took place.
* **{{{context}}}** is an application-supplied ODBC handle identifying the context the event is taking place in.
* **{{{eventInfo}}}** is an unsigned integer code providing more information about the event. The values returned depend on the type of event. **{{{0}}}** signifies 'no further information available'

**{{{oplEvent}}}** is of type {{{oplevent_t}}}, an enumerated type enumerating the types of events reported to event call-backs. {{{oplevent_t}}} is defined as follows:
{{{
typedef enum 
  {
    OPL_EV_NONE             = 0, 
    OPL_EV_FAILOVER_SUCCESS = 16, 
    OPL_EV_FAILOVER_ABORT   = 17 
  }
  oplevent_t; 
}}}

At the moment, only failover events are supported through the {{{OPL_EV_FAILOVER_xxx}}} event class. Other types of event may be supported in the future using this call-back mechanism. {{{OPL_EV_FAILOVER_SUCCESS}}} indicates that failover was successful, {{{OPL_EV_FAILOVER_ABORT}}} that failover was aborted.

**{{{context}}}** is the ODBC handle ({{{HDBC}}}) of the connection for which the application wishes to receive event notifications. This handle should be supplied to the ODBC driver when the call-back is registered, using another Oracle-specific connection attribute, {{{SQL_ATTR_EVENT_CONTEXT (1281)}}}. If this attribute is not set, the call-back receives {{{SQL_NULL_HANDLE}}} for the handle argument. (If other event types are supported in the future, this attribute may accept other types of ODBC handle, e.g., handles of type {{{SQL_HANDLE_STMT}}}, depending on the scope of the event.)

**{{{eventInfo}}}** is reserved for future use. All failover events currently return {{{0}}}.

=== TAF Event Notification: SQLSTATEs ===

In addition to being informed of failover through a call-back routine, an ODBC application also receives notification through {{{SQLSTATE}}}s. After failover completes, the first ODBC call to return on the affected connection can return one of two proprietary {{{SQLSTATE}}}s, {{{IM500}}} or {{{IM501}}}:

* **{{{IM500}}}** denotes successful failover completion. If the ODBC call generated no other errors, the call returns {{{SQL_SUCCESS_WITH_INFO}}} with {{{SQLSTATE IM500}}} and is accompanied by the informational message "{{{Failover completed}}}". As usual, the SQLSTATE and diagnostic message can be retrieved using {{{SQLGetDiagRec()}}}.

* **{{{IM501}}}** ("{{{Failover aborted}}}") indicates failover was unsuccessful. A function returning this SQLSTATE returns with return code {{{SQL_ERROR}}}.

If the ODBC call returning the failover SQLSTATE fails for some reason, a diagnostic record holding the failover SQLSTATE and message is appended to any diagnostic records already generated by the failing call. In this case, even if failover was successful, a {{{SQLSTATE IM500}}} may be accompanied by a function return code of {{{SQL_ERROR}}}. For instance, if a transaction was open at the time failover took place, {{{SQLExecute()}}} may return {{{SQL_ERROR}}} with two diagnostic records, for example:

* <nop>DiagRec #1 ? 
{{{
Native error: 25402 
SQLSTATE: HY000 
Message: [<nop>OpenLink][ODBC][Oracle Server]ORA-25402: transaction must roll back
}}}
* <nop>DiagRec #2 ? 
{{{
Native error: 0 
SQLSTATE: IM500 
Message: [<nop>OpenLink][ODBC][Oracle Server]Failover completed.
}}}


//**Note:** Failover notification using TAF-specific SQLSTATEs cannot be used independently of failover call-backs. The use of these SQLSTATEs is only triggered when an application registers a failover call-back.//


== Related Links ==

* [[http://www.oracle.com/index.html|Oracle]]
* [[http://www.oracle.com/technology/products/ias/hi_av/904ha.pdf|TAF in Oracle 10g]]
* [[http://www.oracle.com/technology/tech/oci/htdocs/oci_faq.html|OCI FAQs (including TAF)]]