IBM Support

Troubleshooting IBM MQ C, C++, COBOL, .NET, pTAL, RPG and Visual Basic clients

Technote (troubleshooting)


Your IBM MQ C, C++, COBOL, .NET, pTAL, RPG or Visual Basic 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

Client software

  • Prior to WebSphere MQ V7.1, the IBM MQ client software was not available for HP NonStop or IBM i systems. However, queue managers on both platforms can accept connections originating from clients on other machines.
  • .NET and Visual Basic client applications are supported by the Windows client only.
  • pTAL client applications are supported by the HP Integrity NonStop Server client only.
  • RPG client applications are supported by the IBM i client only.

Using a client channel table

  • IBM 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)


    HP OpenVMS


  • Traditionally, IBM 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



    IBM i Command Line (for permanent changes)


    IBM i Qshell (for temporary changes)

    ===> export MQCHLLIB=/Some/Directory

    HP OpenVMS


  • Client channel tables on HP OpenVMS are in a indexed file format which is incompatible with other platforms. Use the CONVCLCHL utility to convert client channel tables being transferred to or from HP OpenVMS, or when client channel tables with Java and JMS applications on HP OpenVMS.

  • In MQ V7.0 and later, the mqclient.ini file can point to the client channel definition file. The IBM MQ documentation 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/"



    IBM i Command Line


    IBM i Qshell

    ===> export MQSERVER="D.CHL/TCP/"

    HP OpenVMS


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



    IBM i Command Line


    IBM i Qshell

    ===> unset MQSERVER

    HP OpenVMS


  • 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


  • 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.

Listener problems

  • If the queue manager to which the client connects has configured its listener as an 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


  • 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 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 queue manager is running. The listener (runmqlsr/inetd/xinetd) may be running even when the receiving queue manager is shut down.

Network Connectivity

  • Use the 'ping' command to test network connectivity from the client to the queue manager system.

  • Use telnet to test the 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 MQ traffic. If necessary, you can use the LOCLADDR attribute on sending channels to ensure the 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 IBM MQ V8.0 or 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


  • 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



  • You can take a trace of an 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 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

Product Alias/Synonym

WebSphere MQ WMQ

Document information

More support for: WebSphere MQ
Problem Determination

Software version: 2.1.2, 5.3, 5.3.1, 6.0, 7.0, 7.1, 7.5, 8.0

Operating system(s): AIX, HP-UX, IBM i, Linux, OpenVMS, Solaris, Windows, z/VSE

Software edition: All Editions

Reference #: 1620866

Modified date: 29 February 2016