Novell is now a part of Micro Focus

How to Use Novell Directory Control (NWDir), Part 1

Articles and Tips: article

Gary J. Porter
Senior Network Analyst
MindWorks, Inc. of Kentucky
porter@digitalme.com

01 Mar 2001


This AppNote provides an overview of the theory behind the Novell ActiveX control. It shows how to extract and manage existing information, as well as techniques for adding new objects to the database. The Novell Directory Control (NWDir) is the key RAD component for accessing NDS from any ActiveX or COM technology.

Introduction

This AppNote introduces you to two of the most exciting and empowering technologies in computing today: Novell's eDirectory and ActiveX. We discuss the logic behind the Novell ActiveX control and show how to extract and manage existing information, as well as techniques for adding new objects to the database. The Novell Directory Control (NWDir) is a key RAD component for accessing NDS from any ActiveX or COM technology.

For purposes of consistency, the tree used for the examples in this AppNote will mirror the one found in Figure 1.

The NDS tree used throughout this text.

The History of ActiveX

It may come as a shock to some, but computers haven't always been able to share common data amongst the multitude of programs that grace our computer store shelves. When the personal computer was young, application programs stored their data in proprietary formats. Even today, many still store their data in private, sometimes secret formats. This is hardly news. However, in the early days, these programs didn't even have the ability to convert data from one program's data format to another.

In order to fully appreciate the ActiveX environment, we must take a look at the developmental path which led to ActiveX. It is interesting how a need to share data between applications eventually gave us a new level in programming.

Dynamic Data Exchange (DDE)

Dynamic Data Exchange (DDE) was the first attempt to provide compatibility between applications that were never meant to talk to one another. In the DDE model, a DDE server serves data to a requesting DDE client. The DDE Server is an application program (any application program) that is DDE-aware. The DDE server part of the application silently sits and waits for a request from a client; a DDE server only acts on incoming requests. Once the request is received, the server springs into action.

In this model, both the client application and the server application must be running at the time of connectivity. Data can be exchanged with any application that supports DDE linking.

Each request from a client contains a unique identifier consisting of three parts:

  • DDE Application Name

  • DDE Topic

  • DDE Item Name

The application name is nearly always the executable name of a DDE server application program, the topic refers to a group of data, and the item name refers to a specific field of data within the group. An example of a DDE unique identifier might be:

Excel | Sheet1:A1

The shortcomings of DDE are that it is terribly slow, and that it requires both applications to be running. It's also difficult to implement correctly. The biggest downfall, however, is its inability to share data beyond the application's capability.

Object Linking and Embedding (OLE) 1

The next step toward ActiveX was Object Linking and Embedding (OLE), pronounced o'lay. Developed by Microsoft, OLE 1.0 was a mechanism by which documents could be created containing different kinds of data elements from multiple sources-also known as compound documents. In other words, a single document could be produced using multiple Windows applications-at the same time. Elements from outside sources become objects inside the document and appear as an icon, a metafile, or simply text and will retain the original formatting and links to the source application. Another way to look at it is 'in place editing.'

When editing an OLE object, the source application is launched and used to make the edits. When editing is completed, the object is updated and control is handed back to the original application. Although this is an elegant solution, it has limitations. Editing is not possible on a computer that does not have the object's source application installed. OLE 1.0 had one focus: creating compound documents.

OLE 2/Component Object Model (COM)

As you might expect, the next step was OLE 2.0, which introduced Microsoft's Component Object Model (COM). Also added to OLE 2.0 was visual editing, drag-and-drop support, uniform data transfer, OLE automation, and structured data storage. The idea with COM was to provide a universal apparatus that would allow an application to provide services to another application. It provided the first uniformity across platforms by using OLE as a transport-a form of application object transparency. COM forced the operating system to think of its applications as objects and had the operating system act as a registry, of sorts, for these objects.

The complication with COM -the brainchild of the OLE architects-was that it really addressed more than just compound documents, which was its intended purpose. However, Microsoft needed branding for this new technology and decided to use the term OLE as a brand name. Suddenly, everything associated with OLE or COM was called OLE and this new technology encompassed more than just compound documents.

Visual Basic Controls (VBX)

Visual Basic custom controls (VBX) are 16-bit OLE controls originally written with Visual Basic. The shortcomings with these controls are that they must be installed in the search path of the operating system (they can't be registered within the operating system), they don't have inheritance, and they aren't polymorphic. They simply aren't true objects in the object- oriented sense. VBXs also lack a sophisticated interface and don't have the ability for property pages.

However, during the heyday of Windows 3.1, VBX controls were state-of-the-art. They allowed for reusable software components-one of the first steps toward Rapid Application Development (RAD) programming.

OLE Custom Controls (OCX)

OLE custom control (OCX) was Microsoft's second-generation control architecture. OCX is a 16-/32-bit independent program snippet that can be accessed by other programs in a Windows environment. Introduced with Windows 95, it was used as a bridging mechanism between VBX controls and a true 32-bit custom control environment. Because these controls were a hybrid, they were always slow, not to mention difficult to develop.

ActiveX

In 1996, in an attempt to make the technology less confusing, Microsoft branded the name ActiveX and used it to define COM-based technologies. OLE was once again assigned the mission of referring only to compound documents. ActiveX is actually a collection of smaller things. When thinking of ActiveX, most people are really thinking ActiveX controls. These controls allow disparate applications, object spaces, or networks to speak together by calling each other's methods (discussed later in this section) in a true 32-bit environment.

COM has continued to grow and is now part of nearly all facets of Microsoft technology. As you can see, to use the term ActiveX to describe this technology is not entirely correct.

The good news is that within the Windows environment, ActiveX controls offer an abundance of diversity. Programmers can develop ActiveX controls using several different languages, including C, C++, Visual Basic, and Java. The best news is-it's easy!

RAD (Rapid Application Development)

It comes as no surprise that the term "re-usable" became important during the 1990s. From razor blades to freezer bags to programming-the idea of waste (whether it be time or money) conjures up a most revolting feeling. In an effort to reduce costs and speed up the development process, programmers have moved to a modular or reusable approach to application development. An easy way to describe RAD is as a mind-set more than anything else. This new way to approach programming suggests that you forget the old ideas of programming and bring together all groups associated with a project to make recommendations during the development phase. RAD even encourages user involvement during the development phase of a project, which means that this methodology is often used for corporate in-house development instead of "for-profit" software.

The modularity of the RAD approach makes its use compelling even for professional applications developers. Using ActiveX and RAD development tools, applications can now find their way to the desktop at blinding speeds. The logic behind this new revolution is simple: in order to keep the costs down and productivity up, the programmer follows four steps-only writing new code when all else fails:

  1. Re-use existing code.

  2. Modify existing code.

  3. Buy someone's code.

  4. Write new code.

When the RAD approach to programming was coupled with the need for graphical or visual tools, rapid prototyping, and cross-application connectivity, the relationship between ActiveX and RAD was inevitable.

ActiveX is perfect for the RAD environment because it supports a plethora of development environments, including Visual Basic, PowerBuilder, and Delphi, among others. Another reason ActiveX has cemented firmly in the RAD arena is the toolkit methodology that RAD encourages.

NDS Programming Using ActiveX

The purpose of the Novell ActiveX controls is to wrap more sophisticated calls and functions into a manageable, easily applied set of properties and methods that can be used with several scripting languages, such as Microsoft's Visual Basic and Delphi.

Terminology

For those already familiar with NDS, it will be necessary to make some minor adjustments. NDS terminology comes from well-defined schema specifications; however, there are several name collisions that need to be addressed early on. The following inter-discipline technology terminology table (yes, I know-I smiled, too) has been included to help those who are already familiar with NDS terminology:


NDS
ActiveX

Tree

Directory

Class

Layout

Syntax

Field type

Object

Entry

Attribute

Field

Fully Distinguished Name

Full Name

Relative Distinguished Name

Short Name

I cannot stress how important this table will be to understanding ActiveX programming, particularly to those who come from an NDS background. Throughout this article, I will call objects "entries" and attributes "fields." I will also call the object"s Fully Qualified Distinguished Name (FQDN)-its FullName and the Relative Distinguished Name (RDN)-its "ShortName." Make a mental note-or perhaps more importantly, make a bookmark on this page so you can quickly refer back to the table. You"ll thank yourself later.

Novell ActiveX Controls

The example programs for this AppNote were written and tested using Novell's Controls for ActiveX version 3.0, which contain seventeen separate Novell ActiveX controls. The following table lists the name and the control.

Note: If one counts the number of controls by name, the total number comes to sixteen. However, Socket Control is actually two separate controls listed together, NWSvrSkt and NWCliSkt. Therefore, there are actually seventeen Novell Controls for ActiveX.


Control Name
Control

Application Administration Control

NWAppAdm

Bindery Control

NWBind

Browser Control

NWBrowse

Catalog Administration Control

NWCatAdm

Directory Administration Control

NWDirAdm

Directory Control

NWDir

Internet Directory Control

NWIDir

Network Selector Control

NWSelect

Peer Socket Control

NWPrSkt

Print Queue Administration Control

NWPrtQAdm

Print Server Control

NWPrtSvrAdm

Server Administration Control

NWSrvAdm

Session Control

NWSess

Socket Control

NWSrvSkt, NWCliSkt

User Group Control

NWUsrGrp

Volume Administration Control

NWVolAdm

As you can see from the terms, great functionality is afforded the Novell ActiveX programmer. In this AppNote, we will concentrate on just one of these controls: the Directory control (NWDir). The remaining controls offered by Novell are divided into two categories: visual and non-visual. You have the greatest flexibility with non-visual controls. You can decide just how a collection or function is displayed, and when. The visual controls are used mostly to display elements of a collection, and they allow rapid development of applications that require search and/or display functions.

Before we begin writing programs, however, we'll first discuss some of the ActiveX methods and properties and get a brief description of each of the Novell Controls for ActiveX.

Application Administration Control (NWAppAdm)

The Application Administration Control lets you design ZENworks applications. With ZENworks, user applications can be distributed and managed using NDS to store information about the Application object or the application's user. This control is designed to extract the functionality of ZENworks into a powerful, rapidly deployable tool for application security, application management, and application distribution.

With the Application Administration Control you can accomplish the following:

  • Create and delete an Application object

  • Modify attributes of an Application object

  • Assign User, Group, and Organization privileges to the Application object

The Application control, by itself, has three properties:

  • FullName

  • ShortName

  • Applications

These properties can be used to set and return information about the entire current collection. An example might include setting the current context for the control, which would involve the FullName property.

Bindery Control (NWBind)

The Bindery Control manages backup, search, and restore functions on a server and administrates network entries (users, groups, and printers). During the days of network immaturity, servers maintained database collections of their users locally. In NetWare, this local collection is called the bindery. However, don't underestimate the value of the bindery control just because it represents an abstraction of the traditional Novell Bindery database; it's very powerful and quite useful in many circumstances.

With the bindery control, you are managing individual entries on a given server-rather than in NDS, which abstracts the entire tree. However, all modifications on a given server are automatically updated into NDS. Many objects from throughout the tree will appear as part of a local bindery database because of the external reference function. This function is used to make external objects (objects from outside the local context) appear local to the NDS database.

The Bindery control allows you to:

  • Create and delete local users

  • Search and filter entries

  • Manage passwords

  • Perform backup and restore functions on the local Bindery

Browser Control (NWBrowse)

The Novell Browser Control is a visual control that provides the ability to view an NDS tree and Internet directory that supports either LDAP or NetWare volumes. This control is used in conjunction with one of the following controls:

  • Novell Directory Control

  • Novell Internet Directory Control

  • Novell Volume Administration Control

Information from any one of these controls can be displayed in any of several views, including Tree View, List View, Small Icon View, or Report View.

Once the view is populated with entries from any of the above controls, full name or short name properties from selected entries can be retrieved and displayed. The Browser control will also return an object from a given coordinate within a given view. Figure 2 demonstrates this visual control.

The Browser control is a visual control that provides a window for displaying, browsing or selecting NDS objects.

Directory Administration Control (NWDirAdm)

The Directory Administration Control allows you to manage NDS partitions and replicas. With this control the RAD programmer can create and manage partitions including individual partition replicas. This control can also be thought of as the NDS database administration control.

Don't confuse this control with the functionality offered by the NWDir control for modifying Schema (or Layout) definitions. The Directory Administration control allows the thinning of the NDS database (partitioning) and the placement of individual collections on servers (replication). There are essentially six partition operations possible (although, by strict definition, repairing timestamps can be considered a seventh). The operations include the following:


Partition functions
Replica functions

Split

Add

Merge

Delete

Move

Change type

This control allows you to:

  • Create (split) or Merge (join) a partition

  • View and modify properties of a partition

  • Create and delete partition replicas

  • Change a server's replica type

  • Synchronize replicas of a partition

Catalog Administration Control (NWCatAdm)

A catalog is a subset of NDS information stored as a flat-file on selected servers allowing rapid responses to directory searches. The information in a catalog can be objects, such as users, or it can be specific attributes of a set of objects. The entire tree or a subsection of the tree can be represented. A mechanism call a dredger periodically updates the catalog information from the NDS database.

The Catalog Administration control allows management of NDS catalogs from a RAD environment for uses that include contextless logins and LDAP catalogs. The Catalog Administration controls allows:

  • Management of the dredger

  • Update of catalog contents

  • Query for the FullName of individual dredgers

Directory Control (NWDir)

The Directory control provides an access mechanism to the most basic structures found in NDS as well as the objects contained inside these structures. This control abstracts several different data collections divided into two major categories: Entries and Schema. Entries are the abstraction of the individual objects in NDS. The Schema refers to a set of rules governing the object classes (layouts) in the database and the attributes (fields) associated with each of these layouts. With this control, the RAD programmer can:

  • Edit NDS Entries

  • Add objects

  • Delete objects

  • Search for objects

This control is also used to modify layouts, also known as extending the schema. Truly one of the most powerful features of NDS was introduced when the four principal NDS designers decided to build a structure that could easily be modified. The layout structure of NDS follows the rules defined by the X.500 standard, but it also allows you extreme flexibility for shaping NDS into a powerful tool that, in many cases, seems to be built especially for you. That's because, now it is.

The Directory Control allows modification of NDS layout in the follow manner:

  • Add new layouts (object classes)

  • Add new fields (attributes)

  • Edit non-base class object and attributes definitions

We will spend a large portion of our time working with the NWDir control, which I call "the keys to the kingdom." This allows you the ability to quickly add, delete, search for, and manage most entries, including NDS schema elements.

Internet Directory Control (NWIDir)

This control allows interaction between the RAD environment and any Lightweight Directory Access Protocol (LDAP) enabled Internet directory. Using TCP/IP, an LDAP enabled directory exposes itself through a series of platform independent APIs. The Internet Directory control, which is LDAP version 3 compliant, provides the functionality to:

  • Search and filter LDAP entries

  • Determine the entry layout and associated fields

  • Return a user name and fields

  • Add, delete and modify LDAP entries

Note: LDAP is not a directory information base; it is instead, an access method to an existing X.500 compliant directory or other LDAP enabled directory database. Information about LDAP can be found at the Internet Engineering Task Force (IETF) web page at: http://www.ietf.org

RFCs are divided into two major categories: Informational and Standards. Information about existing and pending standards is listed by Request For Comment (RFC) number. There are several RFCs dealing with LDAP; the three most important are listed below:

  • RFC-1487 X.500 Lightweight Directory Access Protocol

  • RFC-1777 Lightweight Directory Access Protocol (v2)

  • RFC-2251 Lightweight Directory Access Protocol (v3)

Network Selector Control (NWSelect)

The Network Selector control makes selecting objects from a collection much easier. Its interface is easy to navigate providing much more flexibility and functionality for the RAD programmer. This control is part of a group of controls called visual controls and their primary purpose is to take the complexity out of writing object browser code. This control allows visualization of network objects in three basic views:

  • Connections view

  • Details view

  • List view

The control displays both NDS and bindery based objects, and the filtering of objects for a more focused view. Figure 3 shows an example of the Network Selector control and the filter function that is built into the control.

An example of the Network Browser Control visual control and its filtering capabilities.

Peer Socket Control (NWPrSkt)

The Peer Socket control, is a non-visual control that provides connectionless socket functionality. The properties and methods of this control make an in-depth understanding of socket programming unnecessary. It provides a mechanism for communication in a peer-to-peer manner between known network addresses. The Peer Socket control allows:

  • Selection of communication protocol

  • Selection of destination address and peer socket

  • Ability to send and receive formatted and unformatted data

  • Open or close a socket with either UDP or IPX protocol

This control is the first to provide broadcast and multicast capabilities in an ActiveX control.

Print Queue Administration Control (NWPrtQAdm)

The Print Queue Administration control provides properties and methods that allow management of NetWare print queues. Functionality includes:

  • Viewing and management of print jobs

  • Setting update intervals

  • Displaying status

  • Control how data is sent to a captured LPT port

With this control, you can also reorder or cancel print jobs and refresh the print queue.

Print Server Control (NWPrtSvrAdm)

This nonvisual control allows administration of a NetWare print server. The Print Server Administration control allows setup and management of both local and remote print servers. With this control, you can:

  • Identify printers and print queues served by the print server

  • Identify users and operators of a print server

  • Determine the status, version and name of a print server

  • Down a print server

  • Hold, abort or restart a print job

This control allows management of all aspects of basic print server functionality.

Session Control (NWSess)

The Session control is divided into three categories: mappings, ports, and login. The login feature of the control launches the Client32 GINA and allows the user to authorize and authenticate to NDS. (The remaining two controls are very valuable for the ActiveX programmer, but aren't within the scope of this AppNote.)

The Session control provides properties and methods that allow you to:

  • Login to the NDS tree

  • Display the current logged in user

  • Logout from the NDS tree

  • Display the current context

  • Display mapped drives

  • Display and set captured printer ports

Remember while using these controls, that the nomenclature used in ActiveX differs somewhat from that used in NDS, for instance to display the fully qualified current context name, you use the property object.DefaultFullName- FromTreeName . Remember, the FullName property in ActiveX is equivalent to Distinguished Name for NDS puritans.

Server Administration Control (NWSrvAdm)

The Server Administration control provides methods and properties that allow the management of NetWare servers. With this control, we can make changes on the server effecting its operation and performance. With this control, you can:

  • Change server set parameters

  • Load and unload NetWare Loadable Modules (NLMs)

  • Display the server operating system version

  • Execute profiles (NCF files)

  • Broadcast messages

  • Display properties of server connections

Socket Control (NWSrvSkt/NWCliSkt)

Socket controls consist of two separate controls: the server socket ( NWSrvSkt ) and the client socket ( NWCliSkt ). The purpose of this control is to abstract more difficult socket programming techniques into functional modular code snippets.

The Server Socket control uses either TCP or SPX transport protocols for development. The server socket is typically used in conjunction with the client socket control to:

  • Set up the server for listening (for client sockets)

  • Return the server address

  • Indicate the host TCP port or SPX socket

The Client Socket control also uses either TCP or SPX for transport protocols and is generally used in conjunction with the server socket to:

  • Attach or detach from the host server

  • Identify the server TCP port address or the PSX socket address

  • Communicate with the Server Socket host

User Group Control (NWUsrGrp)

The User Group control is a nonvisual control that allows management of certain NDS User and Group functions. It assists the administrator by providing easy manipulation of users and groups, including access rights associated with both layouts. The control allows:

  • Searching for User and Group objects

  • Change properties of Group objects

  • Add or Remove members of a Group

  • Set file rights for a Group object

Volume Administration Control (NWVolAdm)

The Volume Administration control is a very powerful non-visual control that allows control of many of the tasks associated with the NetWare volume object. Use this control to:

  • Set, view, or change disk space or volume limits

  • Manage trustee assignments

  • View loaded namespaces

  • View total, free, and purgeable disk space

The Volume Administration Control also allows moving, copying, renaming and deleting files as well as managing file and directory trustee rights.

NWDir: A Functional Description

The Directory OCX control NWDir abstracts the entire NDS tree, allowing for object searching, selecting, modification, creation, and deletion. It even allows for management of the NDS schema by providing procedures to create new object classes and new field-types, as well as tools for managing existing object classes and fields. (This will be discussed more thoroughly in an upcoming AppNote.)

Wow! This powerful control is probably the most important of all the Novell ActiveX Controls.

The Environment

Most programmers dealing with Microsoft products have a thorough understanding of the terms method and property. But for the sake of those who are new to the Visual environment, I'll define them here.

  • Property is an attribute of a control.

  • Method is a function that an object can perform.

What makes these concepts confusing is that they are both tied to the object by virtue of a dot; for instance: object.FindEntry and object.FullName . Both examples look similar, but one is a property and the other is a method. Can you spot each? The first, object.FindEntry , is a method because it represents a function that the object can perform. The other, object.FullName , is a property- in this case, the fully qualified distinguished name of the object.

The term property is even more confusing because the term has an alternate NDS meaning. To minimize confusion, it should be stated that a property, an attribute, and a field are all the same things with respect to NDS. I will use the terms field, attribute, and property interchangeably. This is necessary because some of the reading audience has a strong NDS background (hence the use of the terms property and attribute), but Visual Basic programmers will be more familiar with the term field. For the remainder of the AppNote, these terms should be viewed as the same conceptually, unless otherwise stated. I will use a qualifier to try to reduce confusion (for example, NDS attribute, NDS property, ActiveX property). The term field doesn't have a name collision and will therefore be used abundantly to describe NDS attributes.

Classes

Most of you are familiar with objects and object classes, so I'll not bore you with a long-winded lecture on object-oriented-programming. However, it is necessary that we review a few of the basics so that we guarantee that common language exists between us.

The concept of the object class allows different kinds of objects, or things, to exist side-by-side in the NDS tree. Object classes describe the kind of objects that can exist and the fields that a specific instance of that object class can possess. Obviously, the User object class is a much different concept than the Print Queue object class, but some things are common between the two: both share a common field-the access control list (ACL), among others.

There are hosts of similarities between object classes and there is a reason for this: in one way or another, all object classes are related. What we are beginning to unravel is the NDS Schema. It's not important to completely uncover the Schema at this point, only to understand some of its terms that will be used to describe NDS concepts.

Actually, the concept of Object Class in NDS is a bit more complicated than I'm describing here. Don't let this statement scare you away, though, the real power of NDS is its robust and flexible schema.

Collections

A collection is an enumeration of objects or an ordered set of items. The Collection provides an interface to a grouping of related "things" in NDS. All the objects defined in the scope of the control are virtual members of the collection.

For instance, the NWDir.Entries property abstracts every object within the current context. On the other hand, NWDir.Entry is a property that returns object information about the root-most container object of the current context. Collections can be defined by a group of similar objects or a single object and its values.

Properties

As stated earlier, ActiveX Properties represent attributes of the control and every collection within the control has independent properties. These properties are different from NDS properties, which are actually fields. Don't let the terminology confuse you. Hhowever, it is absolutely imperative that folks new to ActiveX understand the ActiveX definition for these terms.

Methods

Methods represent various functions that a control can perform. Each collection and object subordinate to a control has a list of Methods. Most methods used in the Novell Controls for ActiveX will take arguments. In object-oriented programming, objects are created from classes. These objects have variables and methods that belong to them. The variables can be thought of as properties of the object. The only way to effect change to the variables (properties) is through the object's methods, which are specifically designed to modify the properties of the object.

Events

An event is an action taken by the system, or a process (such as a mouse click), for which you can write code to take appropriate action. In the NDS Directory control, events are often used to indicate the success, or otherwise, of an NDS update, such as writing to a field or creation of a User object. An event can also be used to indicate the successful deletion of an object or to indicate the end of an NDS search.

If you are new to Visual Basic but not new to NDS, some of the terminology may seem challenging to you at first. If you are new to NDS but not new to Visual Basic, the NDS concepts will seem just as challenging. In either case, it's sometimes difficult to understand a new technology. Since this is the first AppNote in a series on ActiveX, we will explore and integrate the terminology used in these technologies. You'll be amazed how easily programs are written, and you'll also be delighted at the flexibility and control afforded the programmer.

Development Environment

Before we begin, let's take a look at the hardware and software required to program with the Novell Controls for ActiveX using Visual Basic. Since there are several differences from one version of an operating system to another, or from one set of controls to another, I've decided to include both a minimum dependency list and the desired development environment in the ActiveX section of this AppNote.

On several occasions, after repeatedly entering example code character-for- character with unexpected failure, I've asked the question, 'What was the development environment for the AppNote's author?' I hope that this information will help explain any unexpected anomalies.The following is a set of minimum dependencies necessary to perform the tasks and examples in this AppNote:

  • Computer capable of running a Win32 operating system

  • Microsoft Windows 95/98/NT/2000 workstation

  • Novell NDS-aware network (NetWare 4 or 5, eDirectory on Solaris, eDirectory for NT, eDirectory for Linux, eDirectory for Windows 2000)

  • Novell Controls for ActiveX

  • Rapid Application Development (RAD) tool such as Microsoft Visual Basic or Visual Studio

  • Novell Client32

The development environment for this section of the AppNote includes:

  • Intel Pentium II 400MHz with 128 Megs RAM

  • Microsoft Windows NT 4.0 SP4

  • NetWare 4.11 SP7a and NetWare 5.0 SP3a servers

  • Novell Controls for ActiveX version 3.0 dated September 30, 1999

  • Novell Client32 version 4.60 SP2

  • Microsoft Visual Studio 6 SP3

ActiveX Collections: Their Properties, Methods, and Events

There are ten collections within the NWDir control. Some are directly accessible from NWDir while others are collections within collections. In the following section, I'll explain these collections and their associated Properties, Methods, and Events. For each collection listed, I'll list the properties and explain the most popular methods.

It might help to remember that, with methods, you're asking the control to do something. It's a bit like approaching an acrobat and asking, 'I heard you can do a backward flip while rotating twice in the air.' The acrobat turns and says, 'Okay ya'll, watch this!' With properties, you're asking for a characteristic of the control (color, size, quantity, and so on).

The response to a query about a property will be formatted as to type. The properties stored within a control can be of any type, such as:

  • Long

  • Boolean

  • String

  • Index

  • Variant

There are other types, but the ones listed here encompass most of the responses expected. For each of the properties, I've included the response type expected.

There are also nine predefined data field types, also called structured data fields, which are:

  • NWACL-data representing an Access Control List (ACL)

  • NWEMailAdress-data representing an E-mail address

  • NWNetAddress-network address data

  • NWOctetString-byte strings that are uninterrupted by the Directory

  • NWPath-a file system path.NWPostalAddress-postal address data

  • NWTimeStamp-time information concerning an event.

  • NWTypedName-field types whose values represent a level and an interval of an entry

  • NWStream-binary data (usually large amounts of data-but not always)

The structured field types will be discussed in more detail in an upcoming AppNote.

NWDir

NWDir is the essential control for everything discussed in this AppNote. It is used to set context (which determines which collections are in view) and enables the collections that you will use to read information and effect changes. It allows you to search for entries, filter entries, and, if you're using NDS version 8 (eDirectory), sort collections according to an index.

The control itself has eleven properties, nine methods, and four events. The properties are:

  • Entries -( NWEntries Collection ) the entries contained in the current context of the directory.

  • Entry -( NWEntry object ) the root object represented by the current context or FullName.

  • FieldTypes -( NWFieldTypes collection ) the field types or attributes of the Directory.

  • Filters -(String) allows searching and display of specific layouts at run time.

  • FullName -(String) sets or displays the current context.

  • Layouts -( NWLayoutDescription ) the object classes or layouts contained in the current tree.

  • LoginName -(String) the FullName of the current logged-in user.

  • Pictures -( NWPictures collection ) a collection of bitmaps that iconize standard NDS objects.

  • ShortName -(String) the relative distinguished name of the root most object of the current context.

  • SortedEntries -(Boolean) sorts the NWEntries collection when set to TRUE (only available for eDirectory).

  • SortBy -(String) sets or returns the index key to sort the NWEntries collection (only available for eDirectory).

The control provides the following methods:

  • ContextFromFullName -returns only the context portion of a FullName .

  • FindEntry -locates and establishes a link to an entry in the Directory.

  • FindNextEntry -returns the following entry from the list sorted by the key specified in the FindEntry method (only available for eDirectory).

  • FindPrevEntry -returns the previous entry from the list sorted by the key specified in FindEntry (only available for eDirectory).

  • FullNameFromTreeAndContext -Concatenates a given tree name and context to form a FullName .

  • Search -initiates a search of the current context and/or its subordinates for a specific set of elements.

  • StopSearch -stops the search begun by the Search method.

  • TreeFromFullName -returns the name of the tree from the FullName property.

  • SearchLimited -used to narrow a search to a specific element, layout, or number of objects.

The following events are also available for the NWDir control:

  • EntryAdded -triggers when an entry has been successfully added to the tree.

  • EntryDeleted -triggers when an entry has been successfully deleted from the tree.

  • RefreshViews -triggers when the current context or tree name has been modified.

  • SearchCompleted -triggers when a Directory search has been completed.

Name Methods

I've grouped three of the methods into one definition because it makes more sense to explain them all at once they're simply different ideas of the same thing. The FullName property identifies the namespace (NDS:\\), the tree name (NDS_Tree\), and the context (Novell\Accounts) of the currently selected 'position' in the Directory. FullName is the concatenation of all three entities-namespace, tree, and context. ContextFromFullName method extracts the context portion of the current FullName and TreeFromFullName extracts the tree name from the current FullName .

If the current FullName equals NDS:\\NDS_Tree\Novell\Accounts, the tree name equals NDS_Tree and the context portion equals \Novell\Accounts . The tree name is never considered part of the context. Examples of both methods are shown below:

Object.NWDir1.ContextFromFullName(NWDir1.FullName) Object.NWDir1.TreeFromFullName(NWDir1.FullName)

The third name method helps us tie these two concepts back into a FullName.The following syntax is used to accomplish the task.

Object.FullNameFromTreeAndContext(Tree Name as String, Context as String)

By supplying valid values for the tree name and context, as shown below, a complete FullName is generated:

Text1.Text = NWDir1.FullNameFromTreeAndContext("NDS_Tree", "Novell")

Find Methods

One of the most important functions to learn is how to find objects in the NDS tree. This section will discuss all three find methods: FindEntry , FindNextEntry , and FindPrevEntry . The FindEntry method is uncomplicated and a bit easier to code than the search methods that we'll discuss later. The syntax of the method is:

object.FindEntr y(Name As String)

The FindEntry method can operate at warp speed if NDS 8 (eDirectory) is installed, by allowing its advanced search features to perform the find. There are two optional parameters for the eDirectory environment: Key and Value. The key parameter provides the search method with a link to an NDS 8 index. An example of a valid key includes Surname, Given Name, CN, and UniqueID. If a "*" is input for the value parameter, all matching elements will be returned. In the NDS 8 environment, the FindEntry method can be expanded to the following:

object.FindEntry(Name As String, [Key as String, Value As Variant])

FindNextEntry and FindPrevEntry are as simple to use as they sound. FindNextEntry simply increments to the next element in the list and the FindPrevEntry method toggles to the previous entry in the list:

Set entry = NWDir1.FindNextEntry Set entry = NWDir1.FindPrevEntry

Search Methods

This section combines the three search methods: Search , StopSearch , and SearchLimited .

The most obvious question you should have at this point is, "What is the difference between FindEntry and Search?" FindEntry searches for and finds a specific object in the Directory, while Search returns all entries that match a specific set of conditions. The ability to specify conditions for the search is very powerful because it allows for searching for not only object names but for specific object classes, as well. The search is also defined by its limits, which can be the objects bound by the current context ( Search_Subordinates ) or from the current context down the tree ( Search_Subtree ). The term Search_Subordinates seems confusing to some folks until they realize that the focus is the Entry object of the current FullName . Everything in the current context is subordinate to the Entry object that represents the root of the current context. The syntax for the Search method follows:

object.Search(NameFilter As String, ClassFilter As String, Scope As NWSearchScope, StartContext As String, [SearchMode As NWSearchMode])

where NameFilter is a comma-delimited list of names for the search. ClassFilter is the Layout, or list of comma-delimited Layouts to be included in the search. Scope is either Search_Subordinates or Search_Subtree . StartContext is the FullName of the beginning context for the search. SearchMode, which is optional, is either SEARCH_SYNCHRONOUS or SEARCH_ASYNCHRONOUS .

The difference between SEARCH_SYNCHRONOUS and SEARCH_ASYNCHRONOUS is actually rather straightforward. A SEARCH_SYNCHRONOUS search returns information at the end of the search. A SEARCH_ASYNCHRONOUS search returns information as it is found, while the search continues in the background.

For both synchronous and asynchronous searches, the problem exists of how to determine when the search event has completed. This is accomplished with the SearchCompleted event. When a search is completed this event triggers to indicate its successful completion. The SearchCompleted event is handled in code just like a DblClick or a MouseDown or any other event in Visual Basic.

Private Sub NWDir1_SearchCompleted(ByVal Results As Variant)

      ' Place the items found in a listbox'
   If IsArray(Results) Then

      For Each NDSItem In Results

         List1.AddItem NDSItem

      Next

   ElseIf Results Then

      List1.AddItem Results

   Else

      MsgBox "No Items found""
   End If

End Sub

The StopSearch method is used with asynchronous searches. As information is returned, decisions can be made on the completeness of the search. If certain events occur, the StopSearch method can be employed to stop the Search:

object.StopSearch

The SearchLimited method is very similar to the Search method. It employs a limit so that not every member matching a given set of parameters is returned-only the number of elements matching the limit parameter. The SearchLimited method only works in an eDirectory environment. If it is used in a non-NDS 8 environment or if the limit variable is set to zero, every member matching the remaining parameters will be returned. The syntax of the method is:

object.SearchLimited(NameFilter As String, ClassFilter As String, Scope As NWSearchScope, StartContext As String, [SearchMode As NWSearchMode], [Limit As Long])

Note: The SearchLimited method is used in conjunction with the SortBy and SortedEntries properties. The SearchLimited method, and SortBy and SortedEntries properties are eDirectory specific and will only function correctly in an NDS 8 environment.

Speaking to NDS for the First Time

The best way to learn to program using Novell's controls for ActiveX is to write a program. The first one should be simple and useful. For this first program, nothing will be left to chance; each step will be explained along the way.

Before Visual Basic can access NDS, the Novell Controls for ActiveX must be loaded and registered on your computer. If you don't already have the controls, you can download them from Novell's Web site at:

http://developer.novell.com/ndk

Select Downloads and search for Novell Controls for ActiveX in the alphabetized list. You will be downloading OCX.EXE , which contains all the controls. Once downloaded, launch the program and you will be guided through the process of registering the controls.

WhoAmI Program

Begin by completing the following steps:

  1. Launch Visual Basic.

  2. Select Standard EXE .

    Figure 4 shows the generic startup screen that will be similar to your screen.

    Visual Basic Integrated Development Editor (IDE) blank project screen ready to begin editing a Standard EXE template.

    From this screen, several ActiveX controls are available by default. They are represented by the icons listed on the left side of the example in Figure 4. Before you can begin using the Novell Control for ActiveX, you must instruct the IDE to include them in the components list.

  3. To do this, click on Project on the menu bar and select Components.

    Note: You can also add components by pressing Ctrl-T or by right mouse- clicking inside the ActiveX components section and selecting Components.

  4. Choose Novell Directory Control from the alphabetical listing of ActiveX controls and select it by clicking in the box provided.

  5. Click on OK to close the Controls menu.

At this point, your program can use the Directory Services control, but only after you place it somewhere on your form. This may seem a little strange. You may be thinking, "We have already selected the control. Why can"t we simply begin using it?"

That's a good question, and the answer is simple. There are multitudes of ActiveX controls available today, and the list is growing. The components menu on the left of your screen is just that-a menu of possible controls. You could have selected all the Novell controls at once, although you may not use them in this program. In order to keep the menu bar functional, only select the control(s) that you intend to use. Another reason is that most of the controls will allow several instances of themselves inside a program: NWDir1, NWDir2, and so on. This is only possible by selecting a component and placing it on the Form page.

Double-click on the Novell Directory Control, represented by the tree icon displayed in Figure 5, and it will appear on your Form page.

IDE showing the Novell Directory Control on the controls menu and the same control enabled on the form, Form1.

This establishes a link between Visual Basic and the NDS API set necessary to carry out any function that you write into your code.

Select the Label tool from the component menu and draw a rectangular box somewhere on the screen, as shown in Figure 6.

Form1 showing a label drawn horizontally and centered on the form.

Double-click inside Form1 (but not inside the Label1 rectangle) so that the Private Sub Form_Load function is displayed. Now you are ready to write your first NDS-aware program. In the Project1 Form1 (Code) section, type in the following:

Private Sub Form_Load() Label1.Caption = NWDir1.LoginName End Sub

Now click on the Start arrow. Figure 7 displays a sample result of the WhoAmI program.

An NDS aware program displaying the default user's FullName.

With one line of code, you have reached deep inside NDS and extracted information about yourself. You have asked the network, "Who am I?" and your program has responded by displaying the NDS namespace, your tree name, your organization name, your context within the tree, and your userID. Isn"t this exciting? Moreover, you did it with one line of code!

The next example is just as simple and informative. This example displays all the objects that are located within your current context.

Using the same form, add a Listbox just under the label, Label1. Expand it as shown in Figure 8.

A ListBox just under the label, Label1. Items from the current context will be displayed in this list.

Double-click on an empty space inside Form1 and add the following code to your existing code.

Private Sub Form_Load()

Label1.Caption = NWDir1.LoginName

For each Item in NWDir1.Entries

   List1.AddItem  Item.Shortname

Next

End Sub

When this code is executed, it will display every sibling within your current context within the List1 ListBox, as illustrated in Figure 9. Note that a simple modification to display the ShortName (RDN) of all the contents of the current context was added.

The modified WhoAmI program during execution.

These remarkable feats are made possible with just a few simple lines of code. Imagine what you will accomplish with just a little practice, with the full power of the NWDir control!

Conclusion

In this first AppNote in a series on the NWDir ActiveX control, you were introduced to the awesome power and amazing simplicity of using the Novell Controls for ActiveX to extract eDirectory information. We also wrote a simple program that utilized both technologies using only a few lines of code.

Future articles will take us on a journey that will expose much of the functionality of the NWDir control. We will discover and explore the NDS schema along the way and finally write a Mass User import project that will utilize most of the functionality of the control. I can't wait!

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates