Ack
MSMQMessage

The Ack property specifies the type of acknowledgment messages that MSMQ posts (in the administration queue) and when acknowledgments are returned to the sending application.

Type:	Long
Run time:	read/write

Syntax

object.Ack

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

Settings

The Ack property can have any one of the following values:

MQMSG_ACKNOWLEDGMENT_FULL_REACH_QUEUE: Posts positive and negative acknowledgments depending on whether the message reaches the queue. This can happen when the time-to-reach-queue timer expires, or when a message cannot be authenticated.
MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE: Posts a positive or negative acknowledgment depending on whether the message is retrieved from the queue before its time-to-be-received timer expires.
MQMSG_ACKNOWLEDGMENT_NACK_REACH_QUEUE: Posts a negative acknowledgment when the message cannot reach the queue. This can happen when the time-to-reach-queue timer expires or when a message cannot be authenticated
MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE: Posts a negative acknowledgment when an error occurs and the message cannot be retrieved from the queue before its time-to-be-received timer expires.
MQMSG_ACKNOWLEDGMENT_NONE: The default. No acknowledgment messages (positive or negative) are posted.

Remarks

To receive a positive acknowledgment message when a message reaches its destination and when the message is retrieved, the following two full-acknowledgment settings must be combined using the OR operator: MQMSG_FULL_REACH_QUEUE and MQMSG_FULL_RECEIVE.

Positive and negative acknowledgments are MSMQ-generated messages that are sent to an administration queue specified by the message. For an explanation of administration queues, see Administration Queues.

Acknowledgment messages contain some of the information found in the original message; however, each acknowledgment message has its own message identifier and class. The message identifier, Id, identifies the acknowledgment in the same way it identifies each message sent by an MSMQ application. The message class, Class, identifies the type of acknowledgment posted. Both these properties are set by MSMQ when it creates the acknowledgment message.

To indicate that acknowledgment messages are needed, set Ack and AdminQueueInfo when sending the message.

The receiving application can determine if MSMQ is sending acknowledgments back to the sending application by examining Ack and AdminQueueInfo when reading the message in the queue.

For information on the time-to-reach-queue and time-to-be-received timer, see Message Timers. To set the time-to-reach-queue and time-to-be-received timers, set MaxTimeToReachQueue and MaxTimeToReceive properties, respectively.

For a example using acknowledgment messages, see Sending Messages that Request Acknowledgments.

Example

This example uses an administration queue to see if a message reaches its destination queue. It sends a message and then reads the acknowledgment message (returned by MSMQ) to see if the original message reached its destination. The destination and administration queues are created if they don't exist.

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 query As New MSMQQuery
Dim qinfos As MSMQQueueInfos
Dim qinfoAdmin As MSMQQueueInfo
Dim qinfoDest As MSMQQueueInfo
Dim q As MSMQQueue
Dim msgSent As New MSMQMessage
Dim msgAdmin As MSMQMessage

Private Sub Form_Click()
   '**********************************
   ' Locate administration queue
   '(create one if one doesn't exist).
   '**********************************
   Set qinfos = query.LookupQueue(Label:="Administration Queue")
   qinfos.Reset
   Set qinfoAdmin = qinfos.Next
   If qinfoAdmin Is Nothing Then
      Set qinfoAdmin = New MSMQQueueInfo
      qinfoAdmin.PathName = ".\AdminQueue"
      qinfoAdmin.Label = "Administration Queue"
      qinfoAdmin.Create
   End If
         
   '**********************************
   ' 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 q = qinfoDest.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
   
   '**************
   ' Send Message.
   '**************
   msgSent.Label = "Test Message"
   msgSent.Body = "This message tests acknowledgment messages."
   msgSent.Ack = MQMSG_ACKNOWLEDGMENT_FULL_REACH_QUEUE
   Set msgSent.AdminQueueInfo = qinfoAdmin
   msgSent.Send q
  
   MsgBox "The message was sent. Check the MSMQ Explorer to 
           see the messages in the queue."
   q.Close
  
   '********************************
   ' Read Acknowledgment message in the
   ' administration queue.
   '********************************
   Set q = qinfoAdmin.Open(MQ_RECEIVE_ACCESS, MQ_DENY_NONE)
   Set msgAdmin = q.Receive
   
   If msgAdmin.Class = MQMSG_CLASS_ACK_REACH_QUEUE Then
      MsgBox "The message reached the queue."
   Else
      MsgBox " The message did not reach the queue."
   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.