Guidance for setting WebSphere MQ attributes and WebSphere MQ File Transfer Edition properties associated with message size

You can change WebSphere® MQ attributes and WebSphere MQ File Transfer Edition properties to affect the behavior of WebSphere MQ File Transfer Edition 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 WebSphere MQ File Transfer Edition 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 parameter, see Advanced agent properties.

In addition to changing the maxInputOutputMessageLength agent property, you might also have to change some of the WebSphere MQ queue manager properties.

Start of change
  • 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 WebSphere 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.

    Consider each of the following WebSphere MQ attributes:
    • 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
    Ensure that the value of each of these attributes, in bytes, 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 formula is used to calculate the number of checkpoint records that can be held in a single FTE state message for the SYSTEM.FTE.STATE.agent_name queue. This calculation is derived from the following facts:
    • Three checkpoints can be stored in a state message.
    • Each checkpoint might have to buffer up to the maximum size of a message amount of data.
    Because the maximum message size that WebSphere MQ can process is 100 MB, the maximum value that can be set in the maxInputOutputMessageLength property for a message-to-file transfer is 33 MB (34603008 bytes).
  • If the queue that the agent is writing to is a remote queue, you might have to change the WebSphere MQ queue manager, queue, and channel MAXMSGL attributes.

    Ensure that the value of each of the following WebSphere 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
    Consider each of the following WebSphere MQ attributes:
    • 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
    Ensure that the value of each of these attributes, in bytes, 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 formula is used to calculate the number of checkpoint records that can be held in a single FTE state message for the SYSTEM.FTE.STATE.agent_name queue. This calculation is derived from the following facts:
    • Three checkpoints can be stored in a state message.
    • Each checkpoint might have to buffer up to the maximum size of a message amount of data.
    Because the maximum message size that WebSphere MQ can process is 100 MB, the maximum value that can be set in the maxInputOutputMessageLength property for a message-to-file transfer is 33 MB (34603008 bytes).
End of change
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 WebSphere 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 property 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 property of the queue manager that the agent reading from or writing to a queue connects to. For information about how change this value, see MaximumUncommittedMessages property in the WebSphere MQ V7.1.0 product documentation.
  • 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. For information about how change this value, see the Managing log files.

If you are transferring files to or from messages on z/OS queue managers - Version 7.0.3 or later

On z/OS®, you must ensure that the size of the queue manager page sets are sufficient for the size of the messages on the SYSTEM.FTE.STATE.agent_name queue, in addition to the messages on the source and destination queues. For "In progress" transfers, the maximum size that the messages on the SYSTEM.FTE.STATE.agent_name queue can be is as follows:
3 x (maxInputOutputMessageLength) + 1048576 bytes
Each "In progress" source and destination transfer has a message on the SYSTEM.FTE.STATE.agent_name queue. The number of concurrent source transfers is limited by the maxSourceTransfers agent property and the number of concurrent destination transfers is limited by the maxDestinationTransfers agent property.

For further details on sizing page sets and setting their values, see Managing page sets.


Reference Reference

Feedback

Timestamp icon Last updated: Tuesday, 30 January 2018
http://www.ibm.com/support/knowledgecenter/SSEP7X_7.0.4/com.ibm.wmqfte.doc/message_length.htm