The MaxTimeToReachQueue property specifies a time limit (in seconds) for the message to reach the queue.
| Type: | Long |
| Run time: | read/write |
object.MaxTimeToReachQueue
| Syntax Element | Description |
|---|---|
| object | Message (MSMQMessage) object that represents the message. |
Integer value (the default is LONG_LIVED).
MaxTimeToReachQueue sets the message's time-to-reach-queue timer. For a discussion of message timers, see Message Timers. If the time-to-reach-queue timer expires before the message reaches its destination, MSMQ discards the message, sending it to the dead letter queue if the message's Journal property is set to MQMSG_DEADLETTER.
MSMQ can also send a return negative acknowledgment message back to the sending application if the message does not arrive and the message's Ack property is set accordingly.
The default value LONG_LIVED is an enterprise-wide setting that can be adjusted by the MSMQ Administrator. Typically, LONG_LIVED is set to 90 days. Although this timer can be set to INFINITE, MSMQ automatically uses the LONG_LIVED value in its place.
Once a message arrives at the queue, MaxTimeToReachQueue can be used to find out how much time remains in the time-to-reach-queue timer. A value of 0 indicates the timer has expired.
MSMQ uses two message timers: time-to-reach-queue and time-to-be-received. If the time-to-be-received timer is set to a value less than the time-to-reach-queue timer, the time-to-be-received timer takes precedence over the time-to-reach-queue timer.
No matter what value MaxTimeToReachQueue is set to (even if set to 0), MSMQ always gives each message one chance to reach its destination if the queue is waiting for the message. If the queue is local, the message always reaches the queue.
MSMQ automatically uses the time-to-reach-queue timer of the first message when several messages are sent in a transaction. For information on transactions, see MSMQ Transactions.
When MSMQ creates an acknowledgment message, it always sets the message's time-to-reach-queue timer to LONG_LIVED.
When a message is sent from an independent client computer, the time-to-reach-queue timer starts ticking as soon as the send operation succeeds, even if the client computer is offline.
This example first creates and opens a queue for sending messages, sets the time-to-reach-queue timer for a message and sends it off to the queue, and then reads the message in the queue and displays the time remaining in the timer.
To try this example using Microsoft Visual Basic (version 5.0), paste the code into the Code window of a form, run the example, and click the form.
Dim qinfo As MSMQQueueInfo
Dim q As MSMQQueue
Dim msgSent As New MSMQMessage
Dim msgReceived As MSMQMessage
Private Sub Form_Click()
'***************************
' Create queue (no error
' handling if queue exists).
'***************************
Set qinfo = New MSMQQueueInfo
qinfo.PathName = ".\TimerTest"
qinfo.Label = "Test Queue"
qinfo.Create
'**************
' Open queue.
'**************
Set q = qinfo.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
'**************
' Send Message.
'**************
msgSent.Label = "Test Message"
msgSent.Body = "This message tests MaxTimeToReachQueue."
msgSent.MaxTimeToReachQueue = 120
msgSent.Send q
MsgBox "The message was sent. Check the MSMQ Explorer to see the messages in the queue."
q.Close
MsgBox "Click OK to continue"
'**************
' Read Message.
'**************
Set q = qinfo.Open(MQ_PEEK_ACCESS, MQ_DENY_NONE)
Set msgReceived = q.Peek
MsgBox "MaxTimeToReachQueue = " + CStr(msgReceived.MaxTimeToReachQueue)
End Sub
Windows NT: Requires version 4.0 SP3 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in mqoai.h.
Import Library: Use mqoa.lib.
Unicode: Defined only as Unicode.
Body, Close, Create, Label, MSMQMessage, MSMQQueueInfo, MSMQQueue, Open, PathName, Send