Your WebSphere MQ C, C++, COBOL or .NET client application is having difficulty connecting to a queue manager or processing messages and you need to know how to troubleshoot the problem. This document describes several common client problems and how to address them.
Resolving the problem
- The WebSphere MQ client software must be installed on the system, either as a client-only installation or as part of a server installation. WebSphere MQ clients for various platforms are available for free download:
- The WebSphere MQ client software is not available for z/OS. However, it can accept connections originating from clients on other machines, provided you have ordered the client attachment feature, which is available as a separately FMID from the Program Directory for WebSphere MQ. If the client attachment feature is installed you will see a message in the CHIN joblog at startup.
z/OS CHIN Joblog
CSQX900I +CSQ1 CSQXGIP Client attachment feature available
- Prior to WebSphere MQ V7.1, the WebSphere MQ client software was not available for HP NonStop or IBM i systems. However, WebSphere MQ queue managers on both platforms can accept connections originating from clients on other machines.
- WebSphere MQ .NET client applications are supported by the Windows client only.
Using a client channel table
- WebSphere MQ client applications use a client connection channel definition (CLNTCONN) which describes how they should connect to the queue manager. Typically client channel definitions are defined on a queue manager, which creates a binary file with all the definitions. This client channel table can then be copied from the queue manager directory to the client systems that need it. The default location of the client channel table is:
Linux and UNIX
C:\Program Files (x86)\IBM\WebSphere MQ\Qmgrs\QMGRNAME\@ipcc\AMQCLCHL.TAB
IBM i Integrated File System (IFS)
- Traditionally, WebSphere MQ client applications found their client channel table using two environment variables. MQCHLLIB gives the name of the directory, while MQCHLTAB gives the name of the file, if other than AMQCLCHL.TAB. If these variables are set, they take precedence:
Linux and UNIX
sh> export MQCHLLIB=/some/directory
C:\> SET MQCHLLIB=D:\SOME\DIRECTORY
IBM i Command Line (for permanent changes)
===> ADDENVVAR ENVVAR(MQCHLLIB) VALUE('/Some/Directory') LEVEL(*SYS)
IBM i Q Shell (for temporary changes)
===> export MQCHLLIB=/Some/Directory
- In WebSphere MQ V7.0 and later, the mqclient.ini file can point to the client channel definition file. The WebSphere MQ Information Center describes the location of the mqclient.ini file, which can be overridden by the MQCLNTCF environment variable. If the mqclient.ini exists, it uses two attributes to control the location and name of the client channel definition file:
Using the MQSERVER environment variable
- Instead of using a channel definition file, you can create a simple client connection using the MQSERVER environment variable. The MQSERVER variable gives the name of the client connection channel, the transport type (TCP), and the network address of the queue manager. However, it cannot control other client channel definition attributes:
Linux and UNIX
sh> export MQSERVER="A.CHL/TCP/192.168.1.13(1422)"
C:\> SET MQSERVER="B.CHL/TCP/b.example.com"
IBM i Command Line
===> ADDENVVAR ENVVAR(MQSERVER) VALUE(C.CHL/TCP/192.168.1.2) LEVEL(*SYS)
IBM i Q Shell
===> export MQSERVER="D.CHL/TCP/192.168.1.9(1417)"
Checking your client channel settings
- Make sure your client application is running in a good environment, with variables like MQCLNTCF, MQCHLLIB, MQCHLTAB and MQSERVER set (or unset) in order for the client to use the right client channel definitions. If you need to unset an unwanted variable:
Linux and UNIX
sh> unset MQSERVER
C:\> SET MQSERVER=
IBM i Command Line
===> RMVENVVAR ENVVAR(MQSERVER) LEVEL(*SYS)
IBM i Q Shell
===> unset MQSERVER
- If you are using a client channel definition file, examine the file using a queue manager to make sure the definitions are right. Set the MQCHLLIB and MQCHLTAB environment variables to point to your file, then start a queue manager to review and if necessary modify the client channels:
Displaying and altering client channels
DISPLAY CHANNEL(*) CHLTYPE(CLNTCONN) ALL
ALTER CHANNEL(D.CHL) CHLTYPE(CLNTCONN) CONNAME('d.example.com(1432)')...
- Your client application may choose to set its connection parameters programmatically, rather than relying on any external files or environment variables. If you are using this method, check the client application code to ensure it is using the right client channel definition attributes.
- If the queue manager to which the client connects has configured its listener as a WebSphere MQ object, make sure it is configured properly and is running. Use runmqsc to show the listener attributes and status, and if necessary start it:
Displaying and starting listeners
DISPLAY LISTENER(B.LISTENER) ALL
DISPLAY LSSTATUS(B.LISTENER) ALL
- If the listener is started manually, make sure the listener process is active and listening. For example, list processes on the queue manager system and make sure "runmqlsr" is present.
- List network status on the queue manager system to ensure the listener process is active on the proper port. On IBM i you can run WRKTCPSTS, while on other platforms run "netstat -an".
- If you are using inetd or xinetd on UNIX or Linux, make sure your configuration files on the queue manager system are set up properly (for example: /etc/services, /etc/inetd.conf, or /etc/xinetd.conf).
- If the WebSphere MQ port is already in use by another program, on UNIX and Linux you can use the lsof program to determine who is using it. For example, run "lsof -i tcp:1414".
- Make sure the WebSphere MQ queue manager is running. The listener (runmqlsr/inetd/xinetd) may be running even when the receiving queue manager is shut down.
- Use the 'ping' command to test network connectivity from the client to the queue manager system.
- Use telnet to test the WebSphere MQ port on the remote system, for example: 'telnet qmhost 1414'.
- If your client channel definition uses host names instead of IP addresses, make sure they resolve to the expected address. For example, use the 'nslookup' or 'dig' commands, where available, to ensure your DNS servers are providing the right address information. Test with IP addresses in your client channel definition if you are not sure whether DNS is at fault.
- If you have a firewall between the systems, make sure it is configured to allow WebSphere MQ traffic. If necessary, you can use the LOCLADDR attribute on sending channels to ensure the WebSphere MQ channel uses ports which the firewall will allow.
- If you have a firewall, NAT device, or other network equipment which may terminate idle connections, follow the instructions in the Information Center to enable TCP/IP KeepAlive for the client system and reduce the KeepAlive timeout from its default of two hours to something on the order of 5-10 minutes.
- Check the security attributes of the SVRCONN channel to which the client connects, in particular whether the MCAUSER attribute has been set or not.
- Make sure the client user has authority on the queue manager to connect and access the queues and other objects which it wishes to use.
- If you are running WebSphere MQ V7.1 or later, check to see whether channel authentication is enabled or not. Channel authentication is a recommended best practice.
Displaying the channel authentication status
DISPLAY QMGR CHLAUTH
- If channel authentication is enabled, use runmqsc to display and set records which will allow your client to connect while disallowing unwanted traffic. For example:
Displaying and setting channel authentication records
DISPLAY CHLAUTH(*) ALL
SET CHLAUTH(D.CHL) TYPE(ADDRESSMAP) ADDRESS('192.168.7.*') MCAUSER('usr1')
- You can take a trace of a WebSphere MQ client application to see what information it is passing to the queue manager and receiving in return. If you suspect a problem with an MQI call, whether you think the client application is passing a bad parameter or receiving an invalid response, you can gather an API trace on the client. This will show all of the options passed to and returned from every client MQI call, which you can review against the WebSphere MQ documentation:
Generating a client API trace
> strmqtrc -t api
Run your client application and wait for the error occur before stopping the trace:
> endmqtrc -a
WebSphere MQ WMQ