3.1.7.1.20 Read Directory

This event MUST be generated with the following arguments:

• iDirectoryObjectType: A string that specifies the name of the subtype of a DirectoryObject ADM element instance to be read from the directory.

• iFilter: An array of attribute-filter expressions (defined following) where the valid ADM attributes are the set of directory attributes associated with a DirectoryObject ADM element instance of type iDirectoryObjectType. The first DirectoryObject ADM element instance of type iDirectoryObjectType that satisfies all attribute-filter expressions in this array MUST be returned. If this argument is set to NULL, the first DirectoryObject ADM element instance of type iDirectoryObjectType MUST be returned.

• iAttributeList (Optional): An array of strings containing the names of the directory attributes associated with a DirectoryObject ADM element instance of type iDirectoryObjectType to be read from the  directory and included in the rDirectoryObject return value. If this argument is not supplied, all directory attributes will be read. If this argument is supplied, the values of all ADM attributes that were not specified in this list will be undefined and MUST NOT be used.

• iForceDirectoryRead (Optional): A Boolean that specifies whether the QueueManager (section 3.1.1.1) ADM element instance can ignore its DirectoryOffline ADM attribute and read the directory. The default value of this argument is False.

An attribute-filter expression consists of three elements:

• The name of a directory attribute associated with a DirectoryObject ADM element instance of type iDirectoryObjectType. The value of this attribute forms the left side of the comparison.

• One of the following operators:

  • EQUALS

  • NOT-EQUALS

  • LESS-THAN

  • GREATER-THAN

  • LESS-THAN-OR-EQUAL

  • GREATER-THAN-OR-EQUAL

• A value that forms the right side of the comparison, for example:

  • The value of an ADM attribute of an ADM element instance.

  • The value of an argument to an event.

  • The value of a local variable in an event.

For instance:

• "Identifier" EQUALS LocalQueueManager.Identifier

• "ActualCost" LESS-THAN iMinCost

Return Values:

• rStatus: A DirectoryOperationResult that indicates the result of this directory operation.

• rDirectoryObject: A DirectoryObject ADM element instance of type iDirectoryObjectType, populated with the ADM attributes specified in iAttributeList. If an attribute-filter is specified, the ADM attributes of rDirectoryObject MUST match the expression specified by iFilter. This value is undefined if rStatus does not equal DirectoryOperationResult.Success.

The queue manager MUST perform the following actions to process this event:

• If the DirectoryOffline ADM attribute of the QueueManager ADM element instance is True and iForceDirectoryRead is False:

  • If iDirectoryObjectType is set to "Queue":

    • Find the first Queue (section 3.1.1.2) ADM element instance in the QueueCollection ADM attribute of the QueueManager ADM element instance that has ADM attributes that match the ADM attributes specified by iFilter. If no such Queue ADM element instance is found:

      • Set rStatus to DirectoryOperationResult.ObjectNotFound.

      • Take no further action.

    • Set rDirectoryObject to the Queue ADM element instance found in the previous step.

    • Set rStatus to DirectoryOperationResult.Success.

    • Take no further action.

  • If iDirectoryObjectType is set to "QueueManager" and the ADM attributes specified in iFilter match the ADM attributes of the local QueueManager ADM element instance:

    • Set rDirectoryObject to the LocalQueueManager ADM element instance.

    • Set rStatus to DirectoryOperationResult.Success.

    • Take no further action.

  • Set rStatus to DirectoryOperationResult.DirectoryNotConnected.

  • Take no further action.

• Else:

  • Delegate the processing of this event to the Read Directory ([MS-MQDSSM] section 3.1.6.3) event.<25>

  • If the rStatus returned from processing of the invoked event is DirectoryOperationResult.DirectoryNotConnected and iForceDirectoryRead is False:

    • Set LocalQueueManager.DirectoryOffline to True.

    • Start the Directory Online Timer (section 3.1.2.5) if it is not active already.

    • Set rStatus to DirectoryOperationResult.DirectoryNotConnected.

  • Else:

    • Set rStatus to the rStatus returned from the invoked event.

    • Set rDirectoryObject to the rDirectoryObject returned from the invoked event.