MSMQOutgoingQueueManagement.Pause

Article
10/19/2016

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 Pause method of the MSMQOutgoingQueueManagement object, which represents the state of an outgoing queue, stops the transmission of messages out of the outgoing queue.

Sub Pause
()

Parameters

This method has no parameters.

Return Values

This method has no return values.

Error Codes

This method generates one of the following error codes:

MQ_OK (0)

The method call was successful.

MQ_ERROR_QUEUE_NOT_ACTIVE (0xC00E0004)

The destination queue is not open or may not exist.

For a complete list of error and information codes, see Message Queuing Error and Information Codes.

Remarks

After this method is called, the queue manager will not start transmitting messages to the corresponding destination queue until the MSMQOutgoingQueueManagement.Resume method is called. The connection state (MSMQOutgoingQueueManagement.State) of the outgoing queue is then MQ_QUEUE_STATE_ONHOLD.

You can use the Pause method when you know that the corresponding destination queue is unavailable. This can reduce the unnecessary CPU and network load associated with repeated attempts to connect to the unavailable target.

Local administrative permissions are needed to pause the transmission of messages out of an outgoing queue.

Equivalent API Function

When using API functions, call MQMgmtAction and pass L"PAUSE" (QUEUE_ACTION_PAUSE) as the string indicating the action to be performed on the queue.

Example Code

The following code fragment shows how to pause an outgoing queue on a remote source computer, retrieve the number of messages in the queue, and resume the transmission of messages from it.

Dim mgmt As New MSMQManagement  
mgmt.Init Machine:="RemoteSource",  
          PathName:="Target\Q1"    ' Indicates outgoing queue on remote computer.  
Dim outqmgmt As MSMQOutgoingQueueManagement  
Set outqmgmt = mgmt  
  
outqmgmt.Pause  
MsgBox "There are " & mgmt.MessageCount & " messages in the outgoing queue."  
outqmgmt.Resume

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.