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])

Syntax Element	Description
object1	Queue (MSMQQueue) object that represents queue where the message resides.
object2	Message (MSMQMessage) object that represents the message retrieved from the queue.
pTransaction	Optional. An MSMQTransaction object or one of the following constants: MQ_NO_TRANSACTION: Specifies that the call is not part of a transaction. MQ_MTS_TRANSACTION: Default. Specifies that the call is part of the current MTS (Microsoft Transaction Server) transaction. MQ_XA_TRANSACTION: Specifies that the call is part of an externally coordinated, XA-compliant transaction.
WantDestinationQueue	Optional (default is FALSE). If TRUE, DestinationQueueInfo is updated when the message is read from the queue. Setting this property to TRUE may slow down the operation of the application.
WantBody	Optional (default is TRUE). If the Body of the message is not needed, set this property to FALSE to optimize the speed of the application.
ReceiveTimeout	Optional (default is INFINITE). Sets the message's timeout timer. Specifies how long (in milliseconds) MSMQ waits for a message to arrive.

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) forces 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:

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, and 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, 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

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.