Format Name

Format names are used to specify a queue when making calls to several API functions.

Note For ActiveX applications, the MSMQQueueInfo object used to represent the created queue includes a FormatName property that is returned when the queue is created. The object's property can be used as it is, or it can be modified by the application.

The API function calls that require a format name include the following:

Unlike most of the characteristics of a queue, the format name is not an MSMQ queue property. It is simply a unique name for the queue that is generated by MSMQ when the queue is created or generated later by the application. MSMQ never stores the format name of a queue for later reference.

Format names can be obtained by any of the following methods.

Method	Details
When creating a queue.	MSMQ returns a format name when it creates a queue. ActiveX applications can obtain the queue's format name from the MSMQQueueInfo object used to create the queue.
When locating a queue.	The application can retrieve the queue's MSMQ pathname or queue identifier (GUID) and translate it into a format name for the queue. See MQPathNameToFormatName and MQInstanceToFormatName respectivley. ActiveX applications can obtain the queue's format name from the collection of MSMQQueueInfo objects referenced by the MSMQQueueInfos object returned by a query.
When the queue's handle is returned.	The application can translate the queue handle returned by MQOpenQueue to a format name using MQHandleToFormatName. ActiveX applications can obtain the queue's format name from the MSMQQueueInfo object's FormatName property.
When reading application-generated messages from a message queue.	The receiving application can retrieve the format name of the response queue and the format name of administration queue by retrieving the following message properties. The format name of the response queue is found in PROPID_M_RESP_QUEUE. The format name of the administration queue is found in PROPID_M_ADMIN_QUEUE.
When reading MSMQ-generated acknowledgment messages from an administration queue.	When reading the acknowledgment messages in the administration queue, the format name of the original message's destination queue can also be retrieved if PROPID_M_DEST_QUEUE was set by the sending application.

The data type holding the format name is a null-terminated Unicode string with one of the following general formats:

PUBLIC=QueueGUID                             *Public queues.
PUBLIC=QueueGUID;JOURNAL                     *Public queue journals.
PRIVATE=MachineGUID\QueueNumber              *Private queues.
PRIVATE=MachineGUID\QueueNumber;JOURNAL      *Private queue journals.
DIRECT=AddressSpecification\QueueName        *Direct format for public
                                              queues.
DIRECT=AddressSpecification\PRIVATE$\QueueName     *Direct format for 
                                                    private queue.
MACHINE=MachineGUID;JOURNAL                  *Machine journal.
MACHINE=MachineGUID;DEADLETTER                 *Dead letter queue.
MACHINE=MachineGUID;DEADXACT                 *Transaction dead letter
                                              queue.
CONNECTOR=ForeignCNGUID                      *Foreign queues.
CONNECTOR=ForeignCNGUID:XACTONLY             *Transaction foreign
                                              queues.

For information on public, private, and direct format names, see:

Public Format Names
Private Format Names
Direct Format Names

For information on MSMQ pathnames and queue handles, see:

For information on journals and dead letter queues, see:

Public Format Names

Public format names are used to specify queues registered in the MSMQ information store. A queue's public format name contains the string "Public=" followed by the queue identifier generated by MSMQ when the queue was created.

The following is the general format for public format names:

"PUBLIC=QueueGUID"

Example:

Lpwstr Sz = L"PUBLIC=308FB580-1EB2-11CA-923B-08002B1075A7";

When this format is used, MSMQ looks in Active Directory to determine what computer is currently hosting the queue, what protocol the host computer uses, and any other information it needs to get to the queue.

Note A public format name is strictly equivalent to the queue's identifier except that it is formatted as a string rather than as binary data. See PROPID_Q_INSTANCE for API calls or QueueGuid for ActiveX component calls.

The queue's location (the specific computer where the queue's messages are stored) is not part of the format name. This allows message operations to succeed regardless of the queue location; a public queue can be relocated to another computer and the format name remains valid. This is not true of a direct format name where the queue is bound to a specific location.

For information on other types of format names, see:

Private Format Names
Direct Format Names

Private Format Names

Private format names are used to specify queues that are created and managed locally by the Queue Manager on the local computer. Unlike public queues, they are not registered in Active Directory and their scope is restricted to the local computer.

The private format name of the queue includes the string "Private=" followed by the machine identifier of the computer where the queue is located and a hexadecimal number that identifies the queue.

The following is the general format of a private format name:

"PRIVATE=MachineGUID\QueueNumber"

Example:

Lpwstr Sz = L"PRIVATE=ae0c5671-f190-12ce-ae10-00dd0114290f\0000000d";

When MSMQ detects this type of format name, it does not refer to Active Directory for information about the queue. However, it does use Active Directory to look up information on the computer for routing purposes.

For information on other types of format names, see:

Public Format Names
Direct Format Names

Direct Format Names

Direct format names are used to open a queue that is not in your enterprise, or when you want to make sure MSMQ sends messages to the queue in one step. Direct format names have two parts: the address specification of the computer where the queue is located followed by the local name of the queue (the name specified in the queue's MSMQ pathname when the queue was created).

The address specification of the computer can be specified using two forms:

As the network address of the target computer (including the network protocol). MSMQ supports two network protocols: TCP and SPX.
As any string that is supported natively by the underlying operating system to identify the target computer (OS is used as the protocol to indicate that the computer's native protocol should be used).

Protocol	Description	Network Address
TCP	Connection-oriented TCP over IP.	Internet address notation (IP address).
SPX	Connection-oriented SPX over IPX.	Network number and host number (separated by the ":" character).
OS	Connection using native machine-naming convention.	Any machine name supported by the underlying operating system. For Windows NT version 4.0, it is either UNC or DNS (see the following examples).

The following is the general format of a direct format name (public and private queues can be accessed directly):

DIRECT=AddressSpecification\QueueName            (For public queues.)
DIRECT=AddressSpecification\PRIVATE$\QueueName   (For private queues.)

Public queue examples:

Lpwstr Sz = L"DIRECT=SPX: 00000012:00a0234f7500\MyQueue";
Lpwstr Sz = L"DIRECT=TCP:157.18.3.1\MyQueue";
Lpwstr Sz = L"DIRECT=OS:elvisp.ms.com\MyQueue";
Lpwstr Sz = L"DIRECT=OS:elvisp\MqQueue";

Private queue examples:

Lpwstr Sz = L"DIRECT=SPX: 00000012:00a0234f7500\PRIVATE$\MyQueue";
Lpwstr Sz = L"DIRECT=TCP:157.18.3.1\PRIVATE$\MyQueue";
Lpwstr Sz = L"DIRECT=OS:elvisp.ms.com\PRIVATE$\MyQueue";
Lpwstr Sz = L"DIRECT=OS:elvisp\PRIVATE$\MqQueue";

When MSMQ sees a direct format name, it uses the information provided in the format name to locate the queue, not information in Active Directory.

In addition, you cannot use a direct format name to access a journal queue or dead letter queue.

For information on other types of format names, see:

Public Format Names
Private Format Names