Handling errors in WebSphere MQ classes for Java

Handle errors arising from WebSphere® MQ classes for Java using Java try and catch blocks.

Methods in the Java interface do not return a completion code and reason code. Instead, they throw an exception whenever the completion code and reason code resulting from a WebSphere MQ call are not both zero. This simplifies the program logic so that you do not have to check the return codes after each call to WebSphere MQ. You can decide at which points in your program you want to deal with the possibility of failure. At these points, you can surround your code with try and catch blocks, as in the following example:


try {
    myQueue.put(messageA,putMessageOptionsA);
    myQueue.put(messageB,putMessageOptionsB);
}
catch (MQException ex) {
    // This block of code is only executed if one of
    // the two put methods gave rise to a non-zero
    // completion code or reason code.
    System.out.println("An error occurred during the put operation:" +
                          "CC = " + ex.completionCode +
                          "RC = " + ex.reasonCode);
    System.out.println("Cause exception:" + ex.getCause() );
}

The WebSphere MQ call reason codes reported back in Java exceptions for z/OS are documented in Reason codes for z/OS and Reason codes for all other platforms.

Exceptions that are thrown while a WebSphere MQ classes for Java application is running are also written to the log. However, an application can call the MQException.logExclude() method to prevent exceptions associated with a specific reason code from being logged. You might want to do this in situations where you expect many exceptions associated with a specific reason code to be thrown, and you do not want the log to be filled with these exceptions. For example, if your application attempts to get a message from a queue each time it iterates around a loop and, for most of these attempts, you expect no suitable message to be on the queue, you might want to prevent exceptions associated with the reason code MQRC_NO_MSG_AVAILABLE from being logged. If an application has previously prevented exceptions associated with a specific reason code from being logged, it can allow these exceptions to be logged again by calling the method MQException.logInclude().

Sometimes the reason code does not convey all details associated with the error. For each exception that is thrown, an application should check the linked exception. The linked exception itself might have another linked exception, and so the linked exceptions form a chain leading back to the original underlying problem. A linked exception is implemented by using the chained exception mechanism of the java.lang.Throwable class, and an application obtains a linked exception by calling the Throwable.getCause() method. From an exception that is an instance of MQException, MQException.getCause() retrieves the underlying instance of com.ibm.mq.jmqi.JmqiException, and getCause from this exception retrieves the underlying java.lang.Exception that caused the error.

By default, the MQException class automatically streams exceptions to System.err, which typically is directed to the console. If you want to stop exceptions appearing on the console, include a line in your application to set MQException.log=null.