Writing Multivalued Attributes

So far, our examples of how to modify attribute values have used properties and attributes that accept only a single value. We can use the Put method to write multivalued attributes as well, with the limitation that when you call Put it replaces all the current values of the attribute with whatever is contained in the variant array that is passed in.

For example, let's say the otherTelephone attribute has the values 111-1111, 222-2222, and 333-3333. The following code would replace those values with 444-4444 and 555-5555.

 objADs.Put "otherTelephone", Array("444-4444", "555-5555")
objADs.SetInfo 

The Put method is a blunt tool. You cannot use it to slice and dice the various values in a multivalued attribute—it's all or nothing. Of course, you could read all the values into your own data structure, manipulate the structure however you choose, and then write it back en masse using Put. However, for those who crave more control, ADSI gives it to you in the form of the PutEx method.

The PutEx Method

The PutEx method is a more sophisticated version of the Put method. It allows you to change or remove an existing value, append a new value, or clear all the values of the attribute. One scenario for using PutEx would be to add the organization's new toll-free telephone number to each user object without disturbing the existing values.

The PutEx method takes three parameters. The first is the control code, which tells ADSI how to treat multivalued attributes. The next two are the attribute name and the value or values to be written, the same as with the Put method.

The control code value is taken from one of the constants defined in the property control code enumeration (ADS_PROPERTY_OPERATION_ENUM). These constants are listed in Table 6-6.

Property Control Code Constant	Description
ADS_PROPERTY_CLEAR	Removes all values from the attribute
ADS_PROPERTY_UPDATE	Replaces the current values with new values passed in (same as Put)
ADS_PROPERTY_APPEND	Appends the passed value to the list of values for this attribute
ADS_PROPERTY_DELETE	Removes the specified value

Table 6-6 Control codes defined in ADS_PROPERTY_OPERATION_ENUM used with the PutEx method.

Appending Values

Here is an example using the otherTelephone attribute, which is multivalued. The following code, from the PutEx.bas sample on the companion CD, appends an array of telephone numbers to the otherTelephone attribute. You must always pass a variant array to PutEx, even if you may be working with only one value at a time.

 ` Bind to the object
Set objADs = GetObject(strADsPath)

` Use GetEx method to save original numbers as a variant array
varOrigNumbers = objADs.GetEx("otherTelephone")

` Append new numbers to the attribute
objADs.PutEx ADS_PROPERTY_APPEND, "otherTelephone", _
    Array("800-555-1111", "800-555-2222", "800-555-3333")

` Commit the change to the directory
objADs.SetInfo 

Active Directory will allow only a single instance of a value to exist in the attribute. If you run this code several times, it will not continue to append the phone numbers to the otherTelephone attribute. ADSI does not return an error code in this case.

In addition, Active Directory does not concern itself with the order of the attributes. The exact order is undefined and may vary. This is important for a series of numbers. If you write the values in a certain sequence, such as Array(1, 2, 3, 4, 5), they might not be returned in the same sequence.

Do not depend on the order of the values in a multivalued attribute.

Removing Values

To remove a particular value from an attribute you use the ADS_PROPERTY_DELETE control code.

 ` Delete value
objADs.PutEx ADS_PROPERTY_DELETE, "otherTelephone", _
    Array("800-555-1111", "888-888-8888") 

PutEx will not return an error code if one or more values did not exist.

Removing All Values

To remove all the values of a multivalued attribute, use the ADS_PROPERTY_CLEAR control code.

 ` Delete all the values of the attribute
objADs.PutEx ADS_PROPERTY_CLEAR, "otherTelephone", vbNullString 

You can pass anything in the value parameter of PutEx because it is ignored when ADS_PROPERTY_CLEAR is used. After removing all the values of an attribute and updating the directory with SetInfo, the attribute ceases to exist for that object. Subsequent retrievals will result in a "property not found" error. This is normal. See the section "Handling Errors in ADSI" earlier in the chapter for information about how to handle this error.

Updating Values

You can replace all the values at once using the ADS_PROPERTY_UPDATE control code. This is the same as using the Put method, but it works for multivalued attributes.

 ` Update the property value 
adsObj.PutEx ADS_PROPERTY_UPDATE, "otherTelephone", _
    Array("800-555-1111") 

None of the original values will remain. In this example, if there were previously three phone number values, all would be deleted and replaced with one value.

---

Active Directory Attribute Oddities

The otherTelephone attribute is different from the telephoneNumber attribute, which is mapped to the TelephoneNumber property. The otherTelephone attribute is multivalued, whereas telephoneNumber is not. These values can be viewed and changed using the Active Directory Users and Computers administrative tool. The first illustration below shows the Properties dialog box for the Administrator with the single-valued telephoneNumber attribute in the Telephone Number box. The second illustration shows the Phone Number (Others) dialog box displaying values for the multivalued otherTelephone attribute.

You would think that if an attribute can be multivalued, there would be no need for a single-valued version. However, that's not the case. Active Directory uses a multivalued version and a single-valued version for all its phone number attributes, as well as for other attributes. Here's a list of the single-valued and multivalued phone number attributes in Active Directory.

Single-Valued Attribute	Multivalued Attribute
facsimileTelephoneNumber	otherFacsimileTelephoneNumber
homePhone	otherHomePhone
IpPhone	otherIpPhone
Mobile	otherMobile
Pager	otherPager
telephoneNumber	otherTelephoneNumber

---