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)