Label
MSMQQueueInfo    MSMQMessage

Optional. The Label property specifies a description of the queue or message.

Type: String
Run time: read/write

Syntax

object.Label
 
Syntax Element Description
object Either the queue information (MSMQQueueInfo) object that defines the queue, or the message (MSMQMessage) object that defines the message.

Settings

Queue label
Application-defined string (default is ""). The maximum length of the string is MQ_MAX_Q_LABEL_LEN (124 Unicode characters).
Message label
Application-defined string describing the message. The maximum length of a message label is 250 Unicode characters (including end-of-line character).

Remarks

Queue label
For public queues, the queue's label can be used as the search criteria for a query. By setting the label of several queues to the same string, the application can later run a query on the queue label and return all the queues with the same label. (A query can also be used to retrieve the label of a public queue.) For information on running a query, see Locating a Public Queue.

To specify the label of a queue, set Label and call the MSMQQueueInfo object's Create method.

To reset the label of a queue after the queue is created, set Label to a new label and, if the queue is open, call the MSMQQueueInfo object's Update method. If the queue is not open, do not call Update because the queue's properties are updated automatically when the queue is opened.

To find the label of a queue, call the MSMQQueueInfo object's Refresh method.

Message label
Message labels can be used by administration tools for display purposes. For example, a printing application could put the source application and document name in the label of each message it sends to the printer queue.

For an example of how MSMQ sends the messages to a queue, see Sending Messages To a Queue.

Example: Setting a queue label

This example creates a private queue on the local computer, setting the queue's label to "Test 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$\myqueue"
  qinfo.Label = "Test Queue"
  qinfo.Create
   
  MsgBox "Queue's Format name is: " + qinfo.FormatName

End Sub
 

Example: Setting a message label

This example creates a queue, opens the queue for sending messages, sets the label of a message, and sends the message to 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
Dim q As MSMQQueue
Dim msg As New MSMQMessage

Private Sub Form_Click()
   '*************************
   ' Create queue (no error
   ' handling if queue exists.
   '**************************
  Set qinfo = New MSMQQueueInfo
  qinfo.PathName = ".\LabelTest"
  qinfo.Label = "Test Queue"
  qinfo.Create
   '**************
   ' Open queue.
   '**************
  Set q = qinfo.Open(MQ_SEND_ACCESS, MQ_DENY_NONE)
   '**************
   ' Send Message.
   '**************
  msg.Label = "Test Message"
  msg.Body = "This is a test message with a string Body."
  msg.Send q
 
 
 q.Close

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.

See Also

Body, Close, Create, FormatName, MSMQMessage, MSMQQueue, MSMQQueueInfo, Open, PathName