MSMQQueueInfo.PathName

 

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

Required. The PathName property of the MSMQQueueInfo object specifies the name of the computer where the queue's messages are stored, whether the queue is public or private, and the name of the queue.

Data type:	String
Run-time access:	Read/write

Property PathName As String  

Property Value

A String containing the complete Message Queuing path name of the queue.

Remarks

The PathName property is the only property required when calling the MSMQQueueInfo.Create method. For information on how Message Queuing creates queues, see Creating Message Queues.

When setting this property, you can use specify the UNC or DNS path name for the queue. For information on queue path names, see Queue Path Names.

Resetting the MSMQQueueInfo.PathName property causes the MSMQQueueInfo object to reference the queue specified by the new path name and its properties. The path name of a queue cannot be changed after the queue is created.

The set of valid characters for the queue path name varies, depending on the version of Message Queuing that is creating the queue. The following table lists the characters that cannot be used.

Message Queuing version	Invalid queue name characters
MSMQ 1.0	\ (backslash) ; (semicolon) CR (ASCII 13); private queues only LF (ASCII 10); private queues only
MSMQ 2.0 and later	\ (backslash) ; (semicolon) CR (ASCII 13) LF (ASCII 10) + (plus) , (comma) " (double quotation mark)

The path name of a queue includes the name of the computer where the messages for the queue are stored, an optional PRIVATE$ keyword indicating that the queue is private, followed by the name of the queue.

The name of the queue is case insensitive (for example, "MyQueue" and "myQueue" are treated as the same name).

When specifying the name of the computer in the path name, use its NetBIOS or full DNS name. The maximum length allowed for the computer name in the address specification is 256 Unicode characters. Also, queue names longer than 124 Unicode characters are not supported. Using names longer than 64 Unicode characters for public queue names may cause a slight reduction in performance. Furthermore, they are not easily displayed in the directory service.

Here are three examples of Message Queuing path names. The first two examples indicate two public queues (one on a local computer and the other on a remote computer), and the third example indicates a private queue.

"myComputer\myPublicQueue"  
"otherComputer\otherPublicQueue"  
"myComputer\Private$\myPrivateQueue"  

As a shortcut, you can substitute a period "." for the local computer. So myPublicQueue and myPrivateQueue could be specified on the local computer as:

".\myPublicQueue"  
".\Private$\myPrivateQueue"  

Public queues are available to other applications and are registered in the directory service.

Private queues cannot be created from a remote computer. They are created and registered only on the local computer, and it is the application's responsibility to ensure that all queue names on the local computer are unique. If a private queue name already exists when MSMQQueueInfo.Create is called, Message Queuing generates an MQ_ERROR_QUEUE_EXISTS (0xC00E0005) error.

If the MSMQQueueInfo.PathName property is set for a local private queue or any public queue, the queue can be opened by calling the MSMQQueueInfo.Refresh method and then the MSMQQueueInfo.Open method. However, the MSMQQueueInfo.FormatName property must be set with a direct format name to open a remote private queue. Setting the PathName property of any public queue or a local private queue before calling the Open method is more expensive than setting the FormatName property because Message Queuing must retrieve information stored in the directory service or on the local computer to generate a format name from the path name. In addition, computers operating in offline mode cannot access the directory service and obtain the information needed to generate the format name of a public queue, and computers that do not belong to a domain can only generate the format name of a local private queue.

For information about public and private queues, see Destination Queues. Both types of queues exist until deleted explicitly.

Foreign public queues (queues located outside the enterprise) are created in the same way as a Message Queuing public queue. For foreign queues, the PathName property specifies the name of the foreign computer as it is defined in the directory service. For information on foreign computers, see Connector Services.

To access a queue within a cluster, use the virtual server or node in place of the name of the computer. Note that Message Queuing runs on the node independently from any virtual servers that are currently running on the node.

Message Queuing COM components ignore any characters that follow the first Null character in a string without returning an error.

To specify the path name when creating the queue, set the PathName property and call the MSMQQueueInfo.Create method.

To retrieve the stored path name of a queue, call the MSMQQueueInfo.Refresh method and then inspect the PathName property.

Equivalent API Function Property

With function calls, the equivalent property is PROPID_Q_PATHNAME.

Exam3ple Code

The following examples are included in Using Message Queuing.

For an example of	See
Specifying the path name when creating a queue	C/C++ COM Code Example: Creating a Queue  C/C++ COM Code Example: Creating a Transactional Queue  Visual Basic Code Example: Creating a Queue  Visual Basic Code Example: Creating a Transactional Queue
Retrieving the path name of an existing queue	Visual Basic Code Example: Retrieving MSMQQueueInfo.PathName

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.

See Also

MSMQQueueInfo
MSMQQueueInfo.Create
MSMQQueueInfo.FormatName
MSMQQueueInfo.Open
MSMQQueueInfo.Refresh
PROPID_Q_PATHNAME