fteCleanAgent: clean up an MFT Agent

Use the fteCleanAgent command to clean up the queues that a Managed File Transfer Agent uses, by deleting messages from the persistent and non-persistent queues used by the agent. Use the fteCleanAgent command if you are having problems starting an agent, which might be caused by information remaining on the queues used by the agent.

Purpose

Use the fteCleanAgent command to delete messages from the persistent and non-persistent queues used by the agent. Specifically, this command can carry out the following actions:

Remove any transfers that were in progress to this agent or from this agent before the transfer was stopped. These transfers are not resumed when the agent restarts
Remove any commands that have already been submitted to the agent, but have not yet been carried out
Delete all resource monitors stored on the agent
Delete all scheduled transfers stored on the agent
Delete all invalid messages stored on the agent

If the agent is a Connect:Direct® bridge agent, the -ms, -ss, and -ims parameters are not valid. For Connect:Direct bridge agents the command also carries out the following actions:

Deletes all files from the directory where the Connect:Direct bridge agent temporarily stores files while they are being transferred. The location of this directory is defined by the cdTmpDir parameter
Displays information about the Connect:Direct processes that are associated with any ongoing transfers

Before IBM® MQ 9.0.3 and IBM MQ 9.0.0 Fix Pack 2, if you run the fteCleanAgent command with just the agent_name parameter, by default the command runs as if the -all parameter has been supplied, which results in all the scheduled transfers, the resource monitor and scheduled transfer definitions on the agent being cleared.

From IBM MQ 9.0.3 and IBM MQ 9.0.0 Fix Pack 2, you must, by default, specify which Managed File Transfer state to clear by passing the appropriate parameters to the fteCleanAgent command, as well as providing an agent name. This means that, by default, fteCleanAgent does not clear all in-progress and pending transfers, resource monitor definitions and scheduled transfer definitions for the agent specified. You can enable or disable this behavior by setting the failCleanAgentWithNoArguments property in the command.properties file to the appropriate value:

By default, the value of failCleanAgentWithNoArguments is true, which means that the fteCleanAgent command fails to run if only the agent_name parameter is specified.
If failCleanAgentWithNoArguments is set to false and only the agent_name parameter is specified, fteCleanAgent behaves in the same way as it does when you specify the -all parameter.

You must run the fteCleanAgent command on an agent that has been stopped. If you try to run the command on an agent that is currently running, you receive an error. This command does not start the agent. The fteCleanAgent command cleans up an agent on the system where you issue the command. You cannot clean up an agent on a remote system. To run the fteCleanAgent command you must have write access to the agent lock file, which is located at MQ_DATA_PATH\mqft\logs\coordination_QMgr_name\agents\agent_name\agent.lck

The FTEAGENT group must have GET and BROWSE authority on the following queues to run fteCleanAgent successfully:

SYSTEM.FTE.COMMAND.agent_name
SYSTEM.FTE.EVENT.agent_name
SYSTEM.FTE.STATE.agent_name

See Restricting group authorities for MFT-specific resources for further information about the FTEAGENT group and restricting group authorities.

If you are running the fteCleanAgent command on an agent that is connected to its queue manager in bindings mode, and the agent has recently stopped running, the fteCleanAgent command might report messaging problem: MQRC 2042. This MQRC occurs because a queue handle for the agent still exists in the queue manager. After a short delay the queue manager removes this handle, and you can reissue fteCleanAgent.

Specify the optional -p parameter for this command only if you want to use a set of configuration options different from your default set. See Configuration options for more information.

Note: When cleaning a Connect:Direct bridge agent, the user ID used to run the fteCleanAgent command must have read and write access to the Connect:Direct bridge agent temporary directory.

Syntax

fteCleanAgent

Parameters

You can use the fteCleanAgent command to delete specific artifacts. For example, you can specify the -trs command to delete pending transfers but not change any resource monitors and scheduled transfers.

-trs or -transfers: Optional. Specifies that in-progress and pending transfers are to be deleted from the agent. You cannot specify this parameter with -all or -ims parameters.
-ms or -monitors: Optional. Specifies that all resource monitor definitions are to be deleted from the agent. You cannot specify this parameter with -all or -ims parameters.
-ss or -schedules: Optional. Specifies that all scheduled transfer definitions are to be deleted from the agent. You cannot specify this parameter with the -all or -ims parameters.
-all or -allAgentConfiguration: Optional. Specifies that all transfers, resource monitor definitions and scheduled transfer definitions are to be deleted from the agent. You cannot specify this parameter with the -trs,-ss, -ms, or -ims parameters.
Attention: You should use the all parameter only if no other options are available. The action of deleting transfers, resource monitor definitions, and scheduled transfer definitions can have a significant impact on your enterprise.
-ims or -invalidMessages: Optional. Specifies that all invalid messages are to be deleted from the agent. You cannot specify this parameter with the -trs,-ss,-ms, or -all parameters.
-cdu user_name: Optional. Only valid if the agent being cleaned is a Connect:Direct bridge agent. If this parameter is specified, the command uses the user name provided to make a connection to the Connect:Direct bridge node and retrieve additional information about existing Connect:Direct processes. If you do not specify this parameter, the agent is cleaned but information about Connect:Direct processes is not displayed.
-cdp password: Optional. Valid only if the agent being cleaned is a Connect:Direct bridge agent and you have specified the -cdu parameter. If you specify the -cdp parameter, the command uses the password provided to make a connection to the Connect:Direct bridge node and retrieve additional information about existing Connect:Direct processes. If you do not specify this parameter, and the -cdu parameter has been specified, you are asked to provide the password interactively.
-mquserid (userID): Optional. Specifies the user ID to authenticate with the agent queue manager.
-mqpassword (password): Optional. Specifies the password to authenticate with the agent 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.
-p (configuration_options): Optional. This parameter determines the set of configuration options that is used to clean up an agent. By convention 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.
agent_name: Required. The name of the Managed File Transfer agent that you want to clean up.
-? or -h: Optional. Displays command syntax.

Examples

In this basic example, all the queues used by AGENT2 are cleaned up:


 C:\Documents and Settings\Administrator>fteCleanAgent -all AGENT2
5724-H72 Copyright IBM Corp. 2008, 2024. ALL RIGHTS RESERVED

All messages will be deleted from all queues

State Queue Entries:

Transfer Identifier:               414d5120716d312020202020202020202786de4d20485b03
Source Agent Name:                 AGENT2
Destination Agent Name:            AGENT3

Transfer Identifier:               414d5120716d312020202020202020202786de4d20487203
Source Agent Name:                 AGENT2
Destination Agent Name:            AGENT3


Command Queue New Transfer Entries:


Scheduler Queue Schedule Entries:

Directory Monitor Configuration for "MONITOR1" has been cleared from the Agent.


Schedule Identifier:         1
Source Agent Name:           AGENT2
Destination Agent Name:      AGENT3

BFGCL0149I: The agent 'AGENT2' has been cleaned.

In this example, the invalid messages queue used by AGENT2 are cleaned up:


C:\Documents and Settings\Administrator>fteCleanAgent -ims AGENT2
5724-H72 Copyright IBM Corp. 2008, 2024. ALL RIGHTS RESERVED

Invalid messages will be deleted from all queues

State Queue Entries:

Warning - Invalid message found on the queue


Command Queue New Transfer Entries:

Warning - Invalid message found on the queue


Scheduler Queue Schedule Entries:

Warning - Invalid message found on the queue

BFGCL0149I: The agent 'AGENT2' has been cleaned.

In this example, the transfers queue used by the Connect:Direct bridge agent, AGENT_CD_BRIDGE, is cleaned up:


C:\Documents and Settings\Administrator>fteCleanAgent -trs -cdu USER1 AGENT_CD_BRIDGE
5724-H72 Copyright IBM Corp. 2008, 2024. ALL RIGHTS RESERVED
Enter Connect:Direct password:

All messages will be deleted from the state and command queues

State Queue Entries:

Transfer Identifier:               414d5120716d312020202020202020202786de4d2048a703
Source Agent Name:                 AGENT2
Destination Agent Name:            AGENT_CD_BRIDGE
Connect:Direct PNODE Name:         CDNODE1
Connect:Direct SNODE Name:         CDNODE2
Connect:Direct Current Processes:  Name=FA34F8, Number=139



Command Queue New Transfer Entries:

BFGCL0149I: The agent 'AGENT_CD_BRIDGE' has been cleaned.

Return codes

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