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

Back to top

Using a client channel table

• Except on z/OS, IBM MQ queue managers create client channel tables when you define CLNTCONN channels in runmqsc. By default these client channel tables are located in the following path, but if your queue manager data is located in a different path or drive you will have to adjust accordingly:
   

  Linux and UNIX

  /var/mqm/qmgrs/QMGRNAME/@ipcc/AMQCLCHL.TAB

   

  Windows

  C:\Program Files (x86)\IBM\WebSphere MQ\Qmgrs\QMGRNAME\@ipcc\AMQCLCHL.TAB

   

  IBM i Integrated File System (IFS)

  /QIBM/UserData/mqm/qmgrs/QMGRNAME/&ipcc/AMQCLCHL.TAB

• BM MQ clients can create client channel tables without relying on a queue manager by using runmqsc on the client system. IBM MQ client applications find 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

   

  Windows

  C:\> SET MQCHLLIB=D:\SOME\DIRECTORY

   

  IBM i Command Line (for permanent changes)

  ===> ADDENVVAR ENVVAR(MQCHLLIB) VALUE('/Some/Directory') LEVEL(*SYS)

   

  IBM i Qshell (for temporary changes)

  ===> export MQCHLLIB=/Some/Directory

mqclient.ini

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


• CHANNELS:
      ChannelDefinitionDirectory=/some/path
      ChannelDefinitionFile=PROD.CLCHL.TAB

Back to top

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.


• 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. For example, these commands demonstrate how to set, display, and remove the MQSERVER environment variable:
   

  Linux and UNIX

  sh> export MQSERVER="A.CHL/TCP/192.168.1.13(1422)"

  sh> echo $MQSERVER

  sh> unset MQSERVER

   

  Windows

  C:\> SET MQSERVER="B.CHL/TCP/b.example.com"

  C:\> ECHO %MQSERVER%

  C:\> SET MQSERVER=

   

  IBM i Command Line

  ===> ADDENVVAR ENVVAR(MQSERVER) VALUE(C.CHL/TCP/192.168.1.2) LEVEL(*SYS) REPLACE(*YES)

  ===> WRKENVVAR LEVEL(*SYS)

  ===> RMVENVVAR ENVVAR(MQSERVER) LEVEL(*SYS)

   

  IBM i Qshell

  ===> export MQSERVER="D.CHL/TCP/192.168.1.9(1417)"

  ===> echo $MQSERVER

  ===> unset MQSERVER

Displaying and altering client channels

• If you are using a client channel definition file, examine the file using client runmqsc (or using a queue manager) to make sure the definitions are right. Set the MQCHLLIB and MQCHLTAB environment variables to point to your file, then use runmqsc to review and if necessary modify the client channels:
   

  runmqsc -n

  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.

Back to top

Listener problems

Displaying and starting listeners

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

  DISPLAY LISTENER(B.LISTENER) ALL

  DISPLAY LSSTATUS(B.LISTENER) ALL
  START LISTENER(B.LISTENER)

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

Back to top

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.

Back to top

Security

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

Displaying the channel authentication status

• Check to see whether channel authentication is enabled or not. Channel authentication is a recommended best practice.
• DISPLAY QMGR CHLAUTH

Displaying and setting channel authentication records

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

  DISPLAY CHLAUTH(*) ALL

  SET CHLAUTH(D.CHL) TYPE(ADDRESSMAP) ADDRESS('192.168.7.*') MCAUSER('usr1')

Back to top

Tracing

Generating a client API trace

• 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:
  
  > strmqtrc -t api


• Run your client application and wait for the error occur before stopping the trace:
  
  > endmqtrc -a

Back to top