fteCleanAgent (cleans up a WebSphere MQ File Transfer Edition agent)

Use the fteCleanAgent command to clean up the queues that a WebSphere® MQ File Transfer Edition 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

Run this command on an agent that has been stopped. If you try to run the fteCleanAgent 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 configuration_directory\coordination_QMgr_name\agents\agent_name\agent.lck

If you have enabled the Version 7.0.4.1 function, the FTEAGENT group must have 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

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

Syntax diagram format

           

Read syntax diagramSkip visual syntax diagram
fteCleanAgent

>>-fteCleanAgent--+-------------+--+------------+--------------->
                  +- -trs-------+  +- -ms-------+   
                  '- -transfers-'  '- -monitors-'   

>--+-------------+--+-------------------------+----------------->
   +- -ss--------+  +- -all-------------------+   
   '- -schedules-'  '- -allAgentConfiguration-'   

>--+-------------------+---------------------------------------->
   +- -ims-------------+   
   '- -invalidMessages-'   

>--+-------------------------------------------+---------------->
   '- -cdu--(user_name)--+-------------------+-'   
                         '- -cdp--(password)-'     

>--+------------------------------+--agent_name----------------><
   '- -p--(configuration_options)-'               

Parameters

The syntax of this command depends on whether you are using Version 7.0.4 and earlier, or Version 7.0.4.1 and later. The -trs, -ms, -ss, -ims, and -all parameters were introduced at Version 7.0.4.1, so if you have enabled the Version 7.0.4.1 function 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. For V7.0.4 and earlier versions, you can only use the fteCleanAgent command to delete all artifacts.

-trs or -transfers
Optional. Available only if you have enabled the Version 7.0.4.1 function. 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. Available only if you have enabled the Version 7.0.4.1 function. 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. Available only if you have enabled the Version 7.0.4.1 function. 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. Available only if you have enabled the Version 7.0.4.1 function. 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.

-ims or -invalidMessages
Optional. Available only if you have enabled the Version 7.0.4.1 function. 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.

-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 WebSphere MQ File Transfer Edition agent that you want to clean up.

-? or -h
Optional. Displays command syntax.

Examples

In this basic example, for Version 7.0.4 and earlier, the queues used by AGENT2 are cleaned up:
fteCleanAgent AGENT2
In this example, for Version 7.0.4 and earlier, the queues used by the Connect:Direct bridge agent, AGENT_CD_BRIDGE, are cleaned up. There is one incomplete transfer associated with this agent, and the Connect:Direct processes associated with this transfer are displayed in the command output:
fteCleanAgent -cdu cduser01 AGENT_CD_BRIDGE

5655-U80, 5724-R10 Copyright IBM Corp. 2008, 2018. ALL RIGHTS RESERVED
Enter Connect:Direct password:

State Queue Entries:

Transfer Identifier: 414d5120514d3120202020202020202090006e4d20013903
Source Agent Name: AGENT_CD_BRIDGE
Destination Agent Name: AGENT1
Connect:Direct PNODE Name: CDNODE1
Connect:Direct SNODE Name: CDNODE2
Connect:Direct Current Processes: Name=FC52D700, Number=21
                                  Name=FC52D700, Number=22



Command Queue New Transfer Entries:


Scheduler Queue Schedule Entries:

BFGCL0149I: The agent 'AGENT_CD_BRIDGE' has been cleaned.
In this basic example, for Version 7.0.4.1 and later, all the queues used by AGENT2 are cleaned up:
 C:\Documents and Settings\Administrator>fteCleanAgent -all AGENT2
5655-U80, 5724-R10 Copyright IBM Corp.  2008, 2018.  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, for Version 7.0.4.1 and later, the invalid messages queue used by AGENT2 are cleaned up:
C:\Documents and Settings\Administrator>fteCleanAgent -ims AGENT2
5655-U80, 5724-R10 Copyright IBM Corp.  2008, 2018.  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, for Version 7.0.4.1 and later, 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
5655-U80, 5724-R10 Copyright IBM Corp.  2008, 2018.  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.

Reference Reference

Feedback

Timestamp icon Last updated: Tuesday, 30 January 2018
http://www.ibm.com/support/knowledgecenter/SSEP7X_7.0.4/com.ibm.wmqfte.doc/clean_agent_cmd.htm