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

Use the fteCreateWebAgent command to create a web agent. This command provides you with the MQSC commands that you must run on the queue manager that is used by the agent 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
Because the agent is for use with the Web Gateway, two queues are created in addition to the previous list:
  • 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.

Note: The user that your web agent runs as must be the same as, or in the same group as, the user that your application server runs as.

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

fteCreateWebAgent

Read syntax diagramSkip visual syntax diagramfteCreateWebAgent-agentName? agent_name-agentQMgr? agent_qmgr_name-webGatewayName? gateway_name-agentQMgrHost?agent_qmgr_host-agentQMgrPort?agent_qmgr_port-agentQMgrChannel?agent_qmgr_channel-agentDesc?agent_description-ac-authorityChecking-pconfiguration_options-f-s?service_name-su?user_name-sp?password-sj?options-sl?options-n

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 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 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.