Guidance for setting IBM MQ attributes and IBM MQ Managed File Transfer properties associated with message size

You can change IBM® MQ attributes and IBM MQ Managed File Transfer properties to affect the behavior of IBM MQ Managed File Transfer when reading or writing messages of various sizes.

If the size of messages being read from a source queue or written to a destination queue exceeds 1048576 bytes (1 MB), you must increase the value of the IBM MQ Managed File Transfer agent property maxInputOutputMessageLength to a value that is greater than or equal to the maximum message size to be read or written.

If the messages on the source queue are greater than 1048576 bytes, you must set the maxInputOutputMessageLength property on the source agent. If the messages on the destination queue are greater than 1048576 bytes you must set the maxInputOutputMessageLength property on the destination agent. For more information about the maxInputOutputMessageLength property, see Advanced agent properties.

If the queue that the agent is writing to or reading from is local to the agent queue manager, you might have to change the IBM MQ queue manager, queue, and channel MAXMSGL attributes.

Ensure that the value of the maximum message size of the source or destination queue is greater than or equal to the value of the maxInputOutputMessageLength agent property.
Ensure that the value of each of the following IBM MQ attributes, in bytes:
- The maximum message size of the agent queue manager
- The maximum message size of the SYSTEM.FTE.STATE.<agent_name> queue
- The client channel maximum message size, if your agent connects to the queue manager in client mode
is greater than or equal to the result of the following calculation:
For a file-to-message transfer (which supports a file size of up to 100 MB):

The value of maxInputOutputMessageLength

For a message-to-file transfer:

The value of 3 * (maxInputOutputMessageLength) + 1048576

(This calculation is derived from the fact that three checkpoints can be stored in a state message and each checkpoint might have to buffer up to the maximum size of a message amount of data.)
If the queue that the agent is writing to is a remote queue, you might have to change the IBM MQ queue manager, queue, and channel MAXMSGL attributes.
Ensure that the value of each of the following IBM MQ attributes is greater than or equal to the value of the maxInputOutputMessageLength agent property:
- The maximum message size of the remote queue manager transmission queue on the agent queue manager
- The maximum message size of the channel from the agent queue manager to the remote queue manager
- The maximum message size of the destination queue on the remote queue manager
- The maximum message size of the remote queue manager
Ensure that the value of each of the following IBM MQ attributes, in bytes:
- The maximum message size of the agent queue manager
- The maximum message size of the SYSTEM.FTE.STATE.<agent_name> queue
- The client channel maximum message size, if your agent connects to the queue manager in client mode
is greater than or equal to the result of the following calculation:
For a file-to-message transfer (which supports a file size of up to 100 MB):

The value of maxInputOutputMessageLength

For a message-to-file transfer:

The value of 3 * (maxInputOutputMessageLength) + 1048576

(This calculation is derived from the fact that three checkpoints can be stored in a state message and each checkpoint might have to buffer up to the maximum size of a message amount of data.)

If you exceed the value of one of these properties, the agent stops with the following error in the agent event log:

BFGUT0002E: An internal error has occurred. Product failure data was captured in file 
"FFDC.FTE.20100928170828514.8172766022149157013.log". 
BFGSS0025E: An internal error has occurred.  The exception is: cc=2 rc=2010 op=put - MQPUT to SYSTEM.FTE.STATE.<agent_name>
BFGAG0061E: The agent ended abnormally

The following IBM MQ reason codes might be included in this message in the agent event log:

rc=2010 This reason code maps to MQRC_DATA_LENGTH_ERROR and indicates that the value of the client channel maximum message size was exceeded. To resolve this problem ensure that the client channel maximum message size of the agent queue manager is greater than or equal to the result of the following calculation:
```
3 * (maxInputOutputMessageLength) + 1048576
```
rc=2030 This reason code maps to MQRC_MSG_TOO_BIG_FOR_Q and indicates that the value of the maximum message size of the SYSTEM.FTE.STATE.<agent_name> queue was exceeded. To resolve this problem ensure that the maximum message size of the SYSTEM.FTE.STATE.<agent_name> queue is greater than or equal to the result of the following calculation:
```
3 * (maxInputOutputMessageLength) + 1048576
```
rc=2031 This reason code maps to MQRC_MSG_TOO_BIG_FOR_Q_MGR and indicates that the value of the maximum message size of the agent queue manager was exceeded. To resolve this problem ensure that the maximum message size of the agent queue manager is greater than or equal to the result of the following calculation:
```
3 * (maxInputOutputMessageLength) + 1048576
```

If you are transferring many small messages

If the average size of the messages that the agent is reading from or writing to a queue is less than 1310 bytes and the agent is reading or writing more than 10000 messages, you must increase the maximum number of uncommitted messages attribute on the queue manager or reduce the amount of data in a checkpoint interval.

When the agent is reading messages from or writing messages to a queue the corresponding GETs or PUTs are grouped together into transactions. The number of GETs or PUTs in a transaction is determined by the number required to process all of the data within a checkpoint interval. The approximate amount of the data in a checkpoint interval is determined from agent properties using the following calculation:

Checkpoint interval data size (in bytes) = agentCheckpointInterval  * agentFrameSize *
                                           agentWindowSize  * agentChunkSize.

The default checkpoint data size is 1 * 5 * 10 * 262144 bytes = 13107200 bytes (12.5MB). The maximum number of uncommitted messages in a transaction that a queue manager supports is controlled by the MaxUncommittedMsgs queue manager attribute. The default value of this attribute is 10000 messages. If the average message size is less than approximately 1310 bytes the default maximum number of uncommitted messages is exceeded if there are more than 10000 messages to be written.

If you exceed the MaxUncommittedMsgs limit, the agent stops with the following error in the agent event log:

BFGSS0024E: The agent has received a reason code of '2024' from the message queue interface (MQI). 
The agent cannot continue processing and will now end.
BFGAG0139I: The agent has suspended its current transfers and is now stopping.

The reason code 2024 maps to: MQRC_SYNCPOINT_LIMIT_REACHED.

To resolve this problem perform one of the following actions

Increase the value of the MaxUncommittedMsgs queue manager attribute of the queue manager that the agent reading from or writing to a queue connects to. See MaxUncommittedMsgs (MQLONG).
Reduce the amount of data in a checkpoint interval. To do this, decrease the value of one or more of the following agent properties:
- agentCheckpointInterval
- agentFrameSize
- agentWindowSize
- agentChunkSize
For information about these agent properties, see Advanced agent properties.

If you are writing messages to a queue persistently

If you are transferring to a queue and writing the messages to the queue persistently, you might have to increase the size of the queue manager log file space to be able to log all of the data in a checkpoint interval.

If you exceed the queue manager log file space, the agent stops with the following error in the agent event log:

BFGSS0024E: The agent has received a reason code of '2102' from the message queue interface (MQI). 
The agent cannot continue processing and will now end.
BFGAG0062E: The agent has received MQI reason code '2102'.  The agent cannot continue processing and will now end.
BFGAG0061E: The agent ended abnormally

The reason code '2102' maps to: MQRC_RESOURCE_PROBLEM.

To resolve this problem increase the size of the destination agent queue manager log file space.