MSMQManagement.Init

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 Init method initializes an MSMQManagement object to represent the state of a specific active destination queue or outgoing queue. An application can use this object to obtain information that is common to both destination and outgoing queues. The Init method also implicitly creates and initializes an MSMQQueueManagement object for a destination queue or an MSMQOutgoingQueueManagement object for an outgoing queue. The application can use these objects to obtain information that is specific to destination queues and outgoing queues, respectfully.

Sub Init( _  
        [ ByRef Machine As VARIANT ], _  
        [ ByRef PathName As VARIANT ], _  
        [ ByRef FormatName As VARIANT ] _  
)

Parameters

Machine

[in, optional] String that contains the name of the computer where the queue resides (in C++, a reference to a VARIANT containing a BSTR that specifies the computer). If this parameter is omitted, the local computer is used.

PathName

[in, optional] String that contains the path name of the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the path name). If this parameter is omitted the FormatName parameter is required.

FormatName

[in, optional] String that contains the format name of the queue (in C++, a reference to a VARIANT containing a BSTR that specifies the format name). If this parameter is omitted, the PathName parameter is required.

Return Values

This method has no return values.

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

This method uses the computer name and the path name or format name (whichever is provided) to determine if the queue is an outgoing queue or a destination queue. (When sending messages, Message Queuing creates an outgoing queue for each remote destination queue.) The illustration below shows an outgoing queue (Q1) on computer M1 and its associated destination queue (Q2) on computer M2. Although the format name for both queues is the same, the Init method uses the Machine parameter to determine if the queue needed is the outgoing queue or its associated destination queue. If the Machine parameter is set to the name of the computer where the destination queue resides, the objects initialized will represent the destination queue. However, if the Machine parameter is set to the name of any other computer, the objects initialized will represent the corresponding outgoing queue on that computer. For example, if the Machine parameter is set to the name of the local computer (M1) and the FormatName parameter is set to the format name of a queue on another computer (M2), the Init method initializes the MSMQManagement object for the outgoing queue on the local computer with the format name specified in the FormatName parameter and implicitly creates and initializes an MSMQOutgoingQueueManagement object for it.

Note

The FormatName parameter can be used to reference any destination queue or outgoing queue on the local computer or a remote computer, but the PathName parameter cannot be used to reference a remote private queue or an outgoing queue corresponding to a remote private queue. If both the path name and the format name are specified, the call fails with an MQ_ERROR_INVALID_PARAMETER (0xC00E0006) error.

The Init method can only be used to initialize the MSMQManagement object to represent the state of an active queue. An exception is thrown and a nonspecific MQ_ERROR (0xC00E0001) error is generated if the destination or outgoing queue specified does not contain any messages and no handle to it exists.

Example Code

The following code fragments show how to reference an outgoing queue (Q1) and a destination queue (Q2), where M1, M2, Q1, and Q2 are indicated in the previous illustration.

' Initializing an MSMQManagement object for an outgoing queue (Q1).  
Dim qmgmt As New MSMQManagement  
Dim outqmgmt As MSMQOutgoingQueueManagement  
qmgmt.Init Machine:="M1", FormatName:="Direct=OS:M2\Q2"  
Set outqmgmt = qmgmt  
  
' Initializing an MSMQManagement object for a destination queue (Q2).  
Dim qmgmt As New MSMQManagement  
Dim destqmgmt As MSMQQueueManagement  
qmgmt.Init FormatName:="Direct=OS:M2\Q2", Machine:="M2"  
Set destqmgmt = qmgmt

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