Enabling queue depth events

To configure a queue for any of the queue depth events you set the appropriate queue manager and queue attributes.

About this task

By default, all queue depth events are disabled. When enabled, queue depth events are generated as follows:
  • 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 set for QDepthHighLimit.
    • 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.
  • [UNIX, Linux, Windows, IBM i]A Queue Depth Low event is generated when a message is removed from a queue by a GET operation, causing the queue depth to be less than or equal to the value set for QDepthLowLimit.

    [z/OS]A Queue Depth Low event is generated when a message is removed from a queue by a GET operation, or would have been removed but has since expired, causing the queue depth to be less than or equal to the value set for QDepthLowLimit.

    • 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.
  • A Queue Full event is generated when an application is unable to put a message onto a queue because the queue is full.
    • 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.

Perform the following steps to configure a queue for any of the queue depth events:

Procedure

  1. Enable performance events on the queue manager, using the queue manager attribute PERFMEV.
    The events go to the SYSTEM.ADMIN.PERFM.EVENT queue.
  2. Set one of the following attributes to enable the event on the required queue:
    • QDepthHighEvent (QDPHIEV in MQSC)
    • QDepthLowEvent (QDPLOEV in MQSC)
    • QDepthMaxEvent (QDPMAXEV in MQSC)
  3. Optional: To set the limits, assign the following attributes, as a percentage of the maximum queue depth:
    • QDepthHighLimit (QDEPTHHI in MQSC)
    • QDepthLowLimit (QDEPTHLO in MQSC)
    Restriction: QDEPTHHI must not be less than QDEPTHLO.

    If QDEPTHHI equals QDEPTHLO an event message is generated every time the queue depth passes the value in either direction, because the high threshold is enabled when the queue depth is below the value and the low threshold is enabled when the depth is above the value.

Results

Note:

[UNIX, Linux, Windows, IBM i]A Queue Depth Low event is not generated when expired messages are removed from a queue by a GET operation causing the queue depth to be less than, or equal to, the value set for QDepthLowLimit. IBM® MQ generates the queue depth low event message only during a successful GET operation. Therefore, when the expired messages are removed from the queue, no queue depth low event message is generated. Additionally, after the removal of these expired messages from the queue, QDepthHighEvent and QDepthLowEvent are not reset.

[z/OS]IBM MQ generates the queue depth low event message during either a successful destructive GET operation, or a destructive GET operation that would have succeeded had a matching message not expired. Otherwise, when expired messages are removed from a queue during general background processing, no queue depth low event message is generated. Additionally, after the removal of expired messages from a queue during general background processing, QDepthHighEvent and QDepthLowEvent are not reset. For more information on expired message processing, see Tuning your queue manager on IBM MQ for z/OS®.

Example

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)

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)

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

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