Solstice Enterprise Manager 4.1 Developing C++ Applications

Chapter 4

Handling Errors

Users need to know when an attempted network management operation has failed. By providing accurate information on why the operation failed, your applications can ease a user's work by indicating the corrective action required when problems occur.

This chapter explains how to handle errors in your applications.

• Section 4.1 Testing for the Success a Function Call
• Section 4.2 Providing Error Information to Users

4.1 Testing for the Success a Function Call

To provide accurate diagnostic information, test for the success of any function call that may, in some circumstances, fail to return the desired result. Solstice EM enables you to test for the success of a function call by:

• Using the overloaded NOT operator. Use the overloaded NOT operator only when the return value indicates if the function call achieved the desired result.
• Using the get_error_type function. Use the get_error_type function when the return value does not indicate if the function call achieved the desired result, for example, with constructors.

  ---

  Note – Use the get_error_type function only for synchronous operations. To test for the success of an asynchronous operation, use the get_except function of the Waiter class as explained in Section 8.4.1 Verifying the Result of an Asynchronous Operation.

  ---

4.1.1 Using the Overloaded NOT Operator

Most PMI classes contain an overloaded NOT (!) operator to simplify error checking. The overloaded NOT operator provides a shorthand means to verify that the result of a function call is the desired one. Use the overloaded NOT operator only when the return value indicates if the function call achieved the desired result. For example, any function that returns a Result is suitable for use with the overloaded NOT operator.

Code for checking for errors by using the overloaded NOT operator is shown in CODE EXAMPLE 4 -1.

CODE EXAMPLE 4-1   Using the Overloaded NOT Operator for Error Checking 

... #include <pmi/hi.hh>       // High Level PMI ... Image image("/sytemId='test'"); ... if (!image.boot()) {     cout << image.get_error_string() << endl; } ...

In this example, the overloaded NOT (!) operator acts on the call to boot to verify that the Image instance was activated. If it was not activated, the get_error_string function is called and the error string returned is displayed. The Image class inherits the get_error_string function from the Error class.

4.1.2 Using the get_error_type Function

For some function calls, it is not possible to use the overloaded NOT operator to verify that the result of the function call is the desired one. For example, you cannot use the overloaded NOT operator for constructors because their return values do not indicate whether the attempt to instantiate an object was successful.

In such cases, use the get_error_type function of the Error class to verify that the result of the function call is the desired one. Many of the classes of the Solstice EM APIs are derived from the Error class, enabling you to use the get_error_type function to test for the success of Solstice EM API function calls.

The get_error_type function returns an enumerated error type. The list of possible error types is given in the /opt/SUNWconn/em/include/pmi/error.hh file.

Code for checking for errors by using the get_error_type function is shown in CODE EXAMPLE 4- 2.

CODE EXAMPLE 4-2   Using the get_error_type Function for Error Checking 

... #include <pmi/hi.hh>       // High Level PMI ... Image im = Image("/systemId=\"test\""); if (im.get_error_type() != PMI_SUCCESS) { cout << im.get_error_string() << endl; } ...

In this example, the get_error_type function verifies that the attempt to instantiate the Image class is successful. If the attempt is unsuccessful, the get_error_string function is called and the error string returned is displayed. The Image class inherits the get_error_type and get_error_string functions from the Error class.

4.2 Providing Error Information to Users

When you check for errors, use the error-handling functions provided by Solstice EM to obtain information on the error and present that information to the user.

The error-handling functions of Solstice EM are provided by the Error class of the high-level PMI. Many of the classes of the Solstice EM APIs are derived from the Error class, enabling you to use a set of common functions for handling errors related to Solstice EM API calls. Using a common set of error-handling functions enables your applications to provide error checking that is simple and consistent for all Solstice EM API calls.

---

Note – Use the error-handling functions provided by the Error class only for synchronous operations. To obtain information on why an asynchronous operation failed, use functions of the ExceptionType class as explained in Section 8.4.1 Verifying the Result of an Asynchronous Operation.

---

CODE EXAMPLE 4 -1 and CODE EXAMPLE 4- 2 show how to use the get_error_string function of the Error class to display the reason a function call did not succeed.