MSMQQueue.Purge
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
(Introduced in MSMQ 3.0.) The Purge method of the MSMQQueue object deletes all the messages in the queue.
Sub Purge
()
Parameters
This method has no parameters.
Return Values
This method has no return values.
Error Codes
For information on return codes, see Message Queuing Error and Information Codes.
Remarks
Applications can purge messages from a queue opened with receive access (with the Access argument of MSMQQueueInfo.Open set to MQ_RECEIVE_ACCESS).
To purge messages from a local outgoing queue, the corresponding remote destination queue must be opened with administrative access in addition to receive access. Specifically, the MSMQQueue object must be created by calling MSMQQueueInfo.Open with the Access argument set to MQ_RECEIVE_ACCESS | MQ_ADMIN_ACCESS. Local administrative permissions are also needed to purge messages from an outgoing queue.
Note
Messages sent to destination queues to which they cannot be delivered (for example, because the network is unavailable) will remain in the applicable outgoing queue until their time-to-reach-queue timer expires. To reduce the need to use this function to purge messages from outgoing queues, set the time-to-reach-queue property of the messages to a short time interval.
Calling this method is much more efficient then retrieving the messages in a queue using any of the Receive methods. Because purged messages will not be delivered (in the case of outgoing queues) or received (in the case of destination queues), Message Queuing may also return negative acknowledgment messages or place the purged messages in the appropriate dead-letter queue.
If the MSMQMessage.Ack property of a purged message is set to MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE or MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE (the sending application requested acknowledgments), a negative acknowledgment message will be returned to the administration queue specified by the sending application. The MSMQMessage.Class property of each such acknowledgment message will be set to MQMSG_CLASS_NACK_PURGED for a message purged from an outgoing queue or to MQMSG_CLASS_NACK_Q_PURGED for a message purged from a destination queue.
For information on requesting acknowledgment messages, see Acknowledgment Messages.
If the MSMQMessage.Journal property of a purged message is set to MQMSG_DEADLETTER (the sending application requested negative source journaling), the message will be placed in the respective local dead-letter queue with its MSMQMessage.Class property set to MQMSG_CLASS_NACK_Q_PURGED.
Note
For transactional messages in outgoing queues, Message Queuing can process the message in one of two ways. If MSMQ 1.0 semantics are required, Message Queuing will place all purged transactional messages in the local transactional dead-letter queue. If MSMQ 2.0 or later semantics are required, Message Queuing will place only those transactional messages that requested negative source journaling in the local transactional dead-letter queue.
For information on requesting negative source journaling, see Source Journaling.
When you purge recoverable messages or other messages that are stored on disk from a queue, you will not see immediate changes in the size of the memory-mapped files that store these message on the local computer. By default, these files are cleaned up only every six hours, and only message storage files that have no messages in them are deleted. For more information on message storage files, see Storage Folder Files.
In C++ COM applications, you must use a smart pointer to the IMSMQQueue3 interface to expose the Purge method.
Equivalent API Function
When using API function calls, use MQPurgeQueue to purge the messages in a queue.
Requirements
Windows NT/2000/XP: Included in Windows XP and Windows Server 2003.
Windows 95/98/Me: Unsupported.
Header: Declared in Mqoai.h.
Library: Use Mqoa.lib.