MSMQDestination.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
(Introduced in MSMQ 3.0.) The FormatName property of the MSMQDestination object, which can represent one or more queues, specifies a public format name, private format name, direct format name, distribution list format name, multicast address format name, multiple-element format name, or the format name of a queue alias (when a queue alias is specified in MSMQDestination.ADsPath) for sending messages.
Setting this property initializes the MSMQDestination object for sending messages.
| Data type: | String |
| Run-time access: | Read/write |
Property FormatName As String
Property Value
A String that contains a public format name, private format name, direct format name, distribution list format name, multicast address format name, multiple-element format name, or the format name of the queue alias specified in MSMQDestination.ADsPath.
Remarks
The FormatName property can be set by the sending application or by Message Queuing. The sending application must set this property when sending messages using multicast addresses or multiple-element format names. Message Queuing sets this property when the sending application specifies a distribution list, queue alias, or a single public queue using the MSMQDestination.ADsPath property.
Setting the FormatName property initializes the MSMQDestination object so that the object can be opened explicitly by calling MSMQDestination.Open or implicitly by referencing the object in MSMQMessage.Send and closes the object if it is open.
Setting the FormatName property also resets the MSMQDestination.ADsPath and MSMQDestination.PathName properties to zero-length strings.
When you use the FormatName property to send a message to a multiple-element format name, you create the multiple-element format name by concatenating any number of public format names, private format names, direct format names, multicast address format names, or distribution list format names.
Note
MSMQMessage.Send will return MQ_ERROR_INVALID_PARAMETER if you try to send a transactional message, with a MSMQMessage.Journal property of MQMSG_DEADLETTER (that is, with negative source journaling enabled), to a distribution list or multi-queue format name. To correct this, either send the message to a single queue at a time, or disable negative source journaling.
The FormatName property is a string, and Message Queuing COM components ignore any characters that follow the first Null character in a string without returning an error.
Example Code
The following code fragment shows how to specify a three-element format name in the FormatName property and send a message to the corresponding destination queues. The format name strings in this example may contain any public format name, private format name, direct format name, or distribution list format name.
Dim dest As New MSMQDestination
Dim msg As New MSMQMessage
dest.FormatName = strFormatName1 & "," & strFormatName2 & "," & strFormatName3
msg.Send DestinationQueue:=dest
The following examples are included in Using Message Queuing.
| For an Example of | See |
|---|---|
| Sending messages using a multicast address | Visual Basic Code Example: Sending Messages Using Multicast Addresses |
| Sending messages using a multiple-element format name | C/C++ COM Code Example: Sending Messages Using Multiple-Element Format Names Visual Basic Code Example: Sending Messages Using Multiple-Element Format Names |
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
See Also
MSMQDestination
MSMQDestination.ADsPath
MSMQDestination.FormatName
MSMQDestination.Open
MSMQDestination.PathName
MSMQMessage.Send