MQLocateBegin

The MQLocateBegin function starts a query to locate a single public queue (or set of public queues), returning a query handle. Use MQLocateNext to retrieve the query results.

This function does not return the number of matching entries.

HRESULT APIENTRY MQLocateBegin(
  LPCWSTR lpwcsContext,          
  MQRESTRICTION *pRestriction,  
  MQCOLUMNSET *pColumns,        
  MQSORTSET *pSort,             
  PHANDLE phEnum                 
);

Parameters

lpwcsContext: [in] Specifies the starting point of the query within Active Directory. Must be NULL.
pRestriction: [in] Specifies the search criteria for the query. NULL value indicates no restrictions.
pColumns: [in] Specifies which queue properties should be returned by the query. Must not be set to NULL.
pSort: [in] Specifies the sort order for the query results. PROPID_Q_PATHNAME cannot be used as a sort key. Can be set to NULL to indicate no sort order is needed.
phEnum: [out] Pointer to a query handle to use when calling MQLocateNext and MQLocateEnd.

Return Values

MQ_OK: Indicates success.
MQ_ERROR_ILLEGAL_CONTEXT: Indicates that lpwcsContext is not NULL.
MQ_ERROR_ILLEGAL_MQCOLUMNS: Indicates that pColumns is NULL.
MQ_ERROR_ILLEGAL_PROPERTY_VALUE: Indicates that an illegal property value was specified in pRestriction. For example, this error is returned if PROPID_Q_LABEL is specified and the supplied queue label is longer than the maximum label length.
MQ_ERROR_ILLEGAL_PROPID: Indicates that an illegal property identifier was specified in pColumns.
MQ_ERROR_ILLEGAL_RELATION: Indicates that an invalid relationship value was specified in pRestriction.
MQ_ERROR_ILLEGAL_RESTRICTION_PROPID: Indicates that an illegal property identifier was specified in pRestriction. For example, PROPID_Q_PATHNAME is not valid.
MQ_ERROR_ILLEGAL_SORT_PROPID: Indicates that an illegal property identifier was specified in pSort. For example, if pSort specifies PROPID_Q_PATHNAME, this error is returned.
MQ_ERROR_NO_DS: Cannot access Active Directory.

Remarks

Queries can only locate public queues. MQLocateBegin cannot locate a private queue. For a complete description of running a query, see Locating a Public Queue.

The pRestriction parameter specifies the search criteria (which queue properties and values are used in the search). It is a pointer to a structure containing a list of property restrictions logically combined by the And operator, with each restriction including a queue property identifier, a property value, and a comparison operator. Comparison operators include: less than (PRLT), less than or equal to (PRLE), equal (PREQ), not equal (PRNE), greater than or equal to (PRGE), greater than (PRGT).

To specify the search criteria, MSMQ uses two structures: MQPROPERTYRESTRICTION and MQRESTRICTION. MQPROPERTYRESTRICTION defines a single property restriction. MQRESTRICTION specifies an array of restrictions as well as a count of how many restrictions there are (see the following examples).

This example locates queues by their type of service. For example, locating all the queues whose PROPID_Q_TYPE equals guidx.

/*Set property restriction. */
MQPROPERTYRESTRICTION PropertyRestriction;
PropertyRestriction.rel         = PREQ;
PropertyRestriction.prop        = PROPID_Q_TYPE;
PropertyRestriction.prval.vt    = VT_CLSID;
PropertyRestriction.prval.puuid = &guidX;
 
/*Package restrictions. */
MQRESTRICTION rest;
rest.cRes = 1;
rest.paPropRes = &PropertyRestriction;

This example locates queues by their type of service (PROPID_Q_TYPE equals guidx) and by their message journal property (PROPID_Q_JOURNAL equals 1).

First, prepare the property restrictions:

/*Set property restrictions. */
MQPROPERTYRESTRICTION PropertyRestrictions[2];
/*Set first restriction. */
PropertyRestrictions[0].rel = PREQ;
PropertyRestrictions[0].prop = PROPID_Q_TYPE;
PropertyRestrictions[0].prval.vt  = VT_CLSID;
PropertyRestrictions[0].prval.puuid = &guidX;
/*Set second restriction. */
PropertyRestrictions[1].rel = PREQ;
PropertyRestrictions[1].prop = PROPID_Q_JOURNAL;
PropertyRestrictions[1].prval.vt  = VT_UI1;
PropertyRestrictions[1].prval.bVal = 1;
  
/*Package the restrictions. */
MQRESTRICTION rest;
rest.cRes = 2;
rest.paPropRes = PropertyRestrictions;

Setting pRestriction to NULL retrieves information about all the queues.

The pColumns parameter allows you to specify which queue properties to retrieve. You can retrieve any number of queue properties with the same call to MQLocateBegin.

The pSort parameter allows you to specify the sort order (ascending or descending) of the result according to one or more of the properties (PROPID_Q_PATHNAME cannot be used as a sort key). Two structures are used to set the sort order: MQSORTKEY specifies a single sort key, and MQSORTSET specifies an array of sort keys along with the number of keys.

For example, the following code sorts queues according to their quota:

/* Prepare sort key. */
MQSORTKEY SortKey;
SortKey.propColumn = PROPID_Q_QUOTA;
SortKey.dwOrder = QUERY_SORTASCEND;
 
/* Indicate number of sort keys. */
MQSORTSET SortSet;
SortSet.cCol = 1;
SortSet.aCol = &SortKey;

When running a query, MSMQ can locate queues faster when the query is based on PROPID_Q_INSTANCE, PROPID_Q_TYPE, or PROPID_Q_LABEL (PREQ only). 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.

MQLocateBegin can only return queues that are in Active Directory when MQLocateBegin is called. Queues added to Active Directory after MQLocateBegin is called are not included.

Public queues cannot be located if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers that are working offline, and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)

Examples

For an example of using MQLocateBegin, see Locating a Public Queue.

QuickInfo