fteListAgents (list the IBM MQ Managed File Transfer agents for a coordination queue manager)

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

Purpose

You 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 web agent, the agent name is appended with (Web Gateway)
  • 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 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 Configuration options on distributed platforms.

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 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 agent.properties file.

Syntax

fteListAgents

Read syntax diagramSkip visual syntax diagramfteListAgents-pconfiguration_options-mquseriduserID-mqpasswordpassword-vpattern

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 you 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: 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).

pattern
Optional. The pattern to use to filter the list of IBM MQ 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 you do not escape these characters, they are interpreted according to their meaning on the specific UNIX or Linux system.

If you 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 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, 2024. 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.