Oracle Enterprise Manager Application Developer's Guide 
Release 1.6 
A63733-01
 
Library
 
Product
 
Contents
 
Index
 

Prev Next

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:

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:

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.

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



 
Prev
 
Next
 
Oracle 
Copyright © 1998 Oracle Corporation. 
All Rights Reserved. 
 
Library
 
Product
 
Contents
 
Index