Step 2: Performing a Task

Microsoft® Windows® 2000 Scripting Guide

Creating and deleting objects by using a script are straightforward. After the script binds to a container object, you can either create or delete objects in the container. Reading and writing objects from a script are equally straightforward. After the script binds to an object, you can perform either a read or a write operation on the object.

When you call the Create, Put (modify), or Get (read) method to perform a task on a directory object, these operations do not occur against Active Directory. Instead, they are performed locally in a special area of memory called the local property cache. The local property cache contains one or more attributes of an Active Directory object. In contrast, the Delete method acts upon the object in Active Directory. A small number of other methods also operate in this way.

Any changes you make are initially made only on the locally cached objects. To apply the changes to the actual objects in Active Directory, you need to call the SetInfo method.

Task Code

If you review all of the listings shown in each task section, you will notice that the task code of each script contains the name of the object variable that you initialized in the binding step, a dot, and the name of the task, as shown in the following list:

• objVariableName.Create

  To create an object in the container specified by objVariableName

• objVariableName.Get

  To read an attribute of the object specified by objVariableName

• objVariableName.Put

  To modify or write an attribute of the object specified by objVariableName

• objVariableName.Delete

  To delete an object in the container specified by objVariableName

The Create and Delete names are easy to remember because they are synonymous with the task. Use Get to read an attribute, and use Put to modify or write an attribute. In ADSI scripting, these tasks are called methods. Methods perform a task against an object.

Method Parameters

Each method - Create, Get, Put, and Delete - uses syntax specific to the task at hand. The task of creating an object requires you to define the type of object you want to create and give the object a name. On the other hand, the task of reading an attribute requires you to name the attribute you want to read. The required items that a method expects are called the method's parameters.

Create parameters

The Create method requires two parameters, the class name and the relative distinguished name of the object you want to create. A relative distinguished name is the part of an object's name that identifies an object as unique within the container where it is located. A relative distinguished name consists of a naming attribute and a value to be assigned to the object.

Consider the following examples from previous listings:

• Set objOU = objDomain.Create("organizationalUnit", "ou=HR")

  Creates an OU

  The class name is organizationalUnit, the naming attribute is ou, and the value assigned to the object is HR. Thus, the relative distinguished name is ou=HR.

• Set objUser = objOU.Create("user", "cn=MyerKen")

  Creates a user account

  The class name is user, the naming attribute is cn, and the value assigned to the object is MyerKen. Thus, the relative distinguished name is cn=MyerKen.

• Set objGroup = objOU.Create("group", "cn=Atl-Users")

  Creates a group

  The class name is group, the naming attribute is cn, and the value assigned to the object is Atl-Users. Thus, the relative distinguished name is cn=Atl-Users.

Like the binding string, the Create method requires the VBScript Set statement and a variable to serve as a reference to the object created by the method. The object is created in local memory.

Important

• If you write a script to create an object or modify an attribute and the changes requested in the script are not reflected in Active Directory, verify that you included the SetInfo method call in your script.

Just as binding to an object or a container in Active Directory creates an object reference (virtual representation of an object) in local memory, the Create method also creates a virtual representation of an object in local memory. The difference is that the object did not come from Active Directory. Instead, it was created locally by the script, separate from a binding string. The Create method provides an object reference to the local object. You use this object reference to modify the object and ultimately to commit the object to Active Directory.

Figure 5.4 shows the pieces of the three create methods in the previous listings:

Figure 5.4 Comparison of Three Create Method Calls

Modify parameters

The Put method requires two parameters: the name of the attribute (its lDAPDisplayName) and the value you will assign the attribute.

ADSI expects a certain type of attribute name, called the lDAPDisplayName, for completing read and write operations. Attributes are assigned a number of names, but the lDAPDisplayName is common to most ADSI scripts.

Consider the following examples from previous listings:

• objOU.Put "description", "Human Resources"

  Writes an attribute of an OU

  The lDAPDisplayName of the attribute to modify is description, and the value assigned to the attribute is Human Resources.

• objUser.Put "description", "HR employee"

  Writes an attribute of a user account

  The lDAPDisplayName of the attribute to modify is description, and the value assigned to the attribute is HR employee.

• objOU.Put "description", "Atlanta users"

  Writes an attribute of a group

  The lDAPDisplayName of the attribute to modify is description, and the value assigned to the attribute is Atlanta users.

The write operation also appears in the Create task scripts when an object being created contains one or more mandatory attributes that must be assigned values before the object is committed to the directory. Objects cannot be created without configuring those mandatory attributes to which values are not automatically assigned by Active Directory.

The following examples from previous listings illustrate writing a manatory attribute:

• objUser.Put "sAMAccountName", "myerken"

  Writes a mandatory attribute (sAMAccountName) of a user account

• objUser.Put "sAMAccountName", "atl-users"

  Writes a mandatory attribute (sAMAccountName) of a group

Mandatory attributes are defined in Active Directory. For information about how to determine the mandatory attributes of an object, see "Active Directory Architecture" later in this chapter.

Read parameters

The Get method (read task) requires a single parameter, the lDAPDisplayName of the attribute to read. In line 2 of Listing 5.8 and line 3 of Listing 5.9 and Listing 5.10, the description attribute was read.

The goal of Listing 5.8 through Listing 5.10 was to read and display the value of an attribute. Therefore, VBScript's Wscript.Echo statement appears with the call to the Get method to display information on the screen, as shown in the following examples from previous listings:

• Wscript.Echo objOU.Get("description")

  Reads and displays the description attribute of an OU

• Wscript.Echo objUser.Get("description")

  Reads and displays the description attribute of a user account

• Wscript.Echo objGroup.Get("description")

  Reads and displays the description attribute of a group

Delete parameters

Like the Create method, the Delete method requires two parameters: the type of object you want to delete and the relative distinguished name of the object.

These parameters are illustrated in the following examples from previous listings:

• objOU.Delete "group", "cn=Atl-Users"

  Deletes a group

  The class name is group, and the relative distinguished name of the object to delete is cn=Atl-Users.

• objOU.Delete "user", "cn=MyerKen"

  Deletes a user account

  The class name is user, and the relative distinguished name of the object to delete is cn=MyerKen.

• objDomain.Delete "organizationalUnit", "ou=HR"

  Deletes an OU

  The class name is organizationalUnit, and the relative distinguished name of the object to delete is ou=HR.