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.

About this task

In this example, a transfer is in progress between the queue INPUT_QUEUE and the file /home/user/output.file.

A user is creating messages and placing them on the queue INPUT_QUEUE. The source agent is consuming messages from the queue INPUT_QUEUE and is sending the transfer data to the destination agent. The destination agent is writing this data to the file /home/user/output.file.

The user writing messages to the queue INPUT_QUEUE wants to stop the transfer that is in progress and delete any data that has already been written to the destination file.

Procedure

1. The user writes a message to the queue INPUT_QUEUE that has the following IBM MQ message properties set:

   usr.UserReturnCode=1
   usr.UserSupplement="Cancelling transfer - sent wrong data."

2. The source agent reads the IBM MQ message properties and stops processing messages from the queue. The destination agent deletes any file data that has been written to the destination directory.
3. The source agent sends a transfer log message to the coordination queue manager reporting the transfer failure. The message contains the following information:

   <?xml version="1.0" encoding="UTF-8"?>
   <transaction version="1.00"
         	     ID="414d5120514d312020202020202020207e970d4920008702" agentRole="sourceAgent"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation="TransferLog.xsd"
                xmlns="">
     <action time="2008-11-02T21:28:09.593Z">progress</action>
     <sourceAgent agent="FTEAGENT" QMgr="QM1">
       <systemInfo architecture="x86" name="Windows 7"
   			version="6.1 build 7601 Service Pack 1" />
     </sourceAgent>
     <destinationAgent agent="FTEAGENT" QMgr="QM1">
       <systemInfo architecture="x86" name="Windows 7"
   			version="6.1 build 7601 Service Pack 1" />
     </destinationAgent>
     <originator>
       <hostName>reportserver.com</hostName>
       <userID>USER1</userID>
       <mqmdUserID>USER1   </mqmdUserID>
     </originator>
     <transferSet index="0" size="1" 
                  startTime="2008-11-02T21:28:09.281Z"
                  total="1">
       <item mode="binary">
         <source>
           <queue>INPUT_QUEUE@QM1</queue>
         </source>
         <destination exist="error">
           <file>/home/user/output.file</file>
         </destination>
         <status resultCode="1">
           <supplement>Cancelling transfer - sent wrong data.</supplement>
         </status>
       </item>
     </transferSet>
   </transaction>
   

Parent topic: Transfer data from messages to files

Related concepts

• Transfer data from messages to files

Related tasks

• Configure an agent to perform message-to-file transfers
• Example: Transferring from a queue to a single file
• Example: Transferring a group of messages from a queue to a single file
• Example: Inserting a text delimiter before the data from each message
• Example: Inserting a binary delimiter after the data from each message
• Monitor a queue and using variable substitution

Related information

• MQ message properties read by MFT from messages on source queues