Searching Active Directory

Microsoft® Windows® 2000 Scripting Guide

« Previous | Next »   

The goal of performing a search is to return a result set containing zero or more records. A result set containing no records is useful if you are verifying that an object is not present before attempting to create it.

Searching for Active Directory objects involves the following steps:

1. Create an ADO Connection object and use the Open method of the object to access Active Directory with the ADSI OLE DB provider.
2. Create an ADO Command object, and assign the Command object s ActiveConnection property to the Connection object.

   This step is necessary because the Command object holds both the connection and the query string to run against Active Directory.

3. Assign a search request (query string) to the CommandText property of the Command object.

   You can use either SQL syntax or LDAP search dialect for the query string. All of the examples in this chapter use LDAP search dialect. For information about the SQL dialect for performing an Active Directory search, see the Active Directory Programmer s Guide link on the Web Resources page at http://www.microsoft.com/windows/reskits/webresources.

4. Using the Execute method of the Command object, run the query and store the results in a RecordSet object.
5. Using properties of the RecordSet object, read information in the result set.
6. Using the Connection object Close method, close the Connection.

   This final step is optional, but it is good practice to remove objects from memory when a script has finished using them. In much larger scripts that take time to complete, removing unused objects from memory saves resources.

The goal of the scripts in this section is to demonstrate how to construct Active Directory searches by using ADO and the ADSI OLE DB provider. In each case, the script includes the six steps just described for searching Active Directory.

Creating a Simple Search Script

The script in Listing 5.28 returns a result set containing the name of all objects in the na.fabrikam.com domain.

To carry out this task, the script performs the following steps:

1. Create an ADO Connection object to access Active Directory by using the ADSI OLE DB provider.

   Line 1 creates a Connection object in memory, and line 2 opens the Connection object using the ADSI OLE DB provider. Notice that the name of the ADSI OLE DB provider that you use in all ADSI search scripts is ADsDSOObject. This is called the ProgID (Program ID) of the provider.

2. Create an ADO Command object in memory, and assign the Command object s ActiveConnection property to the Connection object (lines 4 and 5).
3. Assign the query string to the CommandText property of the Command object.

   Line 8, which continues line 7, specifies the search base, the attribute to return, and the search scope.

   • The search base, surrounded by angle brackets (< >), specifies the start of the search the ADsPath to the na.fabrikam.com domain.
   • The attribute to return, which appears after two semicolons, specifies the lDAPDisplayName of each attribute that the query should return. In this case, a single attribute, name, is specified. If more than one attribute is specified, separate each attribute with a comma.
   • The search scope, appearing at the end of the query string, specifies where to perform the query subtree, which performs the search of the entire hierarchy, starting from the search base na.fabrikam.com.
4. Run the query by calling the Execute method of the Command object and assigning the return value to the RecordSet object (line 9).

   The query string returns records containing a single field, the name field.

5. Use a While Wend statement to display each record in objRecordSet. Use the MoveNext method of the RecordSet object to move to the next record.
6. Close the Connection object.

Listing 5.28   Searching for the Names of All Objects in the Domain

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<LDAP://dc=NA,dc=fabrikam,dc=com>;;name;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("name")     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name of each object in the domain to the command window, as shown in the following abbreviated result set:

na Builtin Administrators Users ... S-1-5-11 Program Data Microsoft 

The information returned by running the script in Listing 5.28 is of limited use for the following reasons:

• The names of all objects in the na.fabrikam.com domain are returned.
• There is no indication of where in the domain hierarchy the objects exist.
• There is no indication of the type of objects in the result set.
• The result set might be too large or too small, depending on the requirements of your search.

To make the result set more useful, you can change the script by:

Modifying the query string. In the query string, you can specify the attributes to return and the part of the directory that is searched (the search base). You can also implement filters and specify the scope of the search.

Specifying additional search options by using the Command object. Using the Command object lets you control many aspects of the search, such as the sort order of the query, the size limit of the result set, how long the script waits for results, and other options.

Note

• For a complete list of search options and other properties supported by ADO and available from the ADSI OLE DB Provider, see the Active Directory Programmer s Guide link on the Web Resources page at http://www.microsoft.com/windows/reskits/webresources.

The goal of the next eight scripts in this section is to show examples of how you can change the query string, specify additional Command object properties, and modify the script language in other ways to fine-tune the results of a search.

Scripting the Attributes to Be Returned by the Search

Listing 5.28 demonstrated how to return a single value, that of the name attribute. Returning additional attributes can make the result set more useful. For example, by adding the distinguishedName attribute to the result set, you can determine where objects are located in Active Directory.

The script in Listing 5.29 returns a result set containing both the name and the distinguishedName of all objects in the na.fabrikam.com domain. The steps in this listing are exactly the same as those in the preceding listing; therefore, the steps are not repeated here.

To expand the result set, the following modifications were made to the script:

1. Include the distinguishedName attribute in the query string (line 8).
2. Echo the value of the distinguishedName attribute to the command window (lines 14 and 15).

Listing 5.29   Searching for the Names and DNs of All Objects in the Domain

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<LDAP://dc=NA,dc=fabrikam,dc=com>;;distinguishedName,name;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name and DN of each object in the domain to the command window, as shown in the following abbreviated result set:

na [dc=NA,DC=fabrikam,DC=com] Builtin [CN=Builtin,dc=NA,DC=fabrikam,DC=com] Administrators [CN=Administrators,CN=Builtin,dc=NA,DC=fabrikam,DC=com] Users [CN=Users,CN=Builtin,dc=NA,DC=fabrikam,DC=com] ... S-1-5-11 [CN=S-1-5-11,CN=ForeignSecurityPrincipals,dc=NA,DC=fabrikam,DC=com] Program Data [CN=Program Data,dc=NA,DC=fabrikam,DC=com] Microsoft [CN=Microsoft,CN=Program Data,dc=NA,DC=fabrikam,DC=com] 

Limiting a Search to a Specific Type of Object

Suppose you are interested in a result set containing only a certain type of object, such as a computer, printer, user account, or group. To limit a search to a specific type of object, you can specify either the objectClass or objectCategory search filter property in the query string.

Each Active Directory object contains a single-valued objectCategory attribute. This attribute is the DN of the class from which the object is derived. For example, the objectCategory of a group object is cn=Group,cn=Schema,cn=Configuration,dc=fabrikam,dc=com. To return only group objects in the result set, you include the filter property (objectCategory=Group) in the filter portion of the search string.

Each Active Directory object also contains a multivalued objectClass attribute. This attribute contains an ordered list of the entire class hierarchy from which the Active Directory object is derived. The objectClass filter property lets you limit the query to objects matching any one of the values stored in the objectClass multivalued attribute. For example, to return all user and computer objects, you can specify (objectClass=user). This returns both user and computer objects because in the Active Directory hierarchy, the computer class is a child class of the user class.

Because the objectCategory attribute contains a single value, it is better suited for performing searches. Therefore, whenever possible, use the objectCategory filter property instead of objectClass for performing searches containing potentially large result sets.

Note

• For information about Active Directory classes and the class hierarchy, see "Active Directory Architecture" later in this chapter.

Listing 5.30 demonstrates how to return a result set containing a certain category of object the Computer category. The script returns both the name and the distinguishedName of computer objects in the na.fabrikam.com domain. The steps in this listing are exactly the same as those in the preceding listings in this section; therefore, the steps are not repeated here.

To limit the result set to computer objects in the domain, the following modification was made to the script:

• Include the objectCategory filter in the query string, and set its value to return all computer objects (line 8).

Listing 5.30   Searching for the Names and DNs of Computer Objects in the Domain

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<LDAP://dc=NA,dc=fabrikam,dc=com>;(objectCategory=computer)" & _        ";distinguishedName,name;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name and DN of each computer object in the domain to the command window, as shown in the following abbreviated result set:

SEA-DC-02 [CN=SEA-DC-02,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] SEA-DC-03 [CN=SEA-DC-02,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] ... SEA-PM-01 [CN=SEA-PM-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] SEA-SQL-01 [CN=SEA-SQL-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] 

Filter properties can be combined, and wildcards are supported. For details about the search filter syntax, see the Active Directory Programmer s Guide link on the Web Resources page at http://www.microsoft.com/windows/reskits/webresources and perform a search on the phrase, "Search Filter Syntax." For object-specific search examples, see the ADSI task-based chapters in this book.

Specifying the Global Catalog in the Search Base

Suppose you want to return the names and DNs of all computers in the forest. To accomplish this task, you can query the Global Catalog server in the root domain because the name and distinguishedName attributes are two attributes that are located in the Global Catalog server by default. Global catalog servers contain a partial attribute set of every object in the domain. To query the Global Catalog in the forest, change the LDAP moniker in the search base portion of the query string to GC and change the DN to the root domain. Therefore, the ADsPath changes from

<LDAP://dc=NA,dc=fabrikam,dc=com> 

to

<GC://dc=NA,dc=fabrikam,dc=com> 

Listing 5.31 demonstrates how to return a result set containing information about all computer objects in the forest.

To expand the result set to all computer objects in the forest, the following modification was made to the script:

• Use the GC moniker in the search base (ADsPath) of the query string, and change the DN to the root domain, fabrikam.com (line 8).

Listing 5.31   Searching for the Names and DNs of All Computer Objects in the Forest

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<GC://dc=fabrikam,dc=com>;(objectCategory=computer)" & _       ";distinguishedName,name;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the fabrikam.com root domain, it echoes the name and DN of each computer object in the forest to the command window, as shown in the following abbreviated result set:

SEA-DC-01 [CN=SEA-DC-01,OU=Domain Controllers,DC=fabrikam,DC=com] SEA-DC-04 [CN=SEA-DC-04,OU=Domain Controllers,DC=fabrikam,DC=com] SEA-DC-02 [CN=SEA-DC-02,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] SEA-DC-03 [CN=SEA-DC-03,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] ... SEA-PM-01 [CN=SEA-PM-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] SEA-SQL-01 [CN=SEA-SQL-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] 

Using Referral Chasing to Expand the Result Set

If you want to return a complete result set containing one or more attributes that are not in the Global Catalog, you must use referral chasing. When a domain controller in a parent domain, such as the root domain, builds its result set, it passes a list of child domains back to the client computer running the script. The client computer then contacts each of the child domains so that they can build their result sets to satisfy the query. This process is called referral chasing.

Referral chasing increases network traffic and processing load on the domain controllers servicing the request. Network traffic is increased because, in contrast with a Global Catalog search, the client must contact a domain controller in each child domain and each domain controller servicing the request must respond with a result set.

You can explicitly enable referral chasing by setting the Chase Referrals property of the Command object to ADS_CHASE_REFERRALS_SUBORDINATE (a constant with the value &h20). Listing 5.32 demonstrates how to return a result set that uses referral chasing to retrieve attributes from a domain and its child domains. With the exception of four minor additions, the steps in this listing are similar to the previous listings in this section.

To support referral chasing, the following modifications were made to the script:

1. Set the ADS_CHASE_REFERRALS_SUBORDINATE constant for referral chasing (line 1).
2. Enable referral chasing by setting the Chase Referrals property of the ADO Command object to ADS_CHASE_REFERRALS_SUBORDINATE. This instructs the server to send a list of referrals back to the client so that child domains can also process the result set (lines 8 and 9).
3. Include the isCriticalSystemObject attribute in the query string to demonstrate retrieving a value not contained in the Global Catalog (line 13).
4. Echo the value of isCriticalSystemObject to the command window (lines 19 and 20).

Listing 5.32   Using Referral Chasing to Perform a Search

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 

ADS_CHASE_REFERRALS_SUBORDINATE = &h20 Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.Properties("Chase Referrals") = _    ADS_CHASE_REFERRALS_SUBORDINATE objCommand.CommandText = _    "<LDAP://dc=fabrikam,dc=com>;(objectCategory=computer);" & _        "distinguishedName,name,isCriticalSystemObject;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "isCriticalSystemObject: " & _         objRecordSet.Fields("isCriticalSystemObject")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the fabrikam.com root domain, it echoes the name, the DN, and the Boolean value of isCriticalSystemObject of each computer object in the forest to the command window, as shown in the following abbreviated result set:

SEA-DC-01 isCriticalSystemObject: True [CN=SEA-DC-01,OU=Domain Controllers,DC=fabrikam,DC=com] SEA-DC-04 isCriticalSystemObject: True [CN=SEA-DC-04,OU=Domain Controllers,DC=fabrikam,DC=com] SEA-DC-02 isCriticalSystemObject: True [CN=SEA-DC-02,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] SEA-DC-03 isCriticalSystemObject: True [CN=SEA-DC-03,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] ... SEA-PM-01 isCriticalSystemObject: False [CN=SEA-PM-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] SEA-SQL-01 isCriticalSystemObject: False [CN=SEA-SQL-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] 

Controlling the Scope of a Search

Suppose you are interested in limiting a result to attributes of computer objects in the Computers container of a particular domain. Suppose as well that additional child containers in the Computers container contain objects. To limit a search to a specific container, such as the Computers container, you can modify the DN specified in the ADsPath (the search base) as follows:

cn=Computers,dc=NA,dc=fabrikam,dc=com 

A possible query string might look like this:

"<GC://cn=Computers,dc=NA,dc=fabrikam,dc=com>" & _     ";(objectCategory=computer)" & _         ";distinguishedName,name;subtree" 

This query string instructs the script to retrieve the DN and name of all computer objects in the Computers container of the na.fabrikam.com domain. However, because subtree is specified at the end of the query string, the result set will also include any computer objects in child containers of the Computers container. To limit the search to just the Computers container, you can specify a different search scope.

The search scope is the last part of the query string; options for search scope are base, onelevel, and subtree:

Base.   Searches only the DN specified in the search base. For example, a query for the name attribute with the search base <GC://cn=Computers,dc=NA,dc=fabrikam,dc=com> and no search filter returns the name value of the container, Computers. No child objects of the Computers container are searched.

Onelevel.   Searches the immediate children of the specified search base. For example, a query for the name attribute with the search base <GC://cn=Computers,dc=NA,dc=fabrikam,dc=com> and the (objectCategory=computer) search filter returns the name values of all computer objects in the Computers container. Any child containers in the Computers container are not searched.

Subtree.   Searches the entire subtree, including the object specified in the search base. Examples of this search scope appear in all previous search examples. This is the default scope option: If you do not specify a scope option in the query, subtree is used.

The script in Listing 5.33 demonstrates how to return a result set containing the name and distinguishedName of all computer objects in the Computers container. Subcontainers of the Computers container are not searched.

To limit the search scope:

• Specify the Computers container in the na.fabrikam.com domain as the search base.
• Specify onelevel as the search scope.

Listing 5.33   Limiting the Scope of a Search

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<GC://cn=Computers,dc=NA,dc=fabrikam,dc=com>" & _       ";(objectCategory=computer)" & _           ";distinguishedName,name;onelevel" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name and the DN of computer objects in the Computers container to the command window, as shown in the following abbreviated result set:

SEA-PM-01 [CN=SEA-PM-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] SEA-SQL-01 [CN=SEA-SQL-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] ... 

Sorting the Results of a Search

If you want the server to sort the result set before it is sent to the client, you can include the Sort On property of the command object in the ADSI script. The Sort On property instructs the server to perform the sort operation before the data is returned.

You assign the Sort On property the lDAPDisplayName of an attribute. The attribute should contain a meaningful value for the search. For example, you can search on the name attribute to sort a result set alphanumerically or search on the whenCreated attribute to sort a result set chronologically.

Note

• The Sort On property cannot sort on an attribute stored as a distinguished name. If you attempt to sort on this type of attribute, an empty result set is returned.

Listing 5.34 demonstrates how to instruct the server to sort a result set containing information about all computer objects in the forest. The result set includes the name, distinguishedName, and whenCreated attributes of each computer object in the forest. The script instructs the server to sort on the whenCreated attribute. Therefore, the result set contains all computer objects in the forest, from first created to last created.

To sort the result set, the following modifications were made to the script:

1. Assign the whenCreated attribute to the Sort On property of the Command object (line 7).
2. Include the whenCreated attribute in the query string so that its value will be part of the result set (line 11).

   Notice that the script uses the GC moniker in the query string. This works properly because all three attributes are contained in the Global Catalog.

3. Echo the value of the whenCreated attribute to the command window (line 19).

Listing 5.34   Sorting Computer Objects in the Domain Based on Creation Date

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.Properties("Sort On") = "whenCreated" objCommand.CommandText = _    "<GC://dc=fabrikam,dc=com>;(objectCategory=Computer);" & _        "distinguishedName,name,whenCreated;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"     Wscript.Echo objRecordSet.Fields("whenCreated") & VbCrLf     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name, DN, and whenCreated attributes of each computer object in the domain to the command window. The result set is returned by the server in ascending order (oldest to newest object creation date) based on the whenCreated attribute, as shown in the following abbreviated result set:

SEA-DC-01 [CN=SEA-DC-01,OU=Domain Controllers,DC=fabrikam,DC=com] 8/14/2002 9:59:12 AM SEA-DC-02 [CN=SEA-DC-02,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] 8/21/2002 1:53:24 PM SEA-DC-03 [CN=SEA-DC-03,OU=Domain Controllers,dc=NA,DC=fabrikam,DC=com] 8/27/2002 9:53:24 AM SEA-PM-01 [CN=SEA-PM-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] 8/27/2002 11:53:24 AM ... SEA-SQL-01 [CN=SEA-SQL-01,cn=Computers,dc=NA,DC=fabrikam,DC=com] 8/27/2002 4:06:30 PM SEA-DC-04 [CN=SEA-DC-04,OU=Domain Controllers,DC=fabrikam,DC=com] 9/03/2002 2:00:03 PM 

Retrieving Multivalued Attributes from a Search

A number of Active Directory objects contain multivalued attributes. The entries in multivalued attributes can also be part of a result set. For example, you might want to return a list of group members (both user accounts and groups) from the member attribute of groups.

The script in Listing 5.35 returns a result set containing the name and distinguishedName single-valued attributes and the member multivalued attribute for each group in the na.fabrikam.com domain.

To include a multivalued attribute in the result set, the following modifications were made to the script:

1. Include the (objectCategory=Group) filter in the query string to limit the result set to group objects (line 8). Also, include the member multivalued attribute in the query string so that its value is part of the result set (line 9).

   For this script to return group memberships, a global catalog server must be configured in the na.fabrikam.com domain. This is required because the script uses the GC moniker and the distinguished name of the na.fabrikam.com domain for the search base.

   If no global catalog server is in the na.fabrikam.com domain, you must use the LDAP moniker instead.

2. Initialize a variable named arrMembers with the contents of the member attribute contained in the fields property of the RecordSet object (line 19).
3. Using the VBScript IsArray function, test whether the member attribute is an array (line 22).

   This result is false if the member attribute of the group is empty and true if one or more members are listed in the group.

   • If IsArray is true, use a For Each statement to echo each member of the group to the command window (lines 23 25).
   • If IsArray is false, echo the word None to the command window (line 27).

Listing 5.35   Searching for the Names and DNs of All Objects in the Domain

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 21 22 23 24 25 26 27 28 29 30 31 32 33 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<GC://dc=NA,dc=fabrikam,dc=com>;(objectCategory=Group);" & _        "distinguishedName,name,member;subtree" Set objRecordSet = objCommand.Execute While Not objRecordSet.EOF     Wscript.Echo objRecordSet.Fields("Name")     Wscript.Echo "[" & _         objRecordSet.Fields("distinguishedName") & "]"        Wscript.Echo "Group Member(s):"     arrMembers = objRecordSet.Fields("member")       If IsArray(objRecordSet.Fields("member")) Then         For Each strMember in arrMembers             Wscript.Echo vbTab & strMember         Next     Else         Wscript.Echo vbTab & "None"     End If     Wscript.Echo VbCrLf     objRecordSet.MoveNext Wend objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes the name, DN, and members of each group object in the domain to the command window, as shown in the following abbreviated result set:

Administrators [CN=Administrators,CN=Builtin,DC=na,DC=fabrikam,DC=com] Group Member(s):    CN=Enterprise Admins,CN=Users,DC=fabrikam,DC=com    CN=Domain Admins,CN=Users,DC=na,DC=fabrikam,DC=com    CN=Administrator,CN=Users,DC=na,DC=fabrikam,DC=com Users [CN=Users,CN=Builtin,DC=na,DC=fabrikam,DC=com] Group Member(s):    CN=Domain Users,CN=Users,DC=na,DC=fabrikam,DC=com    CN=S-1-5-11,CN=ForeignSecurityPrincipals,DC=na,DC=fabrikam,DC=com    CN=S-1-5-4,CN=ForeignSecurityPrincipals,DC=na,DC=fabrikam,DC=com ... Pre-Windows 2000 Compatible Access [CN=Pre-Windows 2000 Compatible Access,CN=Builtin,DC=na,DC=fabrikam,DC=com] Group Member(s):    None Atl-Users [CN=Atl-Users,CN=Users,DC=na,DC=fabrikam,DC=com] Group Member(s):    CN=LewJudy,OU=Sales,DC=na,DC=fabrikam,DC=com    CN=HuffArlene,OU=HR,DC=na,DC=fabrikam,DC=com    CN=MyerKen,OU=HR,DC=na,DC=fabrikam,DC=com 

Using Range Limits When Retrieving Multivalued Attributes

If a multivalued attribute contains many records, you can request a group of records in the attribute (rather than retrieve them all at once) by specifying Range Limits. This more evenly distributes the processing load placed on a domain controller servicing the request and, as a result, can improve the performance of the search operation. Also, if a multivalued attribute contains more than 1,000 entries, you must specify range limits, or the result set might not be complete.

The script in Listing 5.36 returns a result set containing the first 1,000 entries in the member multivalued attribute for the Atl-Users group in the na.fabrikam.com domain.

Note

• This script will fail if there are fewer than 1,000 members in the Atl-Users group. There must always be more members than the upper limit of the range (in this case, 999).

To specify range limits in a result set, the following modifications are made to the script:

1. Include the Range keyword in the query string to limit the result set to a certain number of entries contained in the member attribute (line 9). The range 0 999 returns the first 1,000 entries in the member attribute of the Atl-Users group.
2. Echo the phrase, "First 1000 Members:" to the screen (line 13).

   This phrase will appear ahead of the entries that are returned from the member attribute of the Atl-Users group.

3. Initialize a variable named arrMembers with the contents of the member attribute contained in the fields property of the RecordSet object. Within the fields property, specify a range limit that instructs the script to return the first 1,000 records (line 14).

   You must specify the Range Limit in the Fields property of the RecordSet object exactly as it was specified in the query string.

Listing 5.36   Searching for Group Membership Using Range Limits

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 21 

Set objConnection = CreateObject("ADODB.Connection") objConnection.Open "Provider=ADsDSOObject;" Set objCommand = CreateObject("ADODB.Command") objCommand.ActiveConnection = objConnection objCommand.CommandText = _    "<LDAP://cn=Atl-Users,cn=Users,dc=NA,dc=fabrikam,dc=com>;;" & _        "member;Range=0-999;base" Set objRecordSet = objCommand.Execute Wscript.Echo "First 1000 Member(s):" arrMembers = objRecordSet.Fields("member;Range=0-999")   For Each strMember in arrMembers     Wscript.Echo vbTab & strMember Next objConnection.Close

When this script runs in the na.fabrikam.com domain, it echoes a list containing the first 1,000 members in the Atl-Users Group to the command window, as shown in the following abbreviated result set:

First 1000 Member(s):         CN=UserNo988,CN=Users,DC=na,DC=fabrikam,DC=com         CN=UserNo987,CN=Users,DC=na,DC=fabrikam,DC=com         CN=UserNo986,CN=Users,DC=na,DC=fabrikam,DC=com               ...         CN=HuffArlene,OU=HR,DC=na,DC=fabrikam,DC=com         CN=MyerKen,OU=HR,DC=na,DC=fabrikam,DC=com 

Important observations about the scripts in this section are:

• They perform the same basic steps:
  1. Create an ADO Connection object using the ADSI OLE DB provider.
  2. Create an ADO Command object, and associate it with the Connection object.
  3. Use the Command object to build a query string.
  4. Create a RecordSet object to run the query and store the result set.
  5. Use the RecordSet object to read each record in the RecordSet.
  6. Close the connection.
• With the exception of Listing 5.36, inside the While Wend statement the scripts echo the records in the result set to the command window. This step is not necessary in Listing 5.36 because the example script returns a single record containing the entries in the member attribute of the Atl-Users group.

Displaying a result set is the most rudimentary task that can be completed with a search operation. For other tasks that can be completed as a result of a search operation, see "Performing an Administrative Task Using a Result Set" later in this chapter.

---

 Send us your feedback

« Previous | Next »