|Oracle® Objects for OLE Developer's Guide
10g Release 1 (10.1)
Part Number B10118-01
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 just described, 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 Real Application Clusters Quick Start documentation.
To enable failover notifications, the option ORADB_ENLIST_FOR_CALLBACK must be passed into the call to OpenDatabase.
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
' 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
str = Switch(fo_type = 1&, "NONE", fo_type = 2&, "SESSION", fo_type =
If IsNull(str) Then
str = "UNKNOWN!"
If fo_event= OO4O_FO_ERROR Then
MsgBox "Failover error gotten. Retrying "
OnFailover = OO4O_FO_RETRY
If fo_event = OO4O_FO_BEGIN Then
MsgBox " Failing Over .... with failover type : " & str
MsgBox "Failover Called with event : " & fo_event
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