Release 1.4.0
A53701_01
 Library |
 Product |
 Contents |
 Index |
| Oracle Enterprise Manager Application Developer's Guide Release 1.4.0 A53701_01 |
|
This chapter describes integration with the Event Management system (EMS). Topics include:
There are two levels of integration with the Event Management System. They are:
These can be implemented separately or together, depending on your needs.
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.
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. Registering interest in event name "*" is the only way to register for third-party events.
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 8-5.
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.
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.
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.
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.
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
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:
You can raise unsolicited events with the Oracle Intelligent Agent using:
orareportevent OraTcl verb in Tcl scripts.
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.
This is the four-part name of the event in the form:
/vendor/product/category/name
All four parts and the forward slashes (/) are required.
The first two levels of name have special significance and have many predefined strings that Oracle script writers must use:
The eventname is assumed to be in 7-bit ASCII, so that it never changes regardless of platform or language. See eventdef.tcl in the ORACLE_HOME\net8\admin directory (Enterprise Manager release 1.4.0 on a Windows platform) for a list of defined event names.
The actual event script name may be shortened, upper-cased, or manipulated in other ways to make it a legal, unique filename on a given platform. The format is operating system-specific. For example, /oracle/rdbms/security/SecurityError can be stored as $oracle_home/network/agent/events/oracle/rdbms/security/securityerror.tcl on a Unix system.
This is the database or service name listed in the snmp.visibleservices parameter in the snmp.ora file, or `host'.
For orareportevent, this is 1 (warning), 2 (error), or -1 (clear). For oemevent, this is the literal text string alert, warning, or clear.
This is a quoted text string with the error message.
This is a Tcl list with the specific results for the event. For example. the tablespace in error or the user who had a security violation.
The Event Management system has the following API calls:
These parameters are used in multiple EMS API calls and are described in this section.
Identifies the OLE service that is interested in the event.
The name of the event that the application is interested in. This can be "*", which means all events.
The name of the system on which the event occurs. This can be "*", which means all destinations that have agents
CancelAllEvents removes all event registration entries for the application specified.
VT_BOOL CancelAllEvents(VTS_BSTR ProgID)
| Name | Type | Mode |
|---|---|---|
|
ProgId |
VTS_BSTR |
IN |
None.
CancelEventInterest cancels interest for the specified event.
CancelEventInterest(VTS_BSTR ProgID,
VTS_BSTR EventName,
VTS_BSTR Destination)
| Name | Type | Mode |
|---|---|---|
|
ProgId |
VTS_BSTR |
IN |
|
EventName |
VTS_BSTR |
IN |
|
Destination |
VTS_BSTR |
IN |
This is a one to one match with the RegisterEventInterest function.
For example, the following commands register interest in events:
RegisterEventInterest( "Test.Doc", "event1", "system1" );
RegisterEventInterest( "Test.Doc", "*", "*" );
The following command removes the second entry alone.
CancelEventInterest( "Test.Doc", "*", "*" )
To cancel the first event, the application has to call:
CancelEventInterest( "Test.Doc", "event1", "system1" )
The Communication Daemon calls this function to notify an application when a registered event has been triggered.
VT_VOID EventNotification(VTS_VARIANT Notification)
| Name | Type | Mode |
|---|---|---|
|
Notification |
VTS_VARIANT |
IN |
A VARIANT containing information regarding the event's name, node, object, date, and severity. Use the unpacker functions to access the information
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 is used to flush queued notifications.
VT_BOOL RegisterApplication(VTS_BSTR ProgID)
| Name | Type | Mode |
|---|---|---|
|
ProgId |
VTS_BSTR |
IN |
The name of the OLE service which implements the JobNotification API.
None.
RegisterEventInterest is used to register an application's interest in any events.
VT_BOOL RegisterEventInterest(VTS_BSTR ProgID,
VTS_BSTR EventName,
VTS_BSTR Destination)
| Name | Type | Mode |
|---|---|---|
|
ProgId |
VTS_BSTR |
IN |
|
EventName |
VTS_BSTR |
IN |
|
Destination |
VTS_BSTR |
IN |
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( "Test.Doc", "event1", "system1" );
RegisterEventInterest( "Test.Doc", "*", "*" );
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.
The VoxEventNotifyUnpacker methods are:
GetDate returns the date and time that the event was triggered.
const CString& GetDate();
None.
GetEventName returns the name of the event.
const CString& GetEventName();
None.
GetFinalResult returns the result string from Tcl event script.
const CString& GetFinalResult();
None.
GetNodeName returns the node name where the event occurred.
const CString& GetNodeName();
None.
GetObjectName returns the name of service object.
const CString& GetObjectName();
None.
GetSeverity returns the severity of the event.
int GetSeverity();
The severity of the event is - 1 (clear), 1 (warning), or 2 (alert)
