fteShowAgentDetails
Use the fteShowAgentDetails command to display the details of a particular Managed File Transfer Agent. These are the details that are stored by the agent's Managed File Transfer coordination queue manager.
Purpose
We can run the fteShowAgentDetails command from any system that can connect to the coordination queue manager. This command uses the coordination.properties file to connect to the coordination queue manager.
Specify the optional -p parameter for this command only if you want to use a set of configuration options different from your default set. For more information, see MFT configuration options on Multiplatforms.
The agent status information that is produced by this command is generated from the status messages that the agent publishes to the SYSTEM.FTE topic. These messages are described in MFT agent status message format. The status information that is produced by the fteShowAgentDetails command gives the agent status at the time when the last status message was published. The frequency of these status messages depends on the value of the agentStatusPublishRateLimit property. For more information, see The MFT agent.properties file.
For IBM® WebSphere MQ Version 7.5.0, Fix Pack 1 or later, specify the optional -d parameter for this command if you want to see diagnostic information about a local agent. This information includes current transfers, scheduled transfers, monitors, and agent queue depths. We can use this information to determine the health and status of a local agent.
For z/OS®, from IBM MQ Version 9.0.2 and IBM MQ Version 9.0.0, Fix Pack 1, the -d parameter can only
be specified if the fteShowAgentDetails command is run by:
- The same userid that the agent process is running as.
- Members of the group that is specified by the agent property adminGroup.
For IBM WebSphere MQ Version 7.5, or later, the status of the agent process controller and queue manager is available if you run the command on the same system as the agent. We can use this information to help with problem determination. Also, when you run the command on the same system as the agent, more detailed agent status information is available for the case where the agent ended unexpectedly.
For a list of the possible agent status values and their meanings, see MFT agent status values.
For a list of the possible status values for the agent process controller and their meanings, see MFT agent process controller status values.
For a list of agent trace values and FFDC specifications and their meanings, see fteSetAgentTraceLevel
Syntax
fteShowAgentDetails
Parameter
- -bl
- Optional. Additionally outputs the product build level for the agent.
- -p (configuration_options)
- Optional. This parameter determines the set of configuration options that is used to issue the
request to display the details of an agent. Use the name of a non-default coordination queue manager
as the input for this parameter. The command then uses the set of properties files associated with
this non-default coordination queue manager.
If we do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.
- -d
- Optional. Specifies that diagnostic information is collected for agent_name.
The diagnostic information is output to the console, and written to a file called diagnostics.<yyyyMMdd>.<HHmmss>.<ssss>.<number>.properties in the directory MQ_DATA_PATH\mqft\logs\coordination_qmgr_name\agents\agent_name\logs. A maximum of five historical files containing diagnostic information about an agent will be created. If five historical files have been created for an agent when the fteShowAgentDetails command is run with the -d parameter specified, the oldest historical file will be deleted and replaced with a new file containing the latest diagnostic information about the agent.
We can use this parameter only when the agent is running, and on the local system.
- -t
- Optional. Specifies terse mode. At IBM MQ Version 9.0.2, the output includes the Status Age information by default. If we do not want to see this information, we can issue the command with the -t parameter. For more information, see What to do if the fteListAgents command shows an agent status of UNKNOWN.
- -v
- Optional. Specifies verbose mode, which generates additional output for the agent. These include
host name, product version, product build level, trace level, and First Failure Data Capture (FFDC)
specification, and a list of transfer states for each of the current source and destination
transfers.
The current transfer information is obtained from the agent status publication, which is described in MFT agent status message format. Therefore this transfer information is only accurate to within the value of the agentStatusPublishRateLimit property. For more details about this property, see The MFT agent.properties file.
- agent_name
- Required. The name of the Managed File Transfer Agent that you want to display.
- -mquserid (userID)
- Optional. Specifies the user ID to authenticate with the coordination queue manager.
- -mqpassword (password)
- Optional. Specifies the password to authenticate with the coordination queue manager. You must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, you will be prompted to supply the associated password. The password will not be displayed.
- -? or -h
- Optional. Displays command syntax.
Example
In the following example, running bindings agent, issuing the fteShowAgentDetails command locally to the agent:
fteShowAgentDetails -v AGENT1
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENT1
Type: Standard
Description:
Operating System: Windows Server 2003
Time Zone: Greenwich Mean Time
Product Version: 7.5
Build Level: f000-20120312-0957
Trace Level: com.ibm.wmqfte.Agent=all
com.ibm.wmqfte.common=all
Trace FFDC: com.ibm.wmqfte.common:Any
com.ibm.wmqfte.Agent:1
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: STARTED
Status Details: The agent process controller has
started the agent process.
Agent Restarts within Interval: 0
Total Agent Restart Count: 0
Agent Availability Information:
Status: READY
Status Details: The agent is running and is publishing
its status at regular intervals. The
last update was received within the
expected time period. The agent is
ready to process transfers, but none
are currently in progress.
Queue Manager Information:
Name: QM1
Transport: Bindings
Last Status Reported: AVAILABLE (Last Error MQRC: 0)
Status Details: The queue manager is available.
Maximum Number of Running Source Transfers: 25
Maximum Number of Queued Source Transfers: 1000
Source Transfer States:
No current transfers
Maximum Number of Running Destination Transfers: 25
Destination Transfer States:
TransferId State
414d51204d49414f5720202020202020822c5b4a648c0b20 progress
414d51204d49414f5720202020202020822c5b4a346c0b20 progress
In the following example, QMGR1 is the non-default coordination queue manager used as input for
the configuration options, and diagnostic information is requested with the -d
parameter. The fteShowAgentDetails command is issued on a IBM WebSphere MQ Version 7.5.0, Fix Pack 1 system with a local agent:
fteShowAgentDetails -p QMGR1 -d AGENT1
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENT1
Type: Standard
Description:
Operating System: Linux
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: STARTED
Status Details: The agent process controller has started
the agent process.
Agent Restarts within Interval: 0
Total Agent Restart Count: 0
Agent Availability Information:
Status: ACTIVE
Status Details: The agent is running and is publishing
its status at regular intervals. The last
update was received within the expected
time period. The agent is currently
processing one or more transfers.
Queue Manager Information:
Name: QMGR1
Transport: Client
Host: host1.hursley.ibm.com
Port: 2021
Channel: SYSTEM.DEF.SVRCONN
Last Status Reported: UNKNOWN
Status Details: Information about the queue manager is
not available because the agent has a
client connection to the queue manager.
Agent Diagnostic Information:
Command Handler Diagnostics:
Last Command Queue Read Time: 2012-07-30T15:23:10.705Z
Pending Command Queue Size: 0
Last Internal Command Type: Resync Request (from sender) - 414d5120514d43414e4445202020202079e20f5064230010
Last Internal Command Time: 2012-07-30T14:17:10.506Z
Last External Command Type: New Monitor Request
Last External Command Time: 2012-07-30T14:10:57.751Z
Diagnostic Properties File name: C:\Program Files (x86)\IBM\WebSphere
MQ\mqft\logs\MUNGEE\agents\MUNGEE\logs\di
agnostics.20121031.083420.0477.1.properti
es
Command Handler Worker Thread 0 Diagnostics:
Status: Waiting
Command Handler Worker Thread 1 Diagnostics:
Status: Waiting
Command Handler Worker Thread 2 Diagnostics:
Status: Waiting
Command Handler Worker Thread 3 Diagnostics:
Status: Waiting
Command Handler Worker Thread 4 Diagnostics:
Status: Waiting
File Transfer Diagnostics:
Source Transfers: 1
Destination Transfers: 2
File Transfer 0 Diagnostics:
Transfer Id: 414d5120514d43414e4445202020202079e20f5064230010
Role: SOURCE
State: ReSynchronisingTransfer
Status: INACTIVE
Start Time: Not started
Retry Count: 0
CheckPoint Index: 0
CheckPoint Position: 0
File Transfer 1 Diagnostics:
Transfer Id: 414d5120514d43414e44452020202020c8fbd54f144f0d20
Role: DESTINATION
State: RunningTransfer
CheckPoint Index: 0
CheckPoint Position: 0
Write Index: 0
Write Position: 0
File Transfer 2 Diagnostics:
Transfer Id: 414d5120514d43414e4445202020202079e20f5086020010
Role: DESTINATION
State: RunningTransfer
CheckPoint Index: 9
CheckPoint Position: 0
Write Index: 3
Write Position: 140923
Monitor 0 Diagnostics:
Name: MONITOR1
Status: STARTED
Resource Type: directory
Resource: /tmp/monitor
Poll Interval: 1 minutes
Batch Size: 2
Condition Match
Pattern: * (wildcard)
Executing: false
Last Execute Start Time: 2012-04-04T16:19:01.852Z
Last Execute End Time: 2012-04-04T16:19:01.852Z
Last Execute Match Count: 0
Schedule 1 Diagnostics:
Id: 1
Next Trigger Time: 2012-07-17T16:00+0100
Occurrences So Far: 14
Repeat Interval: hours
Repeat Frequency: 5
Source Agent: AGCANDE
Destination Agent: AGCANDE
Source File: /tmp/source/a.txt, ...
Destination File: /tmp/dest/a.txt, ...
In the following example, stopped bindings agent, issuing the
fteShowAgentDetails command remotely from the agent:
fteShowAgentDetails AGENT2
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENT2
Type: Standard
Description:
Operating System: Linux
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: UNKNOWN
Status Details: Information about the agent controller
is not available, either because the
agent is not running or the agent is
running on a different system.
Agent Restarts within Interval: 0
Total Agent Restart Count: 0
Agent Availability Information:
Status: STOPPED
Status Details: The agent has been stopped. It was shut
down in a controlled manner.
Queue Manager Information:
Name: QM2
Transport: Bindings
Last Status Reported: UNKNOWN
Status Details: Information about the queue manager is
not available, either because the agent
is not running or the agent is running
on a different system.
In the following example, bindings agent is waiting to restart with the agent queue manager
stopped. The agent has already been restarted once before Total Agent Restart Count:
1, possibly due to a previous agent queue manager restart: Note: The
Last Error MQRC against the Last Status
Reported for the queue manager information; this information will remain even when
the queue manager becomes available.
fteShowAgentDetails AGENT1
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENT1
Type: Standard
Description:
Operating System: Windows Server 2003
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: WAITING
Status Details: The agent process controller is waiting
for the queue manager to become
available before starting the agent.
Agent Restarts within Interval: 0
Total Agent Restart Count: 1
Agent Availability Information:
Status: STOPPED
Status Details: The agent has been stopped. It was shut
down in a controlled manner.
Queue Manager Information:
Name: QM1
Transport: Bindings
Last Status Reported: UNAVAILABLE (Last Error MQRC: 2059)
Status Details: The queue manager is unavailable. It
might be that the queue manager has not
been started or an incorrect queue
manager name has been configured. Look
up the MQ reason code reported against
the status to understand the problem.
In the following example, the client mode agent has just ended unexpectedly and the agent process
controller tries to recover the situation by restarting it after a delay, specified by the
maxRestartDelay agent property value. The default maxRestartDelay
agent property value is -1, and this causes the agent process controller to terminate; hence in this
example the maxRestartDelay property value must have been set to a value greater
than 0. The Current Agent Restart Count: 4 implies that there have been
4 restarts within the maxRestartInterval agent property time period. If the
maxRestartCount agent property is 4 then after 4 restarts within the
maxRestartInterval, the agent process controller will wait for
maxRestartDelay seconds before restarting the agent, which is the case here. The
Total Agent restart Count: 8 suggests that this has occurred before.
This example is not typical and you would only expect to see the agent ending unexpectedly if the
agent runs out of memory, or a custom user exit has caused some sort of runtime error. Full details
as to why the agent ended unexpectedly are in the agent's output0.log file:
fteShowAgentDetails AGENT3
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENT3
Type: Standard
Description:
Operating System: Windows Server 2003
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: RECOVERING
Status Details: The agent process unexpectedly stopped
and the process controller will attempt
to restart it.
Current Agent Restart Count: 4
Total Agent Restart Count: 8
Agent Availability Information:
Status: ENDED UNEXPECTEDLY
Status Details: The agent has ended unexpectedly due to
an unrecoverable problem. The agent
will be automatically restarted.
Queue Manager Information:
Name: QM3
Transport: Client
Host: host3.hursley.ibm.com
Port: 3031
Channel: SYSTEM.DEF.SVRCONN
In the following example, the results for a Connect:Direct® bridge agent are displayed:
fteShowAgentDetails AG_CD1
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AG_CD1
Type: Connect:Direct bridge
Description:
Connect:Direct Node Name: CDNODE
Connect:Direct Node Host: localhost:1363
Operating System: Windows Server 2003
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller type: MQMFT Process Controller
Status: UNKNOWN
Status Details: Information about the agent controller
is not available, either because the
agent is not running or the agent is
running on a different system.
Agent Restarts within Interval: 0
Total Agent Restart Count: 0
Agent Availability Information:
Status: STOPPED
Status Details: The agent has been stopped. It was shut
down in a controlled manner.
Queue Manager Information:
Name: QM_JUPITER
Transport: Bindings
Last Status Reported: UNKNOWN
Status Details: Information about the queue manager is
not available, either because the agent
is not running or the agent is running
on a different system.
In the following example, an agent running on z/OS is registered with the Automatic Restart Manager (ARM):
fteShowAgentDetails AGENTZ
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Information:
Name: AGENTZ
Type: Standard
Description:
Operating System: z/OS
Time Zone: Greenwich Mean Time
Agent Controller Information:
Controller Type: z/OS Automatic Restart Manager (ARM)
Agent registered with ARM: Yes (ELEMTYPE: SYSBFGAG, ELEMENT: AGENTZ)
Agent Restarted: No
Agent Availability Information:
Status: READY
Status Details: The agent is running and is publishing
its status at regular intervals. The last
update was received within the expected
time period. The agent is ready to
process transfers, but none are currently
in progress.
Queue Manager Information:
Name: ZQM
Transport: Bindings
Last Status Reported: AVAILABLE
Status Details: The queue manager is available.
Return codes
- 0
- Command completed successfully.
- 1
- Command ended unsuccessfully.