Undocumented Limits for the $SEARCH() Function (291239)

SYMPTOMS

A Microsoft Metadirectory Services (MMS) object contains an instance of a particular hashed attribute. To locate the object successfully, you can search for the hashed attribute value by using the Compass client. An MMS Management Agent (MA) attempts to locate this same object by employing the $SEARCH() function within one of its templates; however, the expected search results are not returned.

CAUSE

This behavior occurs because the parameters for the $SEARCH() function are not valid.

As listed in the online manual MMS Management Agent Toolkit Manual, the valid parameters for the $SEARCH() function are:

searchAttribute - Mandatory parameter: The string, or the name of an attribute or variable that contains the string for which to search.
region - Optional parameter:
0 - Search only the connector space of the MA; Default value.
1 - Search the metaverse.
In addition, this parameter may contain the following values:
0 - Search only within the connector space of the current MA.
1 - Search within the entire metaverse but do not search at or below the DSA object.
2 - Search within the naming context but do not search at or below the DSA object.
baseDN - Optional parameter: If it is present, search only under this distinguished name.
arbitraryResponse - Optional parameter: Set it to "arbitrary" to receive an arbitrary response instead of a Null response when there are multiple search results.

RESOLUTION

Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.

WORKAROUND

This workaround is based on a scenario in which there are two MAs where:

MA1 is a report MA.
MA2 is any type of MA that has a populated connector space.

In this example, it is necessary to search through the MA2 connector space for a particular object. By using the $SEARCH() function from within an MA1 template, it is impossible to examine the connector space (CS) of MA2. If this is a requirement and if you confidently create the complete distinguished name (DN) of the target object in MA2, use the function $INSTANCE() in place of your existing code. The following code sample provides an example of how to use the function $INSTANCE() to achieve the desired result:

  $v_searchObject = cn=John Doe,ma=MA1,DsaName=NWTraders,ou=Applications,o=PSS,dc=microsoft,dc=com
  if $INSTANCE("$v_searchObject") = T
  then
    $v_result = Found it!
  else
    $v_search = Missed it!
  endif