Oracle Enterprise Manager Application Developer's Guide Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index



Go to previous file in sequence Go to next file in sequence

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




Go to previous file in sequence Go to next file in sequence
Prev Next
Oracle
Copyright © 1997 Oracle Corporation.
All Rights Reserved.
Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index