How to Use Novell Directory
Control (NWDir), Part 1
“How To” Article
NOVELL APPNOTES
Gary J. Porter
Senior Network Analyst
MindWorks, Inc. of Kentucky
[email protected]
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.
Contents:
•
Introduction
•
NDS Programming Using ActiveX
•
NWDir: A Functional Description
•
ActiveX Collections: Their Properties, Methods, and Events
•
Speaking to NDS for the First Time
•
Conclusion
Topics
directory services, NDS eDirectory, ActiveX,
Novell Directory Control (NWDir)
Products
NDS eDirectory
Audience
developers, administrators
Level
intermediate
Prerequisite Skills
familiarity with NWDIR
Operating System
NetWare 4 or 5, Windows 95/98/NT/2000
Tools
Rapid Application Development (RAD)
Sample Code
no
M a r c h
2 0 0 1
43
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.
[ROOT] (NDS_Tree)
O=Novell
Accounts
Engineering
Editorial
Management
Marketing
NTS
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.
44
www.novell.com/appnotes
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.
M a r c h
2 0 0 1
45
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 objectoriented 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.
46
www.novell.com/appnotes
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.
M a r c h
2 0 0 1
47
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.
48
www.novell.com/appnotes
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.
M a r c h
2 0 0 1
49
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:
50
•
Create and delete local users
•
Search and filter entries
•
Manage passwords
•
Perform backup and restore functions on the local Bindery
www.novell.com/appnotes
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.
Figure 2: The Browser control is a visual control that provides a window
for displaying, browsing or selecting NDS objects.
M a r c h
2 0 0 1
51
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:
52
•
Management of the dredger
•
Update of catalog contents
•
Query for the FullName of individual dredgers
www.novell.com/appnotes
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
M a r c h
2 0 0 1
53
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.
54
www.novell.com/appnotes
Figure 3: 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
M a r c h
2 0 0 1
55
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.DefaultFullNameFromTreeName. 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:
56
•
Change server set parameters
•
Load and unload NetWare Loadable Modules (NLMs)
www.novell.com/appnotes
•
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
M a r c h
2 0 0 1
57
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.
58
www.novell.com/appnotes
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.
M a r c h
2 0 0 1
59
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-forcharacter 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:
•
60
Intel Pentium II 400MHz with 128 Megs RAM
www.novell.com/appnotes
•
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
M a r c h
2 0 0 1
61
•
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)
•
Layouts—(NWLayoutDescription) the object classes or layouts contained in
sets or displays the current context.
the current tree.
•
LoginName—(String)
•
Pictures—(NWPictures collection)
the FullName of the current logged-in user.
a collection of bitmaps that iconize
standard NDS objects.
•
the relative distinguished name of the root most object
of the current context.
•
SortedEntries—(Boolean)
•
SortBy—(String)
ShortName—(String)
sorts the NWEntries collection when set to
TRUE (only available for eDirectory).
sets or returns the index key to sort the NWEntries
collection (only available for eDirectory).
The control provides the following methods:
62
www.novell.com/appnotes
•
ContextFromFullName—returns only
the context portion of a FullName.
•
FindEntry—locates
•
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
and establishes a link to an entry in the Directory.
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
•
TreeFromFullName—returns the name of
the search begun by the Search method.
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
EntryDeleted—triggers
entry has been successfully added to the tree.
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.
M a r c h
2 0 0 1
63
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.FindEntry(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:
64
www.novell.com/appnotes
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:
M a r c h
2 0 0 1
65
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.
66
www.novell.com/appnotes
Figure 4: 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 mouseclicking 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?”
M a r c h
2 0 0 1
67
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.
Figure 5: 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.
68
www.novell.com/appnotes
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.
Figure 7: 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!
M a r c h
2 0 0 1
69
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.
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.
70
www.novell.com/appnotes
Figure 9: 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!
Copyright © 2001 by Novell, Inc. All rights reserved.
No part of this document may be reproduced or transmitted
in any form or by any means, electronic or mechanical,
including photocopying and recording, for any purpose
without the express written permission of Novell.
All product names mentioned are trademarks of
their respective companies or distributors.
M a r c h
2 0 0 1
71