Application Failover Notifications

Application failover notifications can be used in the event of the failure of one database instance and failover to another instance. Because of the delay which can occur during failover, the application developer may want to inform the user that failover is in progress, and request that the user stand by. Additionally, the session on the initial instance may have received some ALTER SESSION commands. These will not be automatically replayed on the second instance. Consequently, the developer may wish to replay these ALTER SESSION commands on the second instance.

Failover Notification Registration

To address the problems described above, OO4O supports Application Failover Notifications. To receive Failover notifications, a notification handler must be registered with the MonitorForFailover method of the OraDatabase. The notification handler must be an automation object (Class module in VB) that implements the OnFailover method. An IDispatch pointer to this automation object must be passed in, along with any client-specific context at the time of registering for Failover notifications.

An example of failover registration is included as part of the example in the next section.

In the event of failover, the OnFailover method is invoked several times during the course of reestablishing the user's session.

The first call to the OnFailover method of the notification handler occurs when Oracle first detects an instance connection loss. This is intended to allow the application to inform the user of an upcoming delay. If failover is successful, a second call to the OnFailover method occurs when the connection is reestablished and usable. At this time the client may wish to replay ALTER SESSION commands and inform the user that failover has happened. If failover is unsuccessful, then the OnFailover method is called to inform the application that failover will not take place. For more detailed information about application failover, refer to the Oracle9i Real Application Clusters Concepts documentation.

Enabling Failover

To enable failover notifications, the option ORADB_ENLIST_FOR_CALLBACK must be passed into the call to OpenDatabase.

Example: Failover Notification Example

The following sample shows a typical developer-defined OnFailover implementation and demonstrates how to register an application.

A typical OnFailover method

' Implement the OnFailover method of the FailoverClient

' class module and the necessary arguments that will contain the

' dequeued message. Ctx here is the application-defined

' context sensitive object that was passed in while registering with

' MonitorForFailover.

' An error of OO4O_FO_ERROR indicates that failover was unsuccessful,

' but the application can handle the and retry failover by returning

' a value of OO4O_FO_RETRY

Public Function OnFailover(Ctx As Variant, fo_type As

Variant,fo_event as variant, fo_OraDB as Variant)

Dim str As String

OnFailover=0

str = Switch(fo_type = 1&, "NONE", fo_type = 2&, "SESSION", fo_type =

4&, "SELECT")

If IsNull(str) Then

str = "UNKNOWN!"
End If

If fo_event= OO4O_FO_ERROR Then

MsgBox "Failover error gotten. Retrying "

OnFailover = OO4O_FO_RETRY

End If
If fo_event = OO4O_FO_BEGIN Then

MsgBox " Failing Over .... with failover type : " & str

Else

MsgBox "Failover Called with event : " & fo_event
End If

End Function

Registering the application to receive failover notifications

' First instantiate the Failover_Client. The Failover notification

' will invoke the OnFailover on this class module

Public Failover_Client As New FailoverClient

Dim OraDatabase As OraDatabase

Dim OraSession As OraSession

Set OraSession = CreateObject("OracleInProcServer.XOraSession")

' Pass in the entire database name (ie., the entire Tnsnames entry

' with the domain name)in the opendatabase call

Set OraDatabase = OraSession.DbOpenDatabase("Exampledb.us.

oracle.com", "scott/tiger", ORADB_ENLIST_FOR_CALLBACK)

OraDatabase.MonitorForFailover Failover_Client, OraDatabase