MaxTimeToReceive
MSMQMessage

The MaxTimeToReceive property specifies a time limit (in seconds) for the message to be retrieved from the target queue. This includes the time spent getting to the destination queue plus the time spent waiting in the queue before it is retrieved by an application.

Type:	Long
Run time:	read/write

Syntax

object.MaxTimeToReceive

Syntax Element	Description
object	Message (MSMQMessage) object that defines the message.

Settings

Integer value (the default is INFINITE).

Remarks

MaxTimeToReceive sets the message's time-to-be-received timer. For a discussion of message timers, see Message Timers. If the time-to-be-received timer expires before the message is removed from the queue, 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 negative acknowledgment message back to the sending application if the message's Ack property is set accordingly and the message is not retrieved before the timer expires.

Once a message arrives at the queue, MaxTimeToReceive can be used to find out how much time remains in the time-to-be-received timer.

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.

MSMQ automatically uses the time-to-be-received 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-be-received timer to INFINITE.

When a message is sent from an independent client computer, the time-to-be-received timer starts ticking as soon as the send operation succeeds, even if the client computer is offline.

Example

This example first creates and opens a queue for sending messages, sets the time-to-be-received 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 MaxTimeToReceive."
  msgSent.MaxTimeToReceive = 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 "MaxTimeToReceive = " + CStr(msgReceived.MaxTimeToReceive)
 
End Sub

QuickInfo

  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.