Export (0) Print
Expand All

Modifying Multivalued Attributes

Microsoft® Windows® 2000 Scripting Guide

When an attribute can contain multiple values or entries, there are a number of possible modifications:

  • Clear all entries. Clearing all entries removes the attribute from the target object. From the perspective of an ADSI script, when the attribute contains no values it is no longer a part of the object.

  • Update all entries. Updating all entries removes any existing entries and then writes one or more new entries to the attribute.

  • Append an entry. Appending an entry adds one or more values to the attribute while preserving any existing entries.

  • Delete an entry. Deleting an entry removes one or more values from the attribute while preserving any other existing entries.

Regardless of the type of multivalued attribute modification you want to make, you can use the PutEx method to make the modification. When you call the PutEx method in a script, the first parameter (also known as an argument) of the method designates the type of update you want to make, the second argument designates the attribute to be modified, and the third argument designates the values to set. Table 5.2 shows the arguments of the PutEx method.

Table 5.2 PutEx Arguments

Argument

Type

Required

Default

Description

Control Code

Integer (long)

Yes

None

The value 1 clears all entries, the value 2 updates all entries, the value 3 appends one or more entries, and the value 4 deletes one or more entries.

Attribute

String

Yes

None

The lDAPDisplayName of the attribute to be modified.

Value

Variant (array)

Yes

None

To update, append, or delete entries, surround each value with quotes and, if specifying multiple values, delimit each value with a comma.

To clear an attribute, set this parameter to 0.

Tip

  • To make your ADSI scripts easier to read, use constants to designate the values of the PutEx control code parameter. The constants are:

    • ADS_PROPERTY_CLEAR = 1

    • ADS_PROPERTY_UPDATE = 2

    • ADS_PROPERTY_APPEND = 3

    • ADS_PROPERTY_DELETE = 4

  • One or more of these constants appears in all scripts in this chapter that use the PutEx method.

Modifying multivalued attributes of Active Directory objects involves three basic steps. Note that defining a constant for the control code parameter is optional, so it does not appear in the following steps.

  1. Bind to the Active Directory object you want to modify.

  2. Perform clear, update, add, or delete operations on one or more of an object's multivalued attributes.

  3. Commit the change to Active Directory.

The goal of the first four scripts that appear in this section is to manage group membership by modifying the member multivalued attribute of the Atl-Users global group. The attribute will be modified by updating all members, adding a member, deleting a member, and clearing all members, in that order. The fifth script in this section shows how to update multivalued attributes of a user account object. The purpose of this script is to demonstrate how administering multivalued attributes is similar from one object to the next.

Restrictions in performing modifications by using the PutEx method

PutEx does not allow you to add duplicate entries to a multivalued attribute. For example, you cannot add duplicate telephone numbers to the otherTelephone attribute of a user account object or add duplicate user accounts to the member attribute of a group object. PutEx does not report an error if a script attempts to add a duplicate entry. However, when the SetInfo method is called, the script will fail and report that the object already exists.

PutEx will report an error if you attempt any attribute modification and specify a nonexistent object for an object-dependent entry. That is, if the entry a script attempts to add specifies an Active Directory object that does not exist, the script will end and report that there is no such object on the server. For example, if a script attempts to add the distinguished name of a user account to a Group but the user account object does not exist, the script will fail.

PutEx also does not require an entry to be present to attempt a delete operation. If a script specifies a nonexistent value to delete, PutEx will run normally but will not report an error. However, when the SetInfo method is called, the script will fail and report that the server is unwilling to process the request.

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



objUser.PutEx ADS_PROPERTY_DELETE, "otherTelephone", Array("555-1080")
objUser.PutEx ADS_PROPERTY_APPEND, "otherTelephone", Array("555-1010")
objUser.SetInfo

The number 555-1010 is added as an entry to the otherTelephone attribute when SetInfo is called, but the number 555-1080 is not deleted. To commit both changes to the directory, use this code instead:



objUser.PutEx ADS_PROPERTY_DELETE, "otherTelephone", Array("555-1080")
objUser.SetInfo
objUser.PutEx ADS_PROPERTY_APPEND, "otherTelephone", Array("555-1010")
objUser.SetInfo

Another important nuance of using PutEx is that the order of the entries stored in multivalued attributes is not guaranteed. Therefore, whenever you write scripts that operate on multivalued attributes, do not depend on a specific ordering of entries.

Clearing multivalued and single-valued attributes with the PutEx method

Using the PutEx method to clear attributes applies to both single and multivalued attributes. It is important for single-valued attributes because the Put method cannot completely clear an attribute. For example, you cannot specify NULL or "" for an attribute's value when calling Put. In addition, although the following code will work to update the telephoneNumber attribute, the resulting telephoneNumber attribute is not empty. Instead, it contains a single space.



objUser.Put "telephoneNumber", " "

Therefore, PutEx is the only method capable of completely clearing one or more entries from an attribute.

Updating a Multivalued Attribute of a Group

The script in Listing 5.14 modifies the member attribute of the group named Atl-Users. The member attribute is updated so that it contains two members. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_UPDATE constant equal to the control code parameter used by the PutEx method to indicate this mode of modification (used in lines 5-9).

    This control code replaces any existing entries in a multivalued attribute.

  2. Bind to the Atl-Users group in the HR OU of the na.fabrikam.com domain.

  3. Update the object's member attribute by assigning the distinguished names of the MyerKen and LewJudy user accounts to it. Because PutEx is designed to work with multiple attributes, the two user accounts must be passed to the method in an array.

    Notice that the MyerKen user account is located in the HR OU and the LewJudy user account is located in the Sales OU, both in the na.fabrikam.com domain.

  4. Commit the change to the group in Active Directory.

    Because an update operation is specified in the script, any existing members of the Atl-Users group are removed.

Listing 5.14 Updating the member Attribute of a Group

  
1
2
3
4
5
6
7
8
9


Const ADS_PROPERTY_UPDATE = 2
Set objGroup = GetObject _
 ("LDAP://cn=Atl-Users,ou=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.PutEx ADS_PROPERTY_UPDATE, _
 "member", Array("cn=MyerKen,ou=HR,dc=NA,dc=fabrikam,dc=com", _
 "cn=LewJudy,ou=Sales,dc=NA,dc=fabrikam,dc=com")

objGroup.SetInfo

Appending an Entry to a Multivalued Attribute of a Group

The script in Listing 5.15 appends an entry to the member attribute of the group named Atl-Users. Assuming that the script in Listing 5.14 has been run, the script in Listing 5.15 appends an entry to the member attribute so that it contains a third member. 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 this mode of modification (used in lines 5-8).

    This control code adds one or more entries to a multivalued attribute.

  2. Bind to the Atl-Users group in the HR OU of the na.fabrikam.com domain.

  3. Append an entry to the object's member attribute by specifying the ADS_PROPERTY_APPEND constant, the member attribute, and the distinguished name of the YoungRob user account object.

    Notice that the YoungRob user account is located in the R&D OU in the na.fabrikam.com domain.

  4. Commit the change to the group in Active Directory.

    Because an append operation is specified in the script, any existing members of the Atl-Users group are preserved.

Listing 5.15 Appending an Entry to the member Attribute of a Group

  
1
2
3
4
5
6
7
8


Const ADS_PROPERTY_APPEND = 3
Set objGroup = GetObject _
 ("LDAP://cn=Atl-Users,ou=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.PutEx ADS_PROPERTY_APPEND, _
 "member", Array("cn=YoungRob,ou=R&D,dc=NA,dc=fabrikam,dc=com")

objGroup.SetInfo

Deleting an Entry from a Multivalued Attribute of a Group

The script in Listing 5.16 deletes an entry from the member attribute of the group named Atl-Users. Assuming that the scripts in Listing 5.14 and Listing 5.15 are run, the script in Listing 5.16 deletes an entry from the member attribute so that only two members remain. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_DELETE constant equal to the control code parameter used by the PutEx method to indicate this mode of modification (used in lines 5-8).

    This control code deletes one or more entries from a multivalued attribute.

  2. Bind to the Atl-Users group in the HR OU of the na.fabrikam.com domain.

  3. Delete an entry from the object's member attribute by specifying the ADS_PROPERTY_DELETE constant, the member attribute, and the distinguished name of the MyerKen user account object.

  4. Commit the change to the group in Active Directory.

    Because a delete operation is specified in the script, any existing members of the Atl-Users group are preserved except for the MyerKen user account.

Listing 5.16 Deleting an Entry from the member Attribute of a Group

  
1
2
3
4
5
6
7
8


Const ADS_PROPERTY_DELETE = 4
Set objGroup = GetObject _
 ("LDAP://cn=Atl-Users,OU=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.PutEx ADS_PROPERTY_DELETE, _
 "member", Array("cn=MyerKen,ou=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.SetInfo

Clearing a Multivalued Attribute of a Group

The script in Listing 5.17 clears the member attribute of the group named Atl-Users. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_CLEAR constant equal to the control code parameter used by the PutEx method to indicate this mode of modification (used in line 5).

    This control code clears a multivalued attribute so that, from the script's perspective, the attribute is empty and thus is no longer associated with the object.

  2. Bind to the Atl-Users group in the HR OU of the na.fabrikam.com domain.

  3. Clear the object's member attribute so that it is empty.

    Notice that the last parameter is set to 0. This value is necessary and must be specified in order to successfully clear an attribute.

  4. Commit the change to the group in Active Directory.

Listing 5.17 Clearing the member Attribute of a Group

  
1
2
3
4
5
6
7


Const ADS_PROPERTY_CLEAR = 1
Set objGroup = GetObject _
 ("LDAP://cn=Atl-Users,ou=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.PutEx ADS_PROPERTY_CLEAR,"member", 0

objGroup.SetInfo

Updating Multivalued Attributes of a User Account

Regardless of the Active Directory object, the way that you modify the multivalued attributes of an object is the same. To demonstrate this uniformity, the script in Listing 5.18 updates the url and otherTelephone multivalued attributes of the MyerKen user account. To carry out this task, the script performs the following steps:

  1. Set the ADS_PROPERTY_UPDATE constant equal to the control code parameter used by the PutEx method to indicate this mode of modification (used in lines 5-10 and lines 12 and 13).

  2. Bind to the MyerKen user account in the HR OU of the na.fabrikam.com domain.

  3. Update the object's url and otherTelephone attributes by assigning values to them.

    Notice that the values for the url attribute are in the form of Web addresses and that the values for the otherTelephone attribute are in the form of telephone numbers. However, unlike the member attribute of a group object, these attributes are not limited to specific string formats. In other words, you can insert values that do not comply with any defined format for a url or a telephone number.

  4. Commit the change to the group in Active Directory.

    Because an update operation is specified in the script, any existing values for these two attributes are removed.

Listing 5.18 Updating the url and otherTelephone Attributes of a User Account

  
1
2
3
4
5
6
7
8
9
10
11
12


Const ADS_PROPERTY_UPDATE = 2
Set objGroup = GetObject _
 ("LDAP://cn=MyerKen,ou=HR,dc=NA,dc=fabrikam,dc=com")

objGroup.PutEx ADS_PROPERTY_UPDATE, _
 "url", Array("http://www.microsoft.com", _
 "http://www.fabrikam.com/na","http://www.contoso.com")

objGroup.PutEx ADS_PROPERTY_UPDATE, _
 "otherTelephone", Array("555-0180", "555-0182", "555-0183")

objGroup.SetInfo

Important observations about the scripts in this section are:

  • They perform the same basic steps: They bind to an Active Directory object, modify a multivalued attribute of the object, and write the change to the corresponding Active Directory object.

  • They use the same method (PutEx) without regard to the class of object being modified.

    The PutEx method is similar to the Put method except that it requires a control code parameter to specify the type of modify operation.


Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft