Troubleshooting WebSphere MQ C, C++, COBOL and .NET clients

Client Software

• 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 as SupportPacs MQC75, MQC71, MQC7, MQC6, MQC5 and MQC4.

• The WebSphere MQ C, C++, COBOL and .NET client software is not available for some platforms, including z/OS, HP NonStop, and IBM i (prior to WebSphere MQ 7.1). However, these 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:
  
  IBM i - Look in the Integrated File System (IFS)
      /QIBM/UserData/mqm/qmgrs/QMGR/&ipcc/AMQCLCHL.TAB
  
  Linux & UNIX
      /var/mqm/qmgrs/QMGR/@ipcc/AMQCLCHL.TAB
  
  Windows
      C:\Program Files (x86)\IBM\WebSphere MQ\Qmgrs\QMGR\@ipcc\AMQCLCHL.TAB

• 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:
  
  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
  
  Linux & UNIX
      sh> export MQCHLLIB=/some/directory
  
  Windows
      C:\> SET MQCHLLIB=D:\MQM
  
  
• 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:
  
  CHANNELS:
      ChannelDefinitionDirectory=/some/path
      ChannelDefinitionFile=PROD.CLCHL.TAB
  
  

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:
  
  IBM i Command Line
      ===> ADDENVVAR ENVVAR(MQSERVER) VALUE(A.CHL/TCP/192.168.1.2) LEVEL(*SYS)
  
  IBM i Q Shell
      ===> export MQSERVER="B.CHL/TCP/192.168.1.9(1417)"
  
  Linux & UNIX
      sh> export MQSERVER="C.CHL/TCP/192.168.1.13(1422)"
  
  Windows
      C:\> set MQSERVER="D.CHL/TCP/c.example.com"

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:
  
  IBM i Command Line
      ===> RMVENVVAR ENVVAR(MQSERVER) LEVEL(*SYS)
  
  IBM i Q Shell
      ===> unset MQSERVER
  
  Linux & UNIX
      sh> unset MQSERVER
  
  Windows
      C:\> set 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:
  
  DISPLAY CHANNEL(*) CHLTYPE(CLNTCONN) ALL
  ALTER CHANNEL(D.CHL) CHLTYPE(CLNTCONN) CONNAME('d.example.com')...
  

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

Network Connectivity

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

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.

• 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.
  
  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:
  
  DISPLAY CHLAUTH(*) ALL
  SET CHLAUTH(D.CHL) TYPE(ADDRESSMAP) ADDRESS('9.8.7.*') MCAUSER('usr1')

Tracing

• 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:
  
      strmqtrc -t api
  
  
  Then run your client application and wait for the error to occur before running:
  
      endmqtrc -a