MQ

This is part of an occasional series of small blog posts where I (Morag) will write about some of the quirks in IBM MQ, in the hope of invoking the response, "Well, I didn't know that!" Read other posts in this series.

When using IBM MQ on distributed platforms, you are hopefully familiar with the error log that the queue manager writes. This can be found in MQ_DATA_PATH/qmgrs/qmgr-name/errors/AMQERR01.LOG. Below is an example of an error message you might see on a distributed queue manager.

AMQ9202: Remote host 'localhost (127.0.0.1) (7777)' not available, retry later.

EXPLANATION:
The attempt to allocate a conversation using TCP/IP to host 'localhost
(127.0.0.1) (7777)' for channel MQG1.TO.MQG2 was not successful. However the
error may be a transitory one and it may be possible to successfully allocate a
TCP/IP conversation later. 

In some cases the remote host cannot be determined and so is shown as '????'.
ACTION:
Try the connection again later. If the failure persists, record the error
values and contact your systems administrator. The return code from TCP/IP is
111 (X'6F'). The reason for the failure may be that this host cannot reach
the destination host. It may also be possible that the listening program at
host 'localhost (127.0.0.1) (7777)' was not running.  If this is the case, perform
the relevant operations to start the TCP/IP listening program, and try again.

When using IBM MQ on the z/OS platform, there are also error messages. These are written to the JESMSGLG in the MSTR and CHIN address spaces. Which address depends on the feature of IBM MQ reporting the error. For example, channel related errors are written to the CHIN JESMSGLG whereas logging messages are written to the MSTR JESMSGLG. Here is an example of the same message we showed earlier on the distributed platform, as reported on z/OS.

CSQX202E %MQG1 CSQXRCTL Connection or remote listener unavailable,
channel MQG1.TO.MQG2                                              
connection 127.0.0.1                                              
TRPTYPE=TCP RC=00000468 (ECONNREFUSED) reason=00000000

You'll immediately noticed that the error message on z/OS is much shorter. This is simply because the length of message that can be written on z/OS is less. However, the error message you see in the JESMSGLG is not the whole story. There IS more information about this error than just what you see in the JESMSGLG.

In the days of manuals, products on z/OS all had a "Messages and Codes" manual. These days, the same can be found instead in IBM Knowledge Center. The IBM MQ for z/OS Message and Codes section can be found here.

IBM MQ for z/OS Messages and Codes

Looking up the above message number, CSQX202E in the "Messages & Codes" section we see that the complete description of the error is as follows:-

CSQX202E csect-name Connection or remote listener unavailable, channel channel-name connection conn-id TRPTYPE=trptype RC=return-code (return-text) reason=reason

Severity 8

Explanation An attempt to allocate a conversation was not successful because the connection conn-id was unavailable. The associated channel is channel-name; in some cases its name cannot be determined and so is shown as '????'. trptype shows the communications system used.
The return code from it was: (in hexadecimal) return-code, (in text) return-text. For some errors, there might also be an associated reason code reason (in hexadecimal) giving more information.

System action The attempt to start the channel is retried.

System programmer response Try again later.
A likely cause is that the listener at the remote end was not running or has been started using the wrong port or LU name. If this is the case, perform the necessary operations to start the appropriate listener, and try again.
See Communications protocol return codes for information about the cause of the return code from the communications system.
If using TCP/IP, see the z/OS UNIX System Services Messages and Codes manual for information about the reason code.
If you receive reason code 468:

• You are not using the correct IP address.
• The listener for the port might not be active.
• A firewall does not allow the connection. When there are multiple links defined on a z/OS image, the image can have multiple host names depending on the link. You need to ensure that the correct host name is used as the sender end. Use the NETSTAT HOSTs command to display the host names on the image.

As you can see, there is a lot more information about this error than just the couple of lines you might see in the JESMSGLG. Often these descriptions are updated to include helpful hints for common reason codes as illustrated above for TCP/IP reason code 468. If the message contains an insert with a reason code, it may be an MQRC, or an error code from another product such as TCP/IP, System SSL, Sysplex Services, RACF/SAF, Authorized Services and so on. The full explanation of the error message in "Messages and Codes" will provide details of what type of reason code is reported and where to look it up.

So the IBM MQ products may look different across the platforms, with respect to their error messages, but the closer you look, the more you realise that there is a very similar amount of information to be gleaned. You just have to remember to look up the message in "Messages and Codes".