Topology API

Solstice Enterprise Manager 4.1 C++ API Reference

Chapter 8

Topology API

The Topology API is designed for use by Solstice Enterprise Manager (Solstice EM) application developers. This interface hides the topology implementation from application developers, allows applications to be more easily ported, and allows for faster development of topology-based applications.

This chapter comprises the following topics:

Section 8.1 Topology Classes
Section 8.2 Class Overview
Section 8.4 Persistent Object Classes
Section 8.5 Utility Classes
Section 8.6 Topology API Concepts
Section 8.7 Examples
Section 8.8 Class Reference

Note – Some understanding of GDMO/ASN.1 and network management principles is required to effectively use the Topology API. For example, it is necessary to understand object identifiers (OID) and distinguished names (DN) and how these relate to the object registration tree and management information tree (MIT). In addition, a high-level understanding of the Solstice EM architecture and topology model is necessary.

8.1 Topology Classes

The Topology API consists of the following classes:

TABLE 8-1   Topology API Classes
Class Description

EMStatus Class
Reports status, including error

EMIntegerSet Class
Implements a general purpose integer set

EMIntegerSetIterator Class
Provides a convenient method to visit each member of the integer set

EMTopoPlatform Class
Represents the Topology API as a whole

EMObject Class
Specifies the interface supported by all the persistent object classes

EMTopoNodeDn Class
Uniquely Identifies a topology node out of a set of topology node objects

EMTopoTypeDn Class
Uniquely Identifies a topology type out of the set of topology types

EMTopoNode Class
Represents a topology node

EMTopoType Class
Represents a topology type

EMAgent Class
Contains the agent interface common between EMCmipAgent, EMRpcAgent, and EMSnmpAgent

EMCmipAgentDn Class
Identifies one cmip agent object out of the set of cmip agent objects

EMCmipAgent Class
Represents the MIS object which contains configuration information

EMRpcAgentDn Class
Identifies one rpc agent object out of the set of rpc agent objects

EMRpcAgent Class
Represents the MIS object which contains configuration information

EMSnmpAgentDn Class
Identifies one snmp agent object out of the set of snmp agent objects

EMSnmpAgent Class
Represents the MIS object which contains configuration information

Application developers must work within the hierarchical model with containers and objects, but they do not need to understand the multiple objects within the MIS that represent individual topology elements.

The Topology API is not intended to provide access into non-topology related features provided by the PMI or Nerve Center Interface. Applications such as the Topology Import/Export Tool, Discover, and large parts of the Viewer should be achievable with this interface.

8.1.1 General Comments

Standard RogueWave Tools.h++ classes and templates are used instead of the PMI's DataUnit, Morf, Array, and Queue classes. The RogueWave Tools.h++ classes are simple and easier to understand. Solstice EM 4.1 comes with Rouge Wave tools with standard IO Stream supplied with Forte Update 2 compiler. The Furthermore, many developers just starting to work with Solstice EM are already familiar with the Tools.h++ library.
Fundamental concepts, such as accessing topology objects distributed across multiple MISs, and handling duplicate topology node names, have been factored into the design of the Topology API to help deal with these issues.
In general, the number of lines of code needed to perform some operation on topology objects are fewer (sometimes many times fewer) with the Topology API versus the PMI. In addition, the code is readable and easy to maintain. This should allow for faster development of topology-based applications.

8.1.2 General Description

Using the Topology API, developers can create applications for the Solstice EM platform without learning the details of the MIT naming tree. The following figure gives an idea of how the Topology API is positioned in Solstice EM.

FIGURE 8-1   Position of the Topology API
8.2 Class Overview

Topology classes are related to the GDMO, the PMI, and persistent objects.

8.2.1 Relationship to the GDMO

In terms of the GDMO, the Topology API provides a concrete C++ interface to the MIT objects described in the table below.

TABLE 8-2   Topology API and GDMO Object Relationship
Topology API C++ Class Objects in MIT

EMTopoNode Class
topoNode objects contained under topoNodeDBId=NULL
topoView objects contained under topoViewDBId=NULL
topoViewNode objects contained under topoViewDBId=NULL/topoNodeId=XX

EMTopoType Class
topoType objects contained under topoTypeDBId=NULL

EMCmipAgent Class
cmipAgent objects contained under agentTableType="CMIP"

EMRpcAgent Class
rpcAgent objects contained under agentTableType="RPC"

EMSnmpAgent Class
cmipsnmpProxyAgent objects contained under internetClassId={ 1 3 6 1 4 1 42 2 2 2 9 2 4 1 0}

Through the C++ interface, the Topology API provides services that are equivalent to the following GDMO services:

Create, delete, set attributes of, and get attributes of the object classes topoNode, topoView, topoViewNode, topoType, cmipsnmpProxyAgent, cmipAgent, and rpcAgent.
Provide support for the actions topoGetNodeMODataByNodeList, topoNodeChildAttrsByView, topoNodeGetByMOSet, topoNodeGetByName, topoNodeGetByType, topoNodeGetByMO, topoGetViewGraph, getTopoNodesAttributes, and setTopoNodesAttributessupported by the topoNodeDB object class.
Provide support for the processes of objectCreation, objectDeletion, and attributeValueChange notifications for the topology object classes topoNode, topoView, topoViewNode.

8.2.2 Relationship to PMI

The Topology API is built on top of the PMI. If your client application only needs to manipulate topology nodes, topology types, cmip agents, rpc agents, and snmp agents, then the only places where the PMI must still be used are the following:

A connection to an MIS, established using the PMI Platform class. After the platform instance has been successfully initialized, the Topology API is initialized by calling the EMTopoPlatform::initialize method with the Platform instance as a parameter.
If the application supports access control application features, then Platform::get_authorized_features() must be used to find out which features a particular user is authorized to use.
When the Morf class is used for setting or getting the EMTopoNode::user_data attribute. There is no way around this, since the user_data attribute can contain data defined by any ASN.1 syntax.

Of course, if the application needs to access additional objects in the MIT beyond those outlined in TABLE 8-2, then the PMI Image class must be used. As an example, the Solstice EM Network Viewer makes use of the Topology API to access topology nodes and topology types, the NCI API to manipulate requests, and the PMI for connection, access control features, and a few miscellaneous operations.

The following restrictions on usage of the PMI are necessary in order for the Topology API to function correctly:
If Platform::replace_discriminator(), or Platform::replace_discriminator_classes eliminate the sending of unwanted events from the MIS, the discriminator must allow all events for the following object classes: topoNode, topoView, topoViewNode, topoType, cmipAgent, rpcAgent, and cmipsnmpProxyAgent.
For example, an application that doesn't subscribe to any events itself, that is, doesn't use Album::when(), Image::when(), or Platform::when(), and calls Platform::replace_discriminator() with the argument "or : {}, " which instructs the MIS not to send any events to the application, eliminates unnecessary event traffic and processing time.
However, that same application using the Topology API, would require the following syntax.

#include pmi/hi.hh

Array(DU) object_clases;

object_classes.alloc(7);

object_classes[0] = "topoNode";

object_classes[1] = "topoView";

object_classes[2] = "topoViewNode";

object_classes[3] = "topoType";

object_classes[4] = "cmipAgent";

object_classes[5] = "rpcAgent";

object_classes[6] = "cmipsnmpProxyAgent";

Platform::replace_discriminator_classes(object_classes)
Platform::set_attr_coder() should not be called to change the encoder/decoder for any of the GDMO attributes of the GDMO object classes topoNode, topoView, topoViewNode, topoType, cmipAgent, rpcAgent, or cmipsnmpProxyAgent.
8.3 EMTopoPlatform Class

The EMTopoPlatform class represents the Topology API as a whole. Only one instance of the EMTopoPlatform class is allowed. This instance is initialized by calling EMTopoPlatform::initialize(), and is accessed through the EMTopoPlatform::instance() method¹. The EMTopoPlatform class provides various methods, or member functions including:

Get all MIS systems reachable from the connected MIS
Find topology nodes by name, type, or managed object
Find CMIP, RPC, and SNMP agents by managed object.
Get the topology pathname(s) by topology node DN.
#include pmi/hi.hh

#include topo_api/topo_api.hh

Platform platform;

if (!platform.connect("mishost","em_client")) {

cerr << "Failed to connect to " << "mishost" << endl;

exit(-1);

}

EMTopoPlatform::initialize(platform);
The above code shows how the Topology API is initialized.
8.3.1 get_attributes_by_mo()

EMStatus get_attributes_by_mo(

const RWTValSlistRWCString& managed_objects,

const EMIntegerSet& attributes,

RWTValSlistEMTopoNode& nodes,

const RWTValSlistRWCString&
system_names = RWTValSlistRWCString()

)
This method enables you to get attribute values of topology nodes that represent the given managed objects. To use this method, you must specify the following parameters:

managed_objects

A list of the managed objects.

attributes

A list of attributes whose values you want to get. If you provide an empty list of attributes, this method gets all the attribute values of the topology nodes. In either case, attributes should be created with EMTopoNode::num_attributes.

If this method completes successfully, it returns a list of topology nodes nodes. Each node in the returned list contains at least one of the given managed_objects in the node's topoNodeMOSet attribute. Each node in the list contains the values of the given attributes.

Because a topology node can contain more than one managed object, it is possible that the returned list of topology nodes contains a number of nodes that is less than the number of the given managed objects. Because a managed object can be contained by multiple topology nodes, it is possible that the returned list of topology nodes contains a number of nodes that is greater than the number of the given managed objects.

Note – For topology view-related attributes, it is the user's responsibility to check whether a node is a topology view before getting its attribute values.
8.3.2 set_attributes_by_mo()

EMStatus set_attributes_by_mo(

const RWTValSlistRWCString& managed_objects,

const EMIntegerSet& attributes,

const EMTopoNode &reference_node,

RWTValSlistEMTopoNode& nodes,

const RWTValSlistRWCString&
system_names = RWTValSlistRWCString()

)
This method enables you to set attribute values of topology nodes that represent the given managed objects. To use this method, you must specify the following parameters:

managed_obejcts

A list of the managed objects.

attributes

A list of attributes whose value you want to set.

reference_node

EMTopoNode object filled with the values for attributes.

If this method completes successfully, it returns a list of topology nodes nodes. Each node in the returned list contains, at least, one of the given managed_objects in the node's topoNodeMOSet attribute. Each node in the list contains the values of the given attributes as specified in the reference node.

Because a topology node can contain more than one managed object, it is possible that the returned list of topology nodes contains a number of nodes that is less than the number of the given managed objects. Because a managed object can be contained by multiple topology nodes, it is possible that the returned list of topology nodes contains a number of nodes that is greater than the number of the given managed objects.

Note – For topology view-related attributes, it is the user's responsibility to check whether a node is a topology view before getting its attribute values.

8.4 Persistent Object Classes

The Topology API provides an interface to five Persistent Object Class (POC) objects in the MIS: topology nodes, topology types, SNMP agents, CMIP agents, and RPC agents. Unlike the PMI, where the Image class provides a generic interface to any persistent object in the MIS, the Topology API provides a concrete, type-safe C++ class for each of these five classes.

8.4.1 EMObject Class

The EMObject class is an abstract base class from which the concrete POC classes are derived. This class declares the common methods that all POC classes support. The common methods include:

Creation and deletion in the MIS's persistent store
Loading/storing attributes from/to the MIS

Other methods common among POC classes are not declared in the EMObject class because the signature of the method isn't exactly the same. For example, all the POC classes support the compare_all_attributes() and compare_some_attributes() methods.

8.4.2 EMObject Member Functions

The following are member functions of the EMObject Class.
compare_all_attributes

RWBoolean

EMTopoNode::compare_all_attributes(const EMTopoNode& peer )
compare_some_attributes

RWBoolean

EMTopoNode::compare_some_attributes(const EMTopoNode& peer )
Because the type of the peer parameter differs for each POC, the methods cannot be included in the EMObject base class. Each POC class also provides additional methods specific to the POC; in particular, access methods to the attributes of the POC are provided.

8.4.3 EMTopoType Class

An instance of the EMTopoType class represents a topology type. Every topology node is classified as a particular topology type. The topology types form a hierarchy with the seven base types "Array," "Bus," "Container," "Device," "Monitor," "Link," and "Sun" with other subtypes derived from them.

Beyond the standard POC methods, which allow you to create, delete, and compare topology types, the EMTopoType class provides the static methods is_array(), is_bus(), is_container(), is_device(), is_monitor(), is_link(), and is_view() which can be used to categorize topology types.

8.4.4 EMTopoNode Class

The EMTopoNode class represents a topology node, which is the unit of management in Solstice EM. Using the standard POC methods, you can create, delete, and compare topology nodes. Using the EMTopoNode access methods, you can get and set the name, topology pathname, logical and geographical location, topology type, and associated managed objects and their corresponding CMIP, RPC, and/or SNMP agent objects among others attributes. The EMTopoNode class also provides a callback mechanism to notify clients when a topology node has been created, deleted, or has had one or more attributes changed.

8.4.5 EMSnmpAgent Class

An instance of the EMSnmpAgent class represents the MIS object that contains configuration information for an SNMP agent. The configuration information includes such information as the read and write community strings, supported MIBs, and transport address.

Note – This class does not provide an interface to the agent's managed objects, only to Solstice EM's configuration information for the agent.

8.4.6 EMCmipAgent Class

An instance of the EMCmipAgent class represents the MIS object that contains configuration information for a CMIP agent. The configuration information includes the CMIP MPA hostname and port number, list of managed objects DNs, network SAP, transport selector, presentation selector, session selector, and application entity title (AET).

Note – This class does not provide an interface to the agent's managed objects, only to Solstice EM's configuration information for the agent.

8.4.7 EMRpcAgent Class

An instance of the EMRpcAgent class represents the MIS object that contains configuration information for an RPC agent. The configuration information includes the read and write community strings, and supported schemas.

Note – This class does not provide an interface to the agent's managed objects, only to Solstice EM's configuration information for the agent.

8.5 Utility Classes

8.5.1 EMIntegerSet Class

The EMIntegerSet class implements a general-purpose integer set over the numbers 0 to n. It is used in the Topology API to communicate which attributes of a POC an API method should operate on.

8.5.2 EMStatus Class

Instances of class EMStatus are returned by almost every API method to report status, including errors. A conversion operator to RWBoolean is provided so that EMStatus can be evaluated in boolean expressions. A value of FALSE means there was an error, otherwise success.

8.6 Topology API Concepts

8.6.1 Element Naming

Applications must be able to access individual topology elements without traversing the entire topology hierarchy. The mapping of topology element names to that of a file system model for unique naming is supported. In the event that a file system style reference is ambiguous within the underlying MIT, the method invoked fails and reports the appropriate error. As an example of this naming, an element named "Parrothead," located under the "Internet" view, located under the "Root" view, would be referenced as /Root/Internet/Parrothead. There can be only one root, and as such, the root is represented as / within this model.

8.6.2 Duplicate Topology Node Names

The administrative names of the EMTopoType, EMCmipAgent, EMSnmpAgent, and EMRpcAgent persistent objects are guaranteed to be unique. In contrast, the administrative name of the EMTopoNode is not guaranteed to be unique.

To address this, the EMTopoPlatform class provides several methods to return a list of EMTopoNodeDn instances that:

Have the same administrative name
Have the same type
Share the same proxy agent object
Share the same managed object Dn's

8.6.3 MIS-MIS Awareness

Each persistent object class supports access to any object instance visible from the connected MIS. For example, if MIS A and MIS B have a 2-way MIS-MIS connection setup, you can connect to MIS A, then modify EMTopoNodes, EMTopoTypes, and so forth, on MIS B.

The EMTopoPlatform find methods, such as find_nodes_by_name(), and find_nodes_by_type(), perform the search on the entire set of objects visible from the connected MIS. Using the above example of MIS A and MIS B, if you connect to MIS A, and find_nodes_by_type(), you see a list of all EMTopoNodeDn's on MIS A and/or MIS B of the indicated type.

8.6.4 Performance Considerations

Because the Topo API is built on top of the PMI, most operations take slightly longer when using the Topo API versus writing the code directly with PMI.

In terms of memory usage, however, the persistent object classes require much less memory cache information about an object than if an Image class had been used instead. This is because the Topo API classes can optimize the data storage; they know exactly what attributes each managed object contains.

8.7 Examples

This section presents several examples showing how to use the Topology API for common tasks.

8.7.1 Makefile

The following Makefile was used to compile all of the programs in this section. The version of the SUN C++ SparcCompiler used is "SC4.0 18 Oct 1995 C++ 4.1". (This is the output from "CC -V"). This Makefile and the following sample programs can be found in $EM_HOME/src/topo_api directory.
CCFLAGS = +w -g -noex -I${EM_HOME}/include

-I${EM_HOME}/include/pmi

LDFLAGS = -L${EM_HOME}/lib -ltopo_api -lpmi -lrwtool -lsched

-lnsl -lsocket -lgen -R/opt/SUNWconn/em/lib

EXES = print_topo topo_events traverse

OBJS = $(EXES:%=%.o)

all: $(EXES)

print_topo: print_topo.o

$(LINK.C) -o $@ $@.o

topo_events: topo_events.o

$(LINK.C) -o $@ $@.o

traverse: traverse.o

$(LINK.C) -o $@ $@.o

clean:

rm -rf $(EXES) $(OBJS) Templates.DB;
8.7.2 Finding Topology Nodes

This program accepts as input the name of a topology node. The program then uses EMTopoPlatform::find_nodes_by_name() to find all topology nodes with the given name. Then some information for each node is displayed. This program highlights the fact that more than one topology node can have the same name, so a Solstice EM client should never assume that the topology node names are unique. That is why the Topology API uses instances of EMTopoNodeDn to uniquely identify a single topology node.
#include stdio.h

#include topo_api/topo_api.hh

int

main(int argc, char**argv)

{

if (argc < 2) {

cerr << "Usage: " << argv[0] << " node-name" << endl;

exit(-1);

}

RWCString node_name = argv[1];

Platform platform(duEM);

if (!platform.connect("","em_sample")) {

cerr << "Couldn't connect!" << endl;

exit (-2);

}

EMTopoPlatform::initialize(platform);

RWTValSlistEMTopoNodeDn nodes;

EMTopoPlatform::instance()->find_nodes_by_name(node_name,nodes);

if (nodes.isEmpty()) {

cerr << "No Topology Node Named " << node_name << endl;

exit(-3);

}

for (RWTValSlistIteratorEMTopoNodeDn i(nodes); i(); ) {

EMTopoNode node(i.key());

EMStatus status;

if (!(status = node.load_all_attributes())) {

cerr << "Error: " << status << endl;

exit(-4);

}

//

// The stream output operator << is defined for

// EMTopoNode, EMTopoType, EMCmipAgent, EMSnmpAgent,

// EMRpcAgent, providing an easy way to print out

// the values of an objects while debugging.

cout << "---------debug output--------" << endl;

cout << node << endl;

cout << "---------debug output--------" << endl;

//

// Normally, you want to do more with the values than

// print them out.

//

EMTopoNode::Severity severity;

node.get_severity(severity);

RWCString name;

node.get_name(name); // named the same as node_name

RWCString type_name;

node.get_type_name(type_name);

EMTopoNode::GeoLocation geographical_location;

RWBoolean is_geographical_location_null;

node.get_geographical_location(geographical_location,

is_geographical_location_null);

RWTValSlistEMCmipAgentDn cmip_agents;

RWTValSlistEMSnmpAgentDn snmp_agents;

RWTValSlistEMRpcAgentDn rpc_agents;

node.get_cmip_agents(cmip_agents);

node.get_snmp_agents(snmp_agents);

node.get_rpc_agents(rpc_agents);

cout << "Node named " << name << " is of type "

<< type_name << endl

<< "The most severe outstanding alarm is " << severity << "." << endl

<< "The node is located at ";

if (is_geographical_location_null)

cout << "unknown";

else

cout << geographical_location;

cout << " in the world" << endl;

cout << "CMIP agents: ";

if (cmip_agents.isEmpty()) {

cout << "none" << endl;

} else {

cout << endl;

for

(RWTValSlistIteratorEMCmipAgentDn j(cmip_agents); j(); ) {

cout << "\t" << j.key() << endl;

}

}

cout << "RPC agents: ";

if (rpc_agents.isEmpty()) {

cout << "none" << endl;

} else {

cout << endl;

for

(RWTValSlistIteratorEMRpcAgentDn j(rpc_agents); j(); ) {

cout << "\t" << j.key() << endl;

}

}

cout << "SNMP agents: ";

if (snmp_agents.isEmpty()) {

cout << "none" << endl;

} else {

cout << endl;

for

(RWTValSlistIteratorEMSnmpAgentDn j(snmp_agents); j(); ) {

cout << "\t" << j.key() << endl;

}

}

}

return 0;
}
8.7.3 Registering Events for EMTopoNode

The EMTopoNode class provides an event subscription service to notify clients when a topology node is created, deleted, or modified. This service is not offered by the other persistent object classes.

The following program registers for all three types of events, then proceeds to create, modify, and destroy a single topology node in order to cause some events to be sent to the registered callback. A description of each event is printed to stdout.
#include stdio.h

#include topo_api/topo_api.hh

void topo_event_cb(

const EMTopoNodeCallbackData& cbd

);

int

main(int /*argc*/, char** /*argv*/)

{

Platform platform(duEM);

if (!platform.connect("","em_sample")) {

cerr << "Couldn't connect!" << endl;

exit (-2);

}

EMTopoPlatform::initialize(platform);

//

// Register for create, delete, and attribute change events

// on EMTopoNode objects.

//

EMTopoNode::register_callback(em_any_event,topo_event_cb,NULL);

//

// Now we will create, modify, and then delete an EMTopoNode

// to trigger some events.

//

//

// Find the root node(s) (there will one for each MIS)

// so we have a parent view to create a topology node in.

//

RWTValSlistEMTopoNodeDn roots;

EMTopoPlatform::instance()->find_root_nodes(roots);
}

    // Okay, now we have to set the three mandatory attributes
 
    // for creating a topology node: name, type_name, and parents.
 
    //
 
    EMTopoNode node;
 
 
    node.set_name("first-name");
 
    
 
    node.set_type_name(EMTopoTypeDn::host);
 
    //
 
    // Arbitrarily use the first root node in the list as the 
 
    // parent of the new topology node.
 
    //
 
    node.add_parent(roots.first());
 
 
    //
 
    // Create the node
 
    //
 
 
    EMStatus status;
 
    if (!(status = node.create_with_all_attributes())) {
 
	 cerr << "Error: " << status << endl;
 
	 exit(-1);
 
    }
 
 
    // 
 
    // After the create has completed, the EMTopoNode::dn
 
    // attribute, the unique identifier, is set.
 
    //
 
    EMTopoNodeDn node_dn;
 
    node.get_dn(node_dn);
 
    cout << "Created Topology Node Id=" << node_dn 
 
<< " with parent Id=" << roots.first() << endl;
 
 
    //
 
    // Modify some attributes
 
    //
 
    // We don't want to store the parents and type_name attributes
 
    // again, so we need to reset the EMTopoNode object.
 
    node.clear_all_attributes();
 

 //
 
    // EMTopoNode::dn is the only mandatory attribute when doing
 
    // a store or load.
 
    //
 
    node.set_dn(node_dn);
 
    node.set_name("second-name");
 
    node.set_logical_location(roots.first(),Location(/*x=*/12,/*y=*/34,/*z=*/56));
 
    node.set_geographical_location(GeoLocation(/*longitude=*/-112.0,/*latitude=*/45.0));
 
    
 
    //
 
    // store_all_attributes() only stores attributes that
 
    // have been set.
 
    //
 
    if (!(status = node.store_all_attributes())) {
 
	 cerr << "Error: " << status << endl;
 
	 exit(-2);
 
    }
 
 
    //
 
    // destroy the node
 
    //
 
    if (!(status = node.destroy())) {
 
	 cerr << "Error: " << status << endl;
 
	 exit(-3);
 
    }
 
}
 
 
void topo_event_cb(
 
    const EMTopoNodeCallbackData& cbd
 
)
 
{
 
    switch(cbd.event_type) {
 
      case em_create_event:
 
	 	 cout << "topo_event_cb: node " << cbd.node_dn << " created" << endl;
 
	 	 break;
 
      case em_delete_event:

 	 	 cout << "topo_event_cb: node " << cbd.node_dn 
 
<< " deleted" << endl;
 
	 	 break;
 
      case em_change_event:	 
 
	 	 cout << "topo_event_cb: node " << cbd.node_dn 
 
<< " modifed" << endl;
 
	 
 
	 	 //
 
	 	 // cbd.changes is an instance of EMTopoNode contains all
 
	 	 // the changes.
 
	 	 //
 
	 	 EMIntegerSet attributes(EMTopoNode::num_attributes);
 
	 	 cbd.changes.get_active_attributes(attributes);
 
	 	 cout << "\tAttributes changed: ";
 
	 	 for (EMIntegerSetIterator i(attributes); i.next(); ) {
 
	     	 	 cout << EMTopoNode::get_attribute_name(i.member());
 
	 	 }
 
	 	 cout << endl;
 
	 
 
	 	 for (i.reset(); i.next(); ) {
 
	     	 	 switch (i.member()) {
 
	       	 	 	 case EMTopoNode::name:
 
	 	 	 	 	 {
 
	 	     	 	 	 	 RWCString name;
 
	 	     	 	 	 	 cbd.changes.get_name(name);
 
	 	     	 	 	 	 cout << "\tname changed to " << name << endl;
 
	 	 	 	 	 }
 
	 	 	 	 	 break;
 
	       	 	 	 case 
EMTopoNode::logical_locations:
 
	 	 	 	 	 {
 
	 	     	 	 	 	 RWTValSlistLocationInParent locations;
 
	 	     	 	 	 	 cbd.changes.get_logical_locations(locations);
 
	 	     	 	 	 	 cout << "\tlogical_location in parent view " << locations.first().parent <<
 
	 	 	 	 	 	 " is " << locations.first().location 
 
<< endl;
 
	       	 	 	 case EMTopoNode::children:
 

	 	     	 	 	 	 RWTValSlistEMTopoNodeDn children;
 
	 	     	 	 	 	 cbd.changes.get_children(children);
 
	 	 
 
	 	     	 	 	 	 cout << "\tchildren changed to {";
 
	 	     	 	 	 	 for 
 
(RWTValSlistIteratorEMTopoNodeDn j(children); j(); ) {
 
	 	 	 	 	 	 	 cout << j.key() << " ";
 
	 	     	 	 	 	 }
 
	 	     	 	 	 	 cout << "}" << endl;
 
	 	 	 	 	 }
 
	 	 	 	 	 break;
 
	  	 	 }
 
	 	 }
 
	 } 
 
}
 
8.7.4 Printing the Topology Hierarchy

The topology hierarchy forms a directed acyclic graph. It is a graph, rather than a tree, because each topology node except the root node can have more than one parent. It is acyclic because the parent-child relationship should not have any loops. The following program traverses the topology depth-first, starting at the root node(s). As each node is visited, the EMTopoNode:topology_pathnames attribute is printed to stdout.

Note that the cache_view_graph option of EMTopoPlatform::initialize() is set to TRUE this time since the program accesses the EMTopoNode::topology_pathnames attribute of every node.
#include stdio.h

#include iostream.h

#include topo_api/topo_api.hh

void traverse(

const EMTopoNodeDn& dn

);

long num_traversed = 0;

int

main(int /*argc*/, char** /*argv*/)

{

Platform platform(duEM);

if (!platform.connect("localhost","em_sample")) {

cerr << "Couldn't connect!" << endl;

exit (-1);

}

EMTopoPlatform::initialize(platform,TRUE);

EMStatus status;

//

// Find the root node(s) (there will one for each MIS)

// so we have a parent view to create a topology node in.

//

RWTValSlistEMTopoNodeDn roots;

if (!(status = EMTopoPlatform::instance()-> find_root_nodes(roots))) {

cerr << status << endl;

exit(-2);

}

// Traverse the topology of each MIS

//

for (RWTValSlistIteratorEMTopoNodeDn i(roots); i();) {

traverse(i.key());

}

//

// Note, the number of nodes traversed is most likely not equal

// to the number of nodes since a node with n parents would be

// traversed n times with the simple algorithm used.

//

cout << "Num Nodes Traversed = " << num_traversed << endl;

}

void

traverse(

const EMTopoNodeDn& dn

)

{

EMStatus status;

EMTopoNode node(dn);

num_traversed++;

//

// Load the topology pathnames of the topology node, and also

// the children if the topology node is a view (container or

// monitor type)

//

EMIntegerSet attributes(EMTopoNode::num_attributes);

attributes.add(EMTopoNode::topology_pathnames);

// We need the children attribute so that we can continue

// or depth-first traversal.

if (EMTopoPlatform::instance()->is_view(dn)) {

attributes.add(EMTopoNode::children);

if (!(status = node.load_some_attributes(attributes))) {

cerr << "Error: " << status << endl;

exit(-3);

}

//

// Print out all the possible topology pathnames for the node.

// A node may have more than one valid pathname from the root

// node because this is a directed acyclic graph not a tree.

//

RWTValSlistRWCString topology_pathnames;

if (!(status = node.get_topology_pathnames(topology_pathnames))) {

cerr << "Error: " << status << endl;

exit(-3);

}

cout << "{ ";

for (int i = 0; i < topology_pathnames.entries(); i++) {

cout << topology_pathnames[i];

if (i != topology_pathnames.entries() - 1)

cout << ", ";

}

cout << "}"<< endl;

//

// Recur on the node's children (if it has any)

//

if (EMTopoPlatform::instance()->is_view(dn)) {

RWTValSlistEMTopoNodeDn children;

if (!(status = node.get_children(children))) {

cerr << "Error: " << status << endl;

}

for (RWTValSlistIteratorEMTopoNodeDn j(children); j();) {

traverse(j.key());

}

}

}
8.8 Class Reference

This section includes the following classes:

EMStatus Class
EMIntegerSet Class
EMIntegerSetIterator Class
EMTopoPlatform Class
EMObject Class
EMTopoNodeDn Class
EMTopoTypeDn Class
EMTopoType Class
EMAgent Class
EMCmipAgentDn Class
EMCmipAgent Class
EMSnmpAgentDn Class
EMRpcAgent Class
EMSnmpAgentDn Class
EMSnmpAgent Class

8.9 EMStatus Class

Inheritance: none

#include topo_api/topo_api.hh

Instances of class EMStatus are returned by almost every API method to report status, including errors. A conversion operator to RWBoolean is provided so that EMStatus can be evaluated in Boolean expressions. A value of FALSE means there was an error, otherwise success. The following sample code shows the basic usage.

Static Variables

static EMStatus EMStatus::success;

This static public member can be used to compare to instances of EMStatus. If they are equal, then the operation succeeded. For example:

if (EMStatus::success == node.load_all_attributes()) {

cout << "succeeded" << endl;

}

Enum

enum EMStatus::Code {

successful,

pmi_error,

object_doesnt_exist,

attribute_is_not_creatable,

attribute_is_not_storeable,

attribute_not_set,

key_not_found,

missing_mandatory_attribute,

cannot_set_attribute,

decode_error,

encode_error,

attribute_not_registered,

does_not_exist,

already_exists,

invalid_arg,

not_implemented,

not_supported,

view_graph_not_cached,

duplicate_cmip_managed_fdns,

unknown_error, /* this means an internal error*/

num_status

};

This is a list of all the possible statuses that can be returned by the API.

8.9.1 Constructors and Destructor

EMStatus();

EMStatus(Code error_code,

const RWCString& text);

EMStatus(const EMStatus& status);

~EMStatus();

Normally, only the default constructor is used by clients.

8.9.2

operator RWBoolean () const;

Operators

EMStatus& operator =(const EMStatus& status);

RWBoolean operator ==(

const EMStatus& status

) const;

The following operator overloads are used for equality and logical equivalence.

And, the not-operator

RWBoolean operator !=(

const EMStatus& status

) const;

The RWBoolean conversion operator equates EMStatus::successful with TRUE, otherwise FALSE.

Here is an example of how this can be used to test the return status of a method:

EMStatus status;

if (!(status = node.load_all_attributes())) {

cerr << "Error: " << status << endl;

}

EMStatus::Code code() const;

Finally, it returns the status code.

8.9.3 Global Operators

ostream& operator<<(

ostream& s,

const EMStatus& status

);

The stream output operator << is defined to provide an easy way to print out the value of EMStatus.

8.10 EMIntegerSet Class

Inheritance:

#include topo_api/topo_api.hh

none

The EMIntegerSet class implements a general-purpose integer set over the numbers 0 to n. It is used in the Topology API to communicate which attributes of a POC an API method should operate on. The example below shows how to load the name, topology type, and parents of a topology node.

8.10.1 Example

Instances of EMIntegerSet are used when you only want to load, store, or compare a subset of the attributes of one of the persistent object classes.

EMIntegerSet attrs(EMTopoNode::num_attributes);

attrs.add(EMTopoNode::name);

attrs.add(EMTopoNode::type_name);

attrs.add(EMTopoNode::parents);

node.load_some_attributes(attrs);

8.10.2

EMIntegerSet ();

EMIntegerSet(

long n

);

EMIntegerSet(

long n,

RWBoolean initVal

);

~EMIntegerSet ();

Constructors and Destructor

EMIntegerSet(n) constructs a set of integers drawn from the universe numbered from 0 to n-1. By default, no numbers in the universe belong to the set. EMIntegerSet(n,TRUE) is the same except that every integer is a member of the set.

8.10.3 Operators

The following operator overloads are used for equality and logical equivalence.

EMIntegerSet& operator = (

RWBoolean b

);

RWBoolean operator == (

const EMIntegerSet& set

) const;

And, the not-operator,

RWBoolean operator != (

const EMIntegerSet& set

) const;

Two EMIntegerSet instances are considered equal if they are both of the same dimension and have the exact same members.

RWBoolean operator [] (

long number

) const;

Returns TRUE if the integer number is a member of the set.

The following performs a member-wise-and, exclusive-or, or Boolean operation on the specified set in comparison with another set of integers that must be of the same dimension.

EMIntegerSet& operator&=(

const EMIntegerSet& set

);

EMIntegerSet& operator^=(

const EMIntegerSet& set

);

EMIntegerSet& operator|=(

const EMIntegerSet& set

);

8.10.4 Member Functions

add

void add(long number);

Adds integers to the set.

remove

void remove(long number);

Removes integers from the set.

is_member

void RWBoolean is_member(long number)const;

Returns TRUE if number is a member of the set.

num_members

void num_members(long num_number);

Returns the number of integers in the set.

max_members

long max_members() const;

Returns the number of integers in the universe of potential members.

resize

void resize(long n);

Resizes the integer set to the universe of integers 0 to n-1.

8.10.5 Global Operators

EMIntegerSet operator!(

const EMIntegerSet& set

);

EMIntegerSet operator&(

const EMIntegerSet& set1,

const EMIntegerSet& set2

);

EMIntegerSet operator^(

const EMIntegerSet& set1,

const EMIntegerSet& set2

);

EMIntegerSet operator|(

const EMIntegerSet& set1,

const EMIntegerSet& set2

);

The operator! returns the member-wise negation of the input set. The other operator functions return the member-wise-and, exclusive-or, and-or, of two sets. Note that for the binary operations, the two sets must be of the same dimensions.

8.11 EMIntegerSetIterator Class

Inheritance: none

#include topo_api/topo_api.hh

The EMIntegerSetIterator class provides a convenient method to visit each member of the integer set.

8.11.1 Example

EMTopoNode node;

EMItegerSet(EMTopoNode::num_attributes);

node.get_active_attributes(attrs);

for (EMIntegerSetIterator i(atrrs); i(); ) {

switch (i.key()) {

case EMTopoNode::name:

break;

case EMTopoNode::type_name:

break;

case EMTopoNode::managed_objects:

break;

default:

cout << "Some other attribute" << endl;

break;

}

}

8.11.2 Constructors and Destructor

EMIntegerSetIterator(const EMIntegerSet& set);

The Iterator will visit the members of set in numerical order.

And the corresponding destructor:

~EMIntegerSetIterator(const EMIntegerSet& set);

8.11.3 Member Functions

next

RWBoolean next();

next() advances the iterator one position and returns TRUE if the new position is valid, FALSE otherwise.

member

long member() const;

member() returns the integer member currently being visited.

reset

void reset();

reset() resets the iterator to the first integer member in the set.

8.12 EMTopoPlatform Class

Inheritance: none

#include topo_api/topo_api.hh

The EMTopoPlatform class represents the Topology API as a whole. Only one instance of the EMTopoPlatform class is allowed. This instance is initialized by calling EMTopoPlatform::initialize(), and is accessed through the EMTopoPlatform::instance() method.

The EMTopoPlatform class provides various methods, including:

Get all MIS systems reachable from the connected MIS
Find topology nodes by name, type, or managed object
Find CMIP, RPC, and SNMP agents by managed object
Get the topology pathname(s) by topology node DN

8.12.1 Example

#include pmi/hi.hh

#include topo_api/topo_api.hh

Platform platform;

if (!platform.connect("mishost","em_client")) {

cerr << "Failed to connect to " << "mishost" << endl;

exit(-1);

}

EMTopoPlatform::initialize(platform);

EMStatus status;

RWTValSlistEMTopoNodeDn root_nodes;

if (!(status = EMTopoPlatform::instance()->

find_root_nodes(root_nodes))) {

cerr << "Error: " << status << endl;

exit(-1);

}

The above code shows how the Topology API is initialized, and how the root nodes of the network topology are retrieved.

8.12.2 Static Member Functions

initialize

static RWBoolean initialize(

Platform& platform,

RWBoolean cache_view_graph = FALSE

);

initialize() must be called before using any of the Topology API classes. This method should only be called after the platform has been successfully initialized. It returns TRUE on success, FALSE otherwise. The optional parameter cache_view_graph specifies whether you should optimize methods that operate over the topology view hierarchy.

If cache_view_graph is TRUE, then the topology view hierarchy will be cached into memory from the MIS using a special GDMO action topoGetViewGraph on the topoNodeDBId=NULL object. This optimization greatly increases the speed of loading EMTopoNode::view_children and EMTopoNode::topology_pathnames and executing EMTopoPlatform::is_view(). However, the view cache can require a significant amount of time and memory for large topology view hierarchy (> 5000 nodes).

instance

static EMTopoPlatform* instance();

After initialize() succeeds, the static method instance() returns a pointer to the EMTopoPlatform instance from which the non-static EMTopoPlatform methods can be invoked.

TABLE 8-3 summarizes when the cache_view_graph option should be turned on and off.

TABLE 8-3   cache_view_graph Option
cache_view_graph application type

TRUE
Frequently calls EMTopoPlatform::is_view(), EMTopoPlatform::view_topology_pathnames(), EMTopoPlatform::topology_pathnames(), and/or loads EMTopoNode::view_children, EMTopoNode::topology_pathnames attributes.

FALSE
Does not use the above features or uses them infrequently. Client application should be as lightweight as possible and start up fast.

8.12.3 Access Member Functions

system_names

RWTValSlistRWCString system_names() const;

Platform& platform();

system_names() returns a list of all MIS names visible through the connection to the local MIS, including the local MIS name.

local_system_name

const RWCString& local_system_name() const;

Platform& platform();

local_system_name() returns the name of the MIS that the client application is connected to.

Note – For a remote MIS to be visible to client application, MMC (MIS-MIS Communication) must be set up between the local MIS and each remote MIS. This can be accomplished using the em_mismgr application.

8.12.4 General Member Functions

find_root_nodes

EMStatus find_root_nodes(

RWTValSlistEMTopoNodeDn& root_nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

Returns a list of all nodes named "Root" visible through the connection to the local MIS. The optional parameter system_names specifies the list of MISs to restrict the query. The MIS names in system_names should all appear in system_names(), otherwise EMStatus::invalid_arg will result. If system_names is empty (the default), then the list returned by system_names() is used.

find_nodes_by_name

EMStatus find_nodes_by_name(

const RWCString& name,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

Same as find_root_nodes() except that all nodes named name are returned instead of all nodes named "Root."

find_nodes_by_type

EMStatus find_nodes_by_type(

const RWCString& type_name,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

Same as find_root_nodes() except that all nodes of type type_name are returned instead of all nodes named "Root."

find_nodes_by_managed_object

EMStatus find_nodes_by_managed_object(

const RWCString& managed_object,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

Same as find_root_nodes() except that all nodes that have managed_object listed in their EMTopoNode::managed_objects attribute are returned instead of all nodes named "Root".

is_view

RWBoolean is_view(

const EMTopoNodeDn& node_dn

) const;

Returns TRUE if the topology type of node node_dn is a `view' type, that is, a subtype of EMTopoTypeDn::container or EMTopoTypeDn::monitor.

view_topology_pathnames

EMStatus view_topology_pathnames(

const EMTopoNodeDn& view_dn,

RWTValSlistRWCString& pathnames

) const;

Returns in pathnames a list of all topology pathnames for the node view. The node view should be a `view', that is, a subtype of EMTopoType::container or EMTopoTypeDn::monitor. If cache_view_graph optimization is turned on, then this method is relatively inexpensive since no information needs to be retrieved from the MIS. At a minimum, pathnames will contain one pathname for each parent. However, since each parent can also have more than one parent, and so on, the actual number of pathnames can be higher.

topology_pathnames

EMStatus topology_pathnames(

const EMTopoNodeDn& parent_dn,

const RWCString& name,

RWTValSlistRWCString& pathnames

) const;

The type topology_pathnames is similar to view_topology_pathnames() except that this version works for any type of node. This method will also not send any data requests to the MIS if the cache_view_graph optimization is turned on. The reason that the parameters parent_dn and name are required rather than just the EMTopoNodeDn of the node is because these two pieces of information are not cached by the Topology API -- the topology view cache has this information but only for view nodes. By having the client application pass this information in, the Topology API can take advantage of the cases where the client already has this information in memory.

find_root_types

EMStatus find_root_types(

RWTValSlistEMTopoTypeDn& types

) const;

Returns in types a list of all root types, that is. types with no EMTopoType::base_type. In the default installation of Solstice EM, the root types are EMTopoTypeDn::container, EMTopoTypeDn::device, EMTopoTypeDn::monitor, and EMTopoTypeDn::link.

Note – Unlike the find_root_nodes() method, this method will only return the root types on the local MIS.

find_all_types

EMStatus find_all_types(

RWTValSlistEMTopoTypeDn& types

) const;

Similar to find_root_types() except that types will contain all topology types on the local MIS.

The following methods provide a way to find the agent which is responsible for a particular managed_object. If a match is not found, then EMStatus::key_not_found error will result. These methods are used internally by the EMTopoNode class to calculate the EMTopoNode::snmp_agents, EMTopoNode::rpc_agents, and EMTopoNode::cmip_agents attributes from the EMTopoNode::managed_objects attribute.

managed_object_to_cmip_agent

EMStatus managed_object_to_cmip_agent(

const RWCString& managed_object,

EMCmipAgentDn& cmip_agent

) const;

If the object represented by the parameter managed_object is contained under a branch of the MIT which is managed by a cmip agent, the unique identifier of the cmip configuration object will be returned in cmip_agent and an EMStatus::Success is returned by the function. Otherwise, EMStatus::Key_not_found is returned.

managed_object_to_snmp_agent

EMStatus managed_object_to_snmp_agent(

const RWCString& managed_object,

EMSnmpAgentDn& snmp_agent

) const;

If the object represented by the parameter managed_object is contained under a branch of the MIT which is managed by a snmp agent, the unique identifier of the snmp configuration object will be returned in snmp_agent and an EMStatus::Success is returned by the function. Otherwise, EMStatus::Key_not_found is returned.

managed_object_to_rpc_agent

EMStatus managed_object_to_rpc_agent(

const RWCString& managed_object,

EMRpcAgentDn& rpc_agent

) const;

If the object represented by the parameter managed_object is contained under a branch of the MIT which is managed by a rpc agent, the unique identifier of the rpc configuration object will be returned in rpc_agent and an EMStatus::Success is returned by the function. Otherwise, EMStatus::Key_not_found is returned.

8.13 EMObject Class

Inheritance:

#include topo_api/topo_api.hh

none

The EMObject class is an abstract base class that specifies the interface supported by all the persistent object classes (POC): EMTopoNode, EMTopoType, EMCmipAgent, EMRpcAgent, and EMSnmpAgent.

Each POC instance is an interface to a particular set of objects in the MIT. For more information on which MIT objects the five POCs map to, refer to Section 8.2.1 Relationship to the GDMO." Each unit of persistent state is called an attribute, and an object is made up of a set of these attributes. Note that each POC attribute can translate to one, several, or no GDMO attribute(s) in the corresponding object(s) in the MIT.

To create a new object in the MIS, first set the mandatory attributes required for creation, must be set either by loading values from another object or setting the values explicitly, using the POC's access methods.

Either create_with_all_attributes(), or create_with_some_attributes() is called to create the object in the MIS. Note that create_with_all_attributes() only uses attributes that have been given a value. If the create method succeeds, then the POC::dn attribute will be set with the unique identifier of the new object.

To destroy an object, first the POC::dn identifier must be set, then the destroy() method may be called to delete the object from the MIS. This is a permanent, non-reversible operation; some care when using this method.

In order to get the attribute values of a particular object, first set the POC::dn identifier, then call either load_all_attributes() or load_some_attributes(). Once the attribute values are loaded, they stay cached within the POC and remain constant even if the values change in the MIS.

In order to set the attribute values persistently in the MIS, first set the POC::dn attribute, then call either store_all_attributes() or store_some_attributes(). Note that store_all_attributes() only stores those attributes that have been given a value.

As a point of reference, the persistence model used is a simplified version of the PMI's Image class.

Enum

enum EMObjectOperation {

em_load,

em_create,

em_store,

em_num_object_operations

};

8.13.1 Constructors and Destructor

virtual ~EMObject();

Because this is an abstract base class, no instances of EMObject can be created.

8.13.2 EMObject Member Functions Supported By POC Classes

exists

virtual RWBoolean exists() const;

Returns TRUE if the object represented by the persistent object class instance exists in the MIT.

Note – You must have the unique identifier (EMTopoNode::dn, EMTopoType::dn, etc.) set for this method to work properly. Otherwise, FALSE will be returned.

The following two methods create a new object in the MIS. In order for the create to succeed, the mandatory attributes required by the particular POC must be set. The new object has its attribute values determined as follows:

If create_with_all_attributes() was used, then any attribute that was given a value will be stored in the new object.
If the function create_with_some_attributes() is used, then only the specified attributes are stored in the new object.

In either case, any attributes that are not given a value will take on a default value defined by the GDMO for that object.

The possible error conditions are EMStatus::missing_mandatory_attribute, EMStatus::attribute_is_not_creatable, EMStatus::encode_error, and EMStatus::pmi_error.

create_with_all_attributes

virtual EMStatus create_with_all_attributes();

create_with_some_attributes

virtual EMStatus create_with_some_attributes(

const EMIntegerSet& attributes

);

destroy

virtual EMStatus destroy();

This method deletes the object identified by POC::dn from the MIS. This is a permanent, non-reversible operation; some care should be taken when using this method.

The possible error conditions are EMStatus::missing_mandatory_attribute, EMStatus::object_doesnt_exist, and EMStatus::pmi_error.

load_all_attributes

virtual EMStatus load_all_attributes();

virtual EMStatus load_some_attributes(

const EMIntegerSet& attributes

);

This method loads attributes of the object identified by POC::dn from the MIS into the POC internal cache. load_all_attributes() loads all attributes whereas load_some_attributes() only loads the specified attributes.

The possible error conditions are EMStatus::missing_mandatory_attribute, EMStatus::object_doesnt_exist, EMStatus::not_supported, and EMStatus::pmi_error.

The following methods will store attributes of the object identified by POC::dn to the MIS from the POC internal cache.

store_all_attributes

virtual EMStatus store_all_attributes();

store_all_attributes() stores all attributes that have been given a value.

store_some_attributes

virtual EMStatus store_some_attributes(

const EMIntegerSet& attributes );

store_some_attributes() stores only the specified attributes, without regard to whether the attributes have been given a value. Care must be taken only to specify attributes that have values; otherwise an arbitrary (usually NULL or empty) value is stored.

The possible error conditions are EMStatus::missing_mandatory_attribute, EMStatus::object_doesnt_exist, EMStatus::attribute_is_not_storable, EMStatus::encode_error and EMStatus::pmi_error.

get_active_attributes

virtual void get_active_attributes(

EMIntegerSet& set

) const;

This method returns the set of attributes that have been given a value characteristic of set.

The following two methods clear the internal memory of all or some attributes. This is useful when you want to reuse a POC instance to access a different object and do not want the previous values to remain in effect.

After clear_all_attributes() is called, all attributes no longer have a value in the internal memory, including the POC::dn attribute.

clear_all_attributes

virtual void clear_all_attributes();

clear_some_attributes

virtual void clear_some_attributes(

const EMIntegerSet& set

);

8.13.3 Operators

RWBoolean operator ==(

const EMPOC&

);

Supported by all POC classes

Two instances of EMPOC are considered to be equal if they each have the same attributes with a value and those values are the same for both. If one instance has a value for an attribute for which the other instance does not have a value, then the instances are not equal to one another. To compare a subset of the attributes, use compare_some_attributes().

RWBoolean operator !=(

const EMPOC&

);

And the not-operator,

8.13.4 Other Member Functions Supported by POC Classes.

compare_all_attributes

RWBoolean compare_all_attributes(

const EMPOC& other_poc

) const;

The method compare_all_attributes() is equivalent to operator== ().

compare_some_attributes

RWBoolean compare_some_attributes(

const EMPOC& other_poc,

const EMIntegerSet& attributes

) const;

The method compare_some_attributes() compares only the specified subset of attributes. For each attribute in attributes, either both EMPOC instances must have no value set for the attribute or if both of them have a value set for the attribute then the values must be equal. If one EMPOC instance has a value for the attribute while the other does not, then the instances are not equal.

The following functions are used to compare set attributes and are equivalent to the various set operations provided by other functions.

diff_all_attributes

RWBoolean diff_all_attributes(

const EMPOC& other_agent,

EMIntegerSet& differences

) const;

diff_some_attributes

RWBoolean diff_some_attributes(

const EMPOC& other_agent,

const EMIntegerSet& attributes,

EMIntegerSet& differences

) const;

The diff_all_attributes(), and diff_some_attributes() methods both have a return value equal to compare_all_attributes() and compare_some_attributes(), respectively, and in addition, return the set of attributes where the two instances differed, if any. The class EMIntegerSetIterator can then be used to iterate over the differences.

8.13.5 Static Member Functions Supported by POC Classes

These static methods provide information about the EMPOC's attributes.

get_valid_attributes

static const EMIntegerSet& get_valid_attributes(

EMObjectOperation op = em_load

);

The method get_valid_attributes() returns the set of attributes that are valid for the specified operation op.

get_mandatory_attributes

static const EMIntegerSet& get_mandatory_attributes(

EMObjectOperation op = em_load

);

The method get_mandatory_attributes() returns the set of attributes that are mandatory for the specified operation op. If a mandatory attribute is not set when the particular operation is called, an EMStatus::missing_mandatory_atribute error will result.

get_attribute_name

static const RWCString& get_attribute_name(

EMPOC::Attribute attribute

);

This method returns an attribute name in string form.

8.14 EMTopoNodeDn Class

Inheritance: none

#include topo_api/topo_api.hh

An instance of the EMTopoNodeDn class uniquely identifies one topology node out of the set of topology node objects interfaced by the EMTopoNode class.

Enum

enum NullId {

null_id = -1

};

8.14.1 Constructors and Destructor

The following are constructors for EMTopoNodeDn:

EMTopoNodeDn();

The default constructor creates a EMTopoNodeDn instance that is null. The is_null() method returns TRUE for this instance.

EMTopoNodeDn(

const RWCString& system_name,

long unique_id

);

Creates an EMTopoNodeDn instance that is uniquely identified by system_name and unique_id.

~EMTopoNodeDn();

And the default destructor,

8.14.2 Operators

RWBoolean operator ==(

const EMTopoNodeDn& dn

) const;

Two instances are equal if they have both the same system name and the same
unique name or if they are both null.

RWBoolean operator !=(

const EMTopoNodeDn& dn

) const;

And the not-operator,

8.14.3 Access Member Functions

The following are access methods for the EMTopoNodeDn class.

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

This method returns the name of the MIS where the topology node is stored.

unique_id

long unique_id() const;

void unique_id(

long unique_id

);

The topology node identifier is unique within a single MIS.

8.14.4 General Member Functions

make_null

void make_null();

Set to null value. A null value means that the EMTopoNodeDn does not refer to any topology node.

is_null

RWBoolean is_null() const;

Test for null value. A null value means that the EMTopoNodeDn does not refer to any topology node.

8.14.5 Related Global Operators

ostream& operator<<(ostream& s, const EMTopoNodeDn& dn);

The stream output operator << is defined to provide an easy way to print out the value of EMTopoNodeDn.

8.15 EMTopoNode Class

Inheritance: EMObject

#include topo_api/topo_api.hh

The EMTopoNode class represents a topology node, which is the unit of management in Solstice EM. Using the standard POC methods, you can create, delete, and compare topology nodes. Using the EMTopoNode's access methods you can get and set the name, topology pathname, logical and geographical location, topology type, and associated managed objects and their corresponding CMIP, RPC, and/or SNMP agent objects among other attributes. The EMTopoNode class also provides a callback mechanism to notify clients when a topology node has been created, deleted, or has had one or more attributes changed.

In TABLE 8-4, the attribute key is:

C - Attribute can be set at creation time.
S - Attribute can be set after creation time.
M - Mandatory; attribute must be set for operation to succeed.
X - Allowed; attribute can be set as an option.

TABLE 8-4   EMTopoNode Attributes Table
Attribute Enum C S Description

dn

M
Unique identifier.

name
M
X
Name of this node (need not be unique).

topology_pathnames

List of all topology pathnames for the node. At a minimum, there will be one pathname for each parent. However, since each parent can also have more than one parent, and so on, the actual number of pathnames may be higher. Example list: "/Root/Internet/129.146.74.0/host-45",
"/Root/hosts/host-45".

type_name
M
X
Type name of this node.

managed_objects
X
X
List of DNs (in ASCII slash format) of the managed objects in the MIT associated with this node.

cmip_agents
X
X
List of CMIP agents which have managed objects listed as part of managed_objects attribute.

snmp_agents
X
X
List of SNMP agents which have managed objects listed as part of managed_objects attribute.

rpc_agents
X
X
List of RPC agents which have managed objects listed as part of managed_objects attribute.

parents
M
X
List of topology nodes that contain this node in the topology directed acyclic graph (DAG).

children

List of topology nodes that are contained by this node.

view_children

Subset of children whose type_name is a view; that is, EMTopoType::is_view(type_name) returns TRUE.

links
X
X
List of Link topology nodes connected to this node.

propagate_peers
X
X
List of topology nodes for this node's severity propagation if is_severity_attribute is TRUE.

is_severity_propagated
X
X
If TRUE, then the node's propagated_severity will be propagated to each of the nodes in its parent and propagated peers hierarchy, where it will factor in the calculation of their propagated_severity.

state
X
X
Can be used to store an integer value.

severity

If the Alarm Service is running, the severity indicates the highest severity alarm posted against any of the managed_objects.
Note: Normally, an application never sets the severity attribute; this attribute is automatically updated from the Alarm Service.

propagated_severity

If the Alarm Service is running, the propagated_severity indicates the highest severity among this node's severity and the propagated_severity of any children of this node who have their is_severity_propagated flag set to TRUE.

display_statuses
X
X
A user-defined list of tags, value pairs, such as
{ { "CPUUsage", 45 } , { "DiskLoad" , 2345 } }.

geographical_location
X
X
The latitude and longitude in degrees floating-point of the location of this node.

layer_name
X
X
The layer to which this node belongs.

user_data
X
X
User-defined data that should contain values for each attribute name listed in EMTopoType::user_data_attribute_names for the type_name of this node.

logical_locations
X
X
A list of locations where the node appears in each of its parent views.

view_background_image_filename
X
X
Absolute pathname of Sun raster file image to be displayed when the viewer canvas is in logical view mode.

view_map_config_filename
X
X
Absolute pathname of geographical map configuration (GMC) file to be displayed when the Viewer canvas is in geographical view mode.

view_default_geo_area
X
X
Default geographical area (specified as a center and view width in km) to be displayed when the view_map_config_filename is first displayed.

monitor_rotation
X
X
Number of degrees to rotate the monitor node.

monitor_visible_children

X
Subset of the children list of nodes that should appear in the monitor sections.

monitor_hidden_children

List of children nodes remaining when monitor_visible_children list of nodes are subtracted from the children list of nodes. These nodes do not appear in a monitor section, even if there are empty sections.

monitor_max_visible_children

Maximum number of visible children supported by the particular type of monitor.

array_visible_children

X
List of topology nodes which are displayed in an array. This list is a subset of the preexisting children attribute supported by all containers.

array_hidden_children

List of topology nodes which are not displayed in an array. This list is a subset of the preexisting children attribute supported by all containers.

array_orientation
X
X
The orientation of an array, either horizontal or vertical. This indicates whether the topology nodes grouped by the array should be laid down row by row or column by column.

array_num_columns
X
X
The number of columns in an array with horizontal orientation, or the number of rows in an array with vertical orientation.

array_cell_width
X
X
The width (in characters) of each cell in an array. If the value is 0, then the cell width will be set to the minimum width necessary to display the label of the widest cell.

bus_logical_locations
X
X
List of x,y points which define the bus's shape. Note that the points are constrained so that all line segments are alternatingly horizontal or vertical.

8.15.1 Example

#include topo_api/topo_api.hh

// this assumes the snmp_agent was created

// elsewhere

RWBoolean

create_host(

const EMTopoNodeDn& parent_dn,

const EMSnmpAgentDn& snmp_agent_dn

)

{

EMTopoNode node;

node.set_name(snmp_agent_dn.unique_name());

node.set_type_name(EMTopoTypeDn::host);

node.add_parent(parent_dn);

// for hosts, we use the DN of the snmp agent

// object as the managed object.

node.add_managed_object(snmp_agent_dn.slash_form());

EMStatus status;

if (!(status = node.create_with_all_attributes())) {

cerr << "Error: " << status << endl;

return FALSE;

}

return TRUE;

}

Enum

enum EMTopoNode::AttributeType {

all_attributes,

common_attributes,

view_only_attributes,

monitor_only_attributes,

link_only_attributes,

device_only_attributes,

array_only_attributes,

bus_only_attributes,

num_attribute_types

};

enum EMTopoNode::Attribute {

dn=0,

name,

type_name,

managed_objects,

cmip_agent,

snmp_agent,

rpc_agent,

parents,

children,

children_containers_only,

links,

propagate_peers,

is_severity_propagated,

state,

severity,

propagated_severity,

display_statuses,

geographical_location,

layer_name,

user_data,

logical_locations,

view_background_image_filename,

view_map_config_filename,

view_default_geo_area,

monitor_rotation,

monitor_visible_children,

monitor_hidden_children,

monitor_max_visible_children,

array_visible_children,

array_hidden_children,

array_orientation,

array_num_columns,

array_cell_width,

bus_logical_locations,

num_attributes

};

enum EMTopoNode::Severity {

indeterminate = 0,

critical = 1,

major = 2,

minor = 3,

warning = 4,

cleared = 5,

min_severity = indeterminate,

max_severity = cleared,

num_severity = max_severity - min_severity + 1

};

Structs

struct EMTopoNode::Location

{

long x;

long y;

long z;

Location();

Location(long p_x,long p_y,long p_z=0);

RWBoolean operator == (const Location& l) const;

RWBoolean operator != (const Location& l) const;

ostream& operator<<(ostream& s, const Location& l);

};

struct EMTopoNode::LocationInParent

{

EMTopoNodeDn parent;

Location location;

LocationInParent();

LocationInParent(

const EMTopoNodeDn& p_parent,

const Location& p_location

);

RWBoolean operator == (

const LocationInParent& l

) const;

RWBoolean operator != (

const LocationInParent& l

) const;

ostream& operator<<(

ostream& s,

const LocationInParent& l

);

};

struct EMTopoNode::GeoLocation

{

double longitude;

double latitude;

GeoLocation();

GeoLocation(double p_longitude,double p_latitude);

RWBoolean operator == (const GeoLocation& l) const;

RWBoolean operator != (const GeoLocation& l) const;

ostream& operator<<(ostream& s, const GeoLocation& l);

};

struct EMTopoNode::DisplayStatus

{

RWCString label;

long value;

DisplayStatus();

DisplayStatus(const RWCString& p_label,long p_value);

RWBoolean operator == (const DisplayStatus& d) const;

RWBoolean operator != (const DisplayStatus& d) const;

ostream& operator<<(ostream& s, const DisplayStatus& d);

};

struct EMTopoNode::UserDatum

{

RWCString attribute_name;

Morf value;

UserDatum();

UserDatum(

const RWCString& p_attribute_name,

const Morf& p_value);

RWBoolean operator == (

const UserDatum& d

) const;

RWBoolean operator != (

const UserDatum& d) const;

ostream& operator<<(ostream& s,

const UserDatum& d);

};

8.15.2 Constructors and Destructor

EMTopoNode();

EMTopoNode(

const EMTopoNodeDn& dn

);

EMTopoNode(

const EMTopoNode& node

);

The default destructor,

~EMTopoNode();

8.15.3 Access Member Functions

The member function methods of the EMTopoNode class refer to the attributes listed in the table at the beginning of this section, table 6-4. See the table for a description of each of the attributes.

get_dn

EMStatus get_dn(

EMTopoNodeDn& dn

) const;

This function gets the distinguished name, dn, associated with a node.

set_dn

EMStatus set_dn(

const EMTopoNodeDn& dn

);

This function sets the distinguished name, dn, associated with a node.

get_name

EMStatus get_name(

RWCString& name

) const;

This function gets the name of a node.

set_name

EMStatus set_name(

const RWCString& name

);

This function sets the name of a node.

get_topology_pathnames

EMStatus get_topology_pathnames(

RWTValSlistRWCString& topology_pathnames

) const;

This function gets a list of all the pathnames for a specific node.

get_type_name

EMStatus get_type_name(

RWCString& type_name

) const;

This function gets the type name of a specific node.

set_type_name

EMStatus set_type_name(

const RWCString& type_name

);

This function sets the type name of a specific node.

get_severity

EMStatus get_severity(

EMTopoNode::Severity& severity

) const;

This function gets the severity associated with a node.

set_severity

EMStatus set_severity(

EMTopoNode::Severity severity

);

This function sets the severity associated with a node, but now has no effect. Only the Alarm Service will update this attribute.

get_propagated_severity

EMStatus get_propagated_severity(

EMTopoNode::Severity& severity

) const;

This function gets the propagated severity associated with a node.

get_is_severity_propagated

EMStatus get_is_severity_propagated(

RWBoolean& is_severity_propagated

) const;

This function gets a node's is_severity_propagated and determines whether the property of propagated_severity should be propagated to each of the parent and peer nodes, where it is a factor in the calculation of their severity.

set_is_severity_propagated

EMStatus set_is_severity_propagated(

const RWBoolean& is_severity_propagated

);

This function sets a node's is_severity_propagated and determines whether the property of propagated_severity should be propagated to each of the parent and peer nodes, where it is a factor in the calculation of their severity.

get_propagate_peers

EMStatus get_propagate_peers(

RWTValSlistEMTopoNodeDn& peers

) const;

This function gets a list of propagate_peer nodes in the topology.

set_propagate_peers

EMStatus set_propagate_peers(

const RWTValSlistEMTopoNodeDn& peers

);

This function sets a list of propagate_peer nodes in the topology.

add_propagate_peer

EMStatus add_propagate_peer(

const EMTopoNodeDn& peer

);

This function adds a topology node to the propagate_peers list.

remove_propagate_peer

EMStatus remove_propagate_peer(

const EMTopoNodeDn& peer

);

This function removes a topology node from the propagate_peers list.

get_state

EMStatus get_state(

long& state

) const;

This function is used to get the state associated with a node.

set_state

EMStatus set_state(

long state

);

This function is used to set the state associated with a node.

get_display_statuses

EMStatus get_display_statuses(

RWTValSlistEMTopoNode::DisplayStatus& statuses

) const;

This function gets the user-defined list of tag-value pairs for a number of display statuses.

set_display_statuses

EMStatus set_display_statuses(

const RWTValSlistEMTopoNode::DisplayStatus& statuses

);

This function sets the user-defined list of tag-value pairs for a number of display statuses.

get_display_status

EMStatus get_display_status(

const RWCString& tag,

long& value

) const;

This function will get a value for the specified tag, if it exists. If not, EMStatus:key_not_found will be returned.

add_display_status

EMStatus add_display_status(

const RWCString& tag,

long value

);

This function will add a tag-value pair to the display_status attribute. If the tag already exists, the value will be replaced by value.

remove_display_status

EMStatus remove_display_status(

const RWCString& tag

);

This function will remove the specified tag-value pair from the display_status attribute.

get_children

EMStatus get_children(

RWTValSlistEMTopoNodeDn& children

) const;

This function will get a list of topology nodes that are contained by this node.

get_children_containers_only

EMStatus get_children_containers_only(

RWTValSlistEMTopoNodeDn& children

) const;

This function gets the subset of topology nodes contained by this node which are views, that is, the function EMTopoPlatform::instance()->is_view returns TRUE for each of the applicable topology nodes.

get_parents

EMStatus get_parents(

RWTValSlistEMTopoNodeDn& parents

) const;

This function gets a list of topology nodes that are parents.

set_parents

EMStatus set_parents(

const RWTValSlistEMTopoNodeDn& parents

);

This function sets the parents of a particular node.

add_parent

EMStatus add_parent(

const EMTopoNodeDn& parent

);

This function adds a node parent to the parent's list.

remove_parent

EMStatus remove_parent(

const EMTopoNodeDn& parent

);

This function removes the node parent from the parents list.

get_links

EMStatus get_links(

RWTValSlistEMTopoNodeDn& links

) const;

This function gets a list of links to topology nodes connected to this node.

set_links

EMStatus set_links(

const RWTValSlistEMTopoNodeDn& links

);

This function sets a list of links to topology nodes connected to this node.

add_link

EMStatus add_link(

const EMTopoNodeDn& link

);

This function adds a topology node link to nodes connected to this node.

remove_link

EMStatus remove_link(

const EMTopoNodeDn& link

);

This function removes a topology node link from the list of nodes connected to this node.

get_logical_location

EMStatus get_logical_location(

const EMTopoNodeDn& parent,

EMTopoNode::Location& location

) const;

This function gets the logical location of the node in its parent view parent. If the node is not contained in parent, the EMStatus::key_not_found status string is returned.

set_logical_location

EMStatus set_logical_location(

const EMTopoNodeDn& parent,

const EMTopoNode::Location& location

);

This function sets the logical location of the node in its parent view parent. If the node is not contained in parent, the EMStatus::key_not_found status string is returned.

get_logical_locations

EMStatus get_logical_locations(

RWTValSlistEMTopoNode::LocationInParent& locations

) const;

This function gets a list of logical locations where the node appears in each of its parent views.

set_logical_locations

EMStatus set_logical_locations(

const RWTValSlistEMTopoNode::LocationInParent& locations

);

This function sets a list of logical locations where the node appears in each of its parent views. The node must already be contained within each parent specified in EMTopoNode::LocationInParent struct.

get_geographical_location

EMStatus get_geographical_location(

EMTopoNode::GeoLocation& location,

RWBoolean& is_null

) const;

This function gets the latitude and longitude in degrees floating-point of the location of this node. If is_null is TRUE, then the node has no geographical position, and location is undefined.

set_geographical_location

EMStatus set_geographical_location(

const EMTopoNode::GeoLocation& location,

RWBoolean is_null = FALSE

);

This function sets the latitude and longitude in degrees floating-point of the location of this node. Passing is_null as TRUE, will result in the node having no geographical position, and location is undefined.

get_layer_name

EMStatus get_layer_name(

RWCString& name

) const;

This function gets the layer that a specific node belongs to.

set_layer_name

EMStatus set_layer_name(

const RWCString& name

);

This function sets the layer that a specific node belongs to.

get_managed_objects

EMStatus get_managed_objects(

RWTValSlistRWCString& managed_objects

) const;

This function gets a list of DNs (in ASCII slash format) of the managed objects in the MIT associated with this node.

set_managed_objects

EMStatus set_managed_objects(

const RWTValSlistRWCString& managed_objects

);

This function sets a list of DNs (in ASCII slash format) of the managed objects in the MIT associated with this node.

add_managed_object

EMStatus add_managed_object(

const RWCString& managed_object

);

This function adds a DN (in ASCII slash format) to the list of managed objects in the MIT associated with this node.

remove_managed_object

EMStatus remove_managed_object(

const RWCString& managed_object

);

This function removes a DN (in ASCII slash format) from the list of managed objects in the MIT associated with this node. If managed_object is not in the list, then EMStatus::does_not_exist will be returned.

get_cmip_agents

EMStatus get_cmip_agents(

RWTValSlistEMCmipAgentDn& agents

) const;

This function gets a list of CMIP agents which have managed objects listed as part of managed_objects attribute.

get_snmp_agents

EMStatus get_snmp_agents(

RWTValSlistEMSnmpAgentDn& agents

) const;

This function gets a list of SNMP agents which have managed objects listed as part of managed_objects attribute.

get_rpc_agents

EMStatus get_rpc_agents(

RWTValSlistEMRpcAgentDn& agents

) const;

This function gets a list of RPC agents which have managed objects listed as part of managed_objects attribute.

get_user_data

EMStatus get_user_data(

RWTValSlistEMTopoNode::UserDatum& user_data

) const;

This function gets user-defined data that should contain values for each attribute name listed in EMTopoType::user_data_attribute_names for the type_name of this node.

set_user_data

EMStatus set_user_data(

const RWTValSlistEMTopoNode::UserDatum& user_data

);

This function sets user-defined data that should contain values for each attribute name listed in EMTopoType::user_data_attribute_names for the type_name of this node.

get_user_datum

EMStatus get_user_datum(

const RWCString& attribute_name,

Morf& morf

) const;

This function gets a user-defined datum corresponding to one of the attribute names listed in EMTopoType::user_data_attribute_names for the type_name of this node.

add_user_datum

EMStatus add_user_datum(

const RWCString& attribute_name,const Morf& morf

);

This function adds a user-defined datum for one of the attribute names listed in EMTopoType::user_data_attribute_names for the type_name of this node. If attrib_name is not valid, then EMStatus::Key_not_found is returned.

remove_user_datum

EMStatus remove_user_datum(

const RWCString& attribute_name

);

This function removes a user-defined datum for one of the attribute names listed in EMTopoType::user_data_attribute_names for the type_name of this node. If attrib_name is not valid, then EMStatus::Key_not_found is returned.

get_view_background_image_filename

EMStatus get_view_background_image_filename(

RWCString& filename

) const;

This function gets the absolute pathname of the Sun raster file image to be displayed when the viewer canvas is in logical view mode.

set_view_background_image_filename

EMStatus set_view_background_image_filename(

const RWCString& filename

);

This function set the absolute pathname of the Sun raster file image to be displayed when the viewer canvas is in logical view mode.

get_view_map_config_filename

EMStatus get_view_map_config_filename(

RWCString& filename

) const;

This function gets the absolute pathname of the geographical map configuration (GMC) file to be displayed when the Viewer canvas is in geographical view mode.

set_view_map_config_filename

EMStatus set_view_map_config_filename(

const RWCString& filename

);

This function sets the absolute pathname of the geographical map configuration (GMC) file to be displayed when the Viewer canvas is in geographical view mode.

get_view_default_geo_area

EMStatus get_view_default_geo_area(

EMTopoNode::GeoLocation& center,

double& width_in_km,

RWBoolean& is_null

) const;

This function gets the default geographical area (specified as a center and view width in km) to be displayed when the view_map_config_filename is first displayed.

set_view_default_geo_area

EMStatus set_view_default_geo_area(

const EMTopoNode::GeoLocation& center,

double width_in_km,

RWBoolean is_null = FALSE

);

This function sets the default geographical area (specified as a center and view width in km) to be displayed when the view_map_config_filename is first displayed.

get_monitor_rotation

EMStatus get_monitor_rotation(

long& rotation,

RWBoolean& is_null

) const;

This function gets the number of degrees to rotate the monitor node.

set_monitor_rotation

EMStatus set_monitor_rotation(

long rotation,

RWBoolean is_null = FALSE

);

This function sets the number of degrees to rotate the monitor node.

get_monitor_visible_children

EMStatus get_monitor_visible_children(

RWTValSlistEMTopoNodeDn& children

) const;

This function gets the subset of the children list of nodes that should appear in the monitor sections.

set_monitor_visible_children

EMStatus set_monitor_visible_children(

const RWTValSlistEMTopoNodeDn& children

);

This function sets the subset of the children list of nodes that should appear in the monitor sections.

add_monitor_visible_child

EMStatus add_monitor_visible_child(

const EMTopoNodeDn& child

);

This function adds child to the subset of the children list of nodes that should appear in the monitor sections.

remove_monitor_visible_child

EMStatus remove_monitor_visible_child(

const EMTopoNodeDn& child

);

This function removes child from the subset of the children list of nodes that should appear in the monitor sections.

get_monitor_hidden_children

EMStatus get_monitor_hidden_children(

RWTValSlistEMTopoNodeDn& children

) const;

This function gets the list of children nodes remaining when monitor_visible_children list of nodes are subtracted from the children list of nodes. These nodes do not appear in a monitor section, even if there are empty sections.

get_monitor_max_visible_children

EMStatus get_monitor_max_visible_children(

long& max_children

) const;

This function gets the maximum number of visible children supported by the particular type of monitor.

get_array_orientation

EMStatus get_array_orientation(

ArrayOrientation& orientation

) const;

The get_arrray_orientation function returns the array_orientation attribute in orientation. It returns EMStatus::attribute_not_set if the array_orientation attribute has not been initialized.

set_array_orientation

EMStatus set_array_orientation(

ArrayOrientation orientation

);

The set_arrray_orientation function sets the array_orientation attribute to orientation.

get_array_num_columns

EMStatus get_array_num_columns(

unsigned long& num_columns

) const;

The get_arrray_num_columns function returns the array_num_columns attribute in num_columns. It returns EMStatus::attribute_not_set if the array_num_columns attribute has not been initialized.

set_array_num_columns

EMStatus set_array_num_columns(

unsigned long num_columns

);

The set_arrray_num_columns function sets the array_num_columns attribute to num_columns. If num_columns equals array_num_columns_autosize, then the num_columns is dynamically selected in order to make the array cells layout as close as possible to a square.

get_array_cell_width

EMStatus get_array_cell_width(

unsigned long& cell_width

) const;

The get_arrray_cell_width function returns the array_cell_width attribute in cell_width. It returns EMStatus::attribute_not_set if the array_cell_width attribute has not been initialized.

set_array_cell_width

EMStatus set_array_cell_width(

unsigned long cell_width

);

The set_arrray_cell_width function sets the array_cell_width attribute to cell_width. If cell_width is equal to array_cell_width_autosize, then the cell_width is dynamically adjusted to fit the cell of the cell with the longest label.

get_array_visible_children

EMStatus get_array_visible_children(

RWTValSlistEMTopoNodeDn& children

) const;

The get_arrray_visible_children function returns the array_visible_children attribute in children. It returns EMStatus::attribute_not_set if the array_visible_children attribute has not been initialized.

set_array_visible_children

EMStatus set_array_visible_children(

const RWTValSlistEMTopoNodeDn& children

);

The set_arrray_visible_children function sets the array_visible_children attribute to children.

add_array_visible_child

EMStatus add_array_visible_child(

const EMTopoNodeDn& child

);

The add_arrray_visible_child function adds a node, child, to the array_visible_children attribute. It returns EMStatus::attribute_not_set if the array_visible_children attribute has not been initialized, and EMStatus::already_exists if child is already a member of array_visible_children.

remove_array_visible_child

EMStatus remove_array_visible_child(

const EMTopoNodeDn& child

);

The remove_arrray_visible_child function removes a node, child, from the array_visible_children attribute. It returns EMStatus::attribute_not_set if the array_visible_children attribute has not been initialized, and EMStatus::does_not_exist if child is not a member of array_visible_children.

get_array_hidden_children

EMStatus get_array_hidden_children(

RWTValSlistEMTopoNodeDn& children

) const;

The get_arrray_hidden_children function returns the array_hidden_children attribute in children. It returns EMStatus::attribute_not_set if the array_hidden_children attribute has not been initialized.

get_bus_logical_locations

EMStatus get_bus_logical_locations(

RWTValSlistLocation& logical_locations

) const;

The get_bus_logical_locations function returns the bus_logical_locations attribute in logical_locations. It returns EMStatus::attribute_not_set if the array_visible_children attribute has not been initialized.

set_bus_logical_locations

EMStatus get_bus_logical_locations(

const RWTValSlistLocation& logical_locations

);

The set_bus_logical_locations function sets the bus_logical_locations attribute to logical_locations.

8.15.4 Static Member Functions for Event Subscription

The EMTopoNode class provides an event subscription service so that clients can be notified when a topology node is created, deleted, or modified.

struct EMTopoNodeCallbackData

{

EMEventType event_type;

EMTopoNodeDn node_dn;

EMTopoNode changes;

void* client_data;

};

typedef void (*Callback)(

const EMTopoNodeCallbackData& cbd

);

To register for events, the client must provide a callback function with of type EMTopoNode::Callback. When the client's callback is called, the cbd parameter will be filled in with information about the event. The event_type field indicates the type of event: em_create_event, em_delete_event, or em_change_event. The node_dn parameter uniquely identifies the topology node that was created, deleted, or modified. For em_change_event only, the changes parameter will contain the new values for all attributes which changed. To get a list of the changed attributes, call EMTopoNode::get_active_attributes(). The normal EMTopoNode access methods may be used to get the new attribute values. Finally, the client_data field is the same as the client_data parameter of EMTopoNode::register_callback(). An EMTopoNode events example is $EM_HOME/src/topo_api/topo_events.cc.

void register_callback(

EMEventType event,

Callback callback,

void* client_data

);

Registers callback to be called when event occurs on any topology node. If event equals em_any_event, then callback will be called for any of em_create_event, em_delete_event, or em_change_event. The parameter client_data will be used to initiaze the client_data field in the EMTopoNodeCallbackData struct.

Note – If the same callback has already been registered for the same event, then the callback will not be added a second time. However, the client_data will replace the previous client_data

static void unregister_callback(

EMTopoNode::Callback callback,

void* user_callback_data

);

Removes callback that was previously registered.

8.15.5 Related Global Operators

ostream& operator<<(

ostream& s,

const EMTopoNode& node

);

The stream output operator << is defined to provide an easy way to print out the attribute values of EMTopoNode.

ostream& operator<<(

ostream& s,

const EMTopoTypeDn& dn

);

And the Assignment Operator,

EMTopoNode& operator =(

const EMTopoNode&

);

8.16 EMTopoTypeDn Class

Inheritance: none

#include topo_api/topo_api.hh

An instance of the EMTopoTypeDn class uniquely identifies one topology type out of the set of topology types interfaced by the EMTopoType.

8.16.1 Constants

static const RWCString

EMTopoTypeDn::container,

EMTopoTypeDn::device,

EMTopoTypeDn::link,

EMTopoTypeDn::monitor,

EMTopoTypeDn::array,

EMTopoTypeDn::bus,

EMTopoTypeDn::sun;

Convenience constants for the default base types.

8.16.2 Constructors and Destructor

The default constructor creates a null object.

EMTopoTypeDn();

The following constructor takes the MIS name where the object is stored, and the topology type name.

EMTopoTypeDn(

const RWCString& system_name,

const RWCString& unique_name

);

The default destructor,.

~EMTopoTypeDn();

8.16.3 Operators

The following is the logical equivalence operator:

RWBoolean operator ==(

const EMTopoTypeDn& dn

) const;

Two instances are equal if they have both the same system name and the same unique name or if they are both null.

And the not-operator,

RWBoolean operator !=(

const EMTopoTypeDn& dn

) const;

8.16.4 Access Member Functions

The following are access methods for the EMTopoTypeDn class.

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

The name of the MIS where the topology type is stored.

unique_name

const RWCString& unique_name() const;

void unique_name(

const RWCString& unique_name

);

The name of the topology type. This identifier is unique within a single MIS.

8.16.5 General Member Functions

make_null

void make_null();

Sets to null value. A null value means that the EMTopoTypeDn does not refer to any topology type.

is_null

RWBoolean is_null() const;

And, test for null value. A null value means that the EMTopoTypeDn does not refer to any topology type.

8.17 EMTopoType Class

Inheritance: EMObject

#include topo_api/topo_api.hh

An instance of the EMTopoType class represents a topology type. Every topology node is classified as a particular topology type. The topology types form a hierarchy with the six base types "Container", "Device", "Monitor", "Link", "Array" and "Bus" with other subtypes derived from them. Beyond the standard POC methods which allow you to create, delete, compare, etc. topology types, the EMTopoType class provides the following additional services:

static methods is_container(), is_device(), is_monitor(), is_link(), is_view(), is_array, and is_bus can be used to categorize topology types.

The EM topo type attributes are described in TABLE 8-5.

The attribute key is:

C - Attribute can be set at creation time.
S - Attribute can be set after creation time.
M - Mandatory; attribute must be set for operation to succeed.
X - Allowed; attribute can be set as an option.

TABLE 8-5   EM TopoType Attributes
Attribute Enum C S Description

dn
M
M
Unique identifier.

base_type
M

The parent topology type of this type.

all_base_types

All ancestors of this type.

sub_types

All topology types contained by this type.

legal_children
X
X
List of legal topology types of topology nodes that can be contained by a topology node of this type within the topology hierarchy.

layer_name
M
X
Name of the layer that includes topology nodes of this type.

user_data_attribute_names
X
X
A list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

8.17.1 Example

RWBoolean

create_topo_type(

const RWCString& system_name,

const RWCString& type_name

)

{

EMTopoType type(EMTopoTypeDn(system_name,type_name));

type.set_base_type(EMTopoTypeDn::device);

type.set_layer_name(type_name);

EMStatus status;

if (!(status = type.create_with_all_attributes())) {

cerr << "Error: " << status << endl;

return FALSE;

}

return TRUE;

}

Enum

enum EMTopoType::Attribute {

dn=0,

base_type,

sub_types,

legal_children,

layer_name,

user_data_attribute_names,

num_attributes

};

8.17.2 Constructors and Destructor

EMTopoType(

const EMTopoTypeDn& dn

);

EMTopoType(

const EMTopoType& topo_type

);

The destructor is,

~EMTopoType();

8.17.3 Operators

EMTopoType& operator =(

const EMTopoType& topo_type

);

8.17.4 Access Member Functions

The member function methods of the EMTopoType class refer to the attributes listed in TABLE 8-5. See the table for a description of each of the attributes.

get_dn

EMStatus get_dn(

EMTopoTypeDn& dn

) const;

This function gets the distinguished name, dn, associated with a node.

set_dn

EMStatus set_dn(

const EMTopoTypeDn& dn

);

This function sets the distinguished name, dn, associated with a node.

get_base_type

EMStatus get_base_type(

RWCString& type_name

) const;

This function gets the parent topology type of this type.

set_base_type

EMStatus set_base_type(

const RWCString& type_name

);

This function sets the parent topology type of this type.

get_all_base_types

EMStatus get_all_base_types(

RWTValSlistRWCString& base_types

) const;

This function gets all the ancestors of this type.

get_sub_types

EMStatus get_sub_types(

RWTValSlistRWCString& sub_types

) const;

This function gets all the topology types contained by this type.

get_legal_children

EMStatus get_legal_children(

RWTValSlistRWCString& children

) const;

This function gets a list of legal topology types of topology nodes that can be contained by a topology node of this type within the topology hierarchy.

add_legal_child

EMStatus add_legal_child(

const RWCString& child

);

This function adds child to the list of legal topology types of topology nodes that can be contained by a topology node of this type within the topology hierarchy.

get_layer_name

EMStatus get_layer_name(

RWCString& layer_name

) const;

This function gets the name of the layer that includes topology nodes of this type.

set_layer_name

EMStatus set_layer_name(

const RWCString& layer_name

);

This function sets the name of the layer that includes topology nodes of this type.

get_user_data_attribute_names

EMStatus get_user_data_attribute_names(

RWTValSlistRWCString& names

) const;

This function gets a list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

set_user_data_attribute_names

EMStatus set_user_data_attribute_names(

const RWTValSlistRWCString& names

);

This function sets a list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

add_user_data_attribute_name

EMStatus add_user_data_attribute_name(

const RWCString& name

);

This function adds name to the list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

remove_user_data_attribute_name

EMStatus remove_user_data_attribute_name(

const RWCString& name

);

This function removes name from the list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

8.17.5 Static Member Functions

These methods return TRUE, if type_name is a subtype of the indicated base type.

is_container

static RWBoolean is_container(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the container type.

is_monitor

static RWBoolean is_monitor(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the monitor type.

is_view

static RWBoolean is_view(

const RWCString& type_name

);

This function returns TRUE, if type_name is a view. A type is a view if nodes of the type can contain other nodes, and all the view attributes are supported. For example, all containers and monitors are considered views.

The method is_view() is special because there is no base type named `View'; is_view() is equivalent to is_container() or is_monitor().

is_device

static RWBoolean is_device(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the device type.

is_link

static RWBoolean is_link(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the link type.

is_array

static RWBoolean is_array(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the link type.

is_bus

static RWBoolean is_bus(

const RWCString& type_name

);

This function returns TRUE, if type_name is a subtype of the link type.

8.17.6 Static Member Functions for Event Subscription

The EMTopoType class provides an event subscription service so that clients can be notified when a topology type is created, deleted, or modified.

struct EMTopoTypeCallbackData

{

//

// Note: em_change_event is not supported at this time.

//

EMEventType event_type;

EMTopoTypeDn node_dn

EMTopoNode changes;

void* client_data;

};

typedef void (*Callback)(

const EMTopoTypeCallbackData& cbd

);

To register for events, the client must provide a callback function with of type EMTopoType::Callback. When the client's callback is called, the cbd parameter will be filled in with information about the event. The event_type field indicates the type of event: em_create_event, or em_delete_event.

The node_dn parameter uniquely identifies the topology type that was created, deleted, or modified. For em_change_event only, the changes parameter will contain the new values for all attributes which changed. To get a list of the changed attributes, call EMTopoType::get_active_attributes(). The normal EMTopoType access methods may be used to get the new attribute values. Finally, the client_data field is the same as the client_data parameter of EMTopoType::register_callback().

void register_callback(

EMEventType event,

Callback callback,

void* client_data

);

Registers callback to be called when event occurs on any topology type. If event equals em_any_event, then callback will be called for any of em_create_event, em_delete_event, or em_change_event. The parameter client_data will be used to initiaze the client_data field in the EMTopoTypeCallbackData struct.

Note – If the same callback has already been registered for the same event, then the callback will not be added a second time. However, the client_data will replace the previous client_data

void unregister_callback(

EMEventType event,

EMTopoType::Callback callback

);

Removes callback that was previously registered for event events.

Note – If callback was registered multiple times with different event parameters, the callback will only be removed for this event.

8.17.7 Global Operators

ostream& operator<<(

ostream& s,

const EMTopoType& type

);

The stream output operator << is defined to provide an easy way to print out the attribute values of EMTopoType.

8.18 EMAgent Class

Inheritance: EMObject

#include topo_api/topo_api.hh

The EMAgent class is an abstract class that contains the agent interface, common between EMCmipAgent, EMRpcAgent, and EMSnmpAgent.

Enum

enum EMAgent::Attribute {

operational_state,

administrative_state,

num_attributes

};

enum EMAgent::AdministrativeState {

locked,

unlocked,

shuttingdown,

num_administrative_states

};

Used to suspend and resume the proxy activity relative to the Internet Agent. The EMAgent::unlocked state means that the proxy must continue to perform, or resume performing, proxy activities on behalf of the Internet agent. The EMAgent::locked state means that the proxy must not perform, or suspend performing, proxy activities on behalf of the Internet agent.

enum EMAgent::OperationalState {

disabled,

enabled,

num_operational_states

};

Indicates the perceived state of the Internet agent. The EMAgent::enabled state means that the Internet agent is operational, as perceived by the proxy: it can be reached. The EMAgent::disabled state means that the Internet agent is not operational, as perceived by the proxy; it cannot be reached.

8.18.1 Access Member Functions

get_operational_state

EMStatus get_operational_state(

OperationalState& operational_state

) const;

This function gets the operational state of a component of an equipment from among the managed objects on a network; the possible values are EMAgent::disabled or EMAgent::enabled.

Note – The operational_state is read-only.

get_administrative_state

EMStatus get_administrative_state(

AdministrativeState& administrative_state

) const;

This function gets the administrative state of a component of an equipment from among the managed objects on a network; the possible values are EMAgent::locked, unlocked, or shuttingdown.

set_administrative_state

EMStatus set_administrative_state(

const AdministrativeState& administrative_state

);

This function sets the administrative state of a component of an equipment from among the managed objects on a network; the possible values are EMAgent::locked, unlocked, or shuttingdown.

8.19 EMCmipAgentDn Class

Inheritance: none

#include topo_api/topo_api.hh

An instance of the EMCmipAgentDn class uniquely identifies one rpc agent object out of the set of rpc agent objects interfaced by the EMCmipAgent persistent object class.

8.19.1 Constructors and Destructor

EMCmipAgentDn();

The default constructor creates a null object.

EMCmipAgentDn(

const RWCString& system_name,

const RWCString& unique_name

);

The above constructor takes the MIS name where the object is stored and the CMIP agent name.

~EMCmipAgentDn();

And the default destructor,

8.19.2 Operators

RWBoolean operator ==(

const EMCmipAgentDn& dn

) const;

Two instances are equal if they have both the same system name and the same unique name, or if they are both Null.

RWBoolean operator !=(

const EMTopoNodeDn& dn

) const;

And the not-operator,

8.19.3 Access Member Functions

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

The name of the MIS where the CMIP agent object is stored.

unique_name

const RWCString& unique_name() const;

void unique_name(

const RWCString& unique_name

);

The name of the CMIP agent object. This name is unique within a single MIS.

8.19.4 General Member Functions

make_null

void make_null();

RWBoolean is_null() const;

Sets to null value and tests for null value. A null value means that the EMCmipAgentDn does not refer to any cmip agent object.

8.19.5 Related Global Operators

ostream& operator<<(ostream& s, const EMTopoNodeDn& dn);

The stream output operator << is defined to provide an easy was to print out the value of EMTopoNodeDn.

8.20 EMCmipAgent Class

Inheritance: EMAgent <- EMObject

#include topo_api/topo_api.hh

An instance of the EMCmipAgent class represents the MIS object which contains configuration information for a CMIP agent. The configuration information includes the CMIP MPA hostname and port number, list of managed objects DNs, network SAP, transport selector, presentation selector, session selector, and application entity title (AET).

Note – This class does not provide an interface to the agent's managed objects, but only to Solstice EM's configuration information for the agent.

TABLE 8-6 gives the CmipAgent attributes.

The attribute key is:

C - Attribute can be set at creation time.
S - Attribute can be set after creation time.
M - Mandatory; attribute must be set for operation to succeed.
X - Allowed; attribute can be set as an option.

TABLE 8-6   EMCmipAgent Attributes
Attribute Enum C S Description

dn
M
M
Unique identifier

operational_state

EMAgent::disabled or enabled

administrative_state
M
X
EMAgent::locked, unlocked, or shuttingdown

mpa_address_info
X
X
MPA hostname and port number

agent_address_tag
X
X
Defines format of agent_address_info

agent_address_info
M
X
Agent address information in format defined by agent_address_tag.

managed_objects
M
X
List of DNs in ASCII slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.

application_entity_title
M
X
Application Entity Title (AET).

presentation_selector
M
X
OSI presentation selector.

session_selector
M
X
OSI session selector.

transport_selector
M
X
OSI transport selector.

network_sap
M
X
OSI network sap.

name_translation
X
X
Specifies the format of the managed object instance when sending a request to the CMIP agent. It can be LDN, FDN, or NONE. NONE means FDN. The default value is "NONE".

application_entity_qualifier
X
X
The Application Entity Qualifier. The default value is -1.

application_entity_invoke_id
X
X
The Application Entity Invocation Identifier. The default value is -1.

application_process_invoke_id
X
X
The Application Process Invocation Identifier. The default value is -1.

8.20.1 Example

setup_mis_mis_connection(

const RWCString& manager_hostname,

const RWCString& agent_hostname

)

{

EMCmipAgent cmip_agent(EMCmipAgentDn(manager_hostname,

agent_hostname));

cmip_agent.set_administrative_state(EMAgent::unlocked);

cmip_agent.set_mpa_address_info(agent_hostname,5555);

RWCString managed_object("/systemId=name:\"");

managed_object.append(agent_hostname).append("\"");

cmip_agent.add_managed_object(managed_object);

cmip_agent.set_application_entity_title("objectIdentifier : { 1 2 3 4 }");

cmip_agent.set_presentation_selector("");

cmip_agent.set_session_selector("");

cmip_agent.set_transport_selector("");

char buffer[128];

sprintf(buffer,"%s:%d",agent_hostname,5555);

cmip_agent.set_network_sap(buffer);

// String: {psel,ssel,tsel,nsap}

cmip_agent.set_agent_address_tag(8);

sprintf(buffer,"{,,,%s:%d",agent_hostname,5555);

cmip_agent.set_agent_address_info(buffer);

EMStatus status;

if (!(status = cmip_agent.create_with_all_attributes())) {

cerr << "Error: " << status << endl;

}

}

Enum

enum EMCmipAgent::Attribute {

dn = EMAgent::num_attributes,

mpa_address_info,

agent_address_info,

agent_address_tag,

managed_objects,

application_entity_title,

presentation_selector,

session_selector,

transport_selector,

network_sap,

num_attributes

};

8.20.2 Access Member Functions

This function gets the distinguished name, dn, associated with a node.

The member function methods of the EMCmipAgent class refer to the attributes listed in TABLE 8-6. See the table for a description of each of the attributes.

get_dn

EMStatus get_dn(

EMCmipAgentDn& dn

) const;

This function gets the distinguished name, dn, associated with an agent.

set_dn

EMStatus set_dn(

const EMCmipAgentDn& dn

);

This function sets the distinguished name, dn, associated with an agent.

get_mpa_address_info

EMStatus get_mpa_address_info(

RWCString& hostname,

int& port_number,

RWBoolean& is_null

) const;

This function gets the MPA hostname and port number.

set_mpa_address_info

EMStatus set_mpa_address_info(

const RWCString& hostname,

int port_number,

RWBoolean is_null = FALSE

);

This function sets the MPA hostname and port number.

get_managed_objects

EMStatus get_managed_objects(

RWTValSlistRWCString& dns

) const;

This function gets a list of DNs in slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.

set_managed_objects

EMStatus set_managed_objects(

const RWTValSlistRWCString& dns

);

This function sets a list of DNs in slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.

add_managed_object

EMStatus add_managed_object(

const RWCString& dn

);

This function adds dn to the list of DNs in slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.

remove_managed_object

EMStatus remove_managed_object(

const RWCString& dn

);

This function removes dn from the list of DNs in slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.

get_network_sap

EMStatus get_network_sap(

RWCString& network_sap

) const;

This function gets the OSI network sap.

set_network_sap

EMStatus set_network_sap(

const RWCString& network_sap

);

This function sets the OSI network sap.

get_agent_address_info

EMStatus get_agent_address_info(

RWCString& agent_address_info

) const;

This function gets the agent address information in a format defined by agent_address_tag.

set_agent_address_info

EMStatus set_agent_address_info(

const RWCString& agent_address_info

);

This function sets the agent address information in a format defined by agent_address_tag.

get_agent_address_tag

EMStatus get_agent_address_tag(

int& agent_address_tag

) const;

This function gets the defined format of agent_address_info.

set_agent_address_tag

EMStatus set_agent_address_tag(

int agent_address_tag

);

This function sets the defined format of agent_address_info.

get_presentation_selector

EMStatus get_presentation_selector(

RWCString& presentation_selector

) const;

This function gets the OSI presentation selector.

set_presentation_selector

EMStatus set_presentation_selector(

const RWCString& presentation_selector

);

This function sets the OSI presentation selector.

get_session_selector

EMStatus get_session_selector(

RWCString& session_selector

) const;

This function gets the OSI session selector.

set_session_selector

EMStatus set_session_selector(

const RWCString& session_selector

);

This function sets the OSI session selector.

get_transport_selector

EMStatus get_transport_selector(

RWCString& transport_selector

) const;

This function gets the OSI transport selector.

set_transport_selector

EMStatus set_transport_selector(

const RWCString& transport_selector

);

This function sets the OSI transport selector.

get_application_entity_title

EMStatus get_application_entity_title(

RWCString& application_entity_title

) const;

This function gets the application entity title (AET).

set_application_entity_title

EMStatus set_application_entity_title(

const RWCString& application_entity_title

);

This function sets the application entity title (AET).

get_name_translation

EMStatus get_name_translation(

RWCString& name_translation

) const;

This function gets the format of the managed object instance in a request to the CMIP agent.

set_name_translation

EMStatus set_name_translation(

const RWCString& name_translation

);

This function sets the format of the managed object instance in a request to the CMIP agent.

get_application_entity_qualifier

EMStatus get_application_entity_qualifier(

RWCString& application_entity_qualifier

) const;

This function gets the Application Entity Qualifier.

set_application_entity_qualifier

EMStatus set_application_entity_qualifier(

const RWCString& application_entity_qualifier

);

This function sets the Application Entity Qualifier.

get_application_entity_invoke_id

EMStatus get_application_entity_invoke_id(

int& application_entity_invoke_id

) const;

This function gets the Application Entity Invocation Identifier.

set_application_entity_invoke_id

EMStatus set_application_entity_invoke_id(

int application_entity_invoke_id

);

This function sets the Application Entity Invocation Identifier.

get_application_process_invoke_id

EMStatus get_application_process_invoke_id(

int& application_process_invoke_id

) const;

This function gets the Application Process Invocation Identifier.

set_application_process_invoke_id

EMStatus set_application_process_invoke_id(

int application_process_invoke_id

);

This function sets the Application Process Invocation Identifier.

8.20.3 Global Operators

ostream& operator<<(ostream& s, const EMCmipAgent& agent);

The stream output operator << is defined to provide an easy way to print out the attribute values of EMCmipAgent.

8.21 EMRpcAgentDn Class

Inheritance: none

#include topo_api/topo_api.hh

An instance of the EMRpcAgentDn class uniquely identifies one rpc agent object out of the set of rpc agent objects interfaced by the EMRpcAgent persistent object class.

8.21.1 Constructors and Destructor

The following are constructors:

EMRpcAgentDn();

The default constructor creates a null object.

EMRpcAgentDn(

const RWCString& system_name,

const RWCString& unique_name

);

The above constructor takes the MIS name where the object is stored and the rpc agent name.

~EMRpcAgentDn();

And the default destructor,

8.21.2 Operators

RWBoolean operator ==(

const EMRpcAgentDn& dn

) const;

Two instances are equal if they have both the same system name and the same unique name or if they are both Null.

And the not-operator,

RWBoolean operator !=(

const EMRpcAgentDn& dn

) const;

8.21.3 Access Member Functions

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

The name of the MIS where the rpc agent object is stored.

unique_name

const RWCString& unique_name() const;

void unique_name(

const RWCString& unique_name

);

The name of the rpc agent object. This name is unique within a single MIS.

8.21.4 General Member Functions

make_null

void make_null();

Sets to null value. A null value means that the EMRpcAgentDn does not refer to any rpc agent object.

is_null

RWBoolean is_null() const;

And tests for null value.

8.21.5 Global Operators

ostream& operator<<(ostream& s, const EMRpcAgentDn& dn);

The stream output operator << is defined to provide an easy was to print out the value of EMRpcAgentDn.

8.22 EMRpcAgent Class

Inheritance: EMAgent

#include topo_api/topo_api.hh

<- EMObject

An instance of the EMRpcAgent class represents the MIS object which contains configuration information for an RPC agent. The configuration information includes the read and write community strings, and supported schemas.

This class does not provide an interface to the agent's managed objects, but only to Solstice EM's configuration information for the agent.

TABLE 8-7 gives the EMRpcAgent attributes. The attribute key is:

C - Attribute can be set at creation time.
S - Attribute can be set after creation time.
M - Mandatory; attribute must be set for operation to succeed.
X - Allowed; attribute can be set as an option

TABLE 8-7   EMRpcAgent Attributes
Attribute Enum C S Description

dn
M
M
Unique identifier

operational_state

EMAgent::disabled or enabled

administrative_state
M
X
EMAgent::locked, unlocked, or shuttingdown

get_community_string
X
X
e.g. "public", "private"

set_community_string
X
X
e.g. "public", "private"

schemas
M
X
list of rpc_proxy_hostname and rpc_name pairs, e.g. "ultra-server", "RPC Proxy -ping"

8.22.1 Example

RWBoolean

create_rpc_agent(

const RWCString& system_name,

const RWCString& rpc_agent_name

)

{

EMRpcAgent rpc_agent(EMRpcAgentDn(system_name,

rpc_agent_name));

rpc_agent.set_administrative_state(EMAgent::unlocked);

EMRpcAgent::Schema schema("proxy-hostname",

"RPC Proxy -ping");

rpc_agent.add_schema(schema);

EMStatus status;

if (!(status = rpc_agent.create_with_all_attributes())) {

cerr << "Error: " << status << endl;

return FALSE;

}

return TRUE;

}

enum EMRpcAgent::Attribute {

dn = EMAgent::num_attributes,

get_community_string,

set_community_string,

schemas,

num_attributes

};

Enum

These are the attributes specific to EMRpcAgent, in addition to the attributes defined in EMAgent which are common to EMCmipAgent, EMRpcAgent, and EMSnmpAgent.

Struct

struct EMRpcAgent::Schema

{

RWCString name;

RWCString proxy_hostname;

Schema();

Schema(const RWCString& p_name,

const RWCString& p_proxy_hostname);

RWBoolean operator ==(const Schema& schema) const;

RWBoolean operator !=(const Schema& schema) const;

}

ostream& operator<<(ostream& s, const Schema& schema);

The struct EMRpcAgent::Schema is used to store a RPC proxy hostname and RPC method pairing. Each EMRpcAgent can be configured to support any number of schemas.

8.22.2 Constructors and Destructor

EMRpcAgent(

const EMRpcAgentDn& rpc_agent_dn

);

EMRpcAgent(

const EMRpcAgent& rpc_agent

);

The default destructor,

~EMRpcAgent();

8.22.3 Access Member Functions

The member function methods of the EMRpcAgent class refer to the attributes listed in the table at the beginning of this section, table 6-7. See the table for a description of each attribute.

get_dn

EMStatus get_dn(

EMRpcAgentDn& dn

) const;

This function gets the distinguished name, dn, associated with an agent.

set_dn

EMStatus set_dn(

const EMRpcAgentDn& dn

);

This function sets the distinguished name, dn, associated with an agent.

get_get_community_string

EMStatus get_get_community_string(

RWCString& get_communitry_string

) const;

This function gets the current get_community_string codeword to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

set_get_community_string

EMStatus set_get_community_string(

const RWCString& get_community_string

);

This function sets the current get_community_string codeword to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

get_set_community_string

EMStatus get_set_community_string(

RWCString& set_community_string

) const;

This function gets the current set_community_string codeword to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

set_set_community_string

EMStatus set_set_community_string(

const RWCString& set_community_string

);

This function sets the current set_community_string codeword to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

get_schemas

EMStatus get_schemas(

RWTValSlistEMRpcAgent::Schema& schemas

) const;

This function gets the list of rpc_proxy_hostname and rpc_name pairs, e.g. "ultra-server", "RPC Proxy -ping".

set_schemas

EMStatus set_schemas(

const RWTValSlistEMRpcAgent::Schema& schemas

);

This function sets the list of rpc_proxy_hostname and rpc_name pairs, e.g. "ultra-server", "RPC Proxy -ping".

add_schema

EMStatus add_schema(

const EMRpcAgent::Schema& schema

);

This function adds schema to the list of rpc_proxy_hostname and rpc_name pairs, e.g. "ultra-server", "RPC Proxy -ping".

remove_schema

EMStatus remove_schema(

const EMRpcAgent::Schema& schema

);

This function removes schema from the list of rpc_proxy_hostname and rpc_name pairs, e.g. "ultra-server", "RPC Proxy -ping".

8.22.4 Global Operators

ostream& operator<<(

ostream& s,

const EMRpcAgent& agent

);

The stream output operator << is defined to provide an easy way to print out the attribute values of EMRpcAgent.

The Assignment Operator

EMRpcAgent& operator =(

const EMRpcAgent&

);

8.23 EMSnmpAgentDn Class

Inheritance: none

#include topo_api/topo_api.hh

An instance of the EMSnmpAgentDn class uniquely identifies one snmp agent object out of the set of snmp agent objects interfaced by the EMSnmpAgent persistent object class.

8.23.1 Constructors, and Destructor

The following are constructors for EMSnmpAgentDn

EMSnmpAgentDn();

The default constructor creates a null object.

EMSnmpAgentDn(

const RWCString& system_name,

const RWCString& unique_name

);

The above constructor takes the MIS name where the object is stored and the SNMP agent name.

8.23.2 Operators

RWBoolean operator ==(

const EMSnmpAgentDn& dn

) const;

RWBoolean operator !=(

const EMSnmpAgentDn& dn

) const;

Two instances are equal if they have both the same system name and the same
unique name or if they are both null.

8.23.3 Access Member Functions

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

The name of the MIS where the snmp agent object is stored.

unique_name

const RWCString& unique_name() const;

void unique_name(

const RWCString& unique_name

);

The name of the SNMP agent object which is unique on one MIS. Combined with the system_name, the pair form a globally unique identifier.

8.23.4 General Member Functions

make_null

void make_null();

Sets to null value. A null value means that the EMSnmpAgentDn does not refer to any SNMP agent object.

is_null

RWBoolean is_null() const;

And tests for the null value.

8.23.5 Global Operators

ostream& operator<<(

ostream& s,

const EMSnmpAgentDn& dn

);

The stream output operator<< is defined to provide an easy way to print out the value of EMSnmpAgentDn.

8.24 EMSnmpAgent Class

Inheritance: EMAgent

#include topo_api/topo_api.hh

<- EMObject

An instance of the EMSnmpAgent class represents the MIS object that contains configuration information for an SNMP agent. The configuration information includes the read and write community strings, supported MIBs, and transport address.

Note – This class does not provide an interface to the agent's managed objects, only to Solstice EM's configuration information for the agent.

TABLE 8-8 gives the EMSnmpAgent attributes.

The attribute key is:

C - Attribute can be set at creation time.
S - Attribute can be set after creation time.
M - Mandatory; attribute must be set for operation to succeed.
X - Allowed; attribute can be set as an option.

TABLE 8-8   EMSnmpAgent Attributes
Attribute Enum C S Description

dn
M
M
Unique identifier, which includes the administrative name.

operational_state
X

Possible values are EMAgent::disabled and EMAgent::enabled.

administrative_state
M
X
Possible values are EMAgent::locked, EMAgent::unlocked, or EMAgent::shuttingdown.

system_title
M

OID of system title, e.g. "1.2.3.4".

get_community_string
M
X
e.g. "public" or "private".

set_community_string
M
X
e.g. "public" or "private".

transport_address
M
X
IP address of the system associated with the Internet agent, specified as a string, such as "34.254.129.23". An optional port number may be appended, such as "34.254.129.23:5723".

management_protocol
M

Internet management protocol used by the proxy to manage devices. Possible values are: EMSnmpAgent::snmp_v1 and EMSnmpAgent::snmp_v2.

supported_mibs
M
X
The names of the MIBs that the SNMP agent supports.

access_control_enforcement
< /td> M

Indicates where access control is applied: at the Internet agent, the ISO/Internet proxy, or both. Possible values are EMSnmpAgent::agent, EMSnmpAgent::proxy, or EMSnmpAgent::both.

access_control_mechanism
X

Indicates whether no access control, Internet access control as specified in [SNMPv2SEC], or ISO/CCITT access control as specified in [ISO10164-9] is to be used. Possible values are EMSnmpAgent::no_access_control, EMSnmpAgent::internet, or EMSnmpAgent::iso.

8.24.1 Example

RWBoolean

create_snmp_agent(

const RWCString& system_name,

const RWCString& snmp_agent_name

)

{

EMSnmpAgent snmp_agent(

EMSnmpAgentDn(system_name,snmp_agent_name));

snmp_agent.set_administrative_state(EMAgent::unlocked);

snmp_agent.add_supported_mib("IIMCRFC1213-MIB");

snmp_agent.add_supported_mib("IIMCSUN-MIB");

snmp_agent.set_get_community_string("public");

snmp_agent.set_set_community_string("private");

snmp_agent.set_transport_address("123.234.34.23:2354");

snmp_agent.set_management_protocol(EMSnmpAgent::snmp_v1);

snmp_agent.set_access_control_enforcement(

EMSnmpAgent::agent);

snmp_agent.set_access_control_mechanism(

EMSnmpAgent::internet);

snmp_agent.set_system_title("1.2.3.4");

EMStatus status;

if (!(status = snmp_agent.create_with_all_attributes())) {

cerr << "Error: " << status << endl;

return FALSE;

}

return TRUE;

}

Enum

enum EMSnmpAgent::Attribute {

dn = EMAgent::num_attributes,

system_title,

get_community_string,

set_community_string,

transport_address,

supported_mibs,

management_protocol,

access_control_enforcement,

access_control_mechanism,

num_attributes

};

These are the attributes specific to EMSnmpAgent, in addition to the attribute defined in EMAgent which are common to EMCmipAgent, EMRpcAgent, and EMSnmpAgent.

enum EMSnmpAgent::AccessControlEnforcement {

agent=1,

proxy=2,

both=3,

min_access_control_enforcement = agent,

max_access_control_enforcement = both,

num_access_control_enforcements

};

ostream& operator<<(

ostream& s,

const EMSnmpAgent::AccessControlEnforcement& enforcement

);

enum EMSnmpAgent::AccessControlMechanism {

no_access_control=0,

internet=1,

iso=2,

min_access_control_mechanism = no_access_control,

max_access_control_mechanism = iso,

num_access_control_mechanisms

};

ostream& operator<<(

ostream& s,

const EMSnmpAgent::AccessControlMechanism& mechanism

);

enum EMSnmpAgent::ManagementProtocol {

snmp_v1,

snmp_v2,

num_management_protocols

};

ostream& operator<<(

ostream& s,

const EMSnmpAgent::ManagementProtocol& protocol

);

8.24.2 Constructors and Destructor

EMSnmpAgent(

const EMSnmpAgentDn& snmp_agent_id

);

EMSnmpAgent(

const EMSnmpAgent& snmp_agent

);

And the destructor,

~EMSnmpAgent();

EMSnmpAgent& operator =(

const EMSnmpAgent& other_agent

);

8.24.3 Access Member Functions

The member function methods of the EMSnmpAgent class all refer to the attributes listed in the table at the beginning of this section, TABLE 8-8. See the table for a description of each attribute.

get_dn

EMStatus get_dn(

EMSnmpAgentDn& dn

) const;

This function gets a unique identifier, the distinguished name dn, which includes the administrative name.

set_dn

EMStatus set_dn(

const EMSnmpAgentDn& dn

);

This function sets a unique identifier, the distinguished name dn, which includes the administrative name.

get_system_title

EMStatus get_system_title(

RWCString& system_title

) const;

This function gets the OID of the system, or system title, for example, "1.2.3.4".

set_system_title

EMStatus set_system_title(

const RWCString& system_title

);

This function sets the OID of the system, or system title, for example, "1.2.3.4".

get_get_community_string

EMStatus get_get_community_string(

RWCString& get_communitry_string

) const;

This function gets the current get_community_string to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

set_get_community_string

EMStatus set_get_community_string(

const RWCString& get_community_string

);

This function sets the current get_community_string to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

get_set_community_string

EMStatus get_set_community_string(

RWCString& set_community_string

) const;

This function gets the current set_community_string to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

set_set_community_string

EMStatus set_set_community_string(

const RWCString& set_community_string

);

This function sets the current set_community_string to a component of an equipment from the managed objects on a network, e.g. "public" or "private".

get_transport_address

EMStatus get_transport_address(

RWCString& transport_address

) const;

This function gets the IP address of the system associated with the Internet agent, specified as a string, such as "34.254.129.23". An optional port number may be appended, such as "34.254.129.23:5723".

set_transport_address

EMStatus set_transport_address(

const RWCString& transport_address

);

This function sets the IP address of the system associated with the Internet agent, specified as a string, such as "34.254.129.23". An optional port number may be appended, such as "34.254.129.23:5723".

get_supported_mibs

EMStatus get_supported_mibs(

RWTValSlistRWCString& supported_mibs

) const;

This function gets the names of the MIBs that the SNMP agent supports.

set_supported_mibs

EMStatus set_supported_mibs(

const RWTValSlistRWCString& supported_mibs

);

This function sets the names of the MIBs that the SNMP agent supports.

add_supported_mib

EMStatus add_supported_mib(

const RWCString& supported_mib

);

This function adds supported_mib to the names of the MIBs that the SNMP agent supports.

remove_supported_mib

EMStatus remove_supported_mib(

const RWCString& supported_mib

);

This function removes supported_mib from the names of the MIBs that the SNMP agent supports.

get_management_protocol

EMStatus get_management_protocol(

EMSnmpAgent::ManagementProtocol& management_protocol

) const;

This function gets the Internet management protocol used by the proxy to manage devices. Possible values are EMSnmpAgent::snmp_v1 and EMSnmpAgent::snmp_v2.

set_management_protocol

EMStatus set_management_protocol(

EMSnmpAgent::ManagementProtocol management_protocol

);

This function sets the Internet management protocol used by the proxy to manage devices. Possible values are EMSnmpAgent::snmp_v1 and EMSnmpAgent::snmp_v2.

get_access_control_enforcement

EMStatus get_access_control_enforcement(

EMSnmpAgent::AccessControlEnforcement&

access_control_enforcement

) const;

This function gets and indicates where access control is applied: at the Internet agent, the ISO/Internet proxy, or both. Possible values are EMSnmpAgent::agent, EMSnmpAgent::proxy, or EMSnmpAgent::both.

set_access_control_enforcement

EMStatus set_access_control_enforcement(

EMSnmpAgent::AccessControlEnforcement

access_control_enforcement

);

This function sets and indicates where access control is applied: at the Internet agent, the ISO/Internet proxy, or both. Possible values are EMSnmpAgent::agent, EMSnmpAgent::proxy, or EMSnmpAgent::both.

get_access_control_mechanism

EMStatus get_access_control_mechanism(

EMSnmpAgent::AccessControlMechanism&

access_control_mechanism

) const;

This function gets and indicates whether no access control, Internet access control as specified in [SNMPv2SEC], or ISO/CCITT access control as specified in [ISO10164-9] is to be used. Possible values are EMSnmpAgent::no_access_control, EMSnmpAgent::internet, or EMSnmpAgent::iso.

set_access_control_mechanism

EMStatus set_access_control_mechanism(

EMSnmpAgent::AccessControlMechanism

access_control_mechanism

);

This function sets and Indicates whether no access control, Internet access control as specified in [SNMPv2SEC], or ISO/CCITT access control as specified in [ISO10164-9] is to be used. Possible values are EMSnmpAgent::no_access_control, EMSnmpAgent::internet, or EMSnmpAgent::iso.

8.24.4 Related Global Operators

ostream& operator<<(

ostream& s,

const EMSnmpAgent& agent

);

The stream output operator << is defined to provide an easy way to print out the value of EMSnmpAgent.
¹ For those familiar with C++/OO design, the EMTopoPlatform class uses the Singleton pattern.

Class	Description
EMStatus Class	Reports status, including error
EMIntegerSet Class	Implements a general purpose integer set
EMIntegerSetIterator Class	Provides a convenient method to visit each member of the integer set
EMTopoPlatform Class	Represents the Topology API as a whole
EMObject Class	Specifies the interface supported by all the persistent object classes
EMTopoNodeDn Class	Uniquely Identifies a topology node out of a set of topology node objects
EMTopoTypeDn Class	Uniquely Identifies a topology type out of the set of topology types
EMTopoNode Class	Represents a topology node
EMTopoType Class	Represents a topology type
EMAgent Class	Contains the agent interface common between EMCmipAgent, EMRpcAgent, and EMSnmpAgent
EMCmipAgentDn Class	Identifies one cmip agent object out of the set of cmip agent objects
EMCmipAgent Class	Represents the MIS object which contains configuration information
EMRpcAgentDn Class	Identifies one rpc agent object out of the set of rpc agent objects
EMRpcAgent Class	Represents the MIS object which contains configuration information
EMSnmpAgentDn Class	Identifies one snmp agent object out of the set of snmp agent objects
EMSnmpAgent Class	Represents the MIS object which contains configuration information

Topology API C++ Class	Objects in MIT
EMTopoNode Class	topoNode objects contained under topoNodeDBId=NULL topoView objects contained under topoViewDBId=NULL topoViewNode objects contained under topoViewDBId=NULL/topoNodeId=XX
EMTopoType Class	topoType objects contained under topoTypeDBId=NULL
EMCmipAgent Class	cmipAgent objects contained under agentTableType="CMIP"
EMRpcAgent Class	rpcAgent objects contained under agentTableType="RPC"
EMSnmpAgent Class	cmipsnmpProxyAgent objects contained under internetClassId={ 1 3 6 1 4 1 42 2 2 2 9 2 4 1 0}

cache_view_graph	application type
TRUE	Frequently calls EMTopoPlatform::is_view(), EMTopoPlatform::view_topology_pathnames(), EMTopoPlatform::topology_pathnames(), and/or loads EMTopoNode::view_children, EMTopoNode::topology_pathnames attributes.
FALSE	Does not use the above features or uses them infrequently. Client application should be as lightweight as possible and start up fast.

Attribute Enum	C	S	Description
dn		M	Unique identifier.
name	M	X	Name of this node (need not be unique).
topology_pathnames			List of all topology pathnames for the node. At a minimum, there will be one pathname for each parent. However, since each parent can also have more than one parent, and so on, the actual number of pathnames may be higher. Example list: "/Root/Internet/129.146.74.0/host-45", "/Root/hosts/host-45".
type_name	M	X	Type name of this node.
managed_objects	X	X	List of DNs (in ASCII slash format) of the managed objects in the MIT associated with this node.
cmip_agents	X	X	List of CMIP agents which have managed objects listed as part of managed_objects attribute.
snmp_agents	X	X	List of SNMP agents which have managed objects listed as part of managed_objects attribute.
rpc_agents	X	X	List of RPC agents which have managed objects listed as part of managed_objects attribute.
parents	M	X	List of topology nodes that contain this node in the topology directed acyclic graph (DAG).
children			List of topology nodes that are contained by this node.
view_children			Subset of children whose type_name is a view; that is, EMTopoType::is_view(type_name) returns TRUE.
links	X	X	List of Link topology nodes connected to this node.
propagate_peers	X	X	List of topology nodes for this node's severity propagation if is_severity_attribute is TRUE.
is_severity_propagated	X	X	If TRUE, then the node's propagated_severity will be propagated to each of the nodes in its parent and propagated peers hierarchy, where it will factor in the calculation of their propagated_severity.
state	X	X	Can be used to store an integer value.
severity			If the Alarm Service is running, the severity indicates the highest severity alarm posted against any of the managed_objects. Note: Normally, an application never sets the severity attribute; this attribute is automatically updated from the Alarm Service.
propagated_severity			If the Alarm Service is running, the propagated_severity indicates the highest severity among this node's severity and the propagated_severity of any children of this node who have their is_severity_propagated flag set to TRUE.
display_statuses	X	X	A user-defined list of tags, value pairs, such as { { "CPUUsage", 45 } , { "DiskLoad" , 2345 } }.
geographical_location	X	X	The latitude and longitude in degrees floating-point of the location of this node.
layer_name	X	X	The layer to which this node belongs.
user_data	X	X	User-defined data that should contain values for each attribute name listed in EMTopoType::user_data_attribute_names for the type_name of this node.
logical_locations	X	X	A list of locations where the node appears in each of its parent views.
view_background_image_filename	X	X	Absolute pathname of Sun raster file image to be displayed when the viewer canvas is in logical view mode.
view_map_config_filename	X	X	Absolute pathname of geographical map configuration (GMC) file to be displayed when the Viewer canvas is in geographical view mode.
view_default_geo_area	X	X	Default geographical area (specified as a center and view width in km) to be displayed when the view_map_config_filename is first displayed.
monitor_rotation	X	X	Number of degrees to rotate the monitor node.
monitor_visible_children		X	Subset of the children list of nodes that should appear in the monitor sections.
monitor_hidden_children			List of children nodes remaining when monitor_visible_children list of nodes are subtracted from the children list of nodes. These nodes do not appear in a monitor section, even if there are empty sections.
monitor_max_visible_children			Maximum number of visible children supported by the particular type of monitor.
array_visible_children		X	List of topology nodes which are displayed in an array. This list is a subset of the preexisting children attribute supported by all containers.
array_hidden_children			List of topology nodes which are not displayed in an array. This list is a subset of the preexisting children attribute supported by all containers.
array_orientation	X	X	The orientation of an array, either horizontal or vertical. This indicates whether the topology nodes grouped by the array should be laid down row by row or column by column.
array_num_columns	X	X	The number of columns in an array with horizontal orientation, or the number of rows in an array with vertical orientation.
array_cell_width	X	X	The width (in characters) of each cell in an array. If the value is 0, then the cell width will be set to the minimum width necessary to display the label of the widest cell.
bus_logical_locations	X	X	List of x,y points which define the bus's shape. Note that the points are constrained so that all line segments are alternatingly horizontal or vertical.

Attribute Enum	C	S	Description
dn	M	M	Unique identifier.
base_type	M		The parent topology type of this type.
all_base_types			All ancestors of this type.
sub_types			All topology types contained by this type.
legal_children	X	X	List of legal topology types of topology nodes that can be contained by a topology node of this type within the topology hierarchy.
layer_name	M	X	Name of the layer that includes topology nodes of this type.
user_data_attribute_names	X	X	A list of GDMO attribute names that define the contents of the EMTopoNode::user_data attribute for EMTopoNodes of this type.

Attribute Enum	C	S	Description
dn	M	M	Unique identifier
operational_state			EMAgent::disabled or enabled
administrative_state	M	X	EMAgent::locked, unlocked, or shuttingdown
mpa_address_info	X	X	MPA hostname and port number
agent_address_tag	X	X	Defines format of agent_address_info
agent_address_info	M	X	Agent address information in format defined by agent_address_tag.
managed_objects	M	X	List of DNs in ASCII slash format of managed objects located on agent. Note that the multiple cmip agent configurations can be created for the same cmip MPA but with a different set of managed objects for each.
application_entity_title	M	X	Application Entity Title (AET).
presentation_selector	M	X	OSI presentation selector.
session_selector	M	X	OSI session selector.
transport_selector	M	X	OSI transport selector.
network_sap	M	X	OSI network sap.
name_translation	X	X	Specifies the format of the managed object instance when sending a request to the CMIP agent. It can be LDN, FDN, or NONE. NONE means FDN. The default value is "NONE".
application_entity_qualifier	X	X	The Application Entity Qualifier. The default value is -1.
application_entity_invoke_id	X	X	The Application Entity Invocation Identifier. The default value is -1.
application_process_invoke_id	X	X	The Application Process Invocation Identifier. The default value is -1.

Attribute Enum	C	S	Description
dn	M	M	Unique identifier, which includes the administrative name.
operational_state	X		Possible values are EMAgent::disabled and EMAgent::enabled.
administrative_state	M	X	Possible values are EMAgent::locked, EMAgent::unlocked, or EMAgent::shuttingdown.
system_title	M		OID of system title, e.g. "1.2.3.4".
get_community_string	M	X	e.g. "public" or "private".
set_community_string	M	X	e.g. "public" or "private".
transport_address	M	X	IP address of the system associated with the Internet agent, specified as a string, such as "34.254.129.23". An optional port number may be appended, such as "34.254.129.23:5723".
management_protocol	M		Internet management protocol used by the proxy to manage devices. Possible values are: EMSnmpAgent::snmp_v1 and EMSnmpAgent::snmp_v2.
supported_mibs	M	X	The names of the MIBs that the SNMP agent supports.
access_control_enforcement < /td>	M		Indicates where access control is applied: at the Internet agent, the ISO/Internet proxy, or both. Possible values are EMSnmpAgent::agent, EMSnmpAgent::proxy, or EMSnmpAgent::both.
access_control_mechanism	X		Indicates whether no access control, Internet access control as specified in [SNMPv2SEC], or ISO/CCITT access control as specified in [ISO10164-9] is to be used. Possible values are EMSnmpAgent::no_access_control, EMSnmpAgent::internet, or EMSnmpAgent::iso.

Chapter 8

Topology API

8.1 Topology Classes

8.1.1 General Comments

8.1.2 General Description

8.2 Class Overview

8.2.1 Relationship to the GDMO

8.2.2 Relationship to PMI

8.3 EMTopoPlatform Class

8.3.1 get_attributes_by_mo() EMStatus get_attributes_by_mo( const RWTValSlistRWCString& managed_objects, const EMIntegerSet& attributes, RWTValSlistEMTopoNode& nodes, const RWTValSlistRWCString& system_names = RWTValSlistRWCString() )

8.3.2 set_attributes_by_mo() EMStatus set_attributes_by_mo( const RWTValSlistRWCString& managed_objects, const EMIntegerSet& attributes, const EMTopoNode &reference_node, RWTValSlistEMTopoNode& nodes, const RWTValSlistRWCString& system_names = RWTValSlistRWCString() )

8.4 Persistent Object Classes

8.4.1 EMObject Class

8.4.2 EMObject Member Functions

compare_all_attributes RWBoolean EMTopoNode::compare_all_attributes(const EMTopoNode& peer )

compare_some_attributes RWBoolean EMTopoNode::compare_some_attributes(const EMTopoNode& peer )

8.4.3 EMTopoType Class

8.4.4 EMTopoNode Class

8.4.5 EMSnmpAgent Class

8.4.6 EMCmipAgent Class

8.4.7 EMRpcAgent Class

8.5 Utility Classes

8.5.1 EMIntegerSet Class

8.5.2 EMStatus Class

8.6 Topology API Concepts

8.6.1 Element Naming

8.6.2 Duplicate Topology Node Names

8.6.3 MIS-MIS Awareness

8.6.4 Performance Considerations

8.7 Examples

8.7.1 Makefile

8.7.2 Finding Topology Nodes

8.7.3 Registering Events for EMTopoNode

8.7.4 Printing the Topology Hierarchy

8.8 Class Reference

8.9 EMStatus Class

Static Variables static EMStatus EMStatus::success;

8.9.1 Constructors and Destructor EMStatus(); EMStatus(Code error_code, const RWCString& text); EMStatus(const EMStatus& status); ~EMStatus();

8.9.2 operator RWBoolean () const; Operators

8.9.3 Global Operators ostream& operator<<( ostream& s, const EMStatus& status );

8.10 EMIntegerSet Class

8.10.1 Example

8.10.2 EMIntegerSet (); EMIntegerSet( long n ); EMIntegerSet( long n, RWBoolean initVal ); ~EMIntegerSet (); Constructors and Destructor

8.10.3 Operators

8.10.4 Member Functions

add void add(long number);

remove void remove(long number);

is_member void RWBoolean is_member(long number)const;

num_members void num_members(long num_number);

max_members long max_members() const;

resize void resize(long n);

8.11 EMIntegerSetIterator Class

8.11.2 Constructors and Destructor EMIntegerSetIterator(const EMIntegerSet& set);

8.11.3 Member Functions

next RWBoolean next();

member long member() const;

reset void reset();

8.12 EMTopoPlatform Class

8.12.2 Static Member Functions

initialize static RWBoolean initialize( Platform& platform, RWBoolean cache_view_graph = FALSE );

instance static EMTopoPlatform* instance();

8.12.3 Access Member Functions

system_names RWTValSlistRWCString system_names() const; Platform& platform();

local_system_name const RWCString& local_system_name() const; Platform& platform();

8.12.4 General Member Functions

find_root_nodes EMStatus find_root_nodes( RWTValSlistEMTopoNodeDn& root_nodes, const RWTValSlistRWCString& system_names = RWTValSlist RWCString() ) const;

find_nodes_by_name EMStatus find_nodes_by_name( const RWCString& name, RWTValSlistEMTopoNodeDn& nodes, const RWTValSlistRWCString& system_names = RWTValSlist RWCString() ) const;

find_nodes_by_type EMStatus find_nodes_by_type( const RWCString& type_name, RWTValSlistEMTopoNodeDn& nodes, const RWTValSlistRWCString& system_names = RWTValSlist RWCString() ) const;

find_nodes_by_managed_object EMStatus find_nodes_by_managed_object( const RWCString& managed_object, RWTValSlistEMTopoNodeDn& nodes, const RWTValSlistRWCString& system_names = RWTValSlist RWCString() ) const;

is_view RWBoolean is_view( const EMTopoNodeDn& node_dn ) const;

view_topology_pathnames EMStatus view_topology_pathnames( const EMTopoNodeDn& view_dn, RWTValSlistRWCString& pathnames ) const;

topology_pathnames EMStatus topology_pathnames( const EMTopoNodeDn& parent_dn, const RWCString& name, RWTValSlistRWCString& pathnames ) const;

find_root_types EMStatus find_root_types( RWTValSlistEMTopoTypeDn& types ) const;

find_all_types EMStatus find_all_types( RWTValSlistEMTopoTypeDn& types ) const;

managed_object_to_cmip_agent EMStatus managed_object_to_cmip_agent( const RWCString& managed_object, EMCmipAgentDn& cmip_agent ) const;

managed_object_to_snmp_agent EMStatus managed_object_to_snmp_agent( const RWCString& managed_object, EMSnmpAgentDn& snmp_agent ) const;

managed_object_to_rpc_agent EMStatus managed_object_to_rpc_agent( const RWCString& managed_object, EMRpcAgentDn& rpc_agent ) const;

8.13 EMObject Class

Enum enum EMObjectOperation { em_load, em_create, em_store, em_num_object_operations };

8.13.1 Constructors and Destructor virtual ~EMObject();

8.3.1 get_attributes_by_mo()

EMStatus get_attributes_by_mo(

const RWTValSlistRWCString& managed_objects,

const EMIntegerSet& attributes,

RWTValSlistEMTopoNode& nodes,

const RWTValSlistRWCString&
system_names = RWTValSlistRWCString()

)

8.3.2 set_attributes_by_mo()

EMStatus set_attributes_by_mo(

const RWTValSlistRWCString& managed_objects,

const EMIntegerSet& attributes,

const EMTopoNode &reference_node,

RWTValSlistEMTopoNode& nodes,

const RWTValSlistRWCString&
system_names = RWTValSlistRWCString()

)

compare_all_attributes

RWBoolean

EMTopoNode::compare_all_attributes(const EMTopoNode& peer )

compare_some_attributes

RWBoolean

EMTopoNode::compare_some_attributes(const EMTopoNode& peer )

Static Variables

static EMStatus EMStatus::success;

8.9.1 Constructors and Destructor

EMStatus();

EMStatus(Code error_code,

const RWCString& text);

EMStatus(const EMStatus& status);

~EMStatus();

8.9.2

operator RWBoolean () const;

Operators

8.9.3 Global Operators

ostream& operator<<(

ostream& s,

const EMStatus& status

);

8.10.2

EMIntegerSet ();

EMIntegerSet(

long n

);

EMIntegerSet(

long n,

RWBoolean initVal

);

~EMIntegerSet ();

Constructors and Destructor

add

void add(long number);

remove

void remove(long number);

is_member

void RWBoolean is_member(long number)const;

num_members

void num_members(long num_number);

max_members

long max_members() const;

resize

void resize(long n);

8.11.2 Constructors and Destructor

EMIntegerSetIterator(const EMIntegerSet& set);

next

RWBoolean next();

member

long member() const;

reset

void reset();

initialize

static RWBoolean initialize(

Platform& platform,

RWBoolean cache_view_graph = FALSE

);

instance

static EMTopoPlatform* instance();

system_names

RWTValSlistRWCString system_names() const;

Platform& platform();

local_system_name

const RWCString& local_system_name() const;

Platform& platform();

find_root_nodes

EMStatus find_root_nodes(

RWTValSlistEMTopoNodeDn& root_nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

find_nodes_by_name

EMStatus find_nodes_by_name(

const RWCString& name,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

find_nodes_by_type

EMStatus find_nodes_by_type(

const RWCString& type_name,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

find_nodes_by_managed_object

EMStatus find_nodes_by_managed_object(

const RWCString& managed_object,

RWTValSlistEMTopoNodeDn& nodes,

const RWTValSlistRWCString& system_names =

RWTValSlist RWCString()

) const;

is_view

RWBoolean is_view(

const EMTopoNodeDn& node_dn

) const;

view_topology_pathnames

EMStatus view_topology_pathnames(

const EMTopoNodeDn& view_dn,

RWTValSlistRWCString& pathnames

) const;

topology_pathnames

EMStatus topology_pathnames(

const EMTopoNodeDn& parent_dn,

const RWCString& name,

RWTValSlistRWCString& pathnames

) const;

find_root_types

EMStatus find_root_types(

RWTValSlistEMTopoTypeDn& types

) const;

find_all_types

EMStatus find_all_types(

RWTValSlistEMTopoTypeDn& types

) const;

managed_object_to_cmip_agent

EMStatus managed_object_to_cmip_agent(

const RWCString& managed_object,

EMCmipAgentDn& cmip_agent

) const;

managed_object_to_snmp_agent

EMStatus managed_object_to_snmp_agent(

const RWCString& managed_object,

EMSnmpAgentDn& snmp_agent

) const;

managed_object_to_rpc_agent

EMStatus managed_object_to_rpc_agent(

const RWCString& managed_object,

EMRpcAgentDn& rpc_agent

) const;

Enum

enum EMObjectOperation {

em_load,

em_create,

em_store,

em_num_object_operations

};

8.13.1 Constructors and Destructor

virtual ~EMObject();

exists

virtual RWBoolean exists() const;

create_with_all_attributes

virtual EMStatus create_with_all_attributes();

create_with_some_attributes

virtual EMStatus create_with_some_attributes(

const EMIntegerSet& attributes

);

destroy

virtual EMStatus destroy();

load_all_attributes

virtual EMStatus load_all_attributes();

virtual EMStatus load_some_attributes(

const EMIntegerSet& attributes

);

store_all_attributes

virtual EMStatus store_all_attributes();

store_some_attributes

virtual EMStatus store_some_attributes(

const EMIntegerSet& attributes );

get_active_attributes

virtual void get_active_attributes(

EMIntegerSet& set

) const;

clear_all_attributes

virtual void clear_all_attributes();

clear_some_attributes

virtual void clear_some_attributes(

const EMIntegerSet& set

);

8.13.3 Operators

RWBoolean operator ==(

const EMPOC&

);

Supported by all POC classes

compare_all_attributes

RWBoolean compare_all_attributes(

const EMPOC& other_poc

) const;

compare_some_attributes

RWBoolean compare_some_attributes(

const EMPOC& other_poc,

const EMIntegerSet& attributes

) const;

diff_all_attributes

RWBoolean diff_all_attributes(

const EMPOC& other_agent,

EMIntegerSet& differences

) const;

diff_some_attributes

RWBoolean diff_some_attributes(

const EMPOC& other_agent,

const EMIntegerSet& attributes,

EMIntegerSet& differences

) const;

get_valid_attributes

static const EMIntegerSet& get_valid_attributes(

EMObjectOperation op = em_load

);

get_mandatory_attributes

static const EMIntegerSet& get_mandatory_attributes(

EMObjectOperation op = em_load

);

get_attribute_name

static const RWCString& get_attribute_name(

EMPOC::Attribute attribute

);

Enum

enum NullId {

null_id = -1

};

8.14.2 Operators

RWBoolean operator ==(

const EMTopoNodeDn& dn

) const;

system_name

const RWCString& system_name() const;

void system_name(

const RWCString& system_name

);

unique_id

long unique_id() const;

void unique_id(

long unique_id

);

make_null

void make_null();

is_null

RWBoolean is_null() const;

8.14.5 Related Global Operators

ostream& operator<<(ostream& s, const EMTopoNodeDn& dn);

Enum

enum EMTopoNode::AttributeType {

all_attributes,

common_attributes,

view_only_attributes,

monitor_only_attributes,

link_only_attributes,

device_only_attributes,

array_only_attributes,

bus_only_attributes,

num_attribute_types

};

Structs

struct EMTopoNode::Location

{

long x;

long y;

long z;

Location();

Location(long p_x,long p_y,long p_z=0);

RWBoolean operator == (const Location& l) const;

RWBoolean operator != (const Location& l) const;

ostream& operator<<(ostream& s, const Location& l);

};

8.15.2 Constructors and Destructor

EMTopoNode();

get_dn

EMStatus get_dn(

EMTopoNodeDn& dn

) const;

set_dn

EMStatus set_dn(

const EMTopoNodeDn& dn

);

get_name

EMStatus get_name(

RWCString& name

) const;

set_name

EMStatus set_name(

const RWCString& name

);

get_topology_pathnames

EMStatus get_topology_pathnames(

RWTValSlistRWCString& topology_pathnames

) const;

get_type_name

EMStatus get_type_name(

RWCString& type_name

) const;

set_type_name

EMStatus set_type_name(

const RWCString& type_name

);

get_severity

EMStatus get_severity(

EMTopoNode::Severity& severity

) const;

set_severity

EMStatus set_severity(

EMTopoNode::Severity severity

);

get_propagated_severity

EMStatus get_propagated_severity(

EMTopoNode::Severity& severity

) const;

get_is_severity_propagated

EMStatus get_is_severity_propagated(

RWBoolean& is_severity_propagated

) const;

set_is_severity_propagated

EMStatus set_is_severity_propagated(

const RWBoolean& is_severity_propagated

);

get_propagate_peers

EMStatus get_propagate_peers(

RWTValSlistEMTopoNodeDn& peers

) const;

set_propagate_peers

EMStatus set_propagate_peers(

const RWTValSlistEMTopoNodeDn& peers

);

add_propagate_peer

EMStatus add_propagate_peer(

const EMTopoNodeDn& peer

);