MQLocateBegin

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQLocateBegin function starts a query of the directory service to locate a set of public queues that satisfy the search criteria specified and returns 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 the directory service. This parameter must be NULL.

pRestriction

[in] Specifies the search criteria for the query. NULL indicates no restrictions, and the properties of all public queues registered in the directory service are returned.

pColumns

[in] Specifies which queue properties should be returned by the query. This parameter must not be set to NULL.

pSort

[in] An MQSORTSET structure that specifies the sort keys of the query.

phEnum

[out] Pointer to a variable that receives the query handle to use when calling MQLocateNext and MQLocateEnd.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ILLEGAL_CONTEXT (0xC00E005B)

The lpwcsContext parameter is not NULL.

MQ_ERROR_ILLEGAL_MQCOLUMNS (0xC00E0038)

The pColumns parameter is NULL.

MQ_ERROR_ILLEGAL_PROPERTY_VALUE (0xC00E0018)

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 (0xC00E0039)

An illegal property identifier was specified in pColumns.

MQ_ERROR_ILLEGAL_RELATION (0xC00E003A)

An invalid relationship value was specified in pRestriction.

MQ_ERROR_ILLEGAL_RESTRICTION_PROPID (0xC00E003C)

An illegal property identifier was specified in pRestriction. For example, PROPID_Q_PATHNAME is not valid.

MQ_ERROR_ILLEGAL_SORT_PROPID (0xC00E005C)

An illegal property identifier was specified in pSort. For example, if pSort specifies PROPID_Q_PATHNAME, this error is returned.

MQ_ERROR_MULTI_SORT_KEYS (0xC00E008D)

Multiple sort keys were specified in the pSort parameter.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_Q_ADS_PROPERTY_NOT_SUPPORTED (0xC00E0091)

PROPID_Q_ADS_PATH was specified in the pColumns parameter. You cannot retrieve the ADs path of a queue in a query.

MQ_ERROR_Q_DNS_PROPERTY_NOT _SUPPORTED (0xC00E006E)

PROPID_Q_PATHNAME_DNS was specified in pColumns. You cannot retrieve the DNS path name of a queue in a query.

Note

Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.

Remarks

A query started by MQLocateBegin locates public queues that are in the directory service when MQLocateBegin is called. Public queues added to the directory service after MQLocateBegin is called are not included. MQLocateBegin cannot locate private queues that reside on computers. For a complete description of running a query, see Locating Queues Using Function Calls.

Starting with Windows® XP, the returned query handle is a handle to an ADSI COM object, which means that the calling application cannot change the thread model on the calling thread.

The pRestriction parameter of MQLocateBegin 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 comparison operator, and a property value. 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).

Setting pRestriction to NULL retrieves information about all public queues registered in the directory service.

For information on the structures used to set the search criteria, see Specifying Search Criteria.

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

For information on the structures used to set the queue properties to be returned, see Specifying Queue Properties to Retrieve.

The pSort parameter allows you to specify the key and sort order (ascending or descending) of the query. Each key is a queue property (PROPID_Q_PATHNAME cannot be used as a sort key). The MQSORTSET structure contains an array of MQSORTKEY structures, each representing a single sort key. Currently, Message Queuing supports only one sort key per query.

When running a query, Message Queuing 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 the directory service, providing a faster way for Message Queuing to locate the property specified in the call.

MQLocateBegin cannot locate public queues if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS).

For information on offline operations, see Message Queuing Offline Support.

For information on	See
What information Message Queuing needs to locate queues	Locating Queues Using Function Calls
Structures used to set search criteria	Specifying Search Criteria
Structures used to set returned queue properties	Specifying Queue Properties to Retrieve

Example Code

The following code example is included in Using Message Queuing.

For an example of	See
Locating queues based on queue label	C++ Code Example: Locating a Queue

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.