CAPEXPRY: Limit message expiry time

Administrators can limit the expiry time of any message put to a queue or topic by using the CAPEXPRY attribute.

There are two ways to set CAPEXPRY:

By specifying the CAPEXPRY attribute.
By specifying the CAPEXPRY attribute in the CUSTOM attribute.

[MQ 9.4.0 Jun 2024] From IBM® MQ 9.4.0, you should use the CAPEXPRY attribute without specifying it inside the CUSTOM attribute.

The following information applies regardless of how you have set the CAPEXPRY attribute:

The value of CAPEXPRY is expressed in tenths of seconds, so a value of 600 represents one minute.
If an application sets an expiry time in the MQMD structure that exceeds the CAPEXPRY value of the queue or topic, it is reduced to CAPEXPRY. If the expiry time is lower than CAPEXPRY, it remains unchanged.
If more than one object is used on the resolution path, for example, when a message is put to an alias or remote queue, then the lowest of all the CAPEXPRY values is used as the upper limit for message expiry.
Changes to the CAPEXPRY values take effect immediately. The expiry value is evaluated for each put to a queue or topic and so is sensitive to the object resolution, which might differ between each put operation.
However, existing messages in the queue, prior to a change in CAPEXPRY, are not affected by the change (that is, their expiry time remains the same). Only new messages that are put into the queue or topic after the change in CAPEXPRY have the new expiry time.
In a cluster where a put is performed to a queue opened with MQOO_BIND_NOT_FIXED, messages can be assigned different expiry values on each put, depending on the CAPEXPRY value set for the transmission queue, used by the channel, that sends the message to the selected target queue manager.

Attention: CAPEXPRY must not be used on any queues that hold IBM MQ internally-generated messages such as any SYSTEM.CLUSTER.* queue and the SYSTEM.PROTECTION.POLICY.QUEUE.

Interactions between the CAPEXPRY attribute and the CAPEXPRY attribute in the CUSTOM attribute

When migrating an object from an earlier version of the product, the CAPEXPRY value is set to the default value of NOLIMIT (for queues) and ASPARENT (for topics). Therefore, if set, the CAPEXPRY attribute inside the CUSTOM attribute takes precedence.

If a queue or topic already has the CAPEXPRY attribute set inside the CUSTOM attribute you must remove the CAPEXPRY attribute from the CUSTOM attribute before the new CAPEXPRY attribute is set to a non-default value. You can do this in a single command, for example:

ALTER QLOCAL(Q1) CAPEXPRY(1000) CUSTOM('')

The CAPEXPRY attribute that you set directly on queues or topics (not inside the CUSTOM attribute) is a clustered attribute. All instances of a clustered queue, or clustered topic, should use the same CAPEXPRY value. It is still possible that a transmission queue reduces the expiry time of a message if CAPEXPRY has been set on the transmission queue, and the value is lower than the CAPEXPRY attribute of the cluster queue or topic.