Error handling

This information describes MQAX object properties, how error handling works, rules describing how raising exceptions are handled, and getting a property.

Each MQAX object includes properties to hold error information and a method to reset or clear them. The properties are:

• CompletionCode
• ReasonCode
• ReasonName

The method is:

• ClearErrorCodes

How error handling works

Your MQAX script or application invokes an MQAX object's method, or accesses or updates a property of the MQAX object:

1. The ReasonCode and CompletionCode in the object concerned are updated.
2. The ReasonCode and CompletionCode in the MQSession object are also updated with the same information. Note: See Threading for restrictions on the use of MQSession error codes in threaded applications.

   If the CompletionCode is greater than or equal to the ExceptionThreshold property of MQSession, MQAX throws an exception (number 32000). Use this within your script using the On Error (or equivalent) statement to process it.

3. Use the Error function to retrieve the associated error string, which has the form:

   MQAX: CompletionCode=xxx, ReasonCode=xxx, ReasonName=xxx
   

   For more information about how to use the On Error statements, see the documentation for your ActiveX scripting language.

   Use the CompletionCode and ReasonCode in the MQSession object is convenient for simple error handlers.

   ReasonName property returns the IBM MQ symbolic name for the current value of the ReasonCode.

Raising exceptions

The following rules describe how raising exceptions are handled:

• Whenever a property or method sets the completion code to a value greater than or equal to the exception threshold (typically set to 2) an exception is raised.
• All method calls and property sets set the completion code.

Get a property

This is a special case because the CompletionCode and ReasonCode are not always updated:

• If a property get succeeds, the object and MQSession object ReasonCode and CompletionCode remain unchanged.
• If a property get fails with a CompletionCode of warning, the ReasonCode and CompletionCode remain unchanged.
• If a property get fails with a CompletionCode of error, the ReasonCode and CompletionCode are updated to reflect the true values, and error processing proceeds as described.

The MQSession class has a method ReasonCodeName which might be used to replace an IBM MQ reason code with a symbolic name. This is especially useful while developing programs where unexpected errors might occur. However, the name is not ideal for presentation to users.

Each class also has a property ReasonName, that returns the symbolic name of the current reason code for that class.