Transfer data from messages to files

The message-to-file feature of Managed File Transfer enables you to transfer data from one or more messages on an IBM MQ queue to a file, a data set (on z/OS ), or a user file space. If we have an application that creates or processes IBM MQ messages, we can use the message-to-file capability of Managed File Transfer to transfer these messages to a file on any system in your Managed File Transfer network.

For information about file-to-message transfers, see Transfer data from files to messages.

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

We can transfer IBM MQ message data to a file. The following types of message-to-file transfer are supported:

• From a single message to a single file
• From multiple messages to a single file
• From multiple messages with the same IBM MQ group ID to a single file.
• From multiple messages to a single file, including a text or binary delimiter between the data from each message written to the file.

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

From Version 9.1.0, in a message to file transfer, the source agent browses the messages from the source queue, unlike the destructive GET in earlier versions of IBM MQ. The messages are removed from the source queue after all messages (in a group if message grouping is used) have been browsed and data written to the destination file. This allows messages to remain in the source queue if a transfer fails or is canceled. Due to this change, authority to BROWSE must also be provided along with GET authority to run message to file transfers.

From Version 9.0.0, Fix Pack 2 and Version 9.0.4, Managed File Transfer is updated to restore the comparison check, previously removed by APAR IT18213, of the transfer identifier and the value of the groupId attribute within the transfer request XML payload. If these two identifiers are equivalent, the source agent uses the identifier as a message identifier match option (as opposed to a group identifier match option) for the first MQGET attempt that is made on the input queue for the message-to-file transfer.

• Configure an agent to perform message-to-file transfers
  By default agents cannot perform message to file, or file to message, transfers. To enable this function we must set the agent property enableQueueInputOutput to true.
• Example: Transferring from a queue to a single file
  We can specify an IBM MQ queue as the source of a file transfer by using the -sq parameter with the fteCreateTransfer command.
• Example: Transferring a group of messages from a queue to a single file
  We can specify a single complete group on an IBM MQ queue as the source of a file transfer by using the -sq and -sqgi parameters with the fteCreateTransfer command.
• Example: Inserting a text delimiter before the data from each message
  When we are transferring in text mode from a source queue to a file, we can specify that a text delimiter is inserted before the data from individual messages by using the -sq, -sqdt and -sqdp parameters with the fteCreateTransfer command.
• Example: Inserting a binary delimiter after the data from each message
  When transferring in binary mode from a source queue to a file, we can specify that a binary delimiter is inserted after the data from individual messages by using the -sq, -sqdb, and -sqdp parameters with the fteCreateTransfer command.
• Monitor a queue and using variable substitution
  We can monitor a queue and transfer messages from the monitored queue to a file by using the fteCreateMonitor command. The value of any IBM MQ message property in the first message to be read from the monitored queue can be substituted in the task XML definition and used to define the transfer behavior.
• Example: Failing a message-to-file transfer using IBM MQ message properties
  We can cause a message to file transfer to fail by setting the usr.UserReturnCode IBM MQ message property to a non-zero value. We can also specify supplementary information about the reason for the failure by setting the usr.UserSupplement IBM MQ message property.

Parent topic: Administer Managed File Transfer

Related tasks

• Example: Configuring an MFT resource

Related information

• MQ message properties read by MFT from messages on source queues
• Guidance for setting MQ attributes and MFT properties associated with message size