3.1.6.7 Begin Directory Lookup

This event MUST be generated with the following arguments:

• iRestriction: An MQRESTRICTION (section 2.2.12) structure that specifies a set of constraints over the objects to be returned. The server MUST restrict the query results to include only objects that have properties that satisfy all of the restrictions specified in this parameter.

• iColumnSet: An MQCOLUMNSET (section 2.2.13) structure that specifies the object properties to be returned in subsequent calls to the Lookup Directory Next (section 3.1.6.8) event.

• iSort (optional): An MQSORTSET (section 2.2.15) structure that defines the sort order of the result set.

Return Values:

• rStatus: An HRESULT indicating the result of the operation.

• rLookupDescriptor: A LookupIteratorState (section 3.1.1.13) object.

The server MUST perform the following actions to process this event:

• Create a new LookupIteratorState ADM element instance, which is referred to as newStateObject.

• Examine the property identifiers in iColumnSet.aCol to determine the directory object type for which to search. Directory object types are defined in section 2.2.8, and the association by type with property identifiers is defined in section 2.2.10.1. Store the directory object type in newStateObject.ObjectType. If the property identifiers belong to more than one directory object type, perform no further processing and return an error.

• Populate the newStateObject.PropertyList with the property identifiers from iColumnSet.aCol.

• The server SHOULD<131> generate a Read Directory Begin ([MS-MQDSSM] section 3.1.6.4) event with the following arguments:

  • iDirectoryObjectType := the string representation of newStateObject.ObjectType as defined in the following table. If the object type is not in the table, take no further action, and return an error.

    ObjectType	Object Type (string)
    MQDS_QUEUE	"Queue"
    MQDS_MACHINE	"QueueManager"
    MQDS_SITE	"Site"
    MQDS_ENTERPRISE	"Enterprise"
    MQDS_USER	"User"
    MQDS_ROUTINGLINK	"RoutingLink"

  • iFilter := An array containing the attribute-filter expression ([MS-MQDMPR] section 3.1.7.1.20) of each MQPROPERTYRESTRICTION element in iRestriction. The directory ADM attribute name is determined by the prop attribute of the MQPROPERTYRESTRICTION element, using the mapping defined in section 3.1.4.21.8.1 for the corresponding object type.

  • iAttributeList := An array containing the directory ADM attributes that are determined by the property identifiers in iColumnSet.aCol, using the mapping defined in section 3.1.4.21.8.1 for the corresponding object type.

  • iAttributeSortOrder := An array containing the attribute-sort-order values ([MS-MQDSSM] section 3.1.6.4) to sort the result. For each element in iAttributeList, add one attribute-sort-order value, referred to as sortValue, and initialize it as follows:

    • SortPriority := the index of the MQSORTKEY (section 2.2.14) structure element in iSort whose propColumn matches the property identify of the ADM attribute. If no such element is found in iSort, set it to zero.

    • SortAscending := True if the dwOrder member of the found MQSORTKEY structure element  is QUERY_SORTASCEND; False otherwise.

• If the preceding event does not return DirectoryOperationResult.Success, take no further action, and return an error.

• Set newStateObject.LookupState to the returned rQueryHandle.

• Set rLookupDescriptor to newStateObject.

• Set rStatus to MQ_OK.