Data Caching

  • Article

Microsoft® Windows® 2000 Scripting Guide

Thus far, little has been said about how ADSI scripts use the local property cache to complete read operations. You know from the preceding sections that you use either the Get or the GetEx method to perform read operations. Behind the scenes, both of these methods make implicit calls to the GetInfo method to retrieve attributes from Active Directory and load them into the local property cache. You can make an explicit call to GetInfo or use another method, GetInfoEx, to take control of the data loaded into the local property cache. For more information about the local property cache, see "Step 2: Performing a Task" earlier in this chapter.

Understanding how these four method calls interact with the local property cache will help you avoid accidentally overwriting values, and it can also help you make scripts operate more efficiently.

How the Get Method Retrieves Attributes

The Get method retrieves the value or values of attributes from the local property cache as either a string or a variant array, depending on the type of attribute and its contents:

  • Single-valued attributes. Get returns a string value.

  • Multivalued attributes containing a single entry. Get returns a string value.

  • Multivalued attributes containing more than one entry. Get returns a variant array of values.

Important

  • An attribute that does not contain a value is not considered by ADSI to be associated with an Active Directory object. Therefore, empty attributes are never downloaded to the local property cache.

All of the preceding examples suggest that you should always use Get for single-valued attributes and GetEx for multivalued attributes. Following this rule will simplify the scripting process because then you will not have to determine whether the values are returned as a string or a variant array. However, if you do know whether your target attribute is single-valued or multivalued and you know how many values an attribute contains, using Get is slightly more efficient than GetEx.

If the attribute is not already loaded into the local property cache, the Get method implicitly calls the GetInfo method. As a result, GetInfo loads most attributes into the local property cache, with the exception of operational attributes and attributes that have already been downloaded to the cache.

Operational attributes are attributes whose values are not stored in a directory service but are calculated by the domain controller when they are requested. For example, canonicalName is an operational attribute. Operational attributes are synonymous with constructed attributes.

If you use the Get method again in a script, the specific attribute requested will be retrieved from the property cache without any additional calls to the GetInfo method. Therefore, attribute values that already exist in the local property cache will not be overwritten by an implicit call to the GetInfo method.

How the GetEx Method Retrieves Attributes

The GetEx method always returns the value or values of the specified attribute from the property cache in a variant array. Thus, you must always use a statement such as For Each to read even a single-valued attribute. However, if you do not know whether an attribute is single-valued or multivalued, GetEx can be easier to use than Get because all returned data is packaged in a variant array. This means you can handle all attribute data using the same approach.

If the attribute is not already loaded into the local property cache, the GetEx method implicitly calls the GetInfo method to load all attributes of an object. Attribute values that already exist in the local property cache will not be overwritten by the implicit call to the GetInfo method.