API reason codes

The reason code parameter (Reason) is a qualification to the completion code parameter (CompCode).

If there is no special reason to report, MQRC_NONE is returned. A successful call returns MQCC_OK and MQRC_NONE.

If the completion code is either MQCC_WARNING or MQCC_FAILED, the queue manager always reports a qualifying reason; details are given under each call description.

Where user exit routines set completion codes and reasons, they should adhere to these rules. In addition, any special reason values defined by user exits should be less than zero, to ensure that they do not conflict with values defined by the queue manager. Exits can set reasons already defined by the queue manager, where these are appropriate.

Reason codes also occur in:

  • The Reason field of the MQDLH structure
  • The Feedback field of the MQMD structure

From Version 9.1.0, where multiple client connection attempts are made, for example with a channel with a comma separated connection name and the connection sequence fails, reason codes other than MQRC_HOST_NOT_AVAILABLE and MQRC_STANDBY_Q_MGR are given priority when being returned to an application. In previous versions of the product, the last reason code encountered in the connection sequence is always returned, this could lead to configuration errors such as MQRC_NOT_AUTHORIZED encountered earlier in the connection attempt to not be returned to the application.

Each reason code in its entirety is supported on all the platforms that IBM MQ supports, unless there:

  • Are one or more platform icons at the top of a reason code, in which case that reason code applies only to those platforms shown.
  • Is a platform icon displayed against a specific statement, in which case that statement applies only to that platform.

See platform icons for a description of the icons. The following is a list of reason codes, in numeric order, providing detailed information to help you understand them, including:

  • An explanation of the circumstances that have caused the code to be raised
  • The associated completion code
  • Suggested programmer actions in response to the code

Parent topic: API completion and reason codes