fteDeleteAgent: delete an MFT agent and its configuration

The fteDeleteAgent command deletes a Managed File Transfer Agent and its configuration. If the agent is a protocol bridge agent, the user credentials file is left on the file system.


Purpose

Stop the agent with the fteStopAgentcommand before running the fteDeleteAgent command.

If we have configured your agent to run as a Windows service, running the fteDeleteAgent command deletes the service definition.

From IBM MQ Version 9.1, any resource monitor and scheduled transfers are removed when the agent is deleted.

Only users who are IBM MQ administrators (and members of the mqm group) can run this command. If you try to run this command as a user who is not an IBM MQ administrator, we will receive an error message and the command will not run.

The fteDeleteAgent command provides you with the MQSC commands that we must run against your agent's queue manager to clear and delete the agent's system queues. These queues are as follows:

  • SYSTEM.FTE.AUTHADM1.agent_name
  • SYSTEM.FTE.AUTHAGT1.agent_name
  • SYSTEM.FTE.AUTHMON1.agent_name
  • SYSTEM.FTE.AUTHOPS1.agent_name
  • SYSTEM.FTE.AUTHSCH1.agent_name
  • SYSTEM.FTE.AUTHTRN1.agent_name
  • SYSTEM.FTE.COMMAND.agent_name
  • SYSTEM.FTE.DATA.agent_name
  • SYSTEM.FTE.EVENT.agent_name
  • SYSTEM.FTE.REPLY.agent_name
  • SYSTEM.FTE.STATE.agent_name

The fteCreateAgent command also provides these commands in a file in the following location: 

MQ_DATA_PATH/mqft/config/coordination_qmgr_name/agents/agent_name/agent_name_delete.mqsc


Usage notes

Note the following points when using the -x parameter:
  1. If you specify the -x parameter to delete an agent that is not highly available, the option is ignored and message BFGCL0791I is displayed on the console.
  2. If we do not specify the -x parameter to delete a high availability agent, the command deletes the agent configuration on the machine but does not deregister the agent, meaning that no message is published to the SYSTEM.FTE/Agents/<agent name> topic. This is because another instance of the agent might have been configured, or running, elsewhere.Attention: We should not use the -x parameter when deleting all configurations of standby instances.
  3. If you specify the -x parameter to delete a highly available agent, the command deletes the configuration and deregisters the agent, publishing a message to the SYSTEM.FTE/Agents/<agent name> topic, marking the agent as deleted. Attention: We must specify the -x parameter to delete the last, or the active instance, configuration of an agent.

In the situation where all instances of a highly available agent are deleted without using the -x parameter, the agent does not get deregistered from the SYSTEM.FTE/Agents topic. In such cases, use the existing force (-f) parameter to delete the agent.


Syntax

fteDeleteAgent

fteDeleteAgent-p configuration_options -f-mquseriduserID-mqpasswordpassword-xagent_name


Parameters

    -p (configuration_ options)
    Optional. If we have more than one coordination queue manager, use this parameter to explicitly specify which agent configuration we want to delete. Use the name of a non-default coordination queue manager as the input for this parameter. The command then uses the configuration options associated with this non-default coordination queue manager.

    Specify the optional -p parameter only if we want to use configuration options different from your defaults. If we do not specify -p, the configuration options defined in the installation.properties file are used. See Configuration options for more information.

    -f
    Optional. Forces the command to deregister the agent from the coordination queue manager even if the agent's configuration files cannot be found. Because information about the agent's queue manager is not available in this situation, the command will connect directly to the coordination queue manager instead of using the agent queue manager as it normally would.

    -mquserid (userID)
    Optional. Specifies the user ID to authenticate with the agent queue manager, unless the force -f parameter is present. If the -f parameter is present, it specifies the user ID to authenticate with the coordination queue manager.

    -mqpassword (password)
    Optional. Specifies the password to authenticate with the agent queue manager, unless the force -f parameter is present. If the -f parameter is present, it specifies the password to authenticate with the coordination queue manager. We must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, we will be prompted to supply the associated password. The password will not be displayed.

    -x
    Optional. Deletes the configuration of a highly available agent. If we do not specify this option, the configuration of a highly available agent is deleted from the file system, but the agent is not deregistered. Attention: We must specify this option when deleting the last instance of a highly available agent.
    This option is ignored for an agent that is not configured for high availability.

    agent_name
    Required. The name of the agent that we want to delete.

    -? or -h
    Optional. Displays command syntax.


Example

In this example, AGENT3 and its configuration on coordination queue manager QM_COORD1 are deleted: 
fteDeleteAgent -p QM_COORD1 AGENT3
This example command outputs the following MQSC commands to delete the agent's three queues: 
CLEAR QLOCAL(SYSTEM.FTE.COMMAND.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.COMMAND.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.DATA.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.DATA.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.REPLY.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.REPLY.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.STATE.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.STATE.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.EVENT.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.EVENT.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHADM1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHADM1.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHAGT1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHAGT1.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHTRN1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHTRN1.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHOPS1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHOPS1.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHSCH1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHSCH1.AGENT3)
CLEAR QLOCAL(SYSTEM.FTE.AUTHMON1.AGENT3)
DELETE QLOCAL(SYSTEM.FTE.AUTHMON1.AGENT3)
In this example, an agent that is configured as highly available is deleted.
fteDeleteAgent -p <configuration> -x <agent name>


Return codes

    0
    Command completed successfully.

    1
    Command ended unsuccessfully.

Parent topic: MFT commands


Related reference