MSMQQueueInfo.FormatName
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
The FormatName property of the MSMQQueueInfo object specifies the format name of the queue. This property is used by Message Queuing to open the queue.
| Data type: | String |
| Run-time access: | Read/write |
Property FormatName As String
Property Value
A String specifying the format name of the queue. Possible strings are:
PUBLIC=QueueGUID
DIRECT=Protocol:ComputerAddress\QueueName
DIRECT=OS:ComputerName\private$\QueueName
PRIVATE=ComputerGUID\QueueNumber
Remarks
The FormatName property must be specified or retrieved from the system to open the queue. Message Queuing uses the format name of the queue to identify which queue to open and how to access the opened queue.
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.Open method. However, the FormatName property must be set with a direct format name to open a remote private queue.
Setting the FormatName property of a public queue instead of the PathName property before calling the Open method frees Message Queuing from the need to retrieve information stored in the directory service to generate a format name from the path name of any public queue. Computers operating in offline mode cannot access the directory service and obtain the information needed to generate the format name of a public queue. Computers that belong to a workgroup can only generate the format name of a local private queue.
When creating a queue, if a format name is not provided by the application, Message Queuing generates a format name based on the path name of the queue (MSMQQueueInfo.PathName), which must be provided. After the queue is created, you can use the format name generated by Message Queuing or specify a different one. For example, to open the journal of the queue, modify the format name of the destination queue and then use the MSMQQueueInfo object to open the journal.
When creating a queue in domain mode, Message Queuing stores the public format name for a public queue or the private format name for a local private queue in this property, whereas in offline or workgroup mode, Message Queuing can store only the direct format name for a local private queue in this property.
The format name of a queue cannot be changed while the queue is open. For information on how Message Queuing uses format names to reference queues and the different types of format names, see Direct Format Names.
To send messages directly to and read messages directly from a queue without querying the directory service, as in workgroup mode, the FormatName property must contain a direct format name (as shown below). For information on direct format names see Direct Format Names.
DIRECT=AddressSpecification\QueueName (For public queues.)
DIRECT=AddressSpecification\PRIVATE$\QueueName (For private queues.)
DIRECT=AddressSpecification\SYSTEM$;computersystemqueue (Introduced in MSMQ 2.0)
DIRECT=HTTP://URLAddressSpecification/msmq/QueueName (Introduced in MSMQ 3.0)
DIRECT=HTTPS://URLAddressSpecification/msmq/QueueName (Introduced in MSMQ 3.0)
When this property is set to a direct format 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.
To specify the format name when opening a queue, set the FormatName property and call the MSMQQueueInfo.Open method.
To retrieve the stored format name of a queue represented by a query-generated MSMQQueueInfo object, call the MSMQQueueInfo.Refresh method and inspect the FormatName property. For public queues, this information is stored in the directory service. Thus, the stored format name of a public queue cannot be retrieved by a computer operating in workgroup or offline mode. For private queues, this information is stored on the computer where the messages of the queue are stored.
To retrieve the stored format name of a local private queue or any public queue, initialize an MSMQQueueInfo object by setting its MSMQQueueInfo.PathName property and then retrieve the FormatName property.
Message Queuing COM components ignore any characters that follow the first Null character in a string without returning an error.
Equivalent API Function Property
There is no equivalent API function property for the format name of a queue. When using API function calls, the format name of the queue is specified as a parameter of the MQOpenQueue function call.
Example Code
The following examples are included in Using Message Queuing.
| For an example of | See |
|---|---|
| Retrieving the format name of a queue specified by its path name | Visual Basic Code Example: Retrieving MSMQQueueInfo.FormatName |
| Modifying the format name to read messages from the computer journal | Visual Basic Code Example: Reading Messages in the Computer Journal |
| Modifying the format name to read messages from a dead-letter queue | Visual Basic Code Example: Reading Messages in the Dead-Letter Queue |
| Modifying the format name to read messages from a transactional dead-letter queue | Visual Basic Code Example: Reading Messages in the Transactional Dead-Letter Queue |
| Modifying the format name to read messages from a queue journal | Visual Basic Code Example: Reading Messages in a Queue Journal |
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
MQOpenQueue
MSMQQueueInfo
MSMQQueueInfo.Open
MSMQQueueInfo.PathName
MSMQQueueInfo.Refresh