Microsoft® Windows® 2000 Scripting Guide
« Previous | Next »
When an attribute can contain multiple values or entries, there are a number of possible modifications:
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
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.
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.
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.
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.
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:
This control code replaces any existing entries in a multivalued attribute.
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.
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
|
|
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:
This control code adds one or more entries to a multivalued attribute.
Notice that the YoungRob user account is located in the R&D OU in the na.fabrikam.com domain.
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
|
|
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:
This control code deletes one or more entries from a multivalued attribute.
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
|
|
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:
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.
Notice that the last parameter is set to 0. This value is necessary and must be specified in order to successfully clear an attribute.
Listing 5.17 Clearing the member Attribute of a Group
|
|
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:
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.
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
|
|
Important observations about the scripts in this section are:
The PutEx method is similar to the Put method except that it requires a control code parameter to specify the type of modify operation.
Send us your feedback | « Previous | Next » |