Create
MSMQQueueInfo

The Create method produces a queue based on the queue properties of the MSMQQueueInfo object.

Syntax

object.Create ([IsTransactional][, IsWorldReadable])

Syntax Element	Description
object	Queue information (MSMQQueueInfo) object that defines queue.
IsTransactional	Optional (default is FALSE). BOOLEAN. When TRUE, indicates that the queue is a transaction queue. All messages sent to a transaction queue or read from a transaction queue must be done as part of a transaction.
IsWorldReadable	Optional (default is FALSE). BOOLEAN. When TRUE, anyone can read the messages in the queue and its queue journal. When FALSE, only the owner can read the messages.

Return Codes

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

Remarks

You must always specify the queue's MSMQ pathname (PathName) before calling Create. The PathName property tells MSMQ where to store the queue's messages, if the queue is public or private, and the name of the queue.

Public queues are registered in Active Directory, and private queues are registered on the local computer. All queues exist until deleted explicitly.

Private queues can only be created on the local computer. The applications responsibility is to ensure that no other private queues with the same name exists on the local computer (if a queue with the same name already exists, MSMQ returns an MQ_ERROR_QUEUE_EXISTS error when Create is called).

Setting other queue properties is optional. If a queue property is not set before Create is called, its default value is used when the queue is created. For a list of the queue properties that can be set by an application, see Creating a Queue.

To attach a journal to the queue, set Journal and JournalQuota. The journal keeps a copy of all messages retrieved from the queue. For information about journals, see Journal Queues.

To create a transactional queue, set the IsTransactional parameter to TRUE.

Typically queues are not created from MSMQQueueInfo objects found in a query because the queue already exists. However, you can create a new queue from an MSMQQueueInfo object found in a query if you delete the existing queue and then change the PathName or FormatName property of the queue.

After the queue is created, the MSMQQueueInfo object can be opened multiple times. For example, the same MSMQQueueInfo object can be opened for sending messages to the queue and for reading the messages in the queue.

Access control can be changed by setting isWorldReadable. If this parameter is not set, its default value specifies MSMQ default security. Following are the default values for the security descriptor.

Default Value	Meaning
Owner	The process user.
Group	The process group.
DACL	Full control for the creator of the queue. All other processes can get queue properties, get queue security, and send messages to the queue.
SACL	None.

For information on access control, see Access Control.

Foreign public queues (queues located outside the enterprise) are created in the same way as an MSMQ public queue. For foreign queues, the PathName property specifies the name of the foreign computer as it is defined in Active Directory. For information on foreign computers, see MSMQ Connector Server.

When creating a public queue, some clients may not be able to see the new queue registered in Active Directory even though the queue exists. Changes to Active Directory (such as creating a public queue) are propagated from domain controller to domain controller, which can cause delays in the availability of new information. Consequently, clients using a specific domain controller may not be able to open the queue, even though it exists. Propagation delays, including communication network delays such as down links, are controlled by the MSMQ Administrator.

Example

This example creates a private queue on the local computer, then displays the queue's format name (the queue's format name is used to open the queue). To try this example using Microsoft Visual Basic (version 5.0), paste the code into the Code window of a form, run the example, and click the form.

Dim qinfo As MSMQQueueInfo
   
Private Sub Form_Click()
    
  Set qinfo = New MSMQQueueInfo
  qinfo.PathName = ".\PRIVATE$\CreateTest"
  qinfo.Label = "Test Queue"
  qinfo.Create 
   
  MsgBox "The queue's format name is: " + qinfo.FormatName
  
End Sub

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mqoai.h.
  Import Library: Use mqoa.lib.
  Unicode: Defined only as Unicode.