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

ftePingAgent is a useful command-line utility provided with IBM® MQ Managed File Transfer that enables you check whether an agent is reachable, and whether it is able to respond to requests.

How the command works

You can use the ftePingAgent command to check if an agent is reachable, and whether it is able to process requests. When the command is run, it performs the following steps:

Connects to the command queue manager for the Managed File Transfer (MFT) topology.
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, you can change this by setting the dynamicQueuePrefix property in The MFT command.properties file for the installation.
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 reply message to arrive on the temporary reply queue.

One of the threads within an agent is the CommandHandler. This thread gets messages from the SYSTEM.FTE.COMMAND.agent_name queue of the agent, and processes them.

If this thread receives a message containing a Ping MFT agent request, it builds an MFT agent reply message, and sends it to the temporary queue on the command queue manager. This message goes through the agent's queue manager.

Once the message arrives on the temporary queue, it is picked up by the ftePingAgent command. The command then writes a message similar to the one shown below to the console before exiting:

BFGCL0213I: agent <agent_name> responded to ping in 0.088 seconds.

The following two diagrams show the flow:

Diagram showing the pingAgent request goes to the SYSTEM.FTE.COMMAND.agent_name queue on the agent queue manger, through the command queue manager. — Figure 1. The pingAgent request goes to the SYSTEM.FTE.COMMAND.agent_name queue on the agent queue manger, through the command queue manager

Diagram showing the pingAgent reply coming back through the agent queue manager to the command queue manager. — Figure 2. *The pingAgent reply comes back through the agent queue manager to the command queue manager.*

What to do if the command times out

By default, the ftePingAgent command waits for five seconds for the MFT agent reply message to arrive on the temporary queue. If the reply message does not arrive within five seconds, the command writes a BFGCL0214I message to the console. The following message is an example:

BFGCL0214I: agent AGENT1 didn't respond to ping after 5 seconds.

You can use the following steps to investigate why the reply message did not arrive:

The first thing to do is check that the agent is running. If it is not, it can not respond to the Ping MFT agent request sent by the command.
If the agent is running and busy processing requests, it is possible that it might take longer than five seconds to get the Ping MFT agent request and send back the reply.
To see if this is the case you should rerun the ftePingAgent command again, using the -w parameter to specify a longer wait interval. For example, to specify a 60 second wait interval, issue the following command:
```
ftePingAgent -w 60 AGENT1
```
If the command still times out, check the path through the IBM MQ network between the command queue manager and the agent queue manager. If one or more channels in the path have failed, the Ping MFT agent request message and/or the MFT agent reply message will be stuck on a transmission queue somewhere. In this situation, you should restart the channels and re-run the ftePingAgent command.

If the command still reports a BFGCL0214I message after you have carried out the preceding steps, the Ping MFT agent request and MFT agent reply messages need to be tracked as they flow through the IBM MQ network to see:

Whether the Ping MFT agent message ever reaches the SYSTEM.FTE.COMMAND.agent_name queue.
If the agent picks up the message up from the queue, and sends back an MFT agent reply message.

To do this, you should carry out the following steps:

Enable queue manager traces on both the command and agent queue managers.
Enable trace on the agent dynamically using the trace specification com.ibm.wmqfte=all.
The way to do this depends upon the platform the agent is running on. For agents running on:
- IBM MQ for Multiplatforms, see Collecting a Managed File Transfer agent trace dynamically.
- IBM MQ for z/OS®, see Collecting a Managed File Transfer for z/OS agent trace dynamically.
Next, run the ftePingAgent command with trace enabled, using the trace specification com.ibm.wmqfte=all. For information about tracing the command on:
- IBM MQ for Multiplatforms, see Tracing Managed File Transfer commands on Multiplatforms.
- IBM MQ for z/OS, see Tracing Managed File Transfer for z/OS commands.

When the command times out, stop the agent trace and the queue manager trace. The agent and queue manager traces, along with the trace from the command, should then be made available to IBM support for analysis.