Solstice Enterprise Manager 4.1 Developing C++ Applications

Chapter 3

Enabling Applications to Access Managed Objects

To manage a network, the applications you develop must have access to current data about managed resources. In the Solstice EM environment, managed resources are represented as managed objects. Access to managed objects is provided by a management information server (MIS). The MIS is a repository for all management data and functions. It makes information about managed objects available to its clients, both applications and services. Your applications access the MIS by connecting to it through an application programming interface (API) called the Portable Management Interface (PMI). The MIS then makes information about managed objects available to your applications and their users. For more information about the MIS, refer to the Management Information Server (MIS) Guide.

This chapter explains how to enable your management applications to access managed objects stored in an MIS.

• Section 3.1 Connecting to an MIS
• Section 3.2 Disconnecting From an MIS
• Section 3.3 Bypassing the MIS to Access Solstice EM Databases

3.1 Connecting to an MIS

In the Solstice EM environment, managed objects are accessed through an MIS. To gain access to managed objects, an application must connect to the MIS.

To enable an application to connect to an MIS, use the Platform class of the Portable Management Interface (PMI). An instance of the Platform class represents a connection from an application to an MIS, and contains all the information about the MIS that the application requires.

Enabling an application to connect to an MIS involves:

• Creating and initializing an instance of the Platform class
• Calling the connect function of the Platform class

3.1.1 Creating and Initializing an Instance of the Platform Class

To connect to an MIS, an application must instantiate and initialize an instance of the Platform class. When you call the constructor of the Platform class, you must specify the platform type.

---

Note – The only supported platform type is duEM.

---

Code for creating and initializing an instance of the Platform class is shown in CODE EXAMPLE 3-1.

CODE EXAMPLE 3-1   Creating and Initializing a Platform Instance 

... #include <pmi/hi.hh>       // High Level PMI ... Platform plat;             // Create instance ... plat = Platform(duEM);    // Initialize instance ...

---

Note – The constructor of the Platform class does not throw an exception if the attempt to initialize the instance of Platform fails. If you want to check for errors during initialization, use the get_error_type function as described in Section 4.1.2 Using the get_error_type Function.

---

3.1.2 Calling the connect Function of the Platform Class

After creating and initializing an instance of the Platform class, you need to call the connect function of the Platform class to establish a connection between your application and an MIS. In the call to the connect function, you must specify:

• The location of the MIS. This location is the host name of the machine on which the MIS is running.
• The name of your application. When a user runs your application, the Access Control module verifies that the user has permission to access the MIS by using that application. For more information on access control, refer to Chapter 12.

Code for connecting to an MIS and checking for connection errors is shown in CODE EXAMPLE 3-2.

CODE EXAMPLE 3-2   Calling the connect Function 

... #include <pmi/hi.hh>       // High Level PMI ... if (!plat.connect("a101", "simplemanager")) {     cout << "Failed to connect to " << "a101" << endl;     cout << plat.get_error_string() << endl; } ...

In this example, the location of the MIS is specified by the host name a101. The name of the application is simplemanager. If the connection fails, the error message returned by get_error_string is displayed. For more details on error handling, refer to Chapter 4.

3.2 Disconnecting From an MIS

An application is automatically disconnected when it exits, or when the MIS that it is connected to is shut down. Therefore, in most cases you do not need to provide code for disconnecting your applications from an MIS.

If you want your application to continue running after disconnecting itself from the MIS, include in the application a call to the disconnect function of the Platform class. For example, if you are developing an application that monitors a piece of equipment across a modem line and you want to make most efficient use of the modem connection, you can enable the application to:

• Connect to an MIS
• Gather information from the MIS
• Disconnect from the MIS
• Process the information it has gathered from the MIS
• Reconnect to the MIS when it needs to gather information again

If you want your application to perform a specific operation when it is disconnected from the MIS, enable your application to handle events that indicate that the application is disconnected. For information on how to enable an application to handle events, refer to Chapter 7.

Code for disconnecting from the MIS and checking for disconnection errors is shown in CODE EXAMPLE 3-3.

CODE EXAMPLE 3-3   Calling the disconnect Function 

... #include <pmi/hi.hh>       // High Level PMI ... if (!plat.disconnect()) {     cout << "Failed to disconnect" << endl; } ...

---

Caution – When your application calls the disconnect function, instances of all PMI classes are destroyed. All metadata cached in your application is also destroyed. Make sure that your application does not reference any of the PMI instances or metadata after they have been destroyed. Any attempt to reference an instance or metadata that has been destroyed will cause your application to fail.

---

3.3 Bypassing the MIS to Access Solstice EM Databases

The MIS is a repository for all management data and functions. It makes data about managed objects available to applications. Managed object data are stored in a number of databases, which the MIS communicates with. Different services are associated with different databases, depending on the type of managed objects stored in a database. For example, the log service is associated with the database that stores log objects.

Normally, applications access Solstice EM databases through the MIS. You can bypass the MIS to access Solstice EM databases directly if you want to gain direct access to log record data.

Bypassing the MIS involves:

• Getting information required for a database connection
• Passing database information to a database application development tool

3.3.1 Getting Information Required for a Database Connection

To connect directly to a database, an application requires information on the database. To get the information your application needs to connect to a database, use the EMDBConnectInfo class. The EMDBConnectInfo class represents all the information about the database that an application requires.

Getting information required for a database connection involves:

• Creating and initializing an instance of the EMDBConnectInfo class
• Calling functions of the EMDBConnectInfo class

3.3.1.1 Creating and Initializing an Instance of the EMDBConnectInfo Class

To get the information it requires, an application must create and initialize an instance of the EMDBConnectInfo class. When you call the constructor of the EMDBConnectInfo class, you must specify:

• The location of the database server. This location is the host name of the machine on which the database server is running.
• The service associated with log objects in the database. This service must be specified as LOG_SVC.

  ---

  Note – The only service supported is the log service.

  ---

Code for creating and initializing an instance of the EMDBConnectInfo class is shown in CODE EXAMPLE 3-4.

CODE EXAMPLE 3-4   Creating and Initializing an Instance of the EMDBConnectInfo Class 

... #include <dbapi/dbcon.hh> ...     RWCString misname("indus");     //Create the database connection object     EMDBConnectInfo conn_info(misname,EMDBConnectInfo::LOG_SVC); ...

In this example, the location of the database server is specified by the host name indus. The service associated with log objects in the database is specified as LOG_SVC.

3.3.1.2 Calling Functions of the EMDBConnectInfo Class

Once you have created and initialized an instance of the EMDBConnectInfo class, call functions of the EMDBConnectInfo class to obtain information about the database you want to connect to. Exactly which information is needed depends on the function you call to connect to the database.

Use the functions of the EMDBConnectInfo class listed in TABLE 3-1 to get information you need. By using these functions to get the required information, you make your code for connecting to a database independent of the implementation of the database.

TABLE 3-1   Functions for Getting Information About a Database 

Information	Function
The name of the dynamic library that Rogue Wave Software DBTools.h++ uses for interacting with the database, for example librwinf.so. This library depends on the database server that Solstice EM uses internally. Use the get_server_type function only with the Rogue Wave Software DBTools.h++ database application development tool.	get_server_type
The host name of the database server.	get_server_name
The database user name as defined by the database administrator. This is not necessarily the user's UNIX user name.	get_user_name
The database user's password.	get_user_password
The database name.	get_database_name
The database user's role as defined by the database administrator.	get_role
The status of the EMDBConnectInfo object. It is 0 if the object is valid and -1 if it is invalid.	get_status

For an example of how these functions are called, refer to CODE EXAMPLE 3-5.

3.3.2 Passing Database Information to a Database Application Development Tool

When you have obtained the information you need, pass it to a database application development tool (for example, Rogue Wave Software DBTools.h++) to connect your application to the database.

CODE EXAMPLE 3-5 shows code for getting information about a Solstice EM database and passing that information to a function for connecting to a database.

CODE EXAMPLE 3-5   Connecting to a Solstice EM Database 

...     //Use the connection information to connect to database     RWDBDatabase aDB = RWDBManager::database (         conn_info.get_server_type(),         conn_info.get_server_name(),         conn_info.get_user_name(),         conn_info.get_user_password(),         conn_info.get_database_name()         ); ...

In this example, the static function database of the Rogue Wave Software DBTools.h++ class RWDBManager is called to establish a connection between the application and a database. The database function requires the following information:

• The database server type
• The host name of the database server
• The database user name
• The database user's password
• The database name

3.3.3 Example Database Connection Program

An example program for getting information directly from the Solstice EM database is shown in CODE EXAMPLE 3-6.

CODE EXAMPLE 3-6   Getting Information Directly From a Solstice EM Database 

// Copyright 18 Aug 1999 Sun Microsystems, Inc. All Rights Reserved. #pragma ident "@(#)dbapi_example.cc 1.5 99/08/18 Sun Microsystems" // // Purpose: To get all the log names from the database. // // How:    It uses DB Connection API to get connect information and //         DBTools.h++ to retreive the log names. // // Syntax: dbapi_example // #include <rw/cstring.h> #include <rw/db/dbmgr.h> #include <rw/db/db.h> #include <dbapi/dbcon.hh> #include <pmi/hi.hh> main() {     RWCString misname("indus");     //Create the database connection object     EMDBConnectInfo conn_info(misname,EMDBConnectInfo::LOG_SVC);     if(conn_info.get_status() == -1)     {         cout << "Could not get connection information" << endl;         exit(1);     }     //Use the connection information to connect to database     RWDBDatabase aDB = RWDBManager::database (         conn_info.get_server_type(),         conn_info.get_server_name(),         conn_info.get_user_name(),         conn_info.get_user_password(),         conn_info.get_database_name()         );     RWDBTable table = aDB.table("log");     // Create the selector to get log names.     //--------------------------------------     RWDBSelector anEmSelector = aDB.selector();     anEmSelector << table["logid"];     anEmSelector.where(table["logidtype"] == "string");     RWDBReader rdr = anEmSelector.reader();     RWCString logname;     while(rdr())     {         rdr >> logname;         cout << "Logid: " << logname << endl;     } }

In this example, the application connects directly to a database containing managed objects associated with the log service. The application then extracts from the database the identifier of each log object and displays it.