How To Purge an MSMQ Queue Using Visual Basic (242475)

SUMMARY

As of Windows NT Service Pack 4, a set of Microsoft Message Queue (MSMQ) API functions collectively known as the "Local Admin API" have been exposed in the MSMQ Runtime DLL. One of these API calls, MQPurge, provides the functionality to programmatically purge a Queue of all messages.

WARNING: ANY USE OF THE API CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this information "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.

Microsoft does not provide technical support for these APIs for the following reasons:

These are untested API's and therefore may not work as expected in some circumstances.
These API's may not exist in future releases or their functionality may change in future releases.
These are undocumented API's. They are being documented in the Knowledge Base for use at your own risk.

MORE INFORMATION

The MQPurge API function resides in the MSMQ Runtime DLL "Mqrt.dll" and had the following prototype:

HRESULT MQPurgeQueue( HANDLE hQueue );

Since it is exposed in Mqrt.dll, it may be accessed from Visual Basic by using a declare statement:

Declare Function MQPurgeQueue Lib "mqrt.dll" (ByVal hQueue As Long) As Long

To purge a queue from Visual Basic:

Start a new Visual Basic Standard EXE project.
Reference the MSMQ ActiveX components in the project:
1. From the Project menu, select References.
2. Select the Microsoft Message Queue Object Library checkbox.
3. Click OK.
Add a Textbox ("Text1") and a Command Button ("Command1") to the default form.

Paste the following code into the code window for the form:

Option Explicit

Private Declare Function MQPurgeQueue Lib "mqrt.dll" (ByVal hQueue As Long) As Long

Private Const MQ_OK = 0

Private Sub Command1_Click()
On Error GoTo ERRORHANDLER:
    Dim QInfo As MSMQQueueInfo
    Dim Queue As MSMQQueue
    
    Set QInfo = New MSMQQueueInfo
    QInfo.PathName = Text1.Text
    
    Set Queue = QInfo.Open(MQ_RECEIVE_ACCESS, MQ_DENY_NONE)
    
    If Queue Is Nothing Then
        MsgBox "Couldn't open queue."
        Exit Sub
    End If
        
    Dim result As Long
    
    result = MQPurgeQueue(Queue.Handle)
    
    ' You should check the result for errors here
    If result <> MQ_OK Then
        MsgBox "An error occurred in MQPurgeQueue.  Error number:" & result
    End If
    
    Queue.Close
    
    Set Queue = Nothing
    Set QInfo = Nothing
    
    Exit Sub
ERRORHANDLER:
    MsgBox "There was an error " _
           & Err.Number & " " & Err.Description
End Sub

Run the application. In the textbox enter the pathname of the queue you want to purge and click the command button. For example:
- If you want to clear a local queue named "MyLocal" on your computer, enter the string .\MyLocal in the textbox and click the command button.
- If you want to purge a queue named "MyOtherQueue" on a computer named "OtherMachine", you would enter OtherMachine\MyOtherQueue in the textbox and click the command button.