Transfer data from files to messages

We can use the file-to-message feature of Managed File Transfer to transfer data from a file to a single message, or multiple messages, on an IBM MQ queue.

To perform file-to-message and message-to-file transfers both the source and destination agent of the transfer must either be at IBM WebSphere MQ Version 7.5, or later, or at WebSphere MQ File Transfer Edition Version 7.0.3, or later. For information about message-to-file transfers, see Transfer data from messages to files.

The destination agent for a file-to-message transfer cannot be a protocol bridge agent or a Connect:Direct bridge agent.

We can transfer file data to IBM MQ message data. The IBM MQ messages can be read and used by applications. The following types of file-to-message transfer are supported:

From a single file to a single message. The message does not have an IBM MQ group ID set.
From a single file to multiple messages, by splitting the file into messages of a given length. The messages all have the same IBM MQ group ID.
From a single file to multiple messages, by splitting a text file at a Java regular expression delimiter. The messages all have the same IBM MQ group ID.
From a single file to multiple messages, by splitting a binary file at a hexadecimal delimiter. The messages all have the same IBM MQ group ID.
To split a binary file using a sequence of bytes as the delimiter, use the -sqdb parameter of the fteCreateTransfer command. For more information, see -sqdb parameter.

By default the messages created by a file-to-message transfer are persistent. The messages can be set to be non-persistent or to have the persistence value defined by the destination queue.

If you specify that a file is split into multiple messages, all messages created from the file have the same IBM MQ group ID. If we do not specify that a file is split into multiple messages, only one message is created from the file and this message does not have the IBM MQ group ID set.

If we are transferring files to large messages, or many small messages, you might need to change some IBM MQ or Managed File Transfer properties. For information about, see Guidance for setting MQ attributes and MFT properties associated with message size.

Note: If the destination queue is either a clustered queue, or an alias to a clustered queue, you will get an error message when transferring a file into a queue if the agent property enableClusterQueueInputOutput has not been set to true. For more information see What to do if the destination queue is a clustered queue, or an alias to a clustered queue

Configure an agent to perform file-to-message transfers
By default agents cannot perform file-to-message or message-to-file transfers. To enable this function we must set the agent property enableQueueInputOutput to true. To enable writing to IBM MQ clustered queues, we must also set the agent property enableClusterQueueInputOutput to true.
Example: Transferring a single file to a single message
We can specify a queue as the destination of a file transfer by using the -dq parameter with the fteCreateTransfer command. The source file must be smaller than the maximum message length set on the destination queue. The destination queue does not have to be on the same queue manager as the queue manager that the destination agent connects to, but these two queue managers must be able to communicate.
Example: Splitting a single file into multiple messages by length
We can split a file into multiple IBM MQ messages by using the -qs parameter of the fteCreateTransfer command. The file is split into fixed-length sections, each of which is written to an individual message.
Example: Splitting a text file into multiple messages using a regular expression delimiter
Transfer a single text file to multiple messages by splitting the file at each match of a given Java regular expression. To do this we use the -dqdt parameter of the fteCreateTransfer command.
Example: Splitting a text file with a regular expression delimiter and including the delimiter in the messages
Transfer a single text file to multiple messages by splitting the file at each match of a given Java regular expression and include the regular expression match in the resulting messages. To do this we use the -dqdt and -qi parameters of the fteCreateTransfer command.
Example: Setting IBM MQ message properties on a file-to-message transfer
We can use the -qmp parameter on the fteCreateTransfer command to specify whether IBM MQ message properties are set on the first message written to the destination queue by the transfer. IBM MQ message properties allow an application to select messages to process, or to retrieve information about a message without accessing IBM MQ Message Descriptor (MQMD) or MQRFH2 headers.
Example: Setting user-defined properties on a file-to-message transfer
User-defined metadata is set as an IBM MQ message property on the first message written to the destination queue by the transfer. IBM MQ message properties enable an application to select messages to process, or to retrieve information about a message without accessing IBM MQ Message Descriptor (MQMD) or MQRFH2 headers.
Failure of a file-to-message transfer
If a file-to- message transfer fails after the agent has started writing file data to the destination queue, the agent writes a message to the queue to indicate to an application consuming the messages that a failure has occurred.

Transfer data from files to messages

Related tasks

Related reference

Related information