Windows Dev Center

MQMgmtAction

(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.

See Also

Show:
© 2015 Microsoft