Novell is now a part of Micro Focus

Building eDirectory-Enabled Applications using Delphi:Overview

Articles and Tips: article

Wolfgang Schreiber
Manager of Developer Support
Novell EMEA
wschreiber@novell.com

01 Nov 2001


This is the first in a series of AppNotes on eDirectory (NDS) programming with Delphi. This article reviews the two main methodologies for eDirectory access: through ActiveX controls vs. low-level calls. It then presents some simple implementations. The second article will take a closer look at the ActiveX approach and review the specific features, benefits, and drawbacks of that approach, while the third article will review the more complex but more efficient low-level technique.


Topics

Delphi, eDirectory-enabled applications, NetWare programming, code samples

Products

Novell eDirectory, Delphi

Audience

network programmers

Level

beginner

Prerequisite Skills

familiarity with Delphi programming and Novell eDirectory

Operating System

NetWare

Tools

Novell Developers Kit (NDK)

Sample Code

yes

Introduction

You can use Delphi to create eDirectory-enabled applications in one of two ways: through ActiveX use or low-level calls. If you follow the Rapid Application Development (RAD) approach and use off-the-shelf ActiveX components, a lot of the underlying complexity will be hidden from you. The more time-consuming but more flexible and powerful low-level approach with direct calls into the client DLLs will provide you with better resource utilization and higher speed.

Both approaches have their distinctive pros and cons. It is one of the main purposes of this article series to introduce both concepts and to help you making the right decision as to which one to use.

Getting Started

All concepts that we will discuss in this series deal with NDAP (NetWare Directory Access Protocol), Novell's native protocol to access eDirectory. We will not discuss the popular alternative, LDAP (Lightweight Directory Access Protocol), although you can also use Novell's ActiveX controls or low-level APIs through LDAP to access eDirectory and other directories.

When using NDAP, the NetWare Client 32 software is required on the workstation. Both the eDirectory ActiveX controls and the low-level APIs use the features of the NetWare Client 32 to talk to the directory. The architecture of this environment is represented in Figure 1.

Architecture of the NDAP development environment.

What is an ActiveX control, anyway? ActiveX controls represent reusable components (or objects) that you can insert into an application (or even a Web page) to implement packaged functionality that someone else programmed. For example, the Novell ActiveX controls enable you to enhance your application with sophisticated NetWare features.

Basically an ActiveX control is just another term for an OLE Object or Component Object Model (COM) Object. You often see ActiveX controls as *.OCX files, but strictly speaking a single OCX file may hold one or more ActiveX controls. Not all ActiveX controls have the OCX extension; some (including some Novell controls) are DLL files.

The main advantages of using ActiveX controls are the significantly reduced development cycle and smaller application size. However, you might feel restricted by the predefined objects, properties, and methods a control provides. Depending on the task and the implementation of the control, your application may be slower and more resource-intensive than low-level applications. Finally, with controls you are dependent on the quality of the control, whereas you can fix any bugs in the logic of your own code yourself.

You're probably anxious to get your hands on the keyboard, so let's leave the theory and start looking at some real stuff.

Quick Start: Your First ActiveX Application

This section takes you through how to write a simple application-and I do mean simple-that gives you a first impression of how the Novell ActiveX controls are used in development with Delphi. In this overview article I will not go into detail on any of the steps. More in-depth explanations of the steps will be provided in a later AppNote in this series, where we will take a closer look at the ActiveX controls and Delphi.

So, let's get started!

Step 1: Obtain the Controls and Install

You can download the current Novell Controls for ActiveX from Novell's DeveloperNet Web site at http://developer.novell.com/ndk/ocx.htm. If you are not yet a registered member of DeveloperNet, choose the free electronic membership for now.

Once you have completed the download, run the OCX.EXE file that you downloaded. This will add the controls to your local Win32 registry and install the help files, plus a few code samples.

Step 2: Register the Control with Delphi

To use any ActiveX control in Delphi, you first need to tell Delphi about its existence. To do this, start Delphi and, from the main menu, select Components | Import ActiveX Control. Choose one of the Novell controls (they all start with "Novell ") and click on Install. Accept all upcoming information screens.

Repeat this step for each control you plan to use. For the purposes if this AppNote, you just need the control named "Novell Directory Control".

The new controls should now show up as icons on the ActiveX tab in your Delphi IDE. Delphi will remember the new ones you have registered the next time you start it.

Step 3: Write Your Program

In Delphi, create a new form, and then add a button and two edit boxes. Now add the Novell Directory control by selecting it from the ActiveX tab and then clicking anywhere in your new form. It will appear as a small tree icon. Your screen should resemble the one shown in Figure 2.

Your form as seen in Delphi's design mode (ActiveX example).

Now let's start coding. Double-click the button on your form to open the code window, and then add the following lines of code:

procedure TForm1.Button1Click(Sender: TObject);

VAR

    Me : NWEntry;

begin

    Edit1.Text := NWDir1.LoginName;

    Me := NWDir1.FindEntry(NWDir1.LoginName);

    Edit2.Text := Me.GetFieldValue('Surname', '', FALSE);

end;

Now save and run the application.

What Did You Do?

In these lines of code you checked and displayed your identity, located your own User object in NDS, and read an NDS attribute ("Surname").

We will take a much closer look into this in the next AppNote in this series. In the meantime, I encourage you to do a little experimentation on your own. The online help is available by pressing the <F1> key after selecting the NWDir icon on your form.

Quick Start: Your First Low-Level Application

To compare usage of the ActiveX controls with direct low-level DLL calls as provided by your NetWare client, this section shows how to write a simple eDirectory application using only DLL calls. Again, I have not provided many details about what you're doing, but many of your questions will hopefully be answered in an upcoming AppNote in this series.

If you're ready, here we go!

Step 1: Obtain the Libraries and Install

You can download the current Novell Libraries for Delphi from Novell's DeveloperNet Web site at http://developer.novell.com/ndk/delphilib.htm. If you are not yet a registered member of DeveloperNet, choose the free membership for now.

Once you have completed the download, run the DELPHILIB.EXE file that you downloaded. This will copy the Delphi header files and a small Delphi sample to your local disk.

Step 2: Tell Delphi All About It

Before you can use the new libraries, you need to make Delphi aware of them. In Delphi, start a new project and, from the main menu, select Project | Options. Select the Directories/ Conditionals tab and in the "Search Path" field add "C:\Novell\Libraries\Delphi\Src".

To avoid having to re-enter this for every future NetWare project, check the "Default" check box.

Step 3: Write Your Program

In Delphi, create a new form, and then add a button and one edit box. Your screen should resemble the one shown in Figure 3.

Your form as seen in Delphi's design mode (low-level example).

Now it's time to start coding. Double-click the button on your form to open the code window, and then add the following lines of code (do not forget the "uses" statement):

uses CalWin32, NetWin32;

    

procedure TForm1.Button1Click(Sender: TObject);

VAR

    cCode   : NWDSCCODE;

    context : NWDSContextHandle;

    me      : Array[0..255] of char;

begin

    cCode := NWCallsInit(nil, nil); // initialize

    if cCode<>0 then exit;

    cCode := NWDSCreateContextHandle(context); // create NDS context

    if cCode<>0 then exit;

    cCode := NWDSWhoAmI(context, @me);           // Who Am I

    if cCode=0 then Edit1.Text := StrPas(@me);

    NWDSFreeContext(context);

end;

Now save and run the application.

What Did You Do?

This example required a few more lines of code than the ActiveX sample. You first initialized the application and got a handle into eDirectory. Then you called the API to retrieve your eDirectory name and displayed the results from the return buffer.

We will scrutinize this code more closely in a future AppNote in this series. I promise to show how to read eDirectory attributes, too.

Performance and Overhead Issues

By default, low-level calls do exactly what you ask them to and no more, so there isn't much of an overhead. As a result, the performance of applications using low-level calls is typically better than the performance of applications that use ActiveX controls. But it depends on the task performed. The reason for this is simple: even if you only want to read a single piece of information about a specific object, the controls typically retrieve more information about that object than you need. Or if you just want to select an object, the controls may read all the objects in a given container.

In most situations this is an acceptable behavior and the performance differences may hardly be perceivable, especially in strongly interactive applications or in environments that do not host thousands of objects. In these cases, you probably won't care whether an operation takes 10 milliseconds or 300 milliseconds. However, if you need to operate on large numbers of objects, the performance differences may become too noticeable.

Luckily, there are several ways to fine-tune the performance of your ActiveX applications. We'll review some of these in the next AppNote in this series.

Conclusion

Hopefully this AppNote has given you a first impression of how to access eDiretory from Delphi applications. We'll learn a lot more about it in the next two AppNotes, which will look at what's happening behind the scenes, how different Delphi versions affect your code, how to update existing library or ActiveX control versions, run-time prerequisites, tips and tricks, tuning considerations, and much more. We'll also do real tasks such as reading the schema, scanning the objects, and reading and modifying their attributes.

For additional information, refer to the following resources:

* 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