Understanding queue depth events

In WebSphere MQ applications, queues must not become full. If they do, applications can no longer put messages on the queue that they specify. Although the message is not lost if this occurs, it can be a considerable inconvenience. The number of messages can build up on a queue if the messages are being put onto the queue faster than the applications that process them can take them off.

The solution to this problem depends on the particular circumstances, but may involve:

  • Diverting some messages to another queue.

  • Starting new applications to take more messages off the queue.

  • Stopping nonessential message traffic.

  • Increasing the queue depth to overcome a transient maximum.

Clearly, having advanced warning that problems may be on their way makes it easier to take preventive action. For this purpose, queue depth events are provided.

 

What queue depth events are

Queue depth events are related to the queue depth, that is, the number of messages on the queue. The types of queue depth events are:

  • Queue Depth High events, which indicate that the queue depth has increased to a predefined threshold called the Queue Depth High limit.

  • Queue Depth Low events, which indicate that the queue depth has decreased to a predefined threshold called the Queue Depth Low limit.

  • Queue Full events, which indicate that the queue has reached its maximum depth, that is, the queue is full.

A Queue Full Event is generated when an application attempts to put a message on a queue that has reached its maximum depth. Queue Depth High events give advance warning that a queue is filling up. This means that having received this event, the system administrator should take some preventive action. If this action is successful and the queue depth drops to a 'safe' level, the queue manager can be configured to generate a Queue Depth Low event indicating an 'all clear' state.

 

Shared queues and queue depth events (WebSphere MQ for z/OS)

When a queue depth event occurs on a shared queue, the queue managers in the queue-sharing group produce an event message, if the queue manager attribute PerformanceEvent (PERFMEV in MQSC) is set to ENABLED. If PERFMEV is set to DISABLED on some of the queue managers, event messages are not produced by those queue managers, making event monitoring from an application more difficult. To avoid this, give each queue manager the same setting for the PerformanceEvent attribute. This event message represents the individual usage of the shared queue by each queue manager. If a queue manager performs no activity on the shared queue, various values in the event message are null or zero. Null event messages:

  • Allow you to ensure there is one event message for each active queue manager in a queue-sharing group

  • Can highlight cases where there has been no activity on a shared queue for a queue manager that produced the event message

 

Enabling queue depth events

By default, all queue depth events are disabled. To configure a queue for any of the queue depth events :

  1. Enable performance events on the queue manager, using the queue manager attribute PerformanceEvent (PERFMEV in MQSC).

  2. Enable the event on the required queue by setting the following as required:

    • QDepthHighEvent QDPHIEV(in MQSC)

    • QDepthLowEvent(QDPLOEV in MQSC)

    • QDepthMaxEvent(QDPMAXEV in MQSC)

  3. Set the limits, if required, to the appropriate levels, expressed as a percentage of the maximum queue depth, by setting either:

    • QDepthHighLimit(QDEPTHHI in MQSC), and

    • QDepthLowLimit QDEPTHLO(in MQSC).

 

Enabling queue depth events on shared queues (WebSphere MQ for z/OS)

When a queue manager determines that an event should be issued, the shared queue object definition is updated to toggle the active performance event attributes. For example, depending on the definition of the queue attributes, a Queue Depth High event enables a Queue Depth Low and a Queue Full event. After the shared queue object has been updated successfully, the queue manager that detected the performance event initially becomes the coordinating queue manager.

The coordinating queue manager:

  1. Determines if it has performance events enabled.

  2. If it does, issues an event message that captures all shared queue performance data it has gathered since the last time an event message was created, or since the queue statistics were last reset. The message descriptor (MQMD) of this message contains a unique correlation identifier (CorrelId) created by the coordinating queue manager.

  3. Broadcasts to all other active queue managers in the same queue-sharing group to request the production of an event message for the shared queue. The broadcast contains the correlation identifier created by the coordinating queue manager for the set of event messages.

After receiving a request from the coordinating queue manager, an active queue manager in a queue-sharing group:

  1. Determines if its PERFMEV is ENABLED.

  2. If it is, the active queue manager issues an event message for the shared queue, recording all operations performed by the receiving (active) queue manager since the last time an event message was created, or since the last statistics reset. The message descriptor (MQMD) of this event message contains the unique correlation identifier (CorrelId) specified by the coordinating queue manager.

When performance events occur on a shared queue, n event messages are produced, where n is 1 to the number of active queue managers in the queue-sharing group. Each event message contains data that relates to the shared queue activity for the queue manager where the event message was generated.

You can view event message data for a shared queue using the:

  • Queue-sharing view.

    All data from event messages with the same correlation identifier is collected here.

  • Queue manager view.

    Each event message shows how much it has been used by its originating queue manager.

 

Differences between shared and nonshared queues

Enabling queue depth events on shared queues differs from enabling events on nonshared queues. A key difference is that events are switched for shared queues even if PERFMEV is DISABLED on the queue manager. This is not the case for nonshared queues.

Consider the following example which illustrates this difference.

  • PARIS is a queue manager with PerformanceEvent (PERFMEV in MQSC) set to DISABLED.

  • SQ1 is a shared queue with QSGDISP set to (SHARED) QLOCAL in MQSC.

  • LQ1 is a nonshared queue with QSGDISP set to (QMGR) QLOCAL in MQSC.

Both queues have the following attributes set on their definitions:

  • QDPHIEV (ENABLED)

  • QDPLOEV (DISABLED)

  • QDPMAXEV (DISABLED)

If messages are placed on both queues so that the depth meets or exceeds the QDEPTHHI threshold, the QDPHIEV value on SQ1 switches to DISABLED. Also, QDPLOEV and QDPMAXEV are switched to ENABLED. SQ1's attributes are automatically switched for each performance event at the time the event criteria are met.

In contrast the attributes for LQ1 remain unchanged until PERFMEV on the queue manager is ENABLED. This means that if the queue manager's PERFMEV attribute is ENABLED, DISABLED and then re-ENABLED for instance, the performance event settings on shared queues might not be consistent with those of nonshared queues, even though they might have initially been the same.

 

Enabling Queue Depth High events

When enabled, a Queue Depth High event is generated when a message is put on the queue, causing the queue depth to be greater than or equal to the value determined by the Queue Depth High limit.

To enable Queue Depth High events on the queue MYQUEUE with a limit set at 80%, use the following MQSC commands: 



  ALTER QMGR PERFMEV(ENABLED)
  ALTER QLOCAL('MYQUEUE') QDEPTHHI(80) QDPHIEV(ENABLED)

 

Automatically enabling Queue Depth High events

A Queue Depth High event is automatically enabled by a Queue Depth Low event on the same queue.

A Queue Depth High event automatically enables both a Queue Depth Low and a Queue Full event on the same queue.

 

Enabling Queue Depth Low events

When enabled, a Queue Depth Low event is generated when a message is removed from a queue by an MQGET call operation causing the queue depth to be less than or equal to the value determined by the Queue Depth Low limit.

To enable Queue Depth Low events on the queue MYQUEUE with a limit set at 20%, use the following MQSC commands: 



  ALTER QMGR PERFMEV(ENABLED)
  ALTER QLOCAL('MYQUEUE') QDEPTHLO(20) QDPLOEV(ENABLED)

 

Automatically enabling Queue Depth Low events

A Queue Depth Low event is automatically enabled by a Queue Depth High event or a Queue Full event on the same queue.

A Queue Depth Low event automatically enables both a Queue Depth High and a Queue Full event on the same queue.

 

Enabling Queue Full events

When enabled, a Queue Full event is generated when an application is unable to put a message onto a queue because the queue is full.

To enable Queue Full events on the queue MYQUEUE, use the following MQSC commands: 



  ALTER QMGR PERFMEV(ENABLED)
  ALTER QLOCAL('MYQUEUE') QDPMAXEV(ENABLED)

 

Automatically enabling Queue Full events

A Queue Full event is automatically enabled by a Queue Depth High or a Queue Depth Low event on the same queue.

A Queue Full event automatically enables a Queue Depth Low event on the same queue.

Table 8. Enabling queue depth events using MQSC

Queue depth event
 Queue attributes
Queue depth high
 
 
 
Queue depth low
 
 
 
 
 
 Queue full
 QDPHIEV (ENABLED)
QDEPTHHI (hh) where hh is the queue depth
high limit.
 
QDPLOEV (ENABLED)
QDEPTHLO (ll) where ll is the Queue depth
low limit. (Both values are expressed as a
percentage of the maximum queue depth, which is
specified by the queue
attribute MAXDEPTH.)
 
QDPMAXEV (ENABLED)

Notes:
All performance events must be enabled using the queue manager attribute PERFMEV.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.