6
Discovery Cache Integration

This chapter covers the discovery cache interface. It describes:

Retrieving Nodes and Services

The discovery cache interface allows your application to retrieve:

The nodes and services available to the Console.
The state of nodes and services.

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.

Retrieving User-Defined Groups

You can create groups in Console that contains nodes or services objects of the same type. An application can retrieve:

Groups of a specified type
Objects in a specified group, including subgroups
Objects in a specified group, excluding subgroups, and their respective states
Node name where the service is located.

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.

Service Types

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:

Table 6-1 Service Types


Type Value (from voxtype.h)	Service
VOXEXT_TYPE_AGENT	Oracle Intelligent Agent
VOXTYPE_TYPE_DATABASE	Oracle Database
VOXTYPE_TYPE_LISTENER	Oracle SQL*Net Listener
VOXTYPE_TYPE_NAMESERVER	Oracle Names Server
VOXTYPE_TYPE_NODE	Host machine
VOXTYPE_TYPE_OPS	Oracle Parallel Server
VOXEXT_TYPE_RDBDATABASE	Oracle Rdb Database
VOXEXT_TYPE_TRACE	Oracle Trace

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".

Discovering Services

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.

Discovery Cache API Reference

This section describes the external interfaces for the discovery cache system.

GetGroupsOfType
GetObjectData
GetObjectList
GetObjectsInGroup
GetObjectState
GetServiceNode
GetUniqueServices

Common Parameters

These parameters are used with multiple discovery cache external interfaces and the descriptions are provided in this section.

Type

The service type of objects. See Service Types on page 6-3.

GroupName

The name of the user-defined group from which the services are to be extracted.

pData

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

Note:

These states are listed in the voxext.h file.

GetGroupsOfType

Purpose

GetGroupsOfType retrieves a list of all the user-defined groups of a specified type.

Syntax

VT_BOOL GetGroupsOfType(VTS_BSTR Type, VTS_PVARIANT pData)

Parameters


Name	Type	Mode
Type	VTS_BSTR	IN
pData	VTS_PVARIANT	OUT

See Common Parameters on page 6-5.

pData

pData is an array of the form:

{

{GroupName1},

{GroupName2},

...

{GroupNamex}

}

where GroupNamex is the name of the user-defined group.

Comments

This function returns TRUE if it succeeds, otherwise it returns FALSE.

GetObjectData

Purpose

GetObjectData retrieves data about objects in the Navigator tree.

Syntax

VT_BOOL GetObjectData(VTS_BSTR ServiceName,

               VTS_BSTR ServiceType,

               VTS_BSTR Location,

               VTS_PSTR pServiceData);

Parameters


Name	Type	Mode
ServiceName	VTS_BSTR	IN
ServiceType	VTS_BSTR	IN
Location	VTS_BSTR	IN
pServiceData	VTS_PBSTR	OUT

See Common Parameters on page 6-5.

ServiceName

The name of the third-party discovered service for which you want to get the associated data.

ServiceType

The third-party service type that was used during the agent auto-discovery.

Location

The name of the node on which the service resides.

pServiceData

The data associated with the service. This is an arbitrary string that is a maximum of 1024 bytes.

Comments

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

Purpose

GetObjectList retrieves a list of objects of a specified type.

Syntax

VT_BOOL GetObjectList(VTS_BSTR Type,

               VTS_BSTR Location,

                VTS_BSTR LocationType

                VTS_BOOL WithAgent, 

                VTS_PVARIANT pData)

Parameters


Name	Type	Mode
Type	VTS_BSTR	IN
Location	VTS_BSTR	IN
LocationType	VTS_BSTR	IN
WithAgent	VTS_BOOL	IN
pData	VTS_PVARIANT	OUT

See Common Parameters on page 6-5.

Type

Table 6-2, "Type Parameter Behavior" describes the behavior of GetObjectList for different values of the parameter Type.

Table 6-2 Type Parameter Behavior


Value of Type	Behavior
LISTENER	Retrieves a list of all listeners on the node specified by Location. If Location is NULL returns a list of all listeners.
NAMESERVER	Retrieves a list of all name servers on the node specified by Location. If Location is NULL returns a list of all name servers.
DATABASE	Retrieves a list of all Oracle databases on the node specified by Location. If Location is NULL, returns a list of all Oracle databases.
NODE	Retrieves a list of all known nodes. Location is ignored.
Externally-defined types	Retrieves a list of externally-defined types. Location is ignored.

Location

Name of node or service object that the service is associated with.

LocationType

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.

Table 6-3 Location Types


ServiceType	LocationType	Meaning
VOXTYPE_TYPE_DATABASE	VOXTYPE_TYPE_LISTENER	Returns a list of databases associated with listener with name Location
VOXTYPE_TYPE_DATABASE	VOXTYPE_TYPE_OPS	Returns a list of database instances associated with the Parallel Server with name Location
Any (including external types)	VOXTYPE_TYPE_NODE	Returns a list of services of type ServiceType associated with node with name Location

WithAgent

If TRUE, GetObjectList returns a list of services of the specified type that reside on nodes with agents

pData

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

Comments

This function returns TRUE if it succeeds, otherwise it returns FALSE.

GetObjectsInGroup

Purpose

GetObjectsInGroup retrieves a list of the objects in the specified group.

Syntax

VT_BOOL GetObjectsInGroup(VTS_BSTR GroupName, 

                VTS_PVARIANT pData)

Parameters


Name	Type	Mode
GroupName	VTS_BSTR	IN
pData	VTS_PVARIANT	OUT

See Common Parameters on page 6-5.

pData

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.

Comments

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

Purpose

GetObjectState retrieves the state of a specified node or service.

Syntax

VT_BOOL GetObjectState(VTS_BSTR Type,

                VTS_BSTR Name,

                VTS_BOOL Group,

                VTS_PI2 pReturnState)

Parameters


Name	Type	Mode
Type	VTS_BSTR	IN
Name	VTS_BSTR	IN
Group	VTS_BOOL	IN
pReturnState	VTS_PI2	OUT

See Common Parameters on page 6-5.

Group

Determines whether the object is a group or not.

pReturnState

The state of the node, service, or group

VOXEXT_SERVICE_UP

VOXEXT_SERVICE_DOWN

VOXEXT_SERVICE_UNMONITORED

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE.

GetServiceNode

Purpose

GetServiceNode retrieves the node name where the service is located.

Syntax

VTS_BOOL GetServiceNode(VTS_BSTR ServiceName, 

                VTS_BSTR ServiceType, 

                VTS_PBSTR pNodeName);

Parameters


Name	Type	Mode
ServiceName	VTS_BSTR	IN
ServiceType	VTS_BSTR	IN
pNodeName	VTS_BSTR	OUT

ServiceName

Name of service you want to find the node for.

ServiceType

Type of objects to be retrieved. These types are listed in the voxtype.h file. See Table 6-1, "Service Types".

pNodeName

Retrieves name of node where the service identified by ServiceName is located.

Comments

An example is in the dcsrvnod.cpp file.

GetUniqueServices

Purpose

GetUniqueServices retrieves all services within a group, including those within subgroups, without duplication of services.

Syntax

VT_BOOL GetUniqueServices(VTS_BSTR GroupName, 

                VTS_PVARIANT pData)

Parameters


Name	Type	Mode
GroupName	VTS_BSTR	IN
pData	VTS_PVARIANT	OUT

See Common Parameters on page 6-5.

pData

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

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE

6 Discovery Cache Integration

Retrieving Nodes and Services

Retrieving User-Defined Groups

Service Types

Table 6-1 Service Types

Discovering Services

Discovery Cache API Reference

Common Parameters

Note:

GetGroupsOfType

Purpose

Syntax

Parameters

Comments

GetObjectData

Purpose

Syntax

Parameters

Comments

GetObjectList

Purpose

Syntax

Parameters

Table 6-2 Type Parameter Behavior

Table 6-3 Location Types

Comments

GetObjectsInGroup

Purpose

Syntax

Parameters

Comments

GetObjectState

Purpose

Syntax

Parameters

Comments

GetServiceNode

Purpose

Syntax

Parameters

Comments

GetUniqueServices

Purpose

Syntax

Parameters

Comments

6
Discovery Cache Integration