IBM MQ Family

IBM MQ Little Gem #33: Reason Qualifier

By Morag Hughson posted 06-26-2018 06:55

  
This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

IBM MQ has many different "events", that is notifications which it can emit, to tell you about various situations which have occurred. These events are distinguished by a field within the data which contains a reason code which tells you what the event message is about. This reason code sometimes matches the reason code given to an application when the situation occurred, for example MQRC_NOT_AUTHORIZED. Other times it is a reason code which only occurs in an event message, for example MQRC_CHANNEL_STOPPED.

Sometimes this single reason code is not enough to fully describe the event that has happened, and many event messages (as shown in the table below) also contain a Reason Qualifier. This is another integer which helps to more fully describe the event.

Event Reason Event Reason Qualifier
MQRC_BRIDGE_STOPPED MQRQ_BRIDGE_STOPPED_OK
MQRQ_BRIDGE_STOPPED_ERROR
MQRC_CHANNEL_BLOCKED
MQRC_CHANNEL_BLOCKED_WARNING
MQRQ_CHANNEL_BLOCKED_ADDRESS
MQRQ_CHANNEL_BLOCKED_USERID
MQRQ_CHANNEL_BLOCKED_NOACCESS
MQRC_CHANNEL_NOT_AVAILABLE MQRQ_MAX_ACTIVE_CHANNELS
MQRQ_MAX_CHANNELS
MQRQ_SVRCONN_INST_LIMIT
MQRQ_CLIENT_INST_LIMIT
MQRC_CHANNEL_SSL_ERROR MQRQ_SSL_HANDSHAKE_ERROR
MQRQ_SSL_CIPHER_SPEC_ERROR
MQRQ_SSL_PEER_NAME_ERROR
MQRQ_SSL_CLIENT_AUTH_ERROR
MQRC_CHANNEL_SSL_WARNING MQRQ_SSL_UNKNOWN_REVOCATION
MQRC_CHANNEL_STOPPED MQRQ_CHANNEL_STOPPED_OK
MQRQ_CHANNEL_STOPPED_ERROR
MQRQ_CHANNEL_STOPPED_RETRY
MQRQ_CHANNEL_STOPPED_DISABLED
MQRC_NOT_AUTHORIZED MQRQ_CONN_NOT_AUTHORIZED
MQRQ_SYS_CONN_NOT_AUTHORIZED
MQRQ_CSP_NOT_AUTHORIZED
MQRQ_OPEN_NOT_AUTHORIZED
MQRQ_CLOSE_NOT_AUTHORIZED
MQRQ_CMD_NOT_AUTHORIZED
MQRQ_SUB_NOT_AUTHORIZED
MQRQ_SUB_DEST_NOT_AUTHORIZED
MQRC_Q_MGR_ACTIVE MQRQ_FAILOVER_PERMITTED
MQRQ_FAILOVER_NOT_PERMITTED
MQRQ_STANDBY_ACTIVATED
MQRC_Q_MGR_NOT_ACTIVE MQRQ_Q_MGR_STOPPING
MQRQ_Q_MGR_QUIESCING

Reason_Qualifier.jpgThis reason qualifier should not be ignored, and in fact the combination of Reason Code and Reason Qualifier should be treated as the complete reason for the event message being generated.

Example: Channel Stopped

As one example, consider the event emitted when a channel stops, MQRC_CHANNEL_STOPPED. On it's own the Reason Code is useful for updating a console to remove a previous MQRC_CHANNEL_STARTED event, but it hasn't told you the whole story. If you decided to page the administrator just based on the Reason Code, you might be calling him for no reason. If the Reason Qualifier is MQRQ_CHANNEL_STOPPED_OK, then the channel has likely disconnected after a period of inactivity, and will (if configured to do do) re-trigger when it needs to.

Example: Channel Not Available

In older versions of MQ, getting the problem MQRC_CHANNEL_NOT_AVAILABLE was generally due to hitting the MaxChannels limit in the qm.ini file. However in newer versions of MQ, there are various different limits you might hit and the Reason Qualifier indicates which one is was. So if you're using events to raise these limits, make sure to change the correct one.

So remember that there is a lot of data in each event, and the Reason Qualifier is an important piece to take into account.


Morag Hughson is an MQ expert. She spent 18 years in the MQ Devt organisation before taking on her current job writing MQ Technical education courses with MQGem. She also blogs for MQGem. You can connect with her here on IMWUC or on Twitter and LinkedIn.

#Little-Gem
#IBMMQ
#ChampionsCorner
0 comments
34 views

Permalink