Receive
MSMQQueue

The Receive method retrieves the first message in the queue, removing the message from the queue when the message is read.

Syntax

set object2 = object1.Receive ([pTransaction] [, WantDestinationQueue] [, WantBody] [, ReceiveTimeout])
 

Return Values

MSMQMessage object that represents the first message in the queue.

Remarks

To retrieve messages from the queue, the queue must be opened with receive access (Access = MQ_RECEIVE_ACCESS). Messages retrieved from a queue are also removed from the queue.

The ReceiveTimeout parameter is optional. However, if it is not specified the default value of ReceiveTimeout (INFINITE) will force the Receive call to block execution until a message arrives.

The pTransaction parameter can be set to an MSMQTransaction object, or one of the constants described above. For information on the different types of transactions that MSMQ supports, see:

• MSMQ Internal Transactions
  
  
• MS DTC External Transactions
  
  
• MTS Transactions
  
  
• XA-Compliant Transactions

The WantDestinationQueue and WantBody parameters can be used to optimize the speed of the application.

For synchronous calls, execution is stopped until a message is retrieved from the queue or the message's timeout timer expires. For an example of reading messages synchronously, see Reading Messages Synchronously.

For an example of reading messages asynchronously, see Reading Messages Asynchronously.

To read messages in a queue without removing them, see the Peek, PeekCurrent, or PeekNext.

Example

This example locates a destination queue, sends a message to the queue to make sure at least one message is in the queue, then removes all the messages from the queue. An error handler is added to trap any errors generated as a result of the Receive call.

To try this example using Microsoft® Visual Basic® (version 5.0), paste the code into the Code window of a form, and then run the example and click the form.

Option Explicit
Dim query As New MSMQQuery
Dim qinfos As New MSMQQueueInfos
Dim qinfoDest As MSMQQueueInfo
Dim qDest As MSMQQueue
Dim msgSent As New MSMQMessage
Dim msgDest As MSMQMessage

Private Sub Form_Click()
            
   '***************************
   ' Locate destination queue
   '(create one if one doesn't
   ' exist).
   '***************************
   Set qinfos = query.LookupQueue(Label:="Destination Queue")
   qinfos.Reset
   Set qinfoDest = qinfos.Next
   If qinfoDest Is Nothing Then
      Set qinfoDest = New MSMQQueueInfo
      qinfoDest.PathName = ".\DestQueue"
      qinfoDest.Label = "Destination Queue"
      qinfoDest.Create
   End If
   
   '**************
   ' Open destination queue.
   '**************
   Set qDest = qinfoDest.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
   
   '**************
   ' Send Message.
   '**************
   msgSent.Label = "Test Message A"
   msgSent.Body = "This message is for testing how messages are read from the queue."
   
   msgSent.Send qDest
   qDest.Close
  
   '**********************
   ' Removes all messages
   ' in the queue.
   '**********************
   
   Set qDest = qinfoDest.Open(MQ_RECEIVE_ACCESS, MQ_DENY_NONE)
  
   On Error GoTo Handler
   
   Do While True
      Set msgDest = qDest.Receive(ReceiveTimeout:=1000)
      If msgDest Is Nothing Then Exit Do
      MsgBox msgDest.Label + " is removed from the queue."
   Loop

   Exit Sub

   '***************
   ' Error Handler
   '***************
   
Handler:
   If (Err = MQ_ERROR_IO_TIMEOUT) Then
      MsgBox "All messages are removed from the queue."
      Exit Sub
   Else
      MsgBox "Unexpected error!"
   End If

End Sub
 

See Also

Body, Close, Create, Label, LookupQueue, MSMQMessage, MSMQQuery, MSMQQueue, MSMQQueueInfo, MSMQQueueInfos, Next, Open, PathName, Reset, Send

© 1997 by Microsoft Corporation. All rights reserved.