MDEXP (10-digit signed integer)

Message lifetime.

This is a period of time expressed in tenths of a second, set by the application that puts the message. The message becomes eligible to be discarded if it has not been removed from the destination queue before this period of time elapses.

The value is decremented to reflect the time the message spends on the destination queue, and also on any intermediate transmission queues if the put is to a remote queue. It may also be decremented by message channel agents to reflect transmission times, if these are significant. Likewise, an application forwarding this message to another queue might decrement the value if necessary, if it has retained the message for a significant time. However, the expiration time is treated as approximate, and the value need not be decremented to reflect small time intervals.

When the message is retrieved by an application using the MQGET call, the MDEXP field represents the amount of the original expiry time that still remains.

After a message's expiry time has elapsed, it becomes eligible to be discarded by the queue manager. In the current implementations, the message is discarded when a browse or nonbrowse MQGET call occurs that would have returned the message had it not already expired. For example, a nonbrowse MQGET call with the GMMO field in MQGMO set to MONONE reading from a FIFO ordered queue will cause all the expired messages to be discarded up to the first unexpired message. With a priority ordered queue, the same call will discard expired messages of higher priority and messages of an equal priority that arrived on the queue before the first unexpired message.

A message that has expired is never returned to an application (either by a browse or a non-browse MQGET call), so the value in the MDEXP field of the message descriptor after a successful MQGET call is either greater than zero, or the special value EIULIM.

If a message is put on a remote queue, the message may expire (and be discarded) whilst it is on an intermediate transmission queue, before the message reaches the destination queue.

A report is generated when an expired message is discarded, if the message specified one of the ROEXP* report options. If none of these options is specified, no such report is generated; the message is assumed to be no longer relevant after this time period (perhaps because a later message has superseded it).

Any other program that discards messages based on expiry time must also send an appropriate report message if one was requested.

Notes:

  1. If a message is put with an MDEXP time of zero, the MQPUT or MQPUT1 call fails with reason code RC2013; no report message is generated in this case.

  2. Since a message whose expiry time has elapsed may not actually be discarded until later, there may be messages on a queue that have passed their expiry time, and which are not therefore eligible for retrieval. These messages nevertheless count towards the number of messages on the queue for all purposes, including depth triggering.

  3. An expiration report is generated, if requested, when the message is actually discarded, not when it becomes eligible for discarding.

  4. Discarding of an expired message, and the generation of an expiration report if requested, are never part of the application's unit of work, even if the message was scheduled for discarding as a result of an MQGET call operating within a unit of work.

  5. If a nearly-expired message is retrieved by an MQGET call within a unit of work, and the unit of work is subsequently backed out, the message may become eligible to be discarded before it can be retrieved again.

  6. If a nearly-expired message is locked by an MQGET call with GMLK, the message may become eligible to be discarded before it can be retrieved by an MQGET call with GMMUC; reason code RC2034 is returned on this subsequent MQGET call if that happens.

  7. When a request message with an expiry time greater than zero is retrieved, the application can take one of the following actions when it sends the reply message:

    • Copy the remaining expiry time from the request message to the reply message.

    • Set the expiry time in the reply message to an explicit value greater than zero.

    • Set the expiry time in the reply message to EIULIM.

    The action to take depends on the design of the application suite. However, the default action for putting messages to a dead-letter (undelivered-message) queue should be to preserve the remaining expiry time of the message, and to continue to decrement it.

  8. Trigger messages are always generated with EIULIM.

  9. A message (normally on a transmission queue) which has a MDFMT name of FMXQH has a second message descriptor within the MQXQH. It therefore has two MDEXP fields associated with it. The following additional points should be noted in this case:

    • When an application puts a message on a remote queue, the queue manager places the message initially on a local transmission queue, and prefixes the application message data with an MQXQH structure. The queue manager sets the values of the two MDEXP fields to be the same as that specified by the application.

      If an application puts a message directly on a local transmission queue, the message data must already begin with an MQXQH structure, and the format name must be FMXQH (but the queue manager does not enforce this). In this case the application need not set the values of these two MDEXP fields to be the same. (The queue manager does not check that the MDEXP field within the MQXQH contains a valid value, or even that the message data is long enough to include it.)

    • When a message with a MDFMT name of FMXQH is retrieved from a queue (whether this is a normal or a transmission queue), the queue manager decrements both these MDEXP fields with the time spent waiting on the queue. No error is raised if the message data is not long enough to include the MDEXP field in the MQXQH.

    • The queue manager uses the MDEXP field in the separate message descriptor (that is, not the one in the message descriptor embedded within the MQXQH structure) to test whether the message is eligible for discarding.

    • If the initial values of the two MDEXP fields were different, it is therefore possible for the MDEXP time in the separate message descriptor when the message is retrieved to be greater than zero (so the message is not eligible for discarding), while the time according to the MDEXP field in the MQXQH has elapsed. In this case the MDEXP field in the MQXQH is set to zero.

The following special value is recognized:

EIULIM

Unlimited lifetime.

The message has an unlimited expiration time.

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 EIULIM.