fteCreateCDAgent (create a Connect:Direct bridge agent)

The fteCreateCDAgent command creates a WebSphere® MQ File Transfer Edition agent and its associated configuration for use with the Connect:Direct® bridge. This command is provided with WebSphere MQ File Transfer Edition Server and Client.

Purpose

Use the fteCreateCDAgent command to create a Connect:Direct bridge agent. This type of agent is dedicated to transferring files to and from Connect:Direct nodes. For more information, see The Connect:Direct bridge. For details of the supported operating system versions for the Connect:Direct bridge, see the web page WebSphere MQ File Transfer Edition System Requirements.

This command provides you with the MQSC commands that you must run against your agent queue manager to create the following agent queues:
  • 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

These queues are internal system queues that you must not modify, delete, or read messages from unless you are deleting the agent. The MQSC commands to run are also supplied in a file in the following location: configuration_directory\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc.

If you later want to delete the agent, this command also provides you with the MQSC commands you must run to clear then delete the queues belonging to the agent. The MQSC commands are in a file in the following location: configuration_directory\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc.

WebSphere MQ File Transfer Edition provides advanced agent properties that help you configure agents. These properties are described in Properties files for WebSphere MQ File Transfer Edition.

This command creates three XML files in the agent properties directory. These files are ConnectDirectCredentials.xml, which is used to define the user names and passwords that the Connect:Direct bridge agent uses to connect to Connect:Direct nodes, ConnectDirectNodeProperties.xml, which is used to define information about the remote nodes in a transfer, and ConnectDirectProcessDefinitions.xml, which is used to specify which user-defined Connect:Direct processes are started by transfers.

Syntax diagram format

           

Read syntax diagramSkip visual syntax diagram
fteCreateCDAgent

>>-fteCreateCDAgent-- -agentName-- -(agent_name)---------------->

>-- -agentQMgr-- -(agent_qmgr_name)----------------------------->

>-- -cdNode-- -(cd_node_name)----------------------------------->

>--+--------------------------------------+--------------------->
   '- -agentQMgrHost-- -(agent_qmgr_host)-'   

>--+--------------------------------------+--------------------->
   '- -agentQMgrPort-- -(agent_qmgr_port)-'   

>--+--------------------------------------------+--------------->
   '- -agentQMgrChannel-- -(agent_qmgr_channel)-'   

>--+------------------------------------+----------------------->
   '- -agentDesc-- -(agent_description)-'   

>--+---------------------+-------------------------------------->
   +- -ac----------------+   
   '- -authorityChecking-'   

>--+--------------------------------+--+-----+------------------>
   '- -p-- -(configuration_options)-'  '- -f-'   

>--+--------------------------------+--------------------------->
   '- -cdNodeHost-- -(cd_node_host)-'   

>--+--------------------------------+--------------------------->
   '- -cdNodePort-- -(cd_node_port)-'   

>--+----------------------------+------------------------------->
   '- -cdTmpDir-- -(cd_tmp_dir)-'   

>--+----------------------------------------------------------------------------------------------------------------------+-><
   +- -s-- -+----------------+-- -su-- -(user_name)--+--------------------+--+-------------------+--+-------------------+-+   
   |        '-(service_name)-'                       '- -sp-- -(password)-'  '- -sj-- -(options)-'  '- -sl-- -(options)-' |   
   '- -n------------------------------------------------------------------------------------------------------------------'   

Parameters

-agentName (agent_name)
Required. The name of the agent you want to create. The agent name must be unique to its coordination queue manager.

For more information about naming agents, see Object naming conventions .

-agentQMgr (agent_qmgr_name)
Required. The name of the agent queue manager.

-cdNode (cd_node_name)
Required. The name of the Connect:Direct node to use to transfer messages from this agent to destination Connect:Direct nodes. The value of this parameter is used for logging and not to specify to the Connect:Direct bridge agent which node to connect to. The values of the -cdNodeHost and -cdNodePort specify the Connect:Direct node that is part of the Connect:Direct bridge.

-agentQMgrHost (agent_qmgr_host)
Optional. The host name or IP address of the agent queue manager.

-agentQMgrPort (agent_qmgr_port)
Optional. The port number used for client connections to the agent queue manager.

-agentQMgrChannel (agent_qmgr_channel)
Optional. The channel name used to connect to the agent queue manager.

-agentDesc (agent_description)
Optional. A description of the agent, which is displayed in WebSphere MQ Explorer.

-ac or -authorityChecking
Optional. This parameter enables authority checking. If you specify this parameter, the agent checks that users who are submitting requests are authorized to perform the requested action. For more information, see User authorities on WebSphere MQ File Transfer Edition actions.

-p (configuration_options)
Optional. This parameter determines the set of configuration options that is used to create an agent. By convention use the name of a non-default coordination queue manager as the input for this parameter. The fteCreateCDAgent command then uses the set of properties files associated with this non-default coordination queue manager.

Specify the optional -p parameter only if you want to use configuration options different from your defaults. If you do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

-f
Optional. Forces the command to overwrite the existing configuration.

-cdNodeHost (cd_node_host_name)
Optional. The host name or IP address of the system where the Connect:Direct node, specified by the -cdNode parameter, is located. If you do not specify the -cdNodeHost parameter, a default of the host name or IP address of the local system is used.

In most cases, the Connect:Direct node is on the same system as the Connect:Direct bridge agent. In these cases, the default value of this property, which is the IP address of the local system, is correct. If your system has multiple IP addresses, or your Connect:Direct node is on a different system to your Connect:Direct bridge agent and their systems share a file system, use this property to specify the correct host name for the Connect:Direct node.

-cdNodePort (cd_node_port_name)
Optional. The port number of the Connect:Direct node that client applications use to communicate with the node that is specified by the -cdNode parameter. In Connect:Direct product documentation, this port is referred to as the API port. If you do not specify the -cdNodePort parameter, a default port number of 1363 is assumed.

-cdTmpDir (cd_tmp_directory)
Optional. The directory to be used by this agent to store files temporarily before they are transferred to the destination Connect:Direct node. This parameter specifies the full path of the directory where files are temporarily stored. For example, if cdTmpDir is set to /tmp then the files are temporarily placed in the /tmp directory. If you do not specify the -cdTmpDir parameter, the files are stored temporarily in a directory named cdbridge-agent_name. This default directory is created in the location that is defined by the value of the java.io.tmpdir property.

The Connect:Direct bridge agent and the Connect:Direct bridge node must be able to access the directory specified by this parameter using the same path name. Consider this when planning the installation of your Connect:Direct bridge. If possible, create the agent on the system where the Connect:Direct node that is part of the Connect:Direct bridge is located. If your agent and node are on separate systems, the directory must be on a shared file system and be accessible from both systems using the same path name. For more information about the supported configurations, see The Connect:Direct bridge.

Note: If you run the fteCleanAgent command, all files in this directory are deleted.
-s (service_name)
Optional (Windows only). Indicates that the agent is to run as a Windows service. If you do not specify service_name, the service is named fteAgent<AGENT><QMGR>, where <AGENT> is the agent name and <QMGR> is your agent queue manager name.

The display name for the service, which is shown in the Windows Services window in the Name column, is always IBM WMQFTE agent <AGENT>@<QMGR>.

-su (user_name)
Optional (Windows only). When the agent is to run as a Windows service, this parameter specifies the name of the account under which the service runs. To run the agent using a Windows domain user account specify the value in the form DomainName\UserName. To run the service using an account from the local built-in domain specify the value in the form UserName.

The Windows user account that you specify using the -su parameter must have the Log on as a service right. For information about how to grant this right, see Guidance for running an agent or database logger as a Windows service.

Required when -s specified. Equivalent to -serviceUser.

-sp (password)
Optional (Windows only). Password for the user account set by -su or -serviceUser parameter.

This parameter is only valid when -s is specified. Equivalent to -servicePassword. If you do not specify this parameter when you specify the -s parameter, a warning message is produced. This message warns you that you must set the password using the Windows Services tool before the service starts successfully.

-sj (options)
Optional (Windows only). When the agent is started as a Windows service, defines a list of options in the form of -D or -X that are passed to the JVM. The options are separated using a number sign (#) or semicolon (;) character. If you must embed any # or semicolon (;) characters, put them inside single quotation marks.

This parameter is only valid when -s is specified. Equivalent to -serviceJVMOptions.

-sl (options)
Optional (Windows only). Sets the Windows service log level. Valid options are: error, info, warn, debug. The default is info. This option can be useful if you are having problems with the Windows service. Setting it to debug gives more detailed information in the service log file.

This parameter is only valid when -s is specified. Equivalent to -serviceLogLevel.

-n
Optional (Windows only). Indicates that the agent is to be run as a normal process. This is mutually exclusive with the -s option. If neither one of the -s parameter and the -n parameter is specified, then the agent is configured as a normal Windows process.

Equivalent to -normal.

Example

In this example, a new Connect:Direct bridge agent CD_BRIDGE is created with an agent queue manager QM_NEPTUNE. The agent uses the Connect:Direct node BRIDGE_NODE to transfer files to other Connect:Direct nodes. The BRIDGE_NODE node is located on the same system as the agent and uses the default port for client connections. Files that are transferred to or from Connect:Direct are temporarily stored in the directory /tmp/cd-bridge.
fteCreateCDAgent -agentName CD_BRIDGE -agentQMgr QM_NEPTUNE 
                 -cdNode BRIDGE_NODE -cdTmpDir /tmp/cd-bridge

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/cd_create_agent_cmd.htm