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:
- 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.
- 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.
- An expiration report is generated, if requested, when the message is actually
discarded, not when it becomes eligible for discarding.
- 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.
- 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.
- 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.
- 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.
- Trigger messages are always generated with EIULIM.
- 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.