Searching with ActiveX Data Objects (ADO)

The ActiveX® Data Object model consists of the following objects:

Connection

An open connection to an OLE DB data source such as ADSI.

Command

Defines a specific command to execute against the data source.

Parameters

An optional collection for any parameters to provide to the command object.

Recordset

A set of records from a table, command object, or SQL syntax. A recordset can be created without any underlying Connection object.

Field

A single column of data in a recordset.

Property

A collection of values supplied by the provider for ADO.

Error

Contains details about data access errors, refreshed for each time an error occurs in a single operation.

In order for ADO to communicate with ADSI, you need to have at least three ADO objects: Connection, Command, and RecordSet. These ADO objects serve to authenticate users, initiate queries, and enumerate results, respectively. The Connection object loads the OLE DB provider, and validates user credentials. In Visual Basic, you call CreateObject("ADODB.Connection") to create an instance of a Connection object, and then set the Provider property of the Connection object to "ADsDSOObject". "ADODB.Connection" is the ProgID of the Connection object and "ADsDSOObject" is the name of the OLE DB provider in ADSI. If no credentials are specified, the credentials of the currently logged on user are assumed.

The following code snippet illustrates how to create an instance of a Connection object using VBScript.

Set con = CreateObject("ADODB.Connection")
con.Provider = "ADsDSOObject"

The next example is an equivalent Active Server Page (ASP) code snippet.

<%
Set con = Server.CreateObject("ADODB.Connection")
con.Provider = "ADsDSOObject"
%>

Here is the same example in Visual Basic. Note that you must include the ADO type library (msadoXX.dll) as one of the references in the Visual Basic project.

Dim Con As New Connection
con.Provider = "ADsDSOObject"

You can specify user authentication data by setting the properties of the Connection object. The following properties supported by ADSI are listed in the following table. The ADSI Flag property allows you to set any binding authentication options from the ADS_AUTHENTICATION_ENUM enumeration.

This example shows how the properties are set before creating the Command object.

Set oConnect = CreateObject("ADODB.Connection")
oConnect.Provider = "ADsDSOObject"
oConnect.Properties("User ID") = stUser
oConnect.Properties("Password") = stPass
oConnect.Properties("Encrypt Password") = True
oConnect.Open "DS Query", stUser, stPass
 
Set oCommand = CreateObject("ADODB.Command")
Set oCommand.ActiveConnection = oConnect

The second ADO object is the Command object. The ProgID is "ADODB.Command". This object lets you issue query statements and other commands to ADSI using the active connection. The Command object uses its ActiveConnection property to maintain an active connection. It also maintains the CommandText property to hold query statements issued by a user. The query statements are expressed in either the SQL dialect or the LDAP dialect. The following code snippets illustrate how to create a Command object.

VBScript example:

Set command = CreateObject("ADODB.Command")
Set command.ActiveConnection = con
command.CommandText = 
"SELECT AdsPath, cn, FROM 'LDAP://DC=Microsoft,DC=com' 
 WHERE objectClass = '*'"

Visual Basic example: Note you must include ADO type library (msadoXX.dll) as one of the references.

Dim command As New Command
Set command.ActiveConnection = con
command.CommandText = 
    "<LDAP://DC=Microsoft,DC=com>;(objectClass=*);AdsPath, cn; subTree"

You can specify search options by setting the property of the Command object actually called Property. Acceptable properties are listed in the following table.

The following code example illustrates how to set search options in Visual Basic.

Dim Com As New Command
 
Com.Properties("Page Size") = 1000
Com.Properties("Timeout") = 30     'seconds
Com.Properties("searchscope") = ADS_SCOPE_ONELEVEL     'Define in ADS_SCOPEENUM
Com.Properties("Chase referrals") = ADS_CHASE_REFERRALS_EXTERNAL
Com.Properties("Cache Results") = False     'do not cache the result set

The third ADO object is RecordSet. You obtain this object when you invoke the Execute method on a Command object. The primary function of the RecordSet object is to enumerate the result set and obtain the data. The result set can contain values for attributes that have both single or multiple values. Getting a single-valued attribute is straightforward, similar to getting the column value in the relational database (for example, Fields('name').Value). Getting an attribute with multiple values, however, is more challenging. In this case, the Field.Value is an array and you must check the lower and upper bound of the array, as illustrated in the following example.

Set rs = Com.Execute
 
For i = 0 To rs.Fields.Count - 1
  Debug.Print rs.Fields(i).Name, rs.Fields(i).Type
Next i
 
'--------------------------
'Navigate the record set.
'--------------------------
rs.MoveFirst
lstResult.Clear      'Clear the user interface.
While Not rs.EOF
For i = 0 To rs.Fields.Count - 1
    'For Multi Value attribute
    If rs.Fields(i).Type = adVariant And Not (IsNull(rs.Fields(i).Value)) Then
        Debug.Print rs.Fields(i).Name, " = "
        For j = LBound(rs.Fields(i).Value) To UBound(rs.Fields(i).Value)
            Debug.Print rs.Fields(i).Value(j), " # "
            lstResult.AddItem rs.Fields(i).Value(j)
        Next j
    Else
        'For Single Value attribute.
         Debug.Print rs.Fields(i).Name, " = ", rs.Fields(i).Value
         lstResult.AddItem rs.Fields(i).Value
    End If
Next i
rs.MoveNext
Wend

The following example disables the user accounts on an LDAP server using Visual Basic.

Dim X as IADs
Dim con As New Connection, rs As New Recordset
Dim MyUser As IADsUser
 
con.Provider = "ADsDSOObject"
con.Open "Active Directory Provider", "CN=Foobar,CN=Users,DC=MICROSOFT,DC=COM,O=INTERNET", "Password"
Set rs = con.Execute("<LDAP://MyMachine/DC=MyDomain,DC=Microsoft,DC=com>;(objectClass=User);ADsPath;onelevel")
 
While Not rs.EOF
    ' Bind to the object to make changes 
    ' to it since ADO is currently read-only.
    MyUser = GetObject(rs.Fields(0).Value)
    MyUser.AccountDisabled = True
    rs.MoveNext
Wend

For more information about the ADO object model, see ActiveX Data Objects.