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 Oracle 8i Parallel Server 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 alias (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
