Modifying a Multivalued Attribute

  • Article

Microsoft® Windows® 2000 Scripting Guide

The PutEx method can modify assigned entries in multivalued attributes by specifying either append or delete operations as the first argument of the method. The append control code (ADS_PROPERTY_APPEND) adds to the entries already stored in a multivalued attribute, and the delete control code (ADS_PROPERTY_DELETE) removes specified entries from the multivalued attribute.

Using PutEx to perform modifications to multivalued attributes is efficient because a single trip to the server is all that is required to perform modifications. ADSI does not check Active Directory first to modify the entries in multivalued attributes. When a modification request is received using the SetInfo method, the control code is sent with the modification request and Active Directory performs the identified action.

To confirm that an entry has been modified, use the GetInfo (or GetInfoEx) method to retrieve the modified entry or entries from Active Directory.

Note

  • Even though the description attribute is multivalued, it behaves like a single-valued attribute when performing append or delete operations because it can contain a maximum of one entry. This is to allow for pre-Active Directory compatibility, and this attribute behaves as a single-valued attribute only for security principals such as the user account object.

Scripting Steps

There are multiple ways to modify a multivalued attribute:

  • Adding an entry to a multivalued attribute

  • Removing an entry assigned to a multivalued attribute

Adding an entry to a multivalued attribute

Listing 7.14 contains a script that demonstrates how to add an entry to a multivalued attribute on the General properties page. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_APPEND constant equal to the control code parameter used by the PutEx method to indicate the mode of modification (used on line 6).

    This control code appends an entry to a multivalued attribute.

  2. Bind to the user account object by using the GetObject function and the LDAP provider.

  3. Use the PutEx method of IADs to append the https://www.fabrikam.com/policy entry to the url attribute.

    If the https://www.fabrikam.com/policy entry is already assigned to the multivalued attribute, PutEx does not add a duplicate entry.

  4. Commit the change to the user account object in the local property cache to Active Directory.

Listing 7.14 Appending an Entry to a Multivalued Attribute

   
1
2
3
4
5
6
7
8
9

Const ADS_PROPERTY_APPEND = 3
Set objUser = GetObject _
 ("LDAP://cn=MyerKen,ou=Management,dc=NA,dc=fabrikam,dc=com")
objUser.PutEx ADS_PROPERTY_APPEND, _
 "url", Array("https://www.fabrikam.com/policy")
objUser.SetInfo

Removing an entry assigned to a multivalued attribute

Listing 7.15 contains a script that demonstrates how to use the delete operation of PutEx to remove an entry assigned to a multivalued attribute on the General properties page. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_DELETE constant to the control code parameter used by the PutEx method to indicate the mode of modification (used on lines 69).

    This control code deletes an entry from a multivalued attribute.

  2. Bind to the user account object by using the GetObject function and the LDAP provider.

  3. Use the PutEx method of IADs to delete the (425) 707-9790 entry in the otherTelephone attribute.

    The script in Listing 7.13 added this value to the otherTelephone multivalued attribute by using the PutEx and the ADS_PROPERTY_UPDATE control code. If the (425) 707-9790 entry was not previously assigned to the multivalued attribute, PutEx simply ignores the delete operation.

  4. Commit the change to the user account object in the local property cache to Active Directory.

Listing 7.15 Deleting an Entry in a Multivalued Attribute

   
1
2
3
4
5
6
7
8
9
10
11

Const ADS_PROPERTY_DELETE = 4
Set objUser = GetObject _
 ("LDAP://cn=MyerKen,ou=Management,dc=NA,dc=fabrikam,dc=com")
objUser.PutEx ADS_PROPERTY_DELETE, _
 "otherTelephone", Array("(425) 707-9790")
objUser.PutEx ADS_PROPERTY_DELETE, _
 "initials", Array("E.")
objUser.SetInfo

In Listing 7.13 through Listing 7.15, all PutEx operations are committed using a single SetInfo method call. However, whenever you perform more than one operation on the same multivalued attribute, you must commit the change for each operation before continuing to the next operation. Consider the following code example:

objUser.PutEx ADS_PROPERTY_DELETE, "otherTelephone", Array("(425) 707-9790")
objUser.PutEx ADS_PROPERTY_APPEND, "otherTelephone", Array("(425) 707-9791")
objUser.SetInfo

The number (425) 707-9791 is added as an entry to the otherTelephone attribute when SetInfo is called, but the number (425) 707-9790 is not deleted.

Another important nuance of using PutEx is that the order of the entries stored in multivalued attributes is not guaranteed. For example, suppose you enter three telephone numbers: (425) 707-9791, (425) 707-9792, and (425) 707-9793. If you write a script that returns these phone numbers, the data might be returned in this order instead: (425) 707-9792, (425) 707-9791, and (425) 707-9793.

Therefore, whenever you write scripts that operate on multivalued attributes, do not depend on a specific ordering of entries.