The LookupQueue method returns a collection of public queues based on the following queue properties: queue identifier, service type, label, create time, and modify time.
object.LookupQueue ([QueueGuid] [, ServiceTypeGuid] [, Label] [, CreateTime]
[, ModifyTime] [, RelServiceType] [, RelLabel]
[, RelCreateTime] [, RelModifyTime])
| Syntax Element | Description |
|---|---|
| object | Query. |
| QueueGuid (String) | Optional. Identifier of queue. |
| ServiceTypeGuid (String) | Optional. Type of service provided by the queue. See also RelServiceType. |
| Label (String) | Optional. Label of queue. See also RelLabel. |
| CreateTime (Variant Date) | Optional. Time when queue was created. See also RelCreateTime. |
| ModifyTime (Variant Date) | Optional. Time when queue properties were last set (both when the queue was created and the last time Update was called). See also RelModifyTime. |
| RelServiceType (Long) | Optional (default is REL_EQ). Relationship parameter for ServiceTypeGuid. |
| RelLabel (Long) | Optional (default is REL_EQ). Relationship parameter for Label. |
| RelCreateTime (Long) | Optional (default is REL_EQ). Relationship parameter for CreateTime. |
| RelModifyTime (Long) | Optional (default is REL_EQ). Relationship parameter for ModifyTime. |
MSMQQueueInfos object.
For information on return codes, see MSMQ Error and Information Codes.
LookupQueue returns a single MSMQQueueInfos object that represents a set of MSMQQueueInfo objects that each contain information describing a single MSMQ queue.
The relationship parameters RelServiceType, RelLabel, RelCreateTime, and RelModifyTime provide simple Boolean comparison operators that can be used in conjunction with their respective lookup parameter. These comparison operators include: REL_EQ, REL_NEQ, REL_LT, REL_GT, REL_LE, REL_GE, and REL_NOP (REL_NOP indicates that the associated lookup parameter should be ignored). These operators give you greater control over which queues are returned from to the query.
The CreateTime and ModifyTime parameters return both the date and time. Consequently, using the REL_EQ value for RelCreateTime or RelModifyTime may not prove very useful.
When running a query, MSMQ can locate queues faster when the query is based on QueueGuid, ServiceTypeGuid, or Label (RelLabel = REL_EQ). The query runs faster because these properties are indexed in Active Directory, providing a faster way for MSMQ to locate the property specified in the call.
LookupQueue can only return queues that are in Active Directory when LookupQueue is called. Queues created after LookupQueue is called are not included.
To open a specific queue from the query, use the MSMQQueueInfos object's Reset and Next methods to locate the queue. Reset points the cursor to the front of the query results (not the first queue in the query) and Next points to the next queue. Once the queue is located, use the MSMQQueueInfo object's Open method to open the queue.
This example assumes that at least one queue with the label "Test Queue" already exists. A query is run for the test queues, displaying the format name of each queue it finds.
To try this example using Microsoft® Visual Basic® (version 5.0), make sure the Microsoft Message Queue Object Library is referenced, paste the following Code into the code window of a form, run the example, and click the form.
Dim query As New MSMQQuery
Dim qinfos As MSMQQueueInfos
Dim qinfo As MSMQQueueInfo
Private Sub Form_Click()
Set qinfos = query.LookupQueue(Label:="Test Queue")
qinfos.Reset
Set qinfo = qinfos.Next
While Not qinfo Is Nothing
MsgBox "I found a Test Queue! its Format name is: " + qinfo.FormatName
Set qinfo = qinfos.Next
Wend
End Sub
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.
FormatName, Label, MSMQQuery, MSMQQueueInfo, MSMQQueueInfos, Next, Reset