IBM® MQ and error code relationships

The IBM® MQ adapter returns various error codes when it encounters a problem during code execution. Some of these error codes are related to the errors returned by the MQ calls (such as MQCONN, MQGET) and some of them are not.

The following table lists all MQ calls made by the adapter, and how errors from these calls are mapped to error codes:

IBM® MQ Native Function

Action Taken by Adapter

MQCONN

If MQCONN fails while trying to connect to the queue manager specified in the -QMN adapter command, the error code returned by the adapter is MPIRC_E_BAD_CONNECTION (-13). However, if MQCONN fails while trying to connect to the error queue manager specified by the -EQMN adapter command, the adapter returns error code MPIRC_E_MQS_EQUEUE_OPERATION (-1013) to indicate that the error occurred while transferring messages to the error queue.

MQOPEN

If MQOPEN fails while trying to open the queue specified in the -QN adapter command, the error code returned by the adapter is MPIRC_E_MQS_OPEN_QUEUE (-1003). However, if MQOPEN fails while trying to open the error queue specified by the -EQMN adapter command, the error code returned by the adapter is MPIRC_E_MQS_EQUEUE_OPERATION (-1013) to indicate that the error occurred while transferring messages to the error queue. Additionally, if the MQOPEN call issued for opening the queue manager object fails (this is done as part of the connection validation process), the returned error code is MPIRC_E_BAD_CONNECTION (-13) to indicate to the Resource Manager that the connection is invalid.

MQGET

If MQGET call fails and this error cannot be corrected or handled by the adapter, the adapter returns error code MPIRC_E_MQS_GET_MESSAGE (-1005). Additionally, if MQGET call fails inside of the listener thread, and the MQ reason code is MQRC_CONNECTION_BROKEN (2009L), the adapter returns error code MPIRC_E_BAD_CONNECTION (-13) to signal that the connection is broken and needs to be reestablished.

MQPUT

If MQPUT call fails and this error cannot be corrected or handled by the adapter, the adapter returns error code MPIRC_E_MQS_PUT_MESSAGE (-1004).

MQCMIT

If MQCMIT call fails while committing the messages upon successful map completion, the adapter returns error code MPIRC_E_MQS_COMMIT (-1009).

MQBACK

The adapter does not return an error code as a result of MQBACK failure. This is because if the MQBACK is called, that means that the map has already failed for another reason.

MQBEGIN

This function is called only when the global transactions are used (-GTX adapter command). If MQBEGIN fails, the adapter returns MPIRC_E_MQS_BEGIN_GTX (-1007). On NonStop ZLE, if the BEGINTRANSACTION() call fails, the adapter returns error code MPIRC_E_MQS_BEGINUOW_ERR (-1014).

MQCLOSE

A failure in MQCLOSE does not cause the map to fail (but a textual message indicating this will be traced). The only time a failure in MQCLOSE results in an error code returned by the adapter, is when the queue manager connection is being validated. If MQCLOSE fails for the previously opened queue manager object for validation, the adapter returns error code MPIRC_E_BAD_CONNECTION (-13).

MQDISC

If MQDISC fails, the returned error code is MPIRC_E_MQS_DISCONNECT (-1006).

MQINQ

If MQINQ fails, the adapter does not return any error.

MQCONNX

If MQCONNX fails while trying to connect to the remote queue manager specified in the (-QMN) adapter command, the error code returned by the adapter is MPIRC_E_BAD_CONNECTION (-13). Note that the MQCONNX command is used only by the IBM® MQ (client) adapter, and only if the (-CD) adapter command is specified.

MQPUT1, MQSET

Not used by the adapter.