MFT logger error handling and rejection

The Managed File Transfer logger identifies two types of error: per-message errors and general errors.

Per-message errors are likely to be caused by a problem with one or a few individual messages. Some examples of situations, which are identified as per-message errors are as follows:

• The result code, which is a required item of data, is missing from a message
• A transfer specifies a job name that is 3000 characters long and too large for the associated database column
• A progress message is received for a transfer, but there is no record of the transfer having been started (perhaps because of a misrouted or delayed transfer start message)
• A message is received, which is not a Managed File Transfer log message

General errors are all those errors that are not per-message errors. These are likely to be because of configuration problems or program errors.

When a per-message error is encountered, the logger rejects the message by placing the message on the reject queue. Nothing is written to the output log, so periodically inspect or continuously monitor the reject queue to detect rejected messages.

If too many messages are rejected consecutively, without any messages being successfully written to the database, this is treated as a general error. For example, consider a site that always uses 10 character codes as job names, but which has inadvertently reconfigured the job name column to be two characters wide. Although data that is too wide is usually a per-message error, in this case the configuration problem is general and is detected as a general error. We can tune the number of consecutive per-message errors needed to cause a general error using the wmqfte.max.consecutive.reject property.

If a general error is detected the logger rolls back any messages not yet committed to the queue manager, and then retries periodically. A message identifying the problem is written to the output log and to the console if the logger was started in foreground mode with the -F parameter.

The location of the output logs for the logger is dependent on whether it is a stand-alone or JEE database logger. For a stand-alone database logger it is located in the directory MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/loggers/logger_name. For a JEE database logger it is located in the standard output log of the application server.

The reject queue

Messages that result in per-message errors are moved to the reject queue. On each rejected message, a message property is set to indicate why the message was rejected. The full name of the property is usr.WMQFTE_ReasonForRejection, although usr. is omitted in some contexts (including JMS and the IBM MQ Explorer).

If you are using IBM MQ Explorer, we can view the contents of the reject queue by right-clicking the queue and clicking Browse Messages. To see why a message was rejected, double-click the message to open its properties dialog, then select the Named Properties page. You will see a property called WMQFTE_ReasonForRejection. Alternatively, you could write or configure a monitoring tool to obtain this information automatically.

Sometimes, you might want to reprocess messages from the reject queue. In the example described previously in this topic, with a two-character job name column in the database, the messages could be successfully processed after the width of the database column had been increased. As another example, when a transfer-complete message is rejected because its associated transfer-start was missing, the transfer-start message might be received later. Reprocessing the transfer-complete will then be successful.

To reprocess messages, move them from the reject queue to the input queue. In a normal installation, where the logger created its own managed subscription, the input queue is defined by the queue manager and has a name like SYSTEM.MANAGED.DURABLE.49998CFF20006204. We can identify the input queue by looking at the Destination name in the properties for the subscription SYSTEM.FTE.DATABASELogger.AUTO, or using the following MQSC command:

 DISPLAY SUB(SYSTEM.FTE.DATABASELogger.AUTO) DEST

One way of moving messages between queues is to use the MA01 SupportPac, for example:

 q -IFTE.REJECT -oSYSTEM.MANAGED.DURABLE.49998CFF20006204 

The reject queue might contain messages rejected for various reasons, only some of which have been resolved. In this case we can still reprocess all the messages; those messages that can now be accepted are consumed, and those messages that cannot are again moved to the reject queue.

Malformed log messages in the transfer log are not logged by the logger. These messages are not viewed as being significant and so these messages are sent to the reject queue. For more information about transfer log messages, see File transfer log message formats.