What to do if ftePingAgent times out and reports a BFGCL0214I message

ftePingAgent is a useful command-line utility provided with the IBM MQ Managed File Transfer component that enables you check whether an agent is currently running.

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 roles. See MFT topology overview for more information.

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.

The IBM MQ sender and receiver channels connect:

• The coordination queue manager to all the agent queue managers.
• The command queue managers to all the agent queue managers.
• Every agent to every other agent in the configuration.

When you run the ftePingAgent command, it performs the following steps. The command:

• Connects to a command queue manager.
• Creates a temporary reply queue on the command queue manager.

  By default, the temporary queue has a name that starts with the prefix WMQFTE. However, we can change this by setting the dynamicQueuePrefix property in The MFT command.properties file for the configuration.

• Sends a Ping MFT agent request message to the queue SYSTEM.FTE.COMMAND.agent_name on the agent queue manager, through the command queue manager. The request message contains the name of the temporary reply queue.
• Waits 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 those messages accordingly.

If the thread receives a message containing a PingAgent request, the thread builds a PingAgent response, and sends the response back to the temporary reply queue on the Command Queue Manager; this reply message goes through the queue manager of the agent.

What to do if the command times out

BFGCL0214I: agent agent_name didn't respond to ping after number seconds. 

• By default, the ftePingAgent command waits for 5 seconds to get the response message. If the agent is busy, 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. Do this by specifying the -w parameter. For example, to run the ftePingAgent command with a 60 second wait interval, issue the following command:

  ftePingAgent -w 60 AGENT1

• If the command still times out, check the sender and receiver channels between the command queue manager and the queue manager of the agent. If the channels have failed, 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 does not help, 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.

For help to do this:

• 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:
  • -trace com.ibm.wmqfte=all
  • -tracePath directory_name

  This traces the command, and generates 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.