fteListAgents: list the MFT agents for a coordination queue manager

Use the fteListAgents command to list all of the Managed File Transfer agents that are registered with a particular coordination queue manager.

Purpose

We can run the fteListAgents command from any system that can connect to the coordination queue manager. The following details for each agent are directed to the standard output device (STDOUT):

Agent name
Agent queue manager
If the agent is a protocol bridge agent, the agent name is appended with either (FTP bridge) or (SFTP bridge)
If the agent is a Connect:Direct® bridge agent, the agent name is appended with (Connect:Direct bridge)
Agent status

This command uses the coordination.properties file to connect to the coordination queue manager. For more information, see The MFT coordination.properties file.

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.

If an agent is not listed by the fteListAgents command, use the diagnosis flowchart in the following topic to locate and fix the problem: If your agent is not listed by the fteListAgents command.

Agent status information

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 the topic MFT agent status message format. The status information produced by the fteListAgents 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 topic The MFT agent.properties file.

Syntax

fteListAgents

Parameters

-p (configuration_options)

Optional. This parameter determines the set of configuration options that is used to issue the request to list agents. 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.

-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.

-v

Optional. Specifies verbose mode. Verbose mode generates additional output for each agent, including the current number of transfers in the form Source/Destination, where Source is the current number of source transfers and Destination is the current number of destination transfers.

The current transfer information is obtained from the agent status publication, which is described in the following topic: MFT agent status message format. As a result, this transfer information is only accurate to within the setting for the agentStatusPublishRateLimit agent property value (which defaults to 30 seconds).

-t

Optional. Specifies terse mode. At IBM MQ Version 9.0.2, the output includes the Status Age column by default. If we do not want to see the Status Age information, we can issue the command with the -t parameter to hide the column. For more information, see What to do if the fteListAgents command shows an agent status of UNKNOWN.

pattern

Optional. The pattern to use to filter the list of Managed File Transfer agents. This pattern is matched against the agent name. Asterisk (*) characters are interpreted as wildcards, that match any value, including zero characters.

On UNIX and Linux systems, you must escape special characters like the asterisk (*) and the number sign (#) with quotation marks (' ') or double quotation marks (" ") if you want them to be handled as literals. If we do not escape these characters, they are interpreted according to their meaning on the specific UNIX or Linux system.

If we do not specify this parameter, all agents registered with the coordination queue manager are listed.

-? or -h

Optional. Displays command syntax.

Example

In this example, all of the agents registered on the queue manager detailed in the configuration options with names beginning with B are listed:

fteListAgents "B*"

In this example, agents that are registered with the coordination queue manager QM_EUROPE (the non-default coordination queue manager) are listed in verbose mode:

fteListAgents -p QM_EUROPE -v

The output from this command is as follows:

Agent Name:      Queue Manager Name:     Transfers:               Status:
                                         (Source/Destination)
BERLIN           QM_BERLIN               7/0                      RUNNING
LONDON           QM_LONDON               0/0                      RUNNING
MADRID           QM_MADRID               0/1                      UNREACHABLE

For a list of the possible agent status values and their meanings, see the topic MFT agent status values. In this example, all agents that are registered with the coordination queue manager and that have names beginning with BRIDGE are listed in verbose mode:

fteListAgents -v  "BRIDGE*"

The output from this command is as follows:

C:\Program Files\IBM\WMQFTE\bin>fteListAgents -v
5724-H72 Copyright IBM Corp. 2008, 2020. ALL RIGHTS RESERVED
Agent Name:                            Queue Manager Name:     Transfers:    Status:
                                                               (Source/Destination)
BRIDGE_FTP (FTP bridge)                QM_JUPITER              0/0           STOPPED
BRIDGE_CD1 (Connect:Direct bridge)     QM_JUPITER              0/0           STOPPED

Return codes

0: Command completed successfully.
1: Command ended unsuccessfully.