8
Event Management Integration

This chapter describes integration with the Event Management system (EMS). Topics include:

• Levels of Integration
• Client-Side Integration
• Server-Side Integration
• Event Management System APIs
• VoxEventNotifyUnpacker

Levels of Integration

There are two levels of integration with the Event Management System. They are:

• Application support for event registration and notification.
• Agent interfaces for generation of events by third-party services.

These can be implemented separately or together, depending on your needs.

Client-Side Integration

An application must register interest in an event by calling the RegisterEventInterest API. You must register an event set with the Console Event Management system before calling RegisterEventInterest.

For the Console to monitor third-party events, you need to create an event set with the Event Management system. When you create the event set, check the "Accept Third-Party Events" box in the Event Set General page. You do not need to enter any information in the Events or Parameters pages. After the event set is created, register it on all destinations where an application registers interest. This registration will monitor all third-party events on the specified destination.

Uniqueness of Registration

All event registrations have to be unique, and EMS will return an error if an application tries to register the same event at the same node more than once. The uniqueness is defined by the application, event name, and the system name. However, the string "*" is an exception and can be used as a wildcard event name or destination.

An application may register "*", and "/user/rdbms/fault/event1" at node "smpsun14". EMS handles these as two registrations. If the application tries to register the "*" or the "/user/rdbms/fault/event1" event again at node "smpsun14", EMS raises an error. However, the application can register the same event at other systems. For information on the format of event names, see eventname on page 9-28.

For a particular event, an application will be notified only once. For example, in Table 8-1, "A Sample Event Registration Database", if "/user/rdbms/fault/event1" fires at "smpsun14", the application will be notified only once.

Table 8-1 A Sample Event Registration Database

Application	Event Name	System Name
DbApp	/user/rdbms/fault/event1	smpsun14
DbApp	/user/rdbms/fault/event2	smpsun14
DbApp	*	*
DbApp	*	smpsun14
DbApp	/user/rdbms/fault/event1	*
DbApp	*	smpsun15

 

Notification

In order for an application to be notified of an event you must expose the function EventNotification. This function is called whenever an event you have registered interest in is triggered. The VoxEventNotifyUnpacker class in the vox.dll is provided to unpack the parameters from the variant returned by EventNotification.

If an application is not active when the event is triggered, the Event Management System queues the event notifications. Also, the OLE object service must be declared the active object. When the application next comes up and calls RegisterApplication for the user who owns the event, all the queued events are forwarded.

Who Is Notified

Just as in job notifications (see Who Is Notified on page 7-5), events are referenced by ProgID and current Console user. This means that a user gets only notifications for the events that the user submits. Your server application does not need to pass the username because the Console already knows it.

Discovery Cache Event Management

The Event Management System sets up the discovery cache event-level based on the internally-defined event name that is returned by the intelligent agent. For example, if the event returned is /user/rdbms/fault/event1, then the Event Management System tries to locate the object name as a database, and updates the discovery cache, resulting in the map displaying the appropriate color.

Event Interest

There is one API to register interest in events: RegisterEventInterest. There are two API calls that allow you to cancel interest in events: CancelEventInterest and CancelAllEvents

Server-Side Integration

An unsolicited event is an event that is not discovered by the agent running a Tcl script itself, which is the normal way for events to get triggered. There are a number of reasons why this might occur, such as:

• A third-party, such as the operating system vendor or a systems management vendor, might discover the condition and want to have it appear on the Enterprise Manager Console. A key feature of Enterprise Manager is that it is open to third parties.
• An OEM job might discover the condition. An example of this is the Software Management component of Enterprise Manager, where a job is going to install a new package on the host, and then wants to report the event "new package discovered", rather than relying on the job reporting mechanisms. This provides uniform handling of the condition when there is a new package on this host.

You can raise unsolicited events with the Oracle Intelligent Agent using:

• The orareportevent OraTcl verb in Tcl scripts.
• The oemevent executable located in oracle_home\bin on a Unix platform or oracle_home\agentbin on a Windows NT machine.

The syntax for orareportevent and oemevent is:

orareportevent eventname object severity message [results]

oemevent eventname object severity message [results]

The parameters are the same for both except for severity. See orareportevent on page 9-28.

Event Management System APIs

The Event Management system has the following API calls:

• CancelAllEvents
• CancelEventInterest
• EventNotification
• RegisterApplication
• RegisterEventInterest

Common Parameters

These parameters are used in multiple EMS API calls and are described in this section.

ProgID

Identifies the OLE service that is interested in the event.

EventName

The name of the event that the application is interested in. This can be "*", which means all events.

Destination

The name of the system on which the event occurs. This can be "*", which means all destinations that have agents

CancelAllEvents

Purpose

CancelAllEvents removes all event registration entries for the application specified.

Syntax

VT_BOOL CancelAllEvents(VTS_BSTR ProgID)

Parameters

Name	Type	Mode
ProgId	VTS_BSTR	IN

  See Common Parameters on page 8-5. 

Comments

None.

CancelEventInterest

Purpose

CancelEventInterest cancels interest for the specified event.

Syntax

CancelEventInterest(VTS_BSTR ProgID,

                VTS_BSTR EventName,

                VTS_BSTR Destination)

Parameters

Name	Type	Mode
ProgId	VTS_BSTR	IN
EventName	VTS_BSTR	IN
Destination	VTS_BSTR	IN

  See Common Parameters on page 8-5. 

Comments

This is a one to one match with the RegisterEventInterest function.

Examples

For example, the following commands register interest in events:

RegisterEventInterest("Smpsrv.Document","/user/rdbms/fault/event1","system1");

RegisterEventInterest("Smpsrv.Document","*","*");

The following command removes the second entry alone.

CancelEventInterest("Smpsrv.Document","*","*")

To cancel the first event, the application has to call:

CancelEventInterest("Smpsrv.Document","/user/rdbms/fault/event1","system1")

EventNotification

Purpose

The Communication Daemon calls this function to notify an application when a registered event has been triggered.

Syntax

VT_VOID EventNotification(VTS_VARIANT Notification)

Parameters

Name	Type	Mode
Notification	VTS_VARIANT	IN

   

Notification

A VARIANT containing information regarding the event's name, node, object, date, and severity. Use the unpacker functions to access the information

Comments

Oracle provides a variant unpacker class, VoxEventNotifyUnpacker, to ease the unpacking of the parameters from the variant. This is present in the vox.dll.

RegisterApplication

Purpose

RegisterApplication is used to flush queued notifications.

Syntax

VT_BOOL RegisterApplication(VTS_BSTR ProgID)

Parameters

Name	Type	Mode
ProgId	VTS_BSTR	IN

   

ProgID

The name of the OLE service which implements the JobNotification API.

Comments

None.

RegisterEventInterest

Purpose

RegisterEventInterest is used to register an application's interest in any events.

Syntax

VT_BOOL RegisterEventInterest(VTS_BSTR ProgID,

                VTS_BSTR EventName,

                VTS_BSTR Destination)

Parameters

Name	Type	Mode
ProgId	VTS_BSTR	IN
EventName	VTS_BSTR	IN
Destination	VTS_BSTR	IN

  See Common Parameters on page 8-5. 

Comments

If an application wants to register an interest in multiple events, it has to call this API multiple times with different event names. You can use "*" to register interest in all events. For example, the following commands register interest in events:

RegisterEventInterest("Smpsrv.Document","/user/rdbms/fault/event1","system1");

RegisterEventInterest("Smpsrv.Document", "*", "*");

This service must implement the EventNotification API to receive notices of triggered events. You must register an event set with the Console Event Management system before calling RegisterEventInterest. For information on events available with Enterprise Manager, see the "Event Management System" chapter of the Oracle Enterprise Manager Administrator's Guide.

RegisterEventInterest does not return errors when errors occur.

VoxEventNotifyUnpacker

The VoxEventNotifyUnpacker methods are:

• GetDate
• GetEventName
• GetFinalResult
• GetNodeName
• GetObjectName
• GetSeverity

GetDate

Purpose

GetDate returns the date and time that the event was triggered.

Syntax

const CString& GetDate();

Comments

None.

GetEventName

Purpose

GetEventName returns the name of the event.

Syntax

const CString& GetEventName();

Comments

None.

GetFinalResult

Purpose

GetFinalResult returns the result string from Tcl event script.

Syntax

const CString& GetFinalResult();

Comments

None.

GetNodeName

Purpose

GetNodeName returns the node name where the event occurred.

Syntax

const CString& GetNodeName();

Comments

None.

GetObjectName

Purpose

GetObjectName returns the name of service object.

Syntax

const CString& GetObjectName();

Comments

None.

GetSeverity

Purpose

GetSeverity returns the severity of the event.

Syntax

int GetSeverity();

Comments

The severity of the event is - 1 (clear), 1 (warning), or 2 (alert)

---