The agent.properties file

The interval in complete frames of data between which a checkpoint is taken for recovery purposes. This is an advanced property and for most IBM MQ Managed File Transfer 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 IBM MQ Managed File Transfer networks where transfers rarely enter a recovery state, it may be beneficial to increase this value to increase overall performance.

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 IBM MQ Managed File Transfer 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 = 10240 sets the chunk size to 10 KB.

The number of windows for the transfer frame. This is an advanced property and for most IBM MQ Managed File Transfer 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, multiplied 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.

The number of chunks for each window. This is an advanced property and for most IBM MQ Managed File Transfer 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.

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.

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.

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.

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

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.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

value_of_java.io.tmpdir
/cdbridge-agentName

value_of_java.io.tmpdir
\cdbridge-agentName

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

• TCPIP
• SSL
• TLS

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

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

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

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

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

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

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

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

This property is not available on IBM i.

If the agent is restarted the monitor triggers a transfer again even if the number of times the transfer triggers exceeds the value of monitorGroupRetryLimit. If this behavior causes the number of times that the transfer triggers 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.

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

Determines whether the MQMFT 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 MQMFT 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.

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.

• com.ibm.wmqfte.insertRecordLineSeparator
• com.ibm.wmqfte.newRecordOnLineSeparator
• com.ibm.wmqfte.convertLineSeparators

The value of this property can be true or false.

To enable this feature, APAR IT03450 must be applied for both the source agent and the destination agent, and the failTransferOnFirstFailure property must be set to true in the source agent's agent.properties file. Setting the property to true true on the destination agent is optional.

If the failTransferOnFirstFailure property is not set to true and a managed file transfer contains multiple files and one of these files fails to transfer, for example because the destination file already exists and the overwrite property is set to error, the source agent continues and attempts to transfer any remaining files in the request.

The number of files that are transferred before an agent publishes its next progress log message. Use this property to control the rate that progress log messages are published to the coordination queue manager during a transfer.

The maximum value this property can be set to is 1000.

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.

By default, 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 value to true causes the agent to write directly to the final destination file.

On IBM 4690, do not set this property to true: writing directly to the final file at the destination is not supported on 4690 OS.

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.

The value of this property can be true or false.

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.

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.

The value of this property can be true or false.

The interval, in seconds, between each attempt that an IBM 4690 agent controller makes to check the status that is provided by its associated agent. This interval begins after the last successful status message is received from the agent.

The time, in seconds, that an IBM 4690 agent controller waits for an expected status update from an agent before it assumes the agent is no longer responsive. When the time defined by the processControllerPollingInterval property elapses, the agent controller starts to check for a status update. If a status update does not arrive in the time period that is defined by this property the agent is assumed to be unresponsive.

By default an IBM 4690 agent attempts to start a process controller to monitor its execution. It is recommended this value is set to true, but if the cost of memory usage is too high it can be set to false. The agent will not attempt to start a process controller, but this may reduce the agent reliability.

The timeout in milliseconds that the protocol bridge agent waits to either establish a data connection to an FTP server or to receive data from an FTP server over a connection that is already established. If you set this property to a value of 0, the protocol bridge agent waits indefinitely. If the timeout elapses, the protocol bridge agent closes any existing data connections to the FTP server and attempts to establish a new data connection before resuming the current transfer. If the attempt to establish the new data connection fails, the current transfer also fails.

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

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

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.

• Agent Ant call, filecopy, or filemove tasks
• In an XML message passed to an agent, using one of the supported IBM MQ Managed File Transfer 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.

Important: 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:

• Any existing agent sandbox is configured by the agent when it starts up so that all commandPath directories are automatically added to the list of directories that have denied access for a transfer.
• Any existing user sandboxes are updated when the agent starts up so that all the commandPath directories (and their subdirectories) are added as <exclude> elements to the <read> and <write> elements.
• If the agent is not configured to use either an agent sandbox, or user sandboxes, then a new agent sandbox is created when the agent starts up that has the commandPath directories specified as denied directories.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

• The denied directories for an existing agent sandbox.
• The <exclude> elements for the <read> and <write> elements for any user sandboxes that have been defined.
• A new agent sandbox, if an agent has not been configured with either an agent sandbox, or one or more user sandboxes.

When this property is set to true, the additional checking is enabled. If a transfer request attempts to read a location that is outside of the defined sandbox for file matching of the wildcard, the transfer fails. If there are multiple transfers within one transfer request, and one of these requests fails due to it attempting to read a location outside of the sandbox, the entire transfer fails. If checking fails, the reason for failure is given in an error messages (see Additional checks for wildcard transfers).

If the property is omitted or set to false then no additional checks are made on wildcard transfers.

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.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in IBM MQ Managed File Transfer properties for more information.

On IBM 4690, there is no default directory for this property. Therefore, if you want to use relative paths, you must set the value of this property to a directory path. If you do not set this property, file transfers to or from a 4690 agent that specify a relative source or destination path, fail with an error message.

No default directory for IBM 4690.

The userSandboxes property is not supported on protocol bridge agents.

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

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

From IBM MQ 8.0.0, Fix Pack 8, inquire is a required permission on all of the agent authority queues.

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.

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.

• ConnectDirectCredentials.xml
• ConnectDirectNodeProperties.xml
• ConnectDirectProcessDefinitions.xml
• ProtocolBridgeCredentials.xml
• ProtocolBridgeProperties.xml
• UserSandboxes.xml

BFGAG0092I</b> The <insert_0> file will be used to
request JVM diagnostic information.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

For IBM WebSphere MQ V7.5, or later, the value of this property can contain environment variables.

Before IBM MQ 8.0.0, Fix Pack 3, the default value is false.

From IBM MQ 8.0.0, Fix Pack 3, the default value is true.

The agent queues transfers when the destination agent reaches the limit that is 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.

5 (for Connect:Direct bridge agents)

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.

The source agent queues transfers when the destination agent reaches the limit that is 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.

5 (for Connect:Direct bridge agents)

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.

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

The maximum record length, in bytes, that can be supported for a record-oriented file. IBM MQ Managed File Transfer 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 used only for I/O user exit record-oriented files.

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 IBM MQ Managed File Transfer transfer I/O user exits.

The name of the Web Gateway is not case-sensitive and must conform to the WebSphere MQ object naming conventions. For more information, see Object naming conventions for IBM MQ Managed File Transfer.

A comma-separated list of the compression types for the transfer of file data to negotiate with the remote IBM MQ server. You can find information about these compression types in the following topic: 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 IBM 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.

A comma-separated list of the compression types for the transfer of header data to negotiate with the remote IBM MQ server. Accepted values are MQCOMPRESS_NONE or MQCOMPRESS_SYSTEM. You can find information about these compression types in the following topic: 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 IBM 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.

• Start the agent by using the fteStartAgent command.
• Stop the agent by using the fteStopAgent command.
• Enable or disable the trace for the agent by using the fteSetAgentTraceLevel command.
• Display details of a local agent by running the fteShowAgentDetails command with the -d parameter specified.

adminGroup=MFTADMIN

Some BPXWDYN options must not be specified when using the bpxwdynAllocAdditionalOptions property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with IBM MQ Managed File Transfer.

• MOUNT for z/OS V1R8 and later

Optional property. If the agent is configured for restart by the Automatic Restart Manager (ARM), then set this property to the ARM ELEMTYPE parameter value specified in the associated ARM policy. For an agent, set ELEMTYPE to SYSBFGAG.

Optional property. If the agent is configured for restart by the Automatic Restart Manager (ARM), then set this property to the ARM ELEMENT parameter value specified in the associated ARM policy. You can set the ELEMENT value to correspond to the agent name.

If the MQMD format field is set to MQSTR, there is potential for IBM MQ Managed File Transfer command XML messages to be corrupted if there are channels in the MQ network with data conversion enabled.