fteShowAgentDetails (display IBM MQ Managed File Transfer agent details)
Use the fteShowAgentDetails command to display the details of a particular IBM® MQ Managed File Transfer agent. These are the details that are stored by its IBM MQ Managed File Transfer coordination queue manager.
Purpose
You 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.
The agent status information produced by this command is generated from the status messages that the agent publishes to the SYSTEM.FTE topic. These messages are described in Agent status message format. The status information 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 details about this property, see The agent.properties file.
For IBM WebSphere® MQ 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. You can use this information to determine the health and status of a local agent.
![[V8.0.0.6 Jan 2017]](ng8006.gif)
For z/OS®, IBM MQ 8.0.0, Fix Pack 6,
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 specified by the agent property adminGroup.
For IBM WebSphere MQ 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. You 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 has ended unexpectedly.
For a list of the possible agent status values and their meanings, see Agent status values.
For a list of the possible status values for the agent process controller and their meanings, see Agent process controller status values.
For a list of agent trace values and FFDC specifications and their meanings, see fteSetAgentTraceLevel (set IBM MQ Managed File Transfer agent trace level)
Syntax
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 you 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.
You can use this parameter only when the agent is running, and on the local system.
- -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 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 agent.properties file.
- agent_name
- Required. The name of the IBM MQ 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, 2024. 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
fteShowAgentDetails -p QMGR1 -d AGENT1
5724-H72 Copyright IBM Corp. 2008, 2024. 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, ...
fteShowAgentDetails AGENT2
5724-H72 Copyright IBM Corp. 2008, 2024. 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.
fteShowAgentDetails AGENT1
5724-H72 Copyright IBM Corp. 2008, 2024. 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.
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, 2024. 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
fteShowAgentDetails AG_CD1
5724-H72 Copyright IBM Corp. 2008, 2024. 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.
fteShowAgentDetails AGENTZ
5724-H72 Copyright IBM Corp. 2008, 2024. 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.