For the purposes of this article, we'll assume that the script is interactive, and relies on the invoker to supply valid credentials. We'll further assume that the login context is already known (alternatively, the invoker could supply a fully-qualified Object name). This code builds on Example 1:

Changing the eDirectory context for the script is merely a matter of writing a new value into the FullName Property of the eDirectory Object, although the context must be one into which the Public Object may change context:

Note that it is possible to force your script to use a specific server in the Tree as its Preferred Server, if you want to ensure that you connect to the server holding a replica, or the Master replica, of the partition with the objects you're targeting:

Again, this is simply a matter of writing to the appropriate Property of the eDirectory Object. While any server in the Tree can execute the code presented, you might set the Preferred Server to avoid excess eDirectory traffic.

We're now ready to solicit credentials from the invoker:

At this point, we've set a context for logging in, a preferred server, and have (hopefully) valid credentials for the eDirectory Tree. The easiest way to find out if they are valid is to try to login with the login() method; it will return FALSE if the login fails, although it's not possible to tell why it failed (for example, to distinguish an invalid password from a non-existent user). The call is very similar to the eDirectory Object instantiation:

Of course, it's also important to be able to log out. If you allow your script to end without logging out, the connection won't be cleared and resources may not be released. Logging out is very simple:

Once you have successfully logged in, then during future method calls, you should check method return codes as opposed to using the or die construct, as you want to log out before killing your script.

For the purposes of this article, we'll limit ourselves to opening a local file for writing progress messages and debugging information, and build on the code from Example 2:

Again, it is important that you not simply use the or die construct to exit your script if the file operation fails - remember to log out first. Similarly, if you open a file, then be sure to close it before logging out and exiting the script.

While it is possible for your Perl script to write its log to the SYS: Volume, I specifically recommend against doing so in practice, especially during initial development of your scripts. If your script gets stuck in a loop that includes writing to the file, then since infinite-looping scripts cannot be aborted, it is possible for your script to run the SYS: Volume out of disk space, which can crash the server and have far-reaching consequences to any eDirectory replicas it hosts. Write your files elsewhere whenever possible. If you must write to SYS:, consider applying an appropriate Directory Size Limit, which applies even to Supervisor-equivalent accounts.

Once you've authenticated, as in Example 3, your script is free to change context within the Tree, as permitted by the credentials under which it is logged in. Again, changing context is simply a matter of writing the new context to the FullName Property of the eDirectory Object:

There is no return code or error check. You'll only detect an error when you call a context-sensitive method and it fails.

The first step in searching is to construct a Filter Object. This is done with a simple method call to the eDirectory Object, so let's use the eDirectory Object from Example 3:

By default, the Filter will search in the current context of the eDirectory Object (the value of the FullName Property) when the Filter Object was instantiated. You may change this by writing a different value into the SearchContext Property of the Filter Object:

Next, we want to define a search Scope. It's possible to search your entire eDirectory Tree with a single Filter, but let's limit ourselves to just the current OU:

There are three possible Scope values, each with a pre-defined name and a corresponding integer value. The names should be interpreted with respect to the eDirectory Object, not the current context. This is a subtle and potentially confusing distinction:

If you wanted to search the entire Tree, you'd simply set the eDirectory object's context to [Root] ("nds:\\\\$Tree\\"), instantiate the Filter object, and set the Scope to SEARCH_SUBTREE.

Now that you've set a Scope, you need to formulate the Search. A Search is made up of Expressions, and can be complex, using multiple criteria with Boolean logic. For the purposes of this article, we'll construct a very simple Search that looks for User Objects only:

Once you have listed all the Expressions in the Search, you need to terminate the list of Expressions:

In preparation to execute the Search, we need to initialize a pointer to the list of the eDirectory Objects we expect to be returned:

Finally, we conduct the Search by applying the Filter to the eDirectory Object:

The return value is a pointer to the list of matching Objects, or NULL if the Filter failed to find any Objects. In the former case, we must reset the list pointer to the start of the list. We can also see how many Objects matched the Search criteria:

Again, it is important to detect and handle error conditions gracefully, rather than just using the or die construct.

Once you have obtained a list of matching Objects, you may step through them using a while loop, controlled using the return value of the HasMoreElements() method:

The HasMoreElements() method will return FALSE when the end of the list of Objects is reached. You can use the Reset() method to return the pointer back to the start of the list. $Entry is a pointer to the current Object.

As an alternative to a Search, if you know the Value of the Full Name Attribute of an eDirectory Object, you can use the Item() method of the $Entries Object to find it. The example code below leverages the code in Example 3, and works in whatever happens to be the current context of the eDirectory Object (so if you want to look elsewhere, first change context by altering the FullName Property of the eDirectory Object, as shown in Example 4).

After declaring our local variables for pointers and to hold the Full Name of the User we're looking for, we'll set a pointer to the list of Objects - all Objects, not just User Objects - that are in the current context of the eDirectory Object. We'll then use the Item() method to find our specific target in that list. The result will be NULL if no match is found, or else a pointer to the specific Object we're looking for:

You can also use this code example to locate a specific Object within the list of Objects returned by a Search. If we were to assume that the Search in Example 5 was successful and $Entries was a pointer to the list of Objects returned, then the Item() method will work against that list:

Note that because the Search presented in Example 5 encompassed a sub-tree, we don't know the exact context in which $TargetObject was found. We only know the context of the Filter Object when the Search was performed.

Every Object in eDirectory is associated to a Layout, defined by the eDirectory schema. You can enumerate all of the Layouts in your eDirectory environment by obtaining the list of Layouts from the eDirectory Object. Here, we build on Example 3 by declaring some local variables for accessing the list of Layouts, and displaying some of their Properties:

Each Layout specifies the Attributes of the associated Objects. The Layout() and Fields() methods can be used to enumerate the structure of an Object. This code example assumes that $Entry is already pointing to a User object (as it would in Example 5). We'll declare some local variables, retrieve the Layout for the User Object, and then enumerate the Fields (Attributes) in the Layout:

Finally, you can retrieve the eDirectory Syntax, the description of each Attribute defined in eDirectory. This can tell you if a specific Attribute is a simple data type (e.g. an integer, a BOOLEAN) or a complex data type (e.g. a path, time, an ACL). Additionally, you can find out if an Attribute is single-Valued or multi-Valued, and removable or non-removable. Here, we build on Example 3 and declare some local variables to contain the data we access, obtain the list of Attribute types, the step through the list, displaying the properties of each:

Even for a basic modern eDirectory Tree, the outputs from these three code examples could be quite extensive. For instance, just the User Object Class is defined, by default, with about 200 Attributes (including the ones it inherits). Modern eDirectory easily exceeds a total of a thousand defined Attributes in most cases, and defines over 170 Layouts. Knowing and understanding this information is crucial to being able to leverage eDirectory to its full power as a business advantage.

In this code example, we'll read the CN (aka Common Name), Full Name and Description Attributes of each User Object in our list (as returned by the Search in Example 5, and referenced by $Entry). Because Description is a Multi-Valued Attribute (MVA), we must read it into an array. We can also print out the Values, if there are any (since CN is a required Attribute of a User Object, we know the User Objects will have one):

The output should look something like this made-up example:

We'll build on Example 3, declaring some variables that are simply hard-coded with the data for the new User Object, and getting a pointer to the list of Objects in the current context. We'll create the Object with the AddElement() method, then populate its Attributes with the SetFieldValue() method. Finally, the Update() method will commit the populated Object to eDirectory:

The AddElement() and SetFieldValue() methods work on the Object in memory; however, AddElement() will fail if an Object with the same CN already exists. Not until the Update() method has been successfully invoked is an Object actually created in eDirectory. Note that you can only determine success/failure of a method invocation. eDirectory error codes are not returned by the UCS APIs.

Objects are created in the current context, as stored in the FullName Property of the eDirectory Object.

Make sure the context is properly set before creating the Object.

These code examples assume that $Entry is a pointer to a User Object, already set (as shown in Example 5). We'll start with declaring variables for use in modifying the Object:

A) Change the Value of a Single-Valued Attribute

Changing the Value of an Attribute is done with the SetFieldValue() method. It is important to determine if the Attribute already has a Value, using the GetFieldValue() method, as an existing Value must be passed as the third parameter in the SetFieldValue() call.

$OldTitle = $Entry->GetFieldValue( "Title" );
if ( $OldTitle )
  # There is an existing Title, pass it as the
  # third parameter
  {
    $Return = $Entry->SetFieldValue("Title",$NewTitle,$OldTitle);
  }
else
  # The Title Attribute is empty, no third parameter
  {
    $Return = $Entry->SetFieldValue( "Title", $NewTitle );
  }
if ( $Return )
  {
    $Return = $Entry->Update();
    if ( $Return )
      {
        print LOGFILE "\nSuccessfully changed Title from ", $OldTitle, " to ", $NewTitle, "\n";
      }
    else
      {
        print LOGFILE "\nUpdate failed for Title field\n";
      }
  }
else
  {
    print LOGFILE "\nSetFieldValue failed for Title field\n";
  }

If you know the Attribute has no Value, perhaps because you have just created the Object, then you can skip the step of checking for it and simply omit the third parameter.

B) Change a Value of a Multi-Valued Attribute

The original AppNote article on this particular subject demonstrated using SetFieldValue() for MVAs and passing the arrays by reference. The APIs have changed, and when setting new Values for MVAs, its necessary to set each Value individually. Thus, to change the six Values of the Postal Address Attribute, SetFieldValue() must be called six times.

# Get the user's Full Name for the first line of the Postal Address
$NewPostalAddress[0] = $Entry->GetFieldValue( "Full Name", false );
if ( ! $NewPostalAddress[0] )
  # Full Name Attribute is blank, substitute CN, because
  # an Attribute Value cannot be set to NULL, and since
  # CN is a required Attribute, we know it will have a Value
  {
    $NewPostalAddress[0] = $Entry->GetFieldValue( "CN", false );
  }

# Get the old Value of the Postal Address; since this is an MVA, it
# returns an array, and the second parameter must be TRUE
@OldPostalAddress = $Entry->GetFieldValue( "Postal Address", true );
if ( @OldPostalAddress )
  {
  # The Value is currently empty
  for ( $cntrB=0 ; $cntrB < @NewPostalAddress ; $cntrB++);
    {
      $Return=$Entry->SetFieldValue("Postal Address", $NewPostalAddress[$cntrB]);
      if ( ! $Return )
        # Problem in SetFieldValue - exit loop
        {
          $cntrB = @NewPostalAddress;
        }
    }
  }
else
  {
    # The old Value must be overwritten
    for ( $cntrB=0 ; $cntrB < @NewPostalAddress ; $cntrB++);
      {
        $Return=$Entry->SetFieldValue("Postal Address", $NewPostalAddress[$cntrB],$OldPostalAddress[$cntrB]);
        if ( ! $Return )
          # Problem in SetFieldValue - exit loop
          {
            $cntrB = @NewPostalAddress;
          }
      }
  }

# Only attempt an Update if SetFieldValue was successful
if ( $Return )
  {
    $Return = $Entry->Update();
    if ( ! $Return )
      # Problem in Update
      {
        print "\nERROR: Update failed for Postal Address\n";
      }
  else
      # Success!
      {
        print "\nSuccessfully changed Postal Address\n";
      }
  }
else
  {
    print "\nERROR: SetFieldValue failed Postal Address [$cntrB]\n";
  }

While SetFieldValue() must be called for each Value of the MVA, the Update() method only needs to be called once per Object being changed. This is because SetFieldValue() only changes the Object in memory, and Update() commits the fully-changed Object to eDirectory.

C) Delete a Value from a Multi-Valued Attribute

The original AppNote omitted this concept entirely, and the API documentation does not explain this operation at all. If your set a string-type Value to a zero-length string with SetFieldValue(), the subsequent call to Update() will fail.

Deleting a Value is accomplished with the undef constant that is part of Perl, as shown in this code that removes the first Value in the Object's Description Attribute, while preserving any other Values:

@OldDescription = $Entry->GetFieldValue( "Description", true );
if ( @OldDescription )
  {
    $Return = $Entry->SetFieldValue( "Description", undef, $OldDescription[0] );
    if ( $Return )
      {
        $Return = $Entry->Update();
        if ( $Return )
          {
            print "Successfully changed Description\n";
          }
        else
          {
            print "\nERROR: Update failed for Description\n";
          }
      }
    else
      {
        print "\nERROR: SetFieldValue failed for Description\n";
      }
  }
else
  {
    print "Description Attribute has no Values\n";
  }

Again building on Example 5, we'll assume $Entry is pointing to a specific User Object. We'll declare a few local variables for recording information about the Object:

A) Alias

Helpfully, the Alias Property is a BOOLEAN indicating if the Object is an Alias:

$IsAlias = $Entry->Alias();
print "\nObject ", $Entry->GetFieldValue( "CN", false ), " is ";
if ( $IsAlias )
  {
    print " an Alias\n";
  }
else
  {
    print " not an Alias\n";
  }

B) Locked Out

Using the GetFieldValue() method, you can retrieve the BOOLEAN Value indicating if the User Object has been locked out by Intruder Detection:

$IsLockedOut = $Entry->GetFieldValue( "Locked By Intruder", false);
if ( $IsLockedOut )
  {
    print "\nObject ", $Entry->GetFieldValue( "CN", false ), " is locked out\n";
  }

C) Disabled

Similarly, there is a BOOLEAN Value showing if the User Object has had its logins Disabled:

$IsDisabled = $Entry->GetFieldValue( "Login Disabled", false);
if ( $IsDisabled )
  {
    print "\nObject ", $Entry->GetFieldValue( "CN", false ), " is disabled\n";
  }

Coding Pitfalls and Debugging

The lack of Perl-specific documentation for the UCS APIs is perhaps the most limiting aspect of coding tools to use them. An example is the fact that using the undef Perl constant to delete a Value from an MVA is, as of this writing, completely undocumented.

It is important to note that the SetFieldValue() method only changes the Object in memory. The changes are not actually made until the Update() method is called. It's also possible for the SetFieldValue() method to succeed and a problem not show until Update() is used.

Another limiting factor is the fact that eDirectory errors are not returned via the APIs, only simple success/failure. You will need to use DSTRACE.NLM to capture the eDirectory error codes. These NetWare console commands will help you do that:

Setting the PrefServer Property of the eDirectory Object, as shown in Example 2, can be used to limit where you would need to run DSTRACE.NLM. Optimally, the Preferred Server will host a Master or Read/Write Replica of every Partition holding an Object that your script will access.

[Return to Top]