PROPID_M_TIME_TO_REACH_QUEUE

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The PROPID_M_TIME_TO_REACH_QUEUE property specifies a time limit (in seconds) for the message to reach the queue.

Property ID

PROPID_M_TIME_TO_REACH_QUEUE

Type Indicator

VT_UI4

MQPROPVARIANT Field

ulVal

Property Value

Integer value (the default is the enterprise-wide setting for the time-to-reach-queue interval).

Remarks

PROPID_M_TIME_TO_REACH_QUEUE is used to set the time-to-reach-queue timer for the message. If the time-to-reach-queue interval elapses before the message reaches its destination, Message Queuing discards the message, sending it to the dead-letter queue if the PROPID_M_JOURNAL property of the message is set to MQMSG_DEADLETTER.

Message Queuing can also send a return negative acknowledgment message back to the sending application if the message does not arrive and the PROPID_M_ACKNOWLEDGE property of the message is set accordingly.

To set the time interval for the time-to-reach-queue timer, specify PROPID_M_TIME_TO_REACH_QUEUE in the MQMSGPROPS structure and call MQSendMessage.

If this property is not set or if this property is set to LONG_LIVED or INFINITE, Message Queuing uses the enterprise-wide setting for the time-to-reach-queue interval.

This enterprise-wide setting can be adjusted by the Message Queuing administrator. By default, this setting equals 4 days for messages sent from the following types of computers:

Computers running MSMQ 3.0 in workgroup mode.
Clients running MSMQ 3.0 that belong to a completely new Windows domain.
Clients running MSMQ 3.0 that join an existing domain provided weakened security was not enabled for that forest.

In each hop, Message Queuing subtracts the time elapsed from the value of PROPID_M_TIME_TO_REACH_QUEUE when it dispatches the message to the next computer, where a new timer is set. To find out how much time remains in the time-to-reach-queue timer when the message is received, specify PROPID_M_TIME_TO_REACH_QUEUE in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned value. A value of 0 indicates that the specified interval has elapsed.

If the time-to-be-received and time-to-reach-queue timers are both set, the time-to-be-received timer takes precedence over the time-to-reach-queue timer.

No matter what value PROPID_M_TIME_TO_REACH_QUEUE is set to (even if it is set to 0), Message Queuing always gives each message one chance to reach its destination if all the computers on the way and the queue are in a ready state. If the queue is local, the message always reaches the queue.

When several messages are sent in a transaction, Message Queuing uses only the time-to-reach-queue timer of the first message. For information on transactions, see Transactions.

When Message Queuing creates an acknowledgment message, it always sets the PROPID_M_TIME_TO_REACH_QUEUE property of the message 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 of the sending application succeeds, even if the client computer is currently offline.

Equivalent COM Property

With COM components, the equivalent property for setting the time-to-reach-queue timer and retrieving the remaining time is MSMQMessage.MaxTimeToReachQueue.

For information on	See
Message timers	Message Timers
Transactions	Transactions

Example Code

The following code fragments show how PROPID_M_TIME_TO_REACH_QUEUE is specified in arrays that can be used to initialize an MQMSGPROPS structure for setting the time-to-reach-queue timer and for retrieving the remaining time.

Note

The timer is set to expire in two minutes.

To Set PROPID_M_TIME_TO_REACH_QUEUE

aMsgPropId[i] = PROPID_M_TIME_TO_REACH_QUEUE;  
aMsgPropVar[i].vt = VT_UI4;   
aMsgPropVar[i].ulVal = 60*2;  
i++;

To Retrieve PROPID_M_TIME_TO_REACH_QUEUE

aMsgPropId[i] = PROPID_M_TIME_TO_REACH_QUEUE;  
aMsgPropVar[i].vt = VT_UI4;   
i++;

PROPID_M_TIME_TO_REACH_QUEUE

Property Value

Remarks

Example Code

See Also

Additional resources