ftePingAgent is a handy command-line utility provided with the MQ Managed File Transfer component that lets you check whether an agent is currently running. In this blog post, we will look at how it works, and provide some hints and tips on what to do if it returns an error.
How the command works
In a Managed File Transfer configuration (or topology), there can be a number of queue managers, which perform one or more rolls:
The coordination queue manager is the central store for all of the agent status, transfer status and transfer audit information for the configuration.
Command queue managers are used to route messages containing commands to the various agents in the configuration.
Agent queue managers host all of the internal system queues required by an agent.
MQ sender and receiver channels connect:
The coordination queue manager to all of the agent queue managers.
The command queue managers to all of the agent queue managers.
Every agent to every other agent in the configuration.
Now, when the ftePingAgent command is run, it will perform the following steps:
Connect to a command queue manager.
Create a temporary reply queue on the command queue manager. By default, the temporary queue will have a name that starts with the prefix WMQFTE – however, this can be changed by setting the dynamicQueuePrefix property in the command.properties file for the configuration.
Send a message containing a “pingAgent” request to the queue SYSTEM.FTE.COMMAND.<AgentName> on the agent queue manager, via the command queue manager. The request message contains the name of the temporary reply queue.
Wait for a “PingAgent” reply to arrive on the temporary reply queue.
When an agent starts up, it connects to its agent queue manager, and then creates an internal CommandHandler thread. The purpose of this thread is to pick up messages from the SYSTEM.FTE.COMMAND.<Agent name> queue, and handle them accordingly. If it receives a message containing a “pingAgent” request, it builds a “PingAgent” response and sends it back to the temporary reply queue on the Command Queue Manager – this reply message goes via the Agent's queue manager.
Here are two diagrams which show the flow:
Figure 1: The pingAgent request goes to the SYSTEM.FTE.COMMAND.<Agent name> queue on the agent queue manger, via the command queue manager.
Figure 2: The pingAgent reply comes back via the agent queue manager to the command queue manager.
What to do if the command times out
If the command times out, and you see the following message:
BFGCL0214I: agent <agent name> didn't respond to ping after <number> seconds.
then it doesn't necessarily mean that the agent is not running. Here are a couple of things to do to investigate why the time out occurs:
By default, the ftePingAgent command waits for 5 seconds to get the response message.
If the agent is busy, then it might have taken longer than five seconds for the internal CommandHandler thread to pick up the “PingAgent” message and process it. To see if this is the case, try re-running the command with a longer wait time. This can be done by specifying the -w parameter.
Here is an example where the ftePingAgent command is run with a 60 second wait interval:
ftePingAgent -w 60 AGENT1
If the command still times out, then check the sender and receiver channels between the command queue manager and the agent's queue manager. If the channels are down, then the message containing the “PingAgent” request will be stuck on the transmission queue on the command queue manager.
If the channels are up and running, and increasing the wait interval used by the command doesn't help, then the message needs to be tracked through the configuration to see:
Whether the message ever reaches the SYSTEM.FTE.COMMAND.<Agent name> queue.
If the agent ever picked the message up from this queue.
If you need help doing this, then:
Enable queue manager traces on both the command and agent queue managers.
Enable trace on the agent, using the trace specification com.ibm.wmqfte=all.
Run the ftePingAgent command, specifying the extra command line options
-tracePath <directory name>
This will trace the command, and generate a trace file in the directory specified by the -tracePath argument.
When the command times out, stop all the traces and make them available to IBM Support for analysis!