fteCreateWebAgent (create an IBM MQ Managed File Transfer web agent)
The fteCreateWebAgent command creates an agent and its associated configuration for use with the Web Gateway. This command is provided with IBM® MQ Managed File Transfer Server.
Purpose
- 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
- SYSTEM.FTE.WEB.RESP.agent_name
- SYSTEM.FTE.WEB.gateway_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: MQ_DATA_PATH\mqft\config\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: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc.
IBM MQ Managed File Transfer provides advanced agent properties that help you configure agents. These properties are described in The agent.properties file.
Limitations of the web agent
- A web agent can be only the source agent for transfers initiated by a Web Gateway. If you attempt to perform a transfer with a web agent as the source by another method, the transfer fails with return code 68 (TRANSFER_NOT_SUPPORTED).
- A web agent can only be the destination agent for a transfer when the destination is specified as a file space. If you attempt to perform a transfer with a web agent as the destination agent but a different destination type the transfer will fail with the following error message: BFGCH0103: The transfer request specifies Web Gateway agent 'web_agent_name' as the destination agent. Web Gateway agents can be the destination only for a transfer to a file space.
- A web agent cannot monitor a resource. If you attempt to create a resource monitor for a web agent, the command fails with return code 113 (MONITOR_NOT_SUPPORTED).
Syntax
Parameters
- -agentNameagent_name
- Required. The name of the agent to create. The agent name must
be unique to its coordination queue manager.
For more information about naming agents, see Object naming conventions .
- -agentQMgragent_qmgr_name
- Required. The name of the agent queue manager.
- -webGatewayNamegateway_name
- Required. The name of the Web Gateway that the agent is a component
of.
For more information about naming Web Gateways, see Object naming conventions .
- -agentQMgrHostagent_qmgr_host
- Optional. The host name or IP address of the agent queue manager. If you do not specify this parameter, a bindings mode connection is assumed.
- -agentQMgrPortagent_qmgr_port
- Optional. The port number used for client connections to the agent queue manager. This parameter is used only if you have also specified the agentQMgrHost parameter. If you do not specify the agentQMgrPort parameter, a default port of 1414 is used.
- -agentQMgrChannelagent_qmgr_channel
- Optional. This parameter is used only if you have also specified the agentQMgrHost parameter. If you do not specify the agentQMgrChannel parameter, a default channel of SYSTEM.DEF.SVRCONN is used.
- -agentDescagent_description
- Optional. A description of the agent, which is displayed in IBM 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.
- -pconfiguration_options
- Optional. The name of the set of configuration options that is used to create the agent. By convention, this is the name of a coordination queue manager. If you do not specify this parameter, the default set of configuration options is used.
- -f
- Optional. Forces the command to overwrite the existing configuration.
- -sservice_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
mqmftAgent<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 MQ Managed File Transfer agent <AGENT>@<QMGR>.
- -suuser_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
should run. 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 formUserName
.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 logger as a Windows service.
Required when -s specified. Equivalent to -serviceUser.
- -sppassword
- 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 will start successfully.
- -sjoptions
- 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 will be passed
to the JVM. The options are separated using a number sign (#) or semicolon
(;) character. If you need to embed any # or ; characters, put them
inside single quotation marks.
This parameter is only valid when -s is specified. Equivalent to -serviceJVMOptions.
- -sloptions
- 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
the -s nor the -n option
is specified, then the agent is configured as a normal Windows process.
Equivalent to -normal.
- -? or -h
- Optional. Displays the command syntax.
Example
In this example, the agent WEBAGENT1 is created with an agent queue manager QM_NEPTUNE and the Web Gateway GATEWAY_ONE. The agent uses the default coordination queue manager:fteCreateWebAgent -agentName WEBAGENT1 -webGatewayName GATEWAY_ONE -agentQMgr QM_NEPTUNE
-agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1
Return codes
- 0
- Command completed successfully.
- 1
- Command ended unsuccessfully.