Add (OraSubscriptions Collection) Method

Applies To

Description

Adds a subscription to the OraSubscriptions collection.

Usage

orasubscriptions.Add Name, DbeventsHdl, Ctx

Arguments

The arguments for the method are:

Variants Description

Variants	Description
[`in`] `Name`	The database event of interest. The appropriate event trigger and AQ queue must be set up prior to this. `Name` refers to the subscription name in the form of the string `'SCHEMA.QUEUE'` if the registration is for a single consumer queue and `'SCHEMA.QUEUE:CONSUMER_NAME'` if the registration is for a multiple consumer queue. The `Name` string should be in uppercase.
[`in`] `DbeventsHdl`	The database event handler. An `IDispatch` interface implementing the `NotifyDBEvents` method, which is invoked when the database event of interest is fired.
[`in`] `Ctx`	Context-specific information that the application wants passed to the `NotifyDbEvents` method when it is invoked.

[in] Name

The database event of interest. The appropriate event trigger and AQ queue must be set up prior to this.

Name refers to the subscription name in the form of the string 'SCHEMA.QUEUE' if the registration is for a single consumer queue and 'SCHEMA.QUEUE:CONSUMER_NAME' if the registration is for a multiple consumer queue.

The Name string should be in uppercase.

[in] DbeventsHdl The database event handler. An IDispatch interface implementing the NotifyDBEvents method, which is invoked when the database event of interest is fired.

[in] Ctx Context-specific information that the application wants passed to the NotifyDbEvents method when it is invoked.

Remarks

To register for subscription of a database event, the name identifying the subscription of interest and the name of the dbevent handler that handles the event must be passed in when the Add method is called. The queues and event triggers necessary to support the database event must be set up before the subscriptions can be fired.

The dbevent handler should be an automation object that implements the NotifyDBEvents method.

NotifyDBEvents Handler

The NotifyDBEvents method is invoked by Oracle Objects for OLE when database events of interest are fired.

For more detailed information about setting up the queues and triggers for Oracle Database events, see to Triggers on System Events and User Events in Oracle Database Concepts.

The syntax of the method is:

Public Function NotifyDBEvents(ByVal Ctx As Variant, ByVal Payload As Variant

Variants

The variants for the method are:

Variants	Description
`[in]` `Ctx`	Passed into the `OraSubscriptions.Add` method by the application. Context-sensitive information that the application wants passed on to the `dbevent` handler.
[in] `Payload`	The payload for this notification. Database events are fired by setting up event trigger and queues. `Payload` here refers to the payload, if any, that was enqueued in the queue when the event triggered.

Examples

Example: Registering an Application for Notification of Database Events

In the following example, an application subscribes for notification of database logon events (such as all logons to the database). When a user logs on to the database, the NotifyDBEvents method of the DBEventsHdlr that was passed in at the time of subscription is invoked. The context-sensitive information and the event-specific information are passed into the NotifyDBEvents method.

The DBEventsHdlr in this example is DBEventCls, which is defined later.

The main application:

' First instantiate the dbevent handler. The dbevent notification
' will fire the NotifyDBEvents on the callback handler.
 
Public DBEventsHdlr As New DBEventCls
Private Sub Form_Load()
    Dim gOraSession As Object
    Dim gOraSubscriptions As OraSubscriptions 
    Dim gOraDatabase As OraDatabase
 
    'Create the OraSession Object
    Set gOraSession = CreateObject("OracleInProcServer.XOraSession")
 
   'Create the OraDatabase Object by opening a connection to Oracle.
    Set gOraDatabase = gOraSession.DbOpenDatabase                      
             ("ora90.us.oracle.com", "pubsub/pubsub", 
              ORADB_ENLIST_FOR_CALLBACK)
    Set gOraSubscriptions = gOraDatabase.Subscriptions
    gOraSubscriptions.Add "PUBSUB.LOGON:ADMIN", DBEventsHdlr,
             gOraDatabase
    gOraSubscriptions(0).Register
    MsgBox "OK"
End Sub

The database event handler class that defines the NotifyDBEvents method.

Public countofMsgs as integer
Public Function NotifyDBEvents(Ctx As Variant, Payload As Variant )
    On error goto NotifyMeErr
 
    MsgBox "Retrieved payload " + Payload
   ' do something - here the subscription is unregistered after
   ' receiving 3 notifications
    countofMsgs = countofMsgs + 1
    If countofMsgs > 3 Then
        Ctx.Subscriptions(0).UnRegister
    End If
    Exit Sub
NotifyMeErr:
    Call RaiseError(MyUnhandledError, "newcallback:NotifyMe Method")
 
End Sub