ITCAM MQ agent fails to start on Windows OS

Body

ITCAM for messaging - MQ monitoring agent.

Product code: kmq

Platform: Microsoft Windows OS

Problem

MQ agent fails to start.

When you use Manage Tivoli Enterprise Monitoring Service (aka MTEMS) to start MQ agent instance (TESTQM) service - the service fails to start.

A popup message is displayed: KCICF5100E Unable to start service, see Event Log for information.

You take following steps to find the cause of this failure:

- You check the agent logs directory C:\IBM\ITM\TMAITM6_x64\logs; but no logs for the agent were created, as the agent failed to launch.

- Next you check the event logs as instructed in the error message.

In the application event log, the following event is logged.

Faulting application name: kmqlocal_TESTQM.exe, version: 0.0.0.0, time stamp: 0x59f1a165
Faulting module name: MQM.dll, version: 6.3.9600.18895, time stamp: 0x5a4b1b67
Exception code: 0xc0000135
Fault offset: 0x00000000000ecf30
Faulting process id: 0x27d8
Faulting application start time: 0x01d3a6bd567bef30
Faulting application path: C:\IBM\ITM\TMAITM6_x64\kmqlocal_TESTQM.exe

Troubleshooting

A likely cause of this problem is that a required MQM.dll is not in the PATH of the agent user.

Check the user configured for the agent. For example domain\tivoliuser is the agent startup user seen in the screenshot of MTEMS below.

Steps to check the PATH:

1 - Logon to the host as the user starting the agent (domain\tivoliuser).

2 - Open a command prompt.

3 - echo %PATH% to check if the PATH includes the WebSphere MQ binaries path.

4 - Another way to confirm the PATH as the issue is to run the agent from command prompt.

Change to the agent binaries path C:\IBM\ITM\TMAITM6_x64.

Run command:

KMQAGENT_TESTQM.EXE mq_TESTQM.cfg

You may get the popup error "kmqlocal.exe - System Error" "The program can't start because MQM.dll is missing from your computer. Try reinstalling the program to fix this problem."

However, you can find that the MQ install path contains the MQM.dll, and the user has permissions to access these directories.

From this test, it becomes clear that the startup user for the MQ agent service - does not have the MQ binaries in the PATH environment variable.

Resolution

Use MTEMS to add variable to the MQ agent instance:

PATH=C:\Program Files\IBM\MQ\bin64

Note that if you have 32-bit monitoring agent binaries, then the PATH should be set to 32-bit MQM binaries, for example: C:\Program Files\IBM\MQ\bin

After setting this PATH variable, restart the agent. The service should start successfully.

Notes

1) You may run into a problem where the MTEMS and Windows Services panel both display the service as "Disabled" after it fails to start. You should log off and log back on to the Windows host to see the correct status of MQ agent service.

2) The step to define PATH variable is documented in KnowledgeCenter topic below:

Specifying WebSphere MQ library path

3) Additional MQ agent configuration steps for Windows OS are available from following page. Follow these instructions carefully to make sure all required permissions have been granted to the agent user.

Configuring ITCAM agent for WebSphere MQ

4) Make sure that the MQ agent startup user has full permissions to the installation path of ITCAM MQ agent, such as C:\IBM\ITM.