Priority (MQLONG)

For the MQPUT and MQPUT1 calls, the value must be greater than or equal to zero; zero is the lowest priority. The following special value can also be used:
MQPRI_PRIORITY_AS_Q_DEF
  • If the queue is a cluster queue, the priority for the message is taken from the DefPriority attribute defined at the destination queue manager that owns the particular instance of the queue on which the message is placed.

    When there are multiple instances of the cluster queue, and they differ in this attribute, the value from one of them is picked and it cannot be predicted which one will be used. You should therefore set this attribute to the same value on all instances. If this is not the case, error message AMQ9407 is issued to the queue manager logs. See also How are destination object attributes resolved for aliases, remote and cluster queues?

    The value of DefPriority is copied into the Priority field when the message is placed on the destination queue. If DefPriority is changed subsequently, messages that have already been placed on the queue are not affected.

  • If the queue is not a cluster queue, the priority for the message is taken from the DefPriority attribute defined at the local queue manager, even if the destination queue manager is remote.
    If there is more than one definition in the queue-name resolution path, the default priority is taken from the value of this attribute in the first definition in the path. This can be:
    • An alias queue
    • A local queue
    • A local definition of a remote queue
    • A queue manager alias
    • A transmission queue (for example, the DefXmitQName queue)

    The value of DefPriority is copied into the Priority field when the message is put. If DefPriority is changed subsequently, messages that have already been put are not affected.

The value returned by the MQGET call is always greater than or equal to zero; the value MQPRI_PRIORITY_AS_Q_DEF is never returned.

If a message is put with a priority greater than the maximum supported by the local queue manager (this maximum is given by the MaxPriority queue manager attribute), the message is accepted by the queue manager, but placed on the queue at the queue manager's maximum priority; the MQPUT or MQPUT1 call completes with MQCC_WARNING and reason code MQRC_PRIORITY_EXCEEDS_MAXIMUM. However, the Priority field retains the value specified by the application that put the message.

On z/OS®, if a message with a MsgSeqNumber of 1 is put to a queue that has a message delivery sequence of MQMDS_PRIORITY and an index type of MQIT_GROUP_ID, the queue might treat the message with a different priority. If the message was placed on the queue with a priority of 0 or 1, it is processed as though it has a priority of 2. This is because the order of messages placed on this type of queue is optimized to enable efficient group completeness tests. For more information on the message delivery sequence MQMDS_PRIORITY and the index type MQIT_GROUP_ID, see MsgDeliverySequence attribute.

When replying to a message, applications must use the priority of the request message for the reply message. In other situations, specifying MQPRI_PRIORITY_AS_Q_DEF allows priority tuning to be carried out without changing the application.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQPRI_PRIORITY_AS_Q_DEF.