Handling errors in IBM MQ classes for Java

Handle errors arising from IBM 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 an IBM MQ call are not both zero. This simplifies the program logic so that we do not have to check the return codes after each call to IBM MQ. We can decide at which points in your program we want to deal with the possibility of failure. At these points, we 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 IBM 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 an IBM 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. We might want to do this in situations where you expect many exceptions associated with a specific reason code to be thrown, and we do not want the log to be filled with these exceptions. For example, if the 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.

Parent topic: Writing IBM MQ classes for Java applications