Determining problems with applications, commands and messages

If you encounter problems with IBM MQ applications, commands, and messages, there are a number of questions that we can consider to help you determine the cause of the problem.

Use the following questions as pointers to help you to identify the cause of the problem:

Are some of our queues working?

1. Display the information about this queue, using WRKMQMQSTS or DSPMQMQ.
2. Use the data displayed to do the following checks:
   • If CURDEPTH is at MAXDEPTH, the queue is not being processed. Check that all applications are running normally.
   • If CURDEPTH is not at MAXDEPTH, check the following queue attributes to ensure that they are correct:
     • If triggering is being used:
       • Is the trigger monitor running?
       • Is the trigger depth too large?
       • Is the process name correct?

     • Can the queue be shared? If not, another application might already have it open for input.
     • Is the queue enabled appropriately for GET and PUT?

   • If there are no application processes getting messages from the queue, determine why (for example, because the applications must be started, a connection has been disrupted, or because the MQOPEN call has failed for some reason).

If we cannot solve the problem, contact the IBM support center for help.

Does the problem affect only remote queues?

1. Check that the programs that should be putting messages to the remote queues have run successfully.
2. If we use triggering to start the distributed queuing process, check that the transmission queue has triggering set on. Also, check that the trigger monitor is running.
3. If necessary, start the channel manually. See Distributed queuing and clusters.
4. Check the channel with a PING command.

Are messages failing to arrive on the queue?

• Have you selected the correct queue manager, that is, the default queue manager or a named queue manager?
• Has the message been put on the queue successfully?
  • Has the queue been defined correctly, for example, is MAXMSGLEN sufficiently large?
  • Can applications put messages on the queue (is the queue enabled for putting)?
  • If the queue is already full, it might mean that an application was unable to put the required message on the queue.

• Can you get the message from the queue?
  • Must you take a sync point?

    If messages are being put or retrieved within sync point, they are not available to other tasks until the unit of recovery has been committed.

  • Is your timeout interval long enough?
  • Are you waiting for a specific message that is identified by a message identifier or correlation identifier (MsgId or CorrelId)?

    Check that we are waiting for a message with the correct MsgId or CorrelId. A successful MQGET call sets both these values to that of the message retrieved, so you might need to reset these values in order to get another message successfully.

    Also check if we can get other messages from the queue.

  • Can other applications get messages from the queue?
  • Was the message we are expecting defined as persistent?

    If not, and IBM MQ for IBM i has been restarted, the message has been lost.

If we cannot find anything wrong with the queue, and the queue manager itself is running, make the following checks on the process that you expected to put the message on to the queue:

• Did the application start?

  If it should have been triggered, check that the correct trigger options were specified.

• Is a trigger monitor running?
• Was the trigger process defined correctly?
• Did it complete correctly?

  Look for evidence of an abnormal end in the job log.

• Did the application commit its changes, or were they backed out?

If multiple transactions are serving the queue, they might occasionally conflict with one another. For example, one transaction might issue an MQGET call with a buffer length of zero to find out the length of the message, and then issue a specific MQGET call specifying the MsgId of that message. However, in the meantime, another transaction might have issued a successful MQGET call for that message, so the first application receives a completion code of MQRC_NO_MSG_AVAILABLE. Applications that are expected to run in a multi-server environment must be designed to cope with this situation.

Consider that the message might have been received, but that the application failed to process it in some way. For example, did an error in the expected format of the message cause your program to reject it? If so, see Are unexpected messages received when using distributed queues?.

Do messages contain unexpected or corrupted information?

• Has the application, or the application that put the message on to the queue, changed?

  Ensure that all changes are simultaneously reflected on all systems that need to be aware of the change.

  For example, a copyfile formatting the message might have been changed, in which case, recompile both applications to pick up the changes. If one application has not been recompiled, the data appears corrupted to the other.

• Is an application sending messages to the wrong queue?

  Check that the messages the application is receiving are not intended for an application servicing a different queue. If necessary, change your security definitions to prevent unauthorized applications from putting messages on to the wrong queues.

  If the application has used an alias queue, check that the alias points to the correct queue.

• Has the trigger information been specified correctly for this queue?

  Check that the application should have been started, or should a different application have been started?

• Has the CCSID been set correctly, or is the message format incorrect because of data conversion.

If these checks do not enable you to solve the problem, check the application logic, both for the program sending the message, and for the program receiving it.

Are unexpected messages received when using distributed queues?

• Has distributed queuing been correctly installed on both the sending and receiving systems?
• Are the links available between the two systems?

  Check that both systems are available, and connected to IBM MQ for IBM i. Check that the connection between the two systems is active.

• Is triggering set on in the sending system?
• Is the message we are waiting for a reply message from a remote system?

  Check that triggering is activated in the remote system.

• Is the queue already full?

  If so, it might mean that an application was unable to put the required message on to the queue. Check that the message has been put onto the undelivered-message queue.

  The dead-letter queue message header (dead-letter header structure) contains a reason or feedback code explaining why the message could not be put on to the target queue. For information about the dead-letter header structure, see MQDLH - Dead-letter header. For IBM i, see also IBM i Application Programming Reference (ILE/RPG).

• Is there a mismatch between the sending and receiving queue managers?

  For example, the message length could be longer than the receiving queue manager can handle.

• Are the channel definitions of the sending and receiving channels compatible?

  For example, a mismatch in sequence number wrap stops the distributed queuing component. See Distributed queuing and clusters.

Parent topic: Making initial checks on IBM i