MQ Connectivity problems

Edit online

There are several reasons why you might experience problems when you use MQ Connectivity.

When troubleshooting MQ Connectivity problems, there are a number of tools you can use to diagnose the problem:
  • The destination mapping rule status information. The status of the destination mapping rules is shown in the IBM® IoT MessageSight Web UI on the MQ Connectivity page. Alternatively, you can gather information about the status of the destination mapping rules by using REST Administration APIs. For more information about using REST Administration APIs, see Viewing the status of destination mapping rules by using REST Administration APIs.
  • The imaserver-mqconnectivity.log.
  • The IBM MQ log files.

Has the MQ Connectivity process started?

To create, view or edit queue manager connections and destination mapping rules, the MQ Connectivity process must be started. If the MQ Connectivity process is stopped, you might see an error such as CWLNA5035.

For more information about how to start MQ Connectivity, see Starting, restarting, stopping, and viewing the status of MQ Connectivity.

Is the IBM MQ queue manager or listener stopped?

IBM IoT MessageSight cannot connect to aIBM MQ queue manager if the queue manager or the associated listener is stopped. If the queue manager or the listener is stopped, you might see an error such as CWLNA7011 in the imaserver-mqconnectivity.log. The error might include a reason such as MQRC_Q_MGR_NOT_AVAILABLE if the queue manager is stopped, or MQRC_HOST_NOT_AVAILABLE if the listener is stopped.

You can start the queue manager by using the strmqm command on the IBM MQ system. For more information about strmqm, see strmqm in the IBM MQ documentation.

You can start the listener by using the START LISTENER MQSC command on the IBM MQ system. For more information about START LISTENER, see START LISTENER in the IBM MQ documentation.

Does the IBM MQ queue or topic exist?

IBM IoT MessageSight cannot connect to a IBM MQ queue or topic that does not exist. If IBM IoT MessageSight attempts to connect to a queue or topic that does not exist, you might see an error such as CWLNA7012 in the imaserver-mqconnectivity.log. The error might include a reason such as MQRC_UNKNOWN_OBJECT_NAME.

You can check that the queue exists by using the DISPLAY QUEUE MQSC command on the IBM MQ system. For more information about the DISPLAY QUEUE command, see DISPLAY QUEUE in the IBM MQ documentation.

You can check that the topic exists by using the DISPLAY TOPIC MQSC command on the IBM MQ system. For more information about the DISPLAY TOPIC command, see DISPLAY TOPIC in the IBM MQ documentation.

If the queue or topic exists, check that the name in your destination mapping rule matches the name of the IBM MQ queue or object.

Is the message too large for IBM MQ?

You can set the maximum size of messages that are allowed on a IBM MQ queue manager. You can also set the maximum size of messages that can be transmitted over a server connection channel. If a message is too large for that queue manager or server connection channel, the message does not arrive. The maximum size of a message is determined by the MAXMSGL attribute on the queue manager, and on the server-connection channel. The default value of MAXMSGL is 4,194,304 bytes.

If the message is too large, you might see an error such as CWLNA7010 in the imaserver-mqconnectivity.log.

You can change the MAXMSGL queue manager attribute to increase the maximum size of messages that are allowed on the queue manager. The MAXMSGL attribute can be changed by using the ALTER QMGR MQSC command. For more information, see ALTER QMGR and ALTER CHANNEL, in the IBM MQ documentation.

Has the maximum message limit been reached?

In each destination mapping rule, a maximum message limit is set. This limit defines how many messages can be stored on IBM IoT MessageSight if messages cannot be sent on to IBM MQ. After the limit is reached, any attempts to publish messages to the IBM IoT MessageSight topic in the destination mapping rule fails. After the backlog reduces, messages can be published to IBM IoT MessageSight again.

You must investigate the cause of the message backlog, and ensure that messages are flowing from IBM IoT MessageSight to IBM MQ. If messages are flowing, but the limit is reached, you might want to increase the value of the maximum messages parameter in the destination mapping rule. For more information about editing a destination mapping rule, see Creating and updating a destination mapping rule by using REST Administration APIs. Alternatively, if message order is not important, you might want to use more than one queue manager to handle the volume of messages.

Has the IBM MQ queue depth been reached?

You can set the maximum number of messages that can be put on a IBM MQ queue at any time. If this maximum queue depth is reached, messages cannot be sent. The maximum queue depth is determined by the MAXDEPTH attribute on the queue.

If the queue depth is reached, you might see an error such as CWLNA7010 in the imaserver-mqconnectivity.log. The error might include a reason such as MQRC_Q_FULL.

You can wait for the queue to empty, but you might consider ways to improve performance and make the queue empty faster. For example, you can change the MAXDEPTH attribute by using the ALTER MQSC command on the IBM MQ system. For more information about the ALTER command, see ALTER queues in the IBM MQ documentation.

Is the IBM MQ authority correct?

IBM IoT MessageSight cannot send messages if it is not authorized to use the IBM MQ objects. If the authority is not correct, you might see an error such as CWLNA7011 in the imaserver-mqconnectivity.log. The error might include a reason such as MQRC_NOT_AUTHORIZED.

You can authorize IBM IoT MessageSight to connect to IBM MQ by using the SET CHLAUTH, and SET AUTHREC MQSC commands on the IBM MQ system. For more information about authorizing IBM IoT MessageSight to connect to IBM MQ, see step 6 in Configuring the IBM MQ server connection channel.

Does the IBM IoT MessageSight queue allow concurrent consumers?

If you are using an IBM IoT MessageSight queue with more than one destination mapping rule, and the queue does not allow concurrent consumers, messages cannot be sent. If concurrent consumers are not allowed, you might see an error such as CWLNA7007 in the imaserver-mqconnectivity.log. The error might include a reason such as The destination has too many existing consumers.

You can change the queue to allow concurrent consumers, or you can change the destination mapping rules to use different queues. For more information about changing the queue, see Configuring message queues. For more information about changing the destination mapping rules, see Configuring destination mapping rules.

Is SSL configured correctly?

If you use SSL to secure the connection between IBM IoT MessageSight and IBM MQ, but the connection does not work, check the imaserver-mqconnectivity.log file for errors. You must also check the logs on the IBM MQ server to determine whether the error is occurring on IBM IoT MessageSight, or on IBM MQ.

Common causes of SSL problems on IBM IoT MessageSight include the following causes:
  • The certificate is not in the key repository.
  • The certificate is not valid.
  • The SSL CipherSpec is not correctly defined in the queue manager connection.

Is the IBM MQ heartbeat interval too large?

After you restart IBM IoT MessageSight, you might find a CWLNA7009 error in the logs with reason MQRC_SUBSCRIPTION_IN_USE. This error can occur because the connection between IBM IoT MessageSight and IBM MQ was not yet cleaned up by the queue manager. This error does not mean that MQ Connectivity is not working, only that the connection is not yet cleaned up.

You can use the heartbeat interval setting on the IBM MQ server connection channel to ensure that IBM MQ cleans up the connection in a more timely manner. Alternatively, you can use the keep alive interval. For more information about the heartbeat interval, and the keep alive interval, see Checking that the other end of the channel is still available, in the IBM MQ documentation.

Is there an unwanted durable subscription on IBM MQ?

In some cases, after you disable a destination mapping rule, a durable subscription for that rule can remain on IBM MQ. To remove the subscription, complete the following steps:
  1. Start an MQSC session for the queue manager that is associated with the destination mapping rule by entering the following command:

    runmqsc qmgrName

    Where:
    qmgrName
    Specifies the name of the queue manager that is associated with the destination mapping rule that you want to delete.
  2. List the IBM IoT MessageSight subscriptions by entering the following command:

    display sub(SYSTEM.IMA.*) topicstr

  3. Find the subscription that you want to delete. You can match the value of the TOPICSTR field with the topic string specified in the destination mapping rule. For example, TOPICSTR(/MQ/A1/#).
  4. Delete the subscription by entering the following command:

    delete sub(subName)

    Where:
    subName
    Specifies the name of the subscription. The subscription name is the value that is specified in the SUB field. For example, SUB(SYSTEM.IMA.001641EDA6BB.00000001.00000000.SUB).

Is there an MQRC_NOT_AUTHORIZED error after restarting the queue manager?

It is possible to get an MQRC_NOT_AUTHORIZED error when you attempt to publish or subscribe to a IBM MQ topic at or below a topic node that has a retained message. This error occurs after the queue manager is restarted. To resolve this problem, contact your IBM service representative about the IBM MQ APAR IV45712.

Can the queue manager start the server channel?

It is possible to get the following message in the IBM MQ logs: AMQ9575: Negotiation failed for channel.

This message indicates that the queue manager cannot start the server channel. The cause of this problem might be that the queue manager is running in a CCSID that cannot be converted to the CCSID (819) that is used by the server. To resolve the problem, run the queue manager with a different CCSID.

Is there an MQRC_PUBLICATION_ERROR error on a disabled destination mapping rule?

When you configure IBM MQ topic objects, you decide how IBM MQ responds when it is unable to deliver a message to a subscriber. For more information, see Configuring the IBM MQ server connection channel.

If you configure the topic object such that the message must be delivered to the subscribers, but the message cannot be delivered, the destination mapping rule is disabled. The reason that is shown is MQRC_PUBLICATION_ERROR. This error typically occurs when there is a problem with the subscriber queue. The queue might be full, or the message might be larger than the MAXMSGL attribute of the queue. Investigate the subscriber queue, and re-enable the destination mapping rule.

Does an MQRC_ENVIRONMENT_ERROR error occur when a destination mapping rule is enabled?

When you configure the server-connection channel, specifying a value of zero for the SHARECNV parameter can cause destination mapping rules to fail with IBM MQ reason code 2012 (MQRC_ENVIRONMENT_ERROR) when they are enabled. Ensure that you specify a value of at least 1 for the SHARECNV parameter. For more information, see Configuring the IBM MQ server connection channel.