Conditions for a trigger event

 

References to shared queues in this section mean shared queues in a queue-sharing group, only available on WebSphere MQ for z/OS.

The queue manager creates a trigger message when the following conditions are satisfied:

  1. A message is put on a queue.

  2. The message has a priority greater than or equal to the threshold trigger priority of the queue. This priority is set in the TriggerMsgPriority local queue attribute--if it is set to zero, any message qualifies.

  3. The number of messages on the queue with priority greater than or equal to TriggerMsgPriority was previously, depending on TriggerType:

    • Zero (for trigger type MQTT_FIRST)

    • Any number (for trigger type MQTT_EVERY)

    • TriggerDepth minus 1 (for trigger type MQTT_DEPTH)

    Notes:

    1. For non-shared local queues, the queue manager counts both committed and uncommitted messages when it assesses whether the conditions for a trigger event exist. Consequently an application may be started when there are no messages for it to retrieve because the messages on the queue have not been committed. In this situation, you are strongly recommended to consider using the wait option with a suitable WaitInterval, so that the application waits for its messages to arrive.

    2. For local shared queues the queue manager counts committed messages only.

  4. For triggering of type FIRST or DEPTH, no program has the application queue open for removing messages (that is, the OpenInputCount local queue attribute is zero).

    Notes:

    1. For shared queues, special conditions apply when multiple queue managers have trigger monitors running against a queue. In this situation, if one or more queue managers have the queue open for input shared, then the trigger criteria on the other queue managers will be treated as TriggerType MQTT_FIRST and TriggerMsgPriority zero. When all the queue managers close the queue for input, the trigger conditions revert to those specified in the queue definition.

    2. For shared queues, this condition is applied on a per queue manager basis. That is, a queue manager's OpenInputCount for a queue must be zero for a trigger message to be generated for the queue by that queue manager. However, if any queue manager in the queue-sharing group has the queue open using the MQOO_INPUT_EXCLUSIVE option, no trigger message will be generated for that queue by any of the queue managers in the queue-sharing group.

  5. On WebSphere MQ for z/OS, if the application queue is one with a Usage attribute of MQUS_NORMAL, get requests for it are not inhibited (that is, the InhibitGet queue attribute is MQQA_GET_ALLOWED). Also, if the triggered application queue is one with a Usage attribute of MQUS_XMITQ, get requests for it are not inhibited.

  6. Either:

    • The ProcessName local queue attribute for the queue is not blank, and the process definition object identified by that attribute has been created.

      or

    • The ProcessName local queue attribute for the queue is all blank, but the queue is a transmission queue. As the process definition is optional, the TriggerData attribute may also contain the name of the channel to be started. In this case, the trigger message contains attributes with the following values:

      QName: queue name
      ProcessName: blanks
      TriggerData: trigger data
      ApplType: MQAT_UNKNOWN
      ApplId: blanks
      EnvData: blanks
      UserData: blanks

      This option is not available with MQSeries Version 2 products.

  7. An initiation queue has been created, and has been specified in the InitiationQName local queue attribute. Also:

    • Get requests are not inhibited for the initiation queue (that is, the InhibitGet queue attribute is MQQA_GET_ALLOWED).

    • Put requests must not be inhibited for the initiation queue (that is, the InhibitPut queue attribute must be MQQA_PUT_ALLOWED).

    • The Usage attribute of the initiation queue must be MQUS_NORMAL.

    • In environments where dynamic queues are supported, the initiation queue must not be a dynamic queue that has been marked as logically deleted.

  8. A trigger monitor currently has the initiation queue open for removing messages (that is, the OpenInputCount local queue attribute is greater than zero).

  9. The trigger control (TriggerControl local queue attribute) for the application queue is set to MQTC_ON. To do this, set the trigger attribute when you define your queue, or use the ALTER QLOCAL command.

  10. The trigger type (TriggerType local queue attribute) is not MQTT_NONE.

    If all of the above required conditions are met, and the message that caused the trigger condition is put as part of a unit of work, the trigger message does not become available for retrieval by the trigger monitor application until the unit of work completes, whether the unit of work is committed or, for trigger type MQTT_FIRST or MQTT_DEPTH, backed out.

  11. A suitable message is placed on the queue, for a TriggerType of MQTT_FIRST or MQTT_DEPTH, and the queue:

    • Was not previously empty (MQTT_FIRST)

      or

    • Had TriggerDepth or more messages (MQTT_DEPTH)

    and conditions 2 through 10 (excluding 3) are satisfied, if in the case of MQTT_FIRST a sufficient interval (TriggerInterval queue-manager attribute) has elapsed since the last trigger message was written for this queue.

    This is to allow for a queue server that ends before processing all of the messages on the queue. The purpose of the trigger interval is to reduce the number of duplicate trigger messages that are generated.

    Note:
    If you stop and restart the queue manager, the TriggerInterval "timer" is reset. There is a small window during which it is possible to produce two trigger messages. The window exists when the queue's trigger attribute is set to enabled at the same time as a message arrives and the queue was not previously empty (MQTT_FIRST) or had TriggerDepth or more messages (MQTT_DEPTH).

  12. The only application serving a queue issues an MQCLOSE call, for a TriggerType of MQTT_FIRST or MQTT_DEPTH, and there is at least:

    • One (MQTT_FIRST)

      or

    • TriggerDepth (MQTT_DEPTH)

    messages on the queue of sufficient priority (condition 2), and conditions 6 through 10 are also satisfied.

    This is to allow for a queue server that issues an MQGET call, finds the queue empty, and so ends; however, in the interval between the MQGET and the MQCLOSE calls, one or more messages arrive.

    Notes:

    1. If the program serving the application queue does not want to retrieve all the messages, this can cause a closed loop. Each time the program closes the queue, the queue manager creates another trigger message which causes the trigger monitor to start the server program again.

    2. If the program serving the application queue backs out its get request (or if the program abends) before it closes the queue, the same happens.

    3. To prevent such a loop occurring, you could use the BackoutCount field of MQMD to detect messages that are repeatedly backed out. For more information, see Messages that are backed out.

  13. The following conditions are satisfied using MQSET or a command:

      • TriggerControl is changed to MQTC_ON

        or

      • TriggerControl is already MQTC_ON and the value of either TriggerType, TriggerMsgPriority, or TriggerDepth (if relevant) is changed,

      and there is at least:

      • One (MQTT_FIRST or MQTT_EVERY)

        or

      • TriggerDepth (MQTT_DEPTH)

      messages on the queue of sufficient priority (condition 2), and conditions 4 through 10 (excluding 8) are also satisfied.

      This is to allow for an application or operator changing the triggering criteria, when the conditions for a trigger to occur are already satisfied.

    2. The InhibitPut queue attribute of an initiation queue changes from MQQA_PUT_INHIBITED to MQQA_PUT_ALLOWED, and there is at least:

      • One (MQTT_FIRST or MQTT_EVERY)

        or

      • TriggerDepth (MQTT_DEPTH)

      messages of sufficient priority (condition 2) on any of the queues for which this is the initiation queue, and conditions 4 through 10 are also satisfied. (One trigger message is generated for each such queue satisfying the conditions.)

      This is to allow for trigger messages not being generated because of the MQQA_PUT_INHIBITED condition on the initiation queue, but this condition now having been changed.

    3. The InhibitGet queue attribute of an application queue changes from MQQA_GET_INHIBITED to MQQA_GET_ALLOWED, and there is at least:

      • One (MQTT_FIRST or MQTT_EVERY)

        or

      • TriggerDepth (MQTT_DEPTH)

      messages of sufficient priority (condition 2) on the queue, and conditions 4 through 10, excluding 5, are also satisfied.

      This allows applications to be triggered only when they are able to retrieve messages from the application queue.

    4. A trigger-monitor application issues an MQOPEN call for input from an initiation queue, and there is at least:

      • One (MQTT_FIRST or MQTT_EVERY)

        or

      • TriggerDepth (MQTT_DEPTH)

      messages of sufficient priority (condition 2) on any of the application queues for which this is the initiation queue, and conditions 4 through 10 (excluding 8) are also satisfied, and no other application has the initiation queue open for input (one trigger message is generated for each such queue satisfying the conditions).

      This is to allow for messages arriving on queues while the trigger monitor is not running, and for the queue manager restarting and trigger messages (which are nonpersistent) being lost.

  14. MSGDLVSQ is set correctly. If you set MSGDLVSQ=FIFO, messages are delivered to the queue in a First In First Out basis. The priority of the message is ignored and the default priority of the queue is assigned to the message. If TriggerMsgPriority is set to a higher value than the default priority of the queue, no messages are triggered. If TriggerMsgPriority is set equal to or lower than the default priority of the queue, triggering occurs for type FIRST, EVERY, and DEPTH. For information about these types, see the description of the TriggerType field under Controlling trigger events. If you set MSGDLVSQ=PRIORITY and the message priority is equal to or greater than the TriggerMsgPriority field, messages only count towards a trigger event. In this case, again triggering occurs for type FIRST, EVERY, and DEPTH. As an example, if you put 100 messages of lower priority than the TriggerMsgPriority, the effective queue depth for triggering purposes is still zero. If you then put another message on the queue, but this time the priority is greater than or equal to the TriggerMsgPriority, the effective queue depth increases from zero to one and the condition for TriggerType FIRST is satisfied.

Notes:

  1. From step 12 (where trigger messages are generated as a result of some event other than a message arriving on the application queue), the trigger message is not put as part of a unit of work. Also, if the TriggerType is MQTT_EVERY, and if there are one or more messages on the application queue, only one trigger message is generated.

  2. If WebSphere MQ segments a message during MQPUT, a trigger event will not be processed until all of the segments have been successfully placed on the queue. However, once message segments are on the queue, WebSphere MQ treats them as individual messages for triggering purposes. For example, a single logical message split into three pieces will cause only one trigger event to be processed when it is first MQPUT and segmented. However, each of the three segments will cause their own trigger events to be processed as they are moved through the WebSphere MQ network.

 

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.