WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

Handling errors in C++

If XMS detects an error while processing a call to a method, XMS throws an exception.

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 simply 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);
}

Note that, if an application uses this technique to catch XMS exceptions, the application must catch an exception by reference, and not by value. This ensures that an exception is not sliced and 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 simply specify the std::exception class in the exception declaration of the catch construct. The following code fragment illustrates this point:

#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, the application 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.

If XMS detects more than one error during a call, XMS can create an exception for each error and link the exceptions to form a chain. After an application has caught the first exception, the application 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.

Note that, because the getLinkedException() method returns a pointer to a linked exception, it is the responsibility of the application to 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.

Related concepts
Error conditions that can be handled at run time

Concept topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.