MessageBuffer stanza of the client configuration file

Use the MessageBuffer stanza to specify information about message buffers.

The following attributes can be included in the MessageBuffer stanza:

MaximumSize = integer|1

Size, in kilobytes, of the read-ahead buffer, in the range 1 through 999 999.

This attribute can be read by C, unmanaged .NET, IBM MQ classes for Java, IBM MQ classes for JMS, managed .NET, and managed XMS .NET clients.

The following special values exist:

-1

The client determines the appropriate value.

0

Read ahead is disabled for the client.

PurgeTime = integer|600

Interval, in seconds, after which messages left in the read-ahead buffer are purged.

This attribute can be read by C, unmanaged .NET, IBM MQ classes for Java, IBM MQ classes for JMS, managed .NET, and managed XMS .NET clients.

If the client application is selecting messages based on MsgId or CorrelId it is possible that the read ahead buffer might contain messages sent to the client with a previously requested MsgId or CorrelId. These messages would then be stranded in the read ahead buffer until an MQGET is issued with an appropriate MsgId or CorrelId. We can purge messages from the read ahead buffer by setting PurgeTime. Any messages that have remained in the read ahead buffer for longer than the purge interval are automatically purged. These messages have already been removed from the queue on the queue manager, so unless they are being browsed, they are lost.

The valid range is in the range 1 through 999 999 seconds, or the special value 0, meaning that no purge takes place.

UpdatePercentage = integer|-1

The update percentage value, in the range of 1 - 100, used in calculating the threshold value to determine when a client application makes a new request to the server. The special value -1 indicates that the client determines the appropriate value.

This attribute can be read by C, unmanaged .NET, IBM MQ classes for Java, IBM MQ classes for JMS, managed .NET, and managed XMS .NET clients.

The client periodically sends a request to the server indicating how much data the client application has consumed. A request is sent when the number of bytes, n, retrieved by the client by way of MQGET calls exceeds a threshold T. n is reset to zero each time a new request is sent to the server.

The threshold T is calculated as follows:

T = Upper - Lower

Upper is the same as the read-ahead buffer size, specified by the MaximumSize attribute, in Kilobytes. Its default is 100 Kb.

Lower is lower than Upper, and is specified by the UpdatePercentage attribute. This attribute is a number in the range 1 through 100, and has a default of 20. Lower is calculated as follows:

Lower = Upper x UpdatePercentage / 100

Example 1:

The MaximumSize and UpdatePercentage attributes take their defaults of 100 Kb and 20 Kb.

The client calls MQGET to retrieve a message, and does so repeatedly. This continues until MQGET has consumed n bytes.

Use the calculation

T = Upper - Lower

T is (100 - 20) = 80 Kb.

So when MQGET calls have removed 80 Kb from a queue, the client makes a new request automatically.

Example 2:

The MaximumSize attributes takes its default of 100 Kb, and a value of 40 is chosen for UpdatePercentage.

The client calls MQGET to retrieve a message, and does so repeatedly. This continues until MQGET has consumed n bytes.

Use the calculation

T = Upper - Lower

T is (100 - 40) = 60 Kb

So when MQGET calls have removed 60 Kb from a queue, the client makes a new request automatically. This is sooner than in EXAMPLE 1 where the defaults were used.

Therefore choosing a larger threshold T tends to decrease the frequency at which requests are sent from client to server. Conversely choosing a smaller threshold T tends to increase the frequency of requests that are sent from client to server.

However, choosing a large threshold T can mean that the performance gain of read ahead is reduced as the chance of the read ahead buffer becoming empty can increase. When this happens an MQGET call might have to pause, waiting for data to arrive from the server.

Parent topic: Configure a client using a configuration file