MQMgmtAction
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 MQMgmtAction function changes the state of a computer or a queue.
HRESULT MQMgmtAction(
LPCWSTR pMachineName,
LPCWSTR pObjectName,
LPCWSTR pAction
);
Parameters
pMachineName
[in] Pointer to a Unicode string that contains the name of the computer where the action will take place. The local computer can be specified by setting this parameter to NULL.
pObjectName
[in] Pointer to a Unicode string that describes the type of object that will be worked on. Possible strings are:
L"MACHINE" (MO_MACHINE_TOKEN)
Required to act upon the queue manager on the computer.
L"QUEUE=<formatname>"
Required to act upon a specific queue on the computer.
pAction
[in] Pointer to a Unicode string that indicates the action to be performed on the computer.
L"CONNECT" (MACHINE_ACTION_CONNECT)
Connects the computer to the network and to the directory service.
L"DISCONNECT" (MACHINE_ACTION_DISCONNECT)
Disconnects the computer from the network and from the directory service.
L"TIDY" (MACHINE_ACTION_TIDY)
Cleans up empty message files (Message Queuing cleans up empty message files every six hours). This is helpful when a large number of messages are deleted (purged or received by an application) and the application needs the disk space available at once.
L"PAUSE" (QUEUE_ACTION_PAUSE)
Valid for outgoing queues only. Stops the sending of messages from the computer. The queue manager will not send messages to the applicable destination queue until a RESUME action is initiated.
L"RESUME" (QUEUE_ACTION_RESUME)
Valid for outgoing queues only. Restarts the sending of messages after a PAUSE action has been initiated.
L"EOD_RESEND" (QUEUE_ACTION_EOD_RESEND)
Resends the pending transaction sequence.
Return Values
MQ_OK
Indicates success.
MQ_ERROR_ACCESS_DENIED (0xC00E0025)
The access rights for performing management actions on the queue or computer are not allowed for the calling process.
MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)
The specified format name in pObjectName is illegal.
MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)
The Message Queuing service is not available.
Remarks
You can call MQMgmtAction with pAction = L"PAUSE" 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 change the state of a computer or a queue using MQMgmtAction.
The functionality of the local administration API functions introduced in MSMQ 3.0 (MQMgmtAction, MQMgmtGetInfo, and MQPurgeQueue) is also available for computers running previous versions of Message Queuing. For more information, see MSMQ Local Admin API.
Equivalent COM Methods
When using COM components, you can change the connection state of a computer and clean up the empty message files on a computer by calling the MSMQApplication.Connect, MSMQApplication.Disconnect, and MSMQApplication.Tidy methods of the MSMQApplication object. You can also stop and resume sending messages from an outgoing queue and resend the pending transaction sequence by calling the MSMQOutgoingQueueManagement.Pause, MSMQOutgoingQueueManagement.Resume, and MSMQOutgoingQueueManagement.EodResend methods of the MSMQOutgoingQueueManagement object.
Requirements
Windows NT/2000/XP: Included in Windows XP and Windows Server 2003.
Windows 95/98/Me: Unsupported.
Header: Declared in Mq.h.
Library: Use Mqrt.lib.