WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Error handling in C++

XMS throws an exception when it detects an error while processing a call to a method.

An XMS exception is an object of one of the following types:

The Exception class is a superclass of each of the remaining classes in this list. As a result, an application can include the calls to XMS methods in a try block and, to catch all types of XMS exception, the application can specify the Exception class in the exception declaration of the catch construct. The following code fragment illustrates this technique:

#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])
{
  int nRC = 0;

  try
  {
    xms::ConnectionFactory connFact;
    xms::Connection        conn;

    connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
    connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
    connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
    connFact.setIntProperty(XMSC_RTT_PORT, 1506);

    conn = connFact.createConnection();

    // Other code here
  }
  catch(xms::Exception & ex)
  {
    // Error handling code here

    nRC = -1;
  }

  return(nRC);
}

If an application uses this technique to catch XMS exceptions, it must catch an exception by reference, and not by value. This ensures that an exception is not sliced and that valuable data about the error is not lost.

The Exception class itself is a subclass of the std::exception class. Therefore, to catch all exceptions, including those thrown by the C++ runtime environment, an application can specify the std::exception class in the exception declaration of the catch construct. The following code fragment illustrates this concept:

#include <xms.hpp>

using namespace std;

int main(int argc, char *argv[])
{
  int nRC = 0;

  try
  {
    xms::ConnectionFactory connFact;

    connFact.setIntProperty(XMSC_CONNECTION_TYPE, XMSC_CT_RTT);
    connFact.setIntProperty(XMSC_RTT_CONNECTION_PROTOCOL, XMSC_RTT_CP_TCP);
    connFact.setStringProperty(XMSC_RTT_HOST_NAME, "localhost");
    connFact.setIntProperty(XMSC_RTT_PORT, 1506);

    // Additional code here
  }
  catch(exception & ex)
  {
    // Error handling code here

    nRC = -1;
  }

  return(nRC);
}

After an application catches an XMS exception, it can use the methods of the Exception class to find out information about the error. For the definitions of these methods, see Exception. The information encapsulated by an XMS exception is essentially the same as the information provided to a C application in an error block. For details of this information, see The error block.

XMS can create an exception for each error it detects during a call and link the exceptions to form a chain. After an application has caught the first exception, it can call the getLinkedException() method to get a pointer to the next exception in the chain. The application can continue to call the getLinkedException() method on each exception in the chain until a null pointer is returned, indicating that there are no more exceptions in the chain.

Because the getLinkedException() method returns a pointer to a linked exception, the application must release the object using the C++ delete operator.

The Exception class provides the dump() method, which an application can use to dump an exception, as formatted text, to a specified C++ output stream. The operator << is overloaded on the Exception class and can be used for the same purpose.


Concept topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.