Listing 2 shows how to use the paged-results control, which is a little more complicated than the server-side sort control. In the code at callout A in Listing 2, I import the LDAP_CONTROL_PAGED constant so that I can use the paged-results control. In the code at callout B in Listing 2, I set the search filter ($filter) to match any user object in the GC and the @attrs array, which will contain a list of attributes to return. Specifying the attributes you want to return is important because otherwise the query returns all attributes for each entry, which can greatly increase the time it takes to run the script and the amount of memory it requires.
The code at callout C in Listing 2 instantiates a new paged-results control object and sets the size parameter (i.e., the number of entries to be returned for each page) to 1000. If you specify a number larger than the administrative limit defined on the server, the script will revert to the defined administrative limit during the results processing. The next section of code at callout C defines the @args array, which contains the key/value pairs that are passed to the search() method. The search() method is part of a while loop so that the script will continue to call the method until the method returns no more entries. Inside the while loop, a foreach loop processes each entry returned in the current search page. Then, the code at callout C sets a cookie to inform the server that I want the next page of entries. If this call fails for any reason, the script exits the loop.
Tree Delete
Another important control to understand is the tree-delete control. As I show in "Querying and Updating AD, Part 2," you can use the delete() method of a Net::LDAP object ($ldap) to delete objects in the directory. The delete() method has one significant limitation: It can't delete containers or objects that are parents of other objects.
For example, if you tried to delete an organizational unit (OU) that contained 100 objects as follows:
$rc =
$ldap->delete($dn_to_delete);
you would receive the error message 0000208C: UpdErr: DSID-030A02AF, problem 6003 (CANT_ON_NON_LEAF), data 0. This error message states that you can't delete a nonleaf object (i.e., a container). The tree-delete control lets you delete a container and all its objects. The control was initially created as an Internet draft (http://www.alternic.org/drafts/drafts-a-b/draft-armijo-ldap-treedelete-02.html) and was intended to be an RFC, but the RFC was never formally made and the draft eventually expired. Nevertheless, AD supports this control.
The script in Listing 3 uses the tree-delete control to delete the OU container ou=sales,dc=mycorp,dc=com. The code at callout A in Listing 3 is similar to that of the previous two listings except that it doesn't use the Net::LDAP::Constant module. At publication time, the Net::LDAP modules didn't have a constant for the tree-delete control, so I had to create my own constant that returns the Object Identifier (OID) for the control. The OID is what the script actually passes to the Net::LDAP::Control module's new() method.
The code at callout B in Listing 3 contains some of the same configuration parameters as in Listing 1 and Listing 2 plus a $dn_to_delete variable, which contains the distinguished name (DN) of the object or container you want to delete. The code at callout C in Listing 3 first instantiates the tree-delete control object. The control doesn't require any additional parameters. To use the control, I specify in the delete() method a control parameter that points to an array reference that contains the tree-delete control object. The code at callout C finishes by checking for an error and printing the results.
Controls are an important feature of LDAP because they let you extend LDAP's functionality without breaking the LDAP specification. These examples of how to use the server-side sort, paged-search, and tree-delete controls should get you started using LDAP controls against AD.