Example: Failing a message to file transfer using IBM MQ message properties

You can cause a message to file transfer to fail by setting the usr.UserReturnCode IBM® MQ message property to a non-zero value. You 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

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."
```
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.

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="https://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>