Oracle Enterprise Manager Application Developer's Guide Release 1.4.0 A53701_01 |
|
This chapter covers the discovery cache interface. It describes:
The discovery cache interface allows your application to retrieve:
An application can retrieve information about the databases, listeners, nodes, and third-party (external) service types that have been discovered by Oracle Enterprise Manager. You can retrieve both the names of these nodes and services and state information.
State information is only maintained in the discovery cache for nodes and services which have Up/Down events registered on them. If an Up/Down event is not registered for a node or service, the state is VOXEXT_SERVICE_UNMONITORED
. A consequence of this is that no externally defined service types can be monitored in this release. If the Up/Down event is registered for a node or service, the status can be either VOXEXT_SERVICE_UP
or VOXEXT_SERVICE_DOWN
.
For an example of how to retrieve a list of nodes or services objects of a certain type, see GetObjectList
of CGetObjListDlg::DoGetObjectList
in the dcobjlst.cpp
file. For an example of how to retrieve state of a node or service object, see GetObjectState
of CGetObjStateDlg::DoGetObjectState
in the dcobjsta.cpp
file.
You can create groups in Console that contains nodes or services objects of the same type. An application can retrieve:
For an example of how to retrieve a list of groups of a certain type, see GetGroupsOfType
of CGetGroupsOfTypeDlg::DoGetGroupsOfType
in the dcgrptyp.cpp
file.
For an example of how to retrieve a list of objects, including subgroups, in a specified group, see GetObjectsInGroup
of CGetObjInGroupDlg::DoGetObjectsInGroup
in the dcobjgrp.cpp
file.
For an example of how to retrieve a list of objects in a group with their states, see GetUniqueServices
of CGetUniqueSrvDlg::DoGetUniqueServices
in the dcunqsrv.cpp
file. The list is flattened and objects only appear once in the list.
For an example of how to retrieve the node name where the service is located, see GetServiceNode
of CGetServiceNodeDlg::DoGetServiceNode
in the dcsrvnod.cpp
file.
Most of the discovery cache APIs, as well as many other APIs of other categories, use a VTS_BSTR
to indicate service types. Service types can be those which are defined by Enterprise Manager itself, sometimes referred to as internally-defined service types, or those which third parties have defined themselves, sometimes referred to as externally-defined or user defined service types. The internally-defined service types used in this release are:
The internal type names specified in the NT registry serve as the type values for externally-defined service types. There is no difference between the way the discovery cache treats internally and externally-defined service types or objects.
In almost all cases where you need to specify a service type as a parameter, you can use either internally or externally-defined types. For more information on externally-defined services, see Chapter 5, "Navigator and Map Integration".
Every time the agent starts, it executes the nmiconf.tcl
script which reads configuration files (oratab
, listener.ora
, and tnsnames.ora
) and writes the services.ora
file to the $ORACLE_HOME\network\admin
directory. This text file contains information about services on the node. This information is used to populate the Navigator tree when retrieved by the Navigator Discovery option.
The nmiconf.tcl
script can execute additional Tcl scripts written specifically to discover other services, such as the Oracle Web Server, on the node. If other scripts are used, they should be installed with nmiconf.tcl
in the $ORACLE_HOME\network\agent\config
directory (Windows platforms), and their names should be listed, one script per line, in the nmiconf.lst
file located in the same directory. If errors occur during discovery, these are written to the $ORACLE_HOME\network\log\nmiconf.log
file.
The Tcl scripts must be generate lines in the services.ora
file of the form:
NewService = (servicetype, host, data)
This entry allows this service to be discovered by the Navigator discovery option. For example, to generate the following entry in the services.ora file:
MyNewService = (MY_SERVICE, MyHost, My new service)
you would create a Tcl script in following format:
set Parameters(MY_SERVICE) {ServiceType HostName Data}; set MyNewService "MyNewService"; set ServiceType($MyNewService) MY_SERVICE; set HostName($MyNewService) "MyHost"; set Data($MyNewService) "'My new service'"; lappend ServiceNames $MyNewService;
After the Navigator Discovery wizard has discovered the MyHost
node, a new folder named MY_SERVICE
is added to the Navigator tree. MyNewService
is located in the MY_SERVICE
folder. See GetObjectData on page 6-7 for information on retrieving this information.
This section describes the external interfaces for the discovery cache system.
These parameters are used with multiple discovery cache external interfaces and the descriptions are provided in this section.
The service type of objects. See Service Types on page 6-3.
The name of the user-defined group from which the services are to be extracted.
Pointer to VARIANT containing retrieved data. Contains a SAFEARRAY. For example:
{
Name1, State1}
Name2, State2}
...
{Namex, Statex}
}
where Namex contains the node, service, or group name and Statex is an integer indicating:
VOXEXT_SERVICE_UP
VOXEXT_SERVICE_DOWN
VOXEXT_SERVICE_UNMONITORED
These states are listed in the voxext.h
file.
GetGroupsOfType
retrieves a list of all the user-defined groups of a specified type.
VT_BOOL GetGroupsOfType(VTS_BSTR Type, VTS_PVARIANT pData)
Name | Type | Mode |
---|---|---|
Type |
VTS_BSTR |
IN |
pData |
VTS_PVARIANT |
OUT |
pData is an array of the form:
{
{GroupName1},
{GroupName2},
...
{GroupNamex}
}
where GroupNamex is the name of the user-defined group.
This function returns TRUE if it succeeds, otherwise it returns FALSE.
GetObjectData
retrieves data about objects in the Navigator tree.
VT_BOOL GetObjectData(VTS_BSTR ServiceName,
VTS_BSTR ServiceType,
VTS_BSTR Location,
VTS_PSTR pServiceData);
Name | Type | Mode |
---|---|---|
ServiceName |
VTS_BSTR |
IN |
ServiceType |
VTS_BSTR |
IN |
Location |
VTS_BSTR |
IN |
pServiceData |
VTS_PBSTR |
OUT |
The name of the third-party discovered service for which you want to get the associated data.
The third-party service type that was used during the agent auto-discovery.
The name of the node on which the service resides.
The data associated with the service. This is an arbitrary string that is a maximum of 1024 bytes.
This function will only work for services that have been discovered from an agent using the agent's third-party discovery integration mechanism. See Discovering Services on page 6-4.
GetObjectList
retrieves a list of objects of a specified type.
VT_BOOL GetObjectList(VTS_BSTR Type,
VTS_BSTR Location,
VTS_BSTR LocationType
VTS_BOOL WithAgent,
VTS_PVARIANT pData)
Name | Type | Mode |
---|---|---|
Type |
VTS_BSTR |
IN |
Location |
VTS_BSTR |
IN |
LocationType |
VTS_BSTR |
IN |
WithAgent |
VTS_BOOL |
IN |
pData |
VTS_PVARIANT |
OUT |
Table 6-2, "Type Parameter Behavior" describes the behavior of GetObjectList
for different values of the parameter Type
.
Name of node or service object that the service is associated with.
Type of service specified in Location field. If LocationType is VOXTYPE_TYPE_NULL
and Location is an empty string, GetObjectList
returns a list of all of the objects of type ServiceType
in the discovery cache. Otherwise, the following situations are defined and no others.
If TRUE, GetObjectList
returns a list of services of the specified type that reside on nodes with agents
pData is an array of the form:
{
{Name1, State1},
{Name2, State2},
...
{Namex, Statex}
}
where Namex contains the node, service, or group name and Statex is an integer indicating:
VOXEXT_SERVICE_UP
VOXEXT_SERVICE_DOWN
VOXEXT_SERVICE_UNMONITORED
This function returns TRUE if it succeeds, otherwise it returns FALSE.
GetObjectsInGroup
retrieves a list of the objects in the specified group.
VT_BOOL GetObjectsInGroup(VTS_BSTR GroupName,
VTS_PVARIANT pData)
Name | Type | Mode |
---|---|---|
GroupName |
VTS_BSTR |
IN |
pData |
VTS_PVARIANT |
OUT |
pData is an array of the form:
{
{Name1, Group_Flag1},
{Name2, Group_Flag2},
...
{Namex, Group_Flagx}
}
where Namex contains the node, service, or group name and Group_Flagx is set to TRUE if Namex is a group name, otherwise FALSE.
A user-defined group may contain other groups. The list returned by GetObjectsInGroup
in pData may contain other group names, which are designated by GROUP_FLAG
set to TRUE.
This function returns a TRUE if it succeeds, otherwise it returns FALSE.
GetObjectState
retrieves the state of a specified node or service.
VT_BOOL GetObjectState(VTS_BSTR Type,
VTS_BSTR Name,
VTS_BOOL Group,
VTS_PI2 pReturnState)
Name | Type | Mode |
---|---|---|
Type |
VTS_BSTR |
IN |
Name |
VTS_BSTR |
IN |
Group |
VTS_BOOL |
IN |
pReturnState |
VTS_PI2 |
OUT |
Determines whether the object is a group or not.
The state of the node, service, or group
VOXEXT_SERVICE_UP
VOXEXT_SERVICE_DOWN
VOXEXT_SERVICE_UNMONITORED
This function returns a TRUE if it succeeds, otherwise it returns FALSE.
GetServiceNode retrieves the node name where the service is located.
VTS_BOOL GetServiceNode(VTS_BSTR ServiceName,
VTS_BSTR ServiceType,
VTS_PBSTR pNodeName);
Name | Type | Mode |
---|---|---|
ServiceName |
VTS_BSTR |
IN |
ServiceType |
VTS_BSTR |
IN |
pNodeName |
VTS_BSTR |
OUT |
Name of service you want to find the node for.
Type of objects to be retrieved. These types are listed in the voxtype.h
file. See Table 6-1, "Service Types".
Retrieves name of node where the service identified by ServiceName
is located.
An example is in the dcsrvnod.cpp
file.
GetUniqueServices
retrieves all services within a group, including those within subgroups, without duplication of services.
VT_BOOL GetUniqueServices(VTS_BSTR GroupName,
VTS_PVARIANT pData)
Name | Type | Mode |
---|---|---|
GroupName |
VTS_BSTR |
IN |
pData |
VTS_PVARIANT |
OUT |
pData is an array of the form:
{
{Name1, State1}
{Name2, State2}
...
{Namex, Statex}
}
where Namex contains the node, service, or group name and Statex is an integer indicating:
VOXEXT_SERVICE_UP
VOXEXT_SERVICE_DOWN
VOXEXT_SERVICE_UNMONITORED
This function returns a TRUE if it succeeds, otherwise it returns FALSE