The agent.properties file

Each agent has its own properties file, agent.properties, that must contain the information that an agent uses to connect to its queue manager. The agent.properties file can also contain properties that alter the behavior of the agent.

The agent.properties file is created by the installer or by the fteCreateAgent, fteCreateWebAgent, fteCreateBridgeAgent or fteCreateCDAgent command. You can use any of these commands with the -f flag to change the basic agent queue manager properties and those advanced agent properties associated with the type of agent that you are creating. To change or add advanced agent properties you must edit the file in a text editor.

The agent.properties file for an agent is located in your config_directory/coordination_qmgr_name/agents/agent_name directory.

If you change the agent.properties file you must restart the agent to pick up the changes.

Each agent.properties file contains the following values:
Table 1. Agent properties
Property name Description Default value
agentName The name of the agent. The name of the agent must conform to the WebSphere® MQ object naming conventions. For more information, see Object naming conventions for WebSphere MQ File Transfer Edition. No default
agentDesc The description of the agent - if you have chosen to create a description. No default
agentQMgr The agent queue manager name. No default
agentQMgrHost The host name or IP address of the agent queue manager. No default
agentQMgrPort The port number used for client connections to the agent queue manager. 1414
agentQMgrChannel The SVRCONN channel name used to connect to the agent queue manager. SYSTEM.DEF.SVRCONN
agentType The type of agent: either a protocol bridge agent (BRIDGE) or a standard non-protocol bridge agent (STANDARD). STANDARD

If you do not specify a value for the agentQMgrHost property, bindings mode is used by default.

If you specify a value for the agentQMgrHost property but do not specify values for the agentQMgrPort and agentQMgrChannel properties, a port number of 1414 and a channel of SYSTEM.DEF.SVRCONN are used by default.

Advanced agent properties

WebSphere MQ File Transfer Edition also provides more advanced agent properties that help you configure agents. If you want to use any of the following properties, manually edit the agent.properties file to add the required advanced properties. When you specify file paths on Windows, ensure the separator character backslash (\) is entered as double backslashes (\\), that is, escaped backslash (\). Alternatively, you can use a single forward slash (/) character as a separator. For further information about character escaping in Java™ properties files, see the Oracle documentation Javadoc for the Properties class.

Table 2. Advanced agent properties
Property name Description Default value
Agent size properties:
agentCheckpointInterval

The interval in complete frames of data between which a checkpoint is taken for recovery purposes. This is an advanced property and for most WebSphere MQ File Transfer Edition configurations it is not necessary to modify its value.

If there is a problem which causes the transfer to go into recovery, the transfer can recover only to a checkpoint boundary. Hence, the larger this value (with large agentChunkSize, agentWindowSize, and agentFrameSize values), the longer the time that is needed for the agent to recover transfers. For reliable WebSphere MQ File Transfer Edition networks where transfers rarely enter a recovery state, it may be beneficial to increase this value to increase overall performance.

1
agentChunkSize

The size of each transfer chunk for the transport of file data. Hence, denotes the maximum size of the WebSphere MQ messages that are transferred between the source and the destination agents. This is an advanced property and for most WebSphere MQ File Transfer Edition configurations it is not necessary to modify its value.

This value is negotiated between the source agent and the destination agent, and the larger of the two values is used. If you want to change the value of this property, change the value at both the source agent and at the destination agent.

agentChunkSize is an integer value. For example: agentChunkSize = 10,240 sets the chunk size to 10 KB.

262144-byte (which is equivalent to 256 KB)
agentFrameSize

The number of windows for the transfer frame. This is an advanced property and for most WebSphere MQ File Transfer Edition configurations it is not necessary to modify its value.

For networks that have high latency, increasing this value may improve overall performance as it causes the agent to have more message chunks active concurrently.

The value of this property, multipled by agentWindowSize, multiplied by agentChunkSize, denotes the upper limit of the memory consumption of the agent for each transfer. For example, 262144-byte chunks x 10 x 5 = 12.5 MB for each transfer.

Note: If the size of the files that is transferred in a single transfer is less than 12.5 MB increasing this property has no effect on the performance of the transfer.

5
agentWindowSize

The number of chunks for each window. This is an advanced property and for most WebSphere MQ File Transfer Edition configurations it is not necessary to modify its value.

For networks that have high latency, increasing this value may improve overall performance. This is because it causes the agent to have more message chunks active concurrently and reduces the frequency that acknowledgement messages are sent back to the source agent.

The value of this property, multiplied by agentFrameSize, multiplied by agentChunkSize, denotes the upper limit of the memory consumption of the agent for each transfer, and denotes the upper limit of the WebSphere MQ message data on the command queue of the destination agent. For example, 262144-byte chunks x 10 x 5 = an upper limit of 12.5 MB, for each transfer.

Note: If the size of the files that is transferred in a single transfer is less than 12.5 MB increasing the value of this property has no effect on the performance of the transfer.

10
Code page properties:
agentCcsid The code page the agent connects to its agent queue manager with. If you specify a value for agentCcsid you must also specify a value for agentCcsidName. For information on how to view the known code pages for the JVM, see the -hsc parameter in the fteCreateBridgeAgent command. 1208
agentCcsidName The Java representation of the agentCcsid. If you specify a value for agentCcsidName you must also specify a value for agentCcsid. UTF8
Command properties:
maxCommandHandlerThreads Controls the number of threads available for the initial parsing and processing of transfer command messages. When active, the threads require a connection to the queue manager but the threads release the connection when idle. 5
maxCommandOutput The maximum number of bytes stored for command output. This property applies to commands specified for a managed call and preSource, postSource, preDestination, and postDestination commands for a managed transfer. This limits the length of command output written to the transfer log on the SYSTEM.FTE topic. 10 KB
maxCommandRetries The maximum number of retries for a command that the agent permits. This property applies to commands specified for a managed call and the preSource, postSource, preDestination, and postDestination commands for a managed transfer. 9
maxCommandWait The maximum wait, in seconds, between retries that the agent permits. This property applies to commands specified for a managed call and the preSource, postSource, preDestination, and postDestination commands for a managed transfer. 60
immediateShutdownTimeout For an immediate shutdown of an agent, you can use this property to specify the maximum amount of time in seconds an agent waits for its transfers to complete before forcing a shutdown.
Note: Do not change the value of this property to less than the default of 10 seconds. An immediate shutdown of an agent requires sufficient time to end any external processes. If the value of this property is too low, processes might be left running.

If the value 0 is specified for this property, the agent waits for all outstanding transfers to stop. If an invalid value is specified for this property, the default value is used.

10
Connection properties:
javaLibraryPath When connecting to a queue manager in bindings mode WebSphere MQ File Transfer Edition must have access to the WebSphere MQ Java bindings libraries. By default WebSphere MQ File Transfer Edition looks for the bindings libraries in the default location defined by WebSphere MQ. If the bindings libraries are in a different location, use this property to specify the location of the bindings libraries. /opt/mqm/java/lib
Connect:Direct bridge properties:
cdNode Required property if you want to use the Connect:Direct bridge.

The name of the Connect:Direct node to use to transfer messages from the Connect:Direct bridge agent to destination Connect:Direct nodes. This node is part of the Connect:Direct bridge, not the remote node that is the source or destination of the transfer. For more information, see The Connect:Direct bridge.

No default
cdNodeHost The host name or IP address of the Connect:Direct node to use to transfer files from the Connect:Direct bridge agent to destination nodes (the Connect:Direct bridge node).

In most cases, the Connect:Direct bridge 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 bridge 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 bridge node.

If you have not set the cdNode property, this property is ignored.

The host name or IP address of the local system
cdNodePort The port number of the Connect:Direct bridge node that client applications use to communicate with the node. In Connect:Direct product documentation, this port is referred to as the API port.

If you have not set the cdNode property, this property is ignored.

1363
cdTmpDir The location to store files temporarily on the system where the Connect:Direct bridge agent is running before they are transferred to the destination Connect:Direct node.

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

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.

If you have not set the cdNode property, this property is ignored.

value_of_java.io.tmpdir/cdbridge-agentName

On Windows, value_of_java.io.tmpdir\cdbridge-agentName

cdTrace Whether the agent traces data sent between the Connect:Direct bridge agent and its Connect:Direct node. The value of this property can be true or false. false
cdMaxConnectionRetries The maximum number of Connect:Direct connection attempts, for a file transfer where a successful connection has not yet been made, before the transfer fails. -1 (an infinite number of attempts)
cdMaxPartialWorkConnectionRetries The maximum number of Connect:Direct connection attempts, for a file transfer where a previous connection attempt has been successful and transfer work has been performed, before the transfer fails. -1 (an infinite number of attempts)
cdMaxWaitForProcessEndStats The maximum time in milliseconds to wait for Connect:Direct process completion information to become available within the Connect:Direct node statistics information, after the process has ended, before the file transfer is judged to have failed. Typically the information is available immediately, but under certain failure conditions the information is not published. In these conditions the file transfer fails after waiting for the amount of time specified by this property. 60000
cdAppName The application name that the Connect:Direct bridge agent uses to connect to the Connect:Direct node that is part of the bridge. WebSphere MQ File Transfer Edition current version, where current version is the version number of the product. For example, 7.0.4.
cdNodeLocalPortRange The range of local ports to use for socket connections between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge. The format of this value is a comma-separated list of values or ranges.

By default, the operating system selects the local port numbers.

None
cdNodeProtocol The protocol that the Connect:Direct bridge agent uses to connect to the Connect:Direct node that is part of the bridge. The following values are valid:
  • TCPIP
  • SSL
  • TLS
TCPIP
cdNodeKeystore The path to the keystore that is used for secure communications between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

None
cdNodeKeystorePassword The password for the keystore specified by the cdNodeKeystore property.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

None
cdNodeKeystoreType The file format of the keystore specified by the cdNodeKeystore property. The following values are valid: jks and pkcs12.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

jks
cdNodeTruststore The path to the truststore that is used for secure communications between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

None
cdNodeTruststorePassword The password for the truststore specified by the cdNodeTruststore property.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

None
cdNodeTruststoreType The file format of the truststore specified by the cdNodeTruststore property. The following values are valid: jks and pkcs12.

If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

jks
logCDProcess The level of Connect:Direct process logging that is recorded in the agent event log in the output0.log file. The values that this property can have are None or Failures or All. None
File to message and message to file agent properties:
deleteTmpFileAfterRenameFailure Setting this property to a value of false ensures that temporary files are not deleted from the destination if the rename operation fails. In this case, the transferred data remains at the destination in a temporary (.part) file. You can manually rename this file later. By default, this property has the value of true. This property applies to both message-to-file and file-to-file transfers.

This property is not available on IBM i.

true
enableQueueInputOutput By default, the agent cannot read data from a source queue or write data to a destination queue as part of a transfer. Setting this value to true enables the agent to perform file to message, and message to file transfers. The value of this property can be true or false. false
enableSystemQueueInputOutput Specifies whether the agent can read from or write to WebSphere MQ system queues. System queues are prefixed with the qualifier SYSTEM.
Note: System queues are used by WebSphere MQ, WebSphere MQ File Transfer Edition, and other applications to transmit important information. Changing this property enables the agent to access these queues. If you enable this property, use user sandboxing to limit the queues that the agent can access.
false
maxDelimiterMatchLength The maximum number of characters that can be matched by the Java regular expression used to split a text file into multiple messages as part of a file-to-message transfer. 5
maxInputOutputMessageLength The maximum length, in bytes, of a message that is read from a source queue or written to a destination queue by an agent. The maxInputOutputMessageLength property of the source agent in a transfer determines how many bytes can be read from a message on the source queue. The maxInputOutputMessageLength property of the destination agent in a transfer determines how many bytes can be written to a message on the destination queue. If the length of the message exceeds the value of this property the transfer fails with an error. This property does not affect the WebSphere MQ File Transfer Edition internal queues. For information about changing this property, see Guidance for setting WebSphere MQ attributes and WebSphere MQ File Transfer Edition properties associated with message size. 1048576
monitorGroupRetryLimit The maximum number of times that a monitor triggers a message-to-file transfer again if the message group still exists on the queue. The number of times that the message-to-file transfer has been triggered is determined from the MQMD backout count of the first message in the group.

If the agent is restarted the monitor triggers a transfer again even if the number of times the transfer has been triggered has exceeded the value of monitorGroupRetryLimit. If this behavior causes the number of times that the transfer has been triggered to exceed the value of monitorGroupRetryLimit, the agent writes an error to its event log.

If the value -1 is specified for this property, the monitor triggers the transfer again an unlimited number of times, until the trigger condition is not satisfied.

10
General agent properties:
agentStatusPublishRateLimit The maximum rate in seconds that the agent republishes its status because of a change in file transfer status.

If you set this property to too small a value, the performance of the WebSphere MQ network might be negatively affected.

30
agentStatusPublishRateMin The minimum rate in seconds that the agent publishes its status. This value must be greater than or equal to the value of the agentStatusPublishRateLimit property. 300
agentStatusJitterTolerance

The maximum amount of time an agent status message publication can be delayed by before the message is considered as overdue. This value is measured in milliseconds.

The age of a status message is based on the time at which it was published at the coordination queue manager. However, the message is emitted by the agent some time before it is received at the coordination queue manager, to allow for the time required travel across the WebSphere MQ network. If this transit always takes the same amount of time then messages created 60 seconds apart are published 60 seconds apart, regardless of the actual time in transit. However, if the transit time varies between messages, they might be created at 60 second intervals but published at intervals of, for example, 61, 59, 58, and 62 seconds. The maximum deviation from 60, 2 seconds in this example, is the jitter. This property determines the maximum delay due to jitter before the message is treated as overdue.

3000
enableDetailedReplyMessages Setting this property to true enables managed transfer request replies to contain detailed information about the transferred files. The detailed information and format is the same as that published to the transfer log in the progress messages, that is, the <transferSet> element. For more information, see File transfer log message formats.

The detailed reply information is included only when the managed transfer request specifies that detailed reply information is required. To specify this requirement, set the detailed attribute of the <reply> element of the managedTransfer XML request message sent to the source agent. For more information, see File transfer request message format.

Multiple reply messages can be generated for each transfer request. This number is equal to the number of transfer log progress messages for the transfer plus 1 (where the first reply message is a simple ACK reply). Detailed information is included in all messages, except for the ACK reply messages, but the overall transfer result is included only in the last detailed reply message.

true
enableMemoryAllocationChecking This property is available only if you have enabled the function for Version 7.0.4.3, or later.

Determines whether the WMQFTE agent checks that there is sufficient memory available to run a transfer before a transfer is started. The check is made on both the source and destination agents. If there is insufficient memory available, the transfer is put into recovery, which prevents the agent from failing with an out-of-memory error.

When calculating the memory required for a transfer, the maximum memory that is required by the transfer is used. Therefore, the value might be greater than the actual memory that is used by the transfer. For this reason, the number of concurrent transfers that can run might be reduced if the enableMemoryAllocationChecking property is set to true. You are recommended to set the property to true only if you are experiencing problems with WMQFTE failing with out-of-memory errors. The transfers that are likely to consume large amounts of memory are file-to-message and message-to-file transfers where the sizes of the messages are large.

false
enableUserMetadataOptions Determines whether you can use known keys for user-defined metadata in new transfer requests to provide additional transfer options. These known keys always start with the following prefix com.ibm.wmqfte.. As a consequence when the enableUserMetadataOptions property is set true, keys using this prefix are not supported for user-defined use. When the enableUserMetadataOptions property is set to true, the keys supported currently are as follows:
  • com.ibm.wmqfte.insertRecordLineSeparator
  • com.ibm.wmqfte.newRecordOnLineSeparator
  • com.ibm.wmqfte.convertLineSeparators
For information about what these keys mean, see fteCreateTransfer (create new file transfer).

The value of this property can be true or false.

false
maxInlineFileSize This property is available only if you have enabled the function for Version 7.0.4.3, or later.

For single file-to-file, or file-to-message transfers, the maximum file size (in bytes) that can be automatically included in the initial transfer request message.

You can use this property to improve the speed of your transfers, but if you set the file size to too large a value, this might degrade performance. A suggested initial size for this property is 100 KB but you are recommended to thoroughly test different values until you find the best file size for your system.

0
Input/output properties:
doNotUseTempOutputFile

Not setting a value for this property means the agent writes to a temporary file at the destination and renames this temporary file to the required file name after the file transfer is complete. Setting this property to any value means the agent will not use a temporary file.

On z/OS® systems, this behavior does not apply to sequential data sets, but does apply to PDS data set members.

The value of this property for a transfer is defined by the destination agent.

No default
enableMandatoryLocking When accessing normal files WebSphere MQ File Transfer Edition takes a shared lock for reading and an exclusive lock for writing. On UNIX type platforms, file locking is honored across processes. However, on Windows file locking is advisory only. When this property is set to true, WebSphere MQ File Transfer Edition enforces file locking. On Windows this means that if another application has a file open, monitoring of that file does not trigger until the file is closed. WebSphere MQ File Transfer Edition transfers involving that file fail. For UNIX type platforms, setting this property has no effect.

The value of this property can be true or false.

false
ioIdleThreadTimeout Time in milliseconds for a file system input/output thread to remain idle before the thread shuts down. 10000
ioQueueDepth The maximum number of input/output requests to queue up. 10
ioThreadPoolSize Maximum number of file system input/output threads available. Typically each transfer uses its own file system input/output thread, but if the number of concurrent transfers exceeds this limit, the file system input/output threads are shared between transfers.

If you think you are likely to regularly have more concurrent transfers in progress than the ioThreadPoolSize value, you might see an improvement by increasing this value, so that each transfer has its own file system input/output thread.

10
textReplacementCharacterSequence For text mode transfer, if any of the data bytes cannot be converted from the source code page to the destination code page, the default behavior is for the file transfer to fail.

Set this property to allow the transfer to complete successfully by inserting the specified character value. This property value is a single character. Typically, a question mark (?) is used for any unmappable characters. For example, use this format textReplacementCharacterSequence=? where the question mark (?) is the replacement character. You cannot use a white space character as a replacement character.

None
Multi-channel support:
agentMultipleChannelsEnabled Setting this property to true enables a WebSphere MQ File Transfer Edition agent to send transfer data messages across multiple WebSphere MQ channels. In some scenarios, this might improve performance. However, you should only enable multi-channel support if there is a demonstrable performance benefit. Only messages put to the SYSTEM.FTE.DATA.destinationAgentName queue are sent across multiple channels. The behavior for all other messages remains unchanged.
When you set this property to true, you must also complete the WebSphere MQ configuration steps in one of the following topics to enable multi-channel support: Additionally, you must also complete the standard WebSphere MQ configuration steps required for a WebSphere MQ File Transfer Edition agent, which are detailed in Configuring WebSphere MQ File Transfer Edition for first use.

The value of this property can be true or false.

false
agentMessageBatchSize When configured with multiple channels, a source agent sends data messages for a transfer across each channel on a round-robin basis. This property controls the number of messages sent down each channel at a time. 5
Multi-instance queue manager properties:
agentQMgrStandby The host name and the port number used for client connections, in WebSphere MQ CONNAME format, for the standby instance of a multi-instance agent queue manager defined by agentQMgr. For example, host_name(port_number) No default
Protocol bridge properties:
protocolBridgeCredentialExitClasses Specifies a comma-separated list of classes that implement a protocol bridge credential user exit routine. For more information, see Mapping credentials for a file server using exit classes. No default.
protocolBridgeCredentialConfiguration The value of this property is passed in as a string to the initialize() method of the exit classes specified by protocolBridgeCredentialExitClasses. null
protocolBridgeLogoutBeforeDisconnect Specifies whether the protocol bridge agent logs the user out of the file server before closing the FTP session and disconnecting. If you set this property to true, the protocol bridge agent issues an FTP QUIT command to the file server. false
protocolBridgePropertiesConfiguration This property is available only if you have enabled the Version 7.0.4.1 function.

Passed as one of the bridge properties to the initialize() method of the exit classes specified by the protocolBridgeServerPropertiesExitClasses property.

No default
protocolBridgePropertiesExitClasses This property is available only if you have enabled the Version 7.0.4.1 function.

Specifies a comma-separated list of classes that implement a protocol bridge server properties user exit routine.

For more information, see Looking up protocol file server properties by using exit classes.
No default
protocolServerType Required property if you want to use the protocol bridge.

The type of network protocol that the server you want to send files to or receive files from is using.

The value of this property can be FTP or SFTP.
No default
protocolServerHost Required property if you want to use the protocol bridge.

The host name or IP address of the protocol file server that you want to send files to or receive files from.

No default
protocolServerPort

The port number of the protocol file server that you want to send files to or receive files from.

If you do not provide a value for this property, the FTP, SFTP, or FTPS standard default port numbers are used. FTPS is available only if you have enabled the 7.0.4.1 function.

No default
protocolServerPlatform Required property if you want to use the protocol bridge.

The platform of the protocol file server that you want to send files to or receive files from.

Set this property according to how you enter paths on your FTP, FTPS, or SFTP server. For example, if you are running an FTP server on Windows but when you log in to the server, you must enter UNIX-style paths (that is, with forward slashes), set this value to UNIX and not WINDOWS. Servers running on Windows often present a UNIX-style file system.

Specify either UNIX or WINDOWS.

No default
protocolServerTimeZone

Required property if you want to use the protocol bridge with an FTP server. This property is invalid for SFTP servers.

The time zone of the protocol file server that you want to send files to or receive files from. For example: America/New_York or Asia/Tokyo.

The value of this property is a time zone as defined by the Internet Assigned Numbers Authority (IANA).

No default
protocolServerLocale

Required property if you want to use the protocol bridge with an FTP server. This property is invalid for SFTP servers.

The language used on the protocol file server that you want to send files to or receive files from. For example: en_US or ja_JP

The value of this property is a language tag as defined by the Internet Engineering Task Force (IETF).

No default
protocolServerFileEncoding Required property if you want to use the protocol bridge.

Defines the character encoding used by the file server. This property is used when you transfer files in text mode so that the correct encoding sequences are changed when the files are moved between platforms. For example, UTF-8.

No default
protocolServerListFormat Optional and applies to FTP servers only
The listing format that defines the format of the file listed information returned from the protocol file server. The options are:
  • UNIX - Generic UNIX platform
  • WINDOWS - Generic Microsoft Windows platform
To identify which format to select, use an FTP client program and list a directory. Then select which format is most appropriate.
For example, the UNIX format is as follows:
UNIX -rwxr-xr-x 2 userid groupId 4096 2009-07-23 09:36 filename
The Windows format is as follows:
WINDOWS 437,909 filename
UNIX
protocolServerLimitedWrite The default mode when writing to a file server is to create a temporary file and then rename that file when the transfer has completed. For a file server that is configured as write only, the file is created directly with its final name. The value of this property can be true or false. false
Queue properties:
publicationMDUser The MQMD user ID to associate with messages sent to be published by the coordination queue manager. If you do not set this property, the MQMD user ID is set based on the WebSphere MQ rules for setting MQMD user IDs. No default
Resource monitoring properties:
monitorMaxResourcesInPoll Specifies the maximum number of monitored resources to be triggered in each poll interval. For example, if you specify a monitor pattern of *.txt, a poll interval of 10 seconds, and set the monitorMaxResourcesInPoll property to 10, the monitorMaxResourcesInPoll property limits the agent to trigger on a maximum of 10 matches for each poll interval. Matching resources beyond the limit of 10 are triggered in later poll intervals.

In addition, you can use the monitorMaxResourcesInPoll property in combination with a matching -bs parameter on the fteCreateMonitor command, for example, to restrict each poll interval to triggering one transfer only.

No default
monitorReportTriggerFail Specifies whether failure conditions regarding environment and configuration that are detected in the monitor are reported as a log message to the SYSTEM.FTE topic. A value of true logs messages. A value of false does not log messages. true
monitorReportTriggerNotSatisfied Specifies whether a non-satisfied trigger sends a log message to the SYSTEM.FTE topic that contains the details. A value of true logs messages. A value of false does not log messages. false
monitorReportTriggerSatisfied Specifies whether a satisfied trigger sends a log message to the SYSTEM.FTE topic that contains the details. A value of true logs messages. A value of false does not log messages. false
monitorSilenceOnTriggerFailure The number of consecutive failures of the resource monitor trigger before the failures are no longer reported. 5
monitorStopOnInternalFailure The number of consecutive internal FFDC conditions of the resource monitor before the monitor changes its state to stop. 10
Root directory properties:
commandPath Specifies the set of paths that commands can be called by the agent Ant call, filecopy, or filemove tasks, or by specifying in an XML message passed to an agent, by using one of the supported WebSphere MQ File Transfer Edition agent command XML schemas (for example, managedCall or managedTransfer).

For information about the valid syntax of the value of the commandPath property, see The commandPath property.

Take extreme care when you set this property because any command in one of the specified commandPaths can effectively be called from a remote client system that is able to send commands to the agent. For this reason, by default, when you specify a commandPath, sandboxing is enabled so that all commandPath directories are automatically denied access for a transfer. You can set the sandboxRoot property to override this default behavior, but you are not recommended to do so, because this override effectively enables a client to transfer any command to the agent system and call the command.

None - no commands can be called
sandboxRoot Specifies the set of root paths to include and exclude when you use sandboxing. See Working in a sandbox for information about this feature.

Separate paths with a platform-specific path separator. Prefix paths with an exclamation point (!) character to denote paths as excluded from the sandbox. This feature is useful if you want to exclude a subdirectory under an included root path.

The sandboxRoot property is not supported on protocol bridge agents.

You cannot specify the sandboxRoot property and the userSandboxes property together.

None - no sandbox
transferRoot Default root directory for relative paths specified to the agent The home directory for the user that started the agent process.
transferRootHLQ Default HLQ (user ID) for non-fully qualified data sets specified to the agent The user name of the user that started the agent process.
userSandboxes Restrict the area of the file system that files can be transferred to and from based on the MQMD user name of the user that requests the transfer. For more information, see Working with user sandboxes.

The userSandboxes property is not supported on protocol bridge agents.

You cannot specify the sandboxRoot property and the userSandboxes property together.

false
Scheduler property:
maxSchedulerRunDelay The maximum interval, in minutes, that the agent waits to check for scheduled transfers. Specify a positive integer to enable this property. For more information about why you might want to use this property, see What to do if your scheduled transfer does not run or is delayed.

Because the agent might be reading a command from its command queue at the time that scheduled transfers are due to run, there could be an additional delay before the scheduled transfers are started. In this case the scheduler will run immediately after that command has been completed.

No default
Security properties:
authorityChecking Specifies whether the security features described in User authorities on WebSphere MQ File Transfer Edition actions are enabled. false
logAuthorityChecks The level of authority check logging that is recorded in the agent event log in the output0.log file. The values that this property can have are None or Failures or All. None
userIdForClientConnect The user ID that gets flowed through the client connections to WebSphere MQ. If java is specified the user name reported by the JVM is flowed as part of the WebSphere MQ connection request. The values that this property can have are None or java. None
advancedSecurityPath The location of one or more Java archive (jar) files containing the WebSphere MQ Advanced Message Security Java Interceptor. If multiple jar files are specified, you must separate the file names with semi-colon characters. If this property is not set then WebSphere MQ Advanced Message Security is not used.

This parameter is not used with embedded WebSphere MQ Advanced Message Security.

None
Timeout properties:
maxTransferNegotiationTime The maximum time in milliseconds that a transfer waits for a destination agent to complete negotiation. If negotiation does not complete in this time, the transfer is put into a resynchronization state and allows another transfer, when available, to run.

In scenarios where the source or destination agent is under heavy load it is possible that the default value is too low for the agent to respond quickly enough to the negotiation request. This is most likely when a source agent has a large number of resource monitors defined or when its resource monitors are monitoring directories that contain large numbers of files. However, it can also occur when a large number of transfer requests is submitted to an agent. Increasing the value of this property to 200,000 or more may be necessary in such scenarios.

30 000
recoverableTransferRetryInterval The time to wait in milliseconds between detecting a recoverable transfer error and attempting to resume the transfer. 60 000
senderTransferRetryInterval The time in milliseconds to wait until a rejected transfer is retried because the destination is already running the maximum number of transfers. Minimum value is 1000. 30 000
transferAckTimeout Timeout in milliseconds that a transfer waits for acknowledgment or data from the other end before a retry is issued. This is an advanced property and for most WebSphere MQ File Transfer Edition configurations it is not necessary to modify its value.

Acknowledgments are sent from the receiving agent to the sending agent whenever a complete window of data is received. For bandwidth-constrained or unreliable networks and large agentWindowSize and agentChunkSize settings, it is possible that the default is not long enough. This can cause unnecessary retransfer of data between the agents. Therefore increasing this value might be beneficial and may reduce the likelihood of a transfer going into recovery mode because of a slow network.

60 000
transferAckTimeoutRetries Maximum number of acknowledgment retries for a transfer without a response before the agent gives up and moves the transfer into a recovery state 5
Tracing and logging properties:
ITLMTraceLevel ITLM trace level. Controls the amount of trace and log information that is output by Tivoli® License Manager.

Possible values (in increasing level of verbosity) are: MIN, MID, and MAX

MIN
javaCoreTriggerFile The full path to a file location that the agent monitors. If you create or update a file at this location, the agent triggers a Javacore file.
A separate thread polls this file every 30 seconds to check whether the file has been created or updated. If the file has been created or updated since the last poll, the agent generates a Javacore file in the following directories:
  • UNIX and Linux: config/coordination_qmgr_name/agents/agent_name
  • Windows: config\coordination_qmgr_name\agents\agent_name
When you specify this property, the agent outputs the following message at startup:
BFGAG0092I</b> The <insert_0> file will be used to request JVM diagnostic information.
None
trace Trace specification when agent is to be run with trace enabled at agent start. The trace specification is a comma-separated list of classes, the equals character, and a trace level. For example, com.ibm.wmqfte.agent.Agent,com.ibm.wmqfte.commandhandler=all. You can specify multiple trace specifications in a colon-separated list. For example, com.ibm.wmqfte.agent.Agent=all:com.ibm.wmqfte.commandhandler=moderate. None
outputLogFiles The total number of output.log files to keep. This applies to an agent's process controller as well as the agent itself. 5
outputLogSize The maximum size in MB of each output.log file, before output wraps onto the next file. This applies to an agent's process controller as well as the agent itself. 1
outputLogEncoding The character encoding that the agent uses when writing its output.log file. The default character encoding of the platform that the agent is running on.
traceFiles The total number of trace files to keep. This applies to an agent's process controller as well as the agent itself. 5
traceSize The maximum size in MB of each trace file, before trace wraps onto the next file. This applies to an agent's process controller as well as the agent itself. 20
traceMaxBytes The limit to the amount of message data that is output in the trace file. 4096 bytes
logTransferRecovery When this property is set to a value of true, whenever a transfer enters recovery diagnostic, events are reported to the agent's event log.

Before Version 7.0.4.5, the default value is false.

From Version 7.0.4.5, the default value is true.

Transfer limit properties:
maxDestinationTransfers The maximum number of concurrent transfers that the destination agent processes at any given point in time. Each transfer request submitted to an agent counts against this total regardless of the number of files that are transferred to satisfy the request. This means that a transfer request that transfers a single file counts in the same way as a transfer request that transfers 10 files.

When a Version 7.0.0 or Version 7.0.1 agent is acting as the source agent, if you attempt to start additional transfers, these additional transfers fail if the destination agent has reached the limit specified by the maxDestinationTransfers property. When a Version 7.0.2 or later agent is acting as the source agent, the agent queues transfers when the destination agent has reached the limit specified by the maxDestinationTransfers property.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

25 (for all agents except Connect:Direct bridge agents)

5 (for Connect:Direct bridge agents)

maxFilesForTransfer The maximum number of transfer items that are allowed for a single managed transfer. If a managed transfer contains more items than the value of maxFilesForTransfer, the managed transfer fails and no transfer items are processed.

Setting this property prevents you from accidentally transferring too many files because of a bad transfer request, for example, if a user accidentally specifies the transfer of the root directory / on a UNIX system.

5000
maxSourceTransfers The maximum number of concurrent transfers that the source agent processes at any given point in time. Each transfer request submitted to an agent counts against this total regardless of the number of files that are transferred to satisfy the request. This means that a transfer request that transfers a single file counts in the same way as a transfer request that transfers 10 files.

When a V7.0.0 or V7.0.1 agent is acting as a source agent, if you attempt to start additional transfers, these additional transfers fail if this agent has reached the limit specified by the maxSourceTransfers property. When a V7.0.2 or later agent is acting as the source agent, the source agent queues transfers when the destination agent has reached the limit specified by the maxSourceTransfers property.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

25 (for all agents except Connect:Direct bridge agents)

5 (for Connect:Direct bridge agents)

maxQueuedTransfers For WebSphere MQ File Transfer Edition V7.0.2 and later, the maximum number of pending transfers that can be queued by an agent until the agent rejects a new transfer request. You can set this property so that in spite of the limits of maxDestinationTransfers and maxSourceTransfers being met or exceeded, any new transfer requests you make at this time are accepted, queued and then carried out later.

The order that queued transfer requests are processed in is a factor of their priority and how long they have been queued. Old and high priority pending transfers are selected first. Transfers with a low priority that have been on the queue for a long time are selected in preference to newer, higher priority transfers.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

1000
User exit routine properties:
agentForceConsistentPathDelimiters Force the path delimiter in the source file and destination file information provided to the transfer exits to be the UNIX style: forward slash (/). Valid options are true and false. false
destinationTransferEndExitClasses Specifies a comma-separated list of classes that implement a destination transfer end user exit routine. No default
destinationTransferStartExitClasses Specifies a comma-separated list of classes that implement a destination transfer start user exit routine. No default
exitClassPath Specifies a platform-specific, character-delimited list of directories that act as the class path for user exit routines.

The agent exit directory is searched before any entries in this class path.

Agent's exits directory
exitNativeLibraryPath Specifies a platform-specific, character-delimited list of directories that act as the native library path for user exit routines.

The agent exit directory is not searched before any entries in this native library path.

Agent's exits directory
ioMaxRecordLength This property is available only if you have enabled the Version 7.0.4.1 function.

The maximum record length, in bytes, that can be supported for a record-oriented file. WebSphere MQ File Transfer Edition can support writing to record-oriented files with any record length. However, large record lengths might cause out-of-memory errors, so to avoid these errors the maximum record length is restricted by default to 64 K. When reading from record-oriented files an entire record must fit into a single transfer chunk, therefore the record length is additionally limited by the transfer chunk size. This property is currently used only for I/O user exit record-oriented files.

64 KB
monitorExitClasses Specifies a comma-separated list of classes that implement a monitor exit routine. For more information, see Resource monitor user exits. No default
protocolBridgeCredentialExitClasses Specifies a comma-separated list of classes that implement a protocol bridge credential user exit routine. For more information, see Mapping credentials for a file server using exit classes. No default.
sourceTransferEndExitClasses Specifies a comma-separated list of classes that implement a source transfer end exit routine. No default
sourceTransferStartExitClasses Specifies a comma-separated list of classes that implement a source transfer start exit routine. No default
IOExitClasses This property is available only if you have enabled the Version 7.0.4.1 function.

Specifies a comma-separated list of classes that implement an I/O user exit routine. List only the classes that implement the IOExit interface, that is, do not list classes that implement the other I/O user exit interfaces, for example IOExitResourcePath and IOExitChannel. For more information, see Using WebSphere MQ File Transfer Edition transfer I/O user exits.

No default.
WebSphere MQ client compression:
agentDataCompression This property is supported for client connections to WebSphere MQ Version 7.0.1 or later queue managers only.

A comma-separated list of the compression types for the transfer of file data to negotiate with the remote WebSphere MQ server. You can find information about these compression types in the following topic in the WebSphere MQ product documentation: Message data compression list

The values are checked for validity and then passed through in order of appearance as properties to the agent client channel. The WebSphere MQ client then handles negotiation between this client channel and the remote server channel to find the matching lowest common denominator between the compression properties on the two channels. If no match is found, MQCOMPRESS_NONE is always selected.

MQCOMPRESS_NONE
agentHeaderCompression This property is available only if you have enabled the Version 7.0.4.1 function and is supported for client connections to WebSphere MQ Version 7.0.1 or later queue managers only.

A comma-separated list of the compression types for the transfer of header data to negotiate with the remote WebSphere MQ server. Accepted values are MQCOMPRESS_NONE or MQCOMPRESS_SYSTEM. You can find information about these compression types in the following topic in the WebSphere MQ product documentation: Message header compression list

The values are checked for validity and then passed through in order of appearance as properties to the agent client channel. The WebSphere MQ client then handles negotiation between this client channel and the remote server channel to find the matching lowest common denominator between the compression properties on the two channels. If no match is found, MQCOMPRESS_NONE is always selected.

MQCOMPRESS_NONE
z/OS-specific:
bpxwdynAllocAdditionalOptions WebSphere MQ File Transfer Edition uses the BPXWDYN text interface to create and open z/OS data sets. When BPXWDYN is used for data set allocation by default WebSphere MQ File Transfer Edition ensures, when possible, the data device is mounted (not required for disk-based data sets but is required for tape data sets). Because the options might not be supported for certain environments, use this property to change this behavior. Also when transferring to a data set it is also possible to specify options for BPXWDYN on the command line; these options are in addition to those options specified by this property.

Some BPXWDYN options must not be specified when using the fteCreateTemplate command, the fteCreateTransfer command or the bpxwdynAllocAdditionalProperties property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with WebSphere MQ File Transfer Edition.

Default is as follows:
  • MOUNT for z/OS V1R8 and later

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