Novell is now a part of Micro Focus

How to Access NDS from HTML or ASP, Part 1

Articles and Tips: article

Rostislav Letos
Software Engineer
Developer Support
rletos@novell.com

01 Mar 2001


In this series of articles discusses ways Novell ActiveX controls can be used to access NDS by using HTML browser over the Internet.

Introduction

We have learned in the previous articles in AppNotes and Developer Notes how to manipulate data stored in the DS database by using NWDir ActiveX control. The DS database was handled from specifically written VB EXE applications, and this approach required having not only the application itself available to the user, but also NW client DLL libraries and NWDir ActiveX control installed on the local PC. This is not bad in general, but as you can see, such an approach adds some limitations in terms of components' availability. Such usage is quite strictly limited to the boundaries of the local network. And because there is a dependency on NW client, there is also a dependency to use only the protocol used by this NW client.

But what if we want access information stored in the DS database remotely, from the Internet? Can we accomplish this task by using either of Novell's ActiveX controls? What possibilities do we have in this field? Can we reasonably think or plan to use Novell ActiveX controls for accessing NDS resources over the Internet?

In this series of articles in AppNotes I present some of the ways Novell ActiveX controls can be used to access NDS by using HTML browser over the Internet.

Novell offers several AX components to access NDS -namely NWDir, NWDirSearch, NWIDir, NWIDirSearch, NWUsrGrp, NWAppAdm, NWCatAdm. The one which is most common, and also most frequently used is NWDir -Novell Directory control. In this article I will primarily focus on and discuss this control only, although I will also mention usability of some other Novell controls.

Some basic level of experience in using NWDir in VB applications or in VBScripts is expected here from the reader, but it is not necessarily required. For those of you who never touched NWDir a good idea might be to stop reading now, go back and read through some of the articles published previously on NWDir in Developer Notes or AppNotes.

In the following text I want to focus clearly on HTML or ASP specifics when using NWDir in HTML or ASP page. Some basic knowledge and experience with HTML is also an advantage.

All sample code presented here can be found on http://developer.novell.com.

The Novell AX control in ASP or HTML Pages

At this point you may be quite surprised -how can we pass in with Novell Directory ActiveX control into the Internet world? How can this proprietary AX control, which is fully dependent on Novell client DLL librares, be usefully used in the Internet, in the world of the IP protocol suite, Web servers, and HTML browsers?

It is the COM-Component Object Model (Microsoft's technology, which AX controls in general are based on)-which allows us to use the NWDir AX control as an embedded object in an HTML or ASP page. But just knowing how to embed the control into HTML or ASP is not a big deal and would not be a big help. The more important thing here is to find a useful way the Novell NWDir ActiveX control can be engaged in this area. This is possible thanks to the scripting capabilities of the HTML/ASP environment.

I will focus here on VBScript on both the client and the server side. And we will also use here some other "nice" technologies. Because the whole story described here is somehow dependent on Microsoft"s components, technologies, and specifications, the discussed techniques and samples here can be used without any problem only with Microsoft"s Internet Explorer (IE) and Microsoft"s Internet Information Server (IIS). Some samples, however, can also be tested with Netscape, and I will point them out.

You should also keep in mind that NWDir (and most other Novell ActiveX controls) are fully dependent on NW client libraries. It means that any usage of this component requires Novell client installed, either on the workstation with an HTML browser, or on the side of IIS server, where we want our ASP scripts to be processed.

Principles of NWDir Usage on the Internet

What are the very basic communication principles on which we build our code throughout this text? They are described in the following two figures - 1 and 2. Let's discuss them a bit. To understand these principles now will significantly help us later when learning from sample code and adding some more sophisticated techniques.

PC client, Web server, and DS server.

As you can see in Figure 1, we have a client PC here with both NW client and NWDir ActiveX control installed, a remote Web server, and at least one DS server with DS database.

Imagine the user starts his or her HTML browser and connects to a given Web server (step 1). First, the home HTML page is sent back to the browser (step 2) as a response of the Web server. The code in this HTML page uses VBScripts and/or JAVAScripts and also embeds some COM objects, and one of them is our NWDir ActiveX control.

When a user downloads the page, the NWDir control (installed on the client PC) is instantiated by IE (step 3), and because there is a NW client installed on that PC machine and because there is a NW client connection to the DS server, the code written in scripting language can be easily processed and can retrieve required information from the DS database (step 4). The underlying communication protocol used here is the same as the one used with NW client and other programs/utilities -it is NCP (NetWare Core Protocol) over either IPX or IP.

Well, it may happen that the client PC has NW client DLL libraries installed but not NWDir ActiveX control. Does that mean that our HTML application should fail in this case? Not at all! One of the Micorsoft's HTML language syntax enhancements makes it possible to download and install missing COM objects 'on the fly.' This means that the required NWDir object can be simply downloaded along with the HTML page from the Web server.

Typically the scenario presented above suits best (if not only) to an intranet network, because the requirement to have NW client installed locally on the client PC make the usability of such HTML applications a bit complicated. In fact, in this scenario only the code which is written in HTML is downloaded to the client PC, and all the processing and information exchange with the NDS is simply done locally, from the client side. The Web server here is used as a storehouse for HTML code only (and perhaps also for NWDir control).

We can think about this scenario to be a kind of two-tier architecture, where business rules and the user interface remain part of the client HTML application. The data retrieval and manipulation is performed on a separate system (DS server) by a separate application (DS agent on the DS server).

But didn't I promise you at the beginnning of this article to use NWDir AX to access DS database remotely over the Internet? Indeed, I did. So far, the presented method does not seem to comply with what remote access over the Internet means and requires. To achieve this we have to take one step ahead and move to a technology called ASP - Active Server Pages. Let me stop here for a moment and explain shortly what ASP means:

ASP - Active Server Pages - is Microsoft's programming environment (or technology if you like) that provides programmers with the ability to create powerful Internet applications by combining HTML, scripting, and COM components. The most important fact is that these ASP applications, although invoked from the client HTML browser, run on the Web server and simply send their outputs in the form of HTML files to the client.

Let's have a look at Figure 2. We have a client PC with an HTML browser installed and connected to the Internet. We also have (over the Internet) connection to the Web server with an ASP application. This Web server has an NW client installed, it keeps a copy of NWDir ActiveX control, and it also has a direct connection to the DS server with a DS database.

Client PC with an HTML browser installed and connected to the Internet.

When user sends from his or her browser an HTTP request to the Web server (step 1), asking for a certain page, in fact an ASP application is started. Because this ASP application has the NWDir ActiveX control embedded, the ASP engine (ASP.DLL) creates and initializes an instance of a NWDir on the Web server (step 2), and allows it to process ASP/VBScripts on the server. The results are then sent in the form of an HTML document back to the client side (step 3). From now on the client HTML browser can send various requests to and receive replies from the DS server through the Web server (steps 4 and 5 in Figure 3). The Web server is used here as an in-between translator.

It is important to notice here that this solution does not require any part of the NetWare client installed on the client PC and so this can be used as a "pure Internet" solution when there is a need to get/set NDS information over the Internet from any remote side.

This model can be seen from our point of view (accessing DS data) as a typical three-tier architecture model. Business rules (in our case DS APIs) are removed from the client and executed on the Web server, which is between the user interface (HTML browser on the client PC) and the data storage system presented by the DS server with the DS database.

While accessing DS database according to Figure 1 requires Internet Explorer to be used on the client PC (because we need to embed COM object on the client side in this case), accessing the DS database following Figure 2 does not have any special requirements on the client. The ASP engine can generate default HTML code, which can be then processed and displayed by any HTML browser. Sure, the code generated on the ASP side can also be more sophisticated (and in fact it will be as you will learn later), and thus it might require IE presence for correct data interpretation.

We will discuss both presented approaches in more details in the following text.

Using AX NWDir in HTML

Now we have some basic understanding how NWDir ActiveX control can be used in an HTML document, and what might be the limitations of such usage. But there is another, perhaps even worse limitation than those already. What is it? It is the HTML itself! What do I mean by this?

Well, we cannot suppose HTML to be a real programming language. When the whole HTML story started few years ago, it was designed as a kind of stateless language, using HTTP connectionless and stateless protocol. Each HTML page realizes one stateless transaction with the Web server, with very poor and very limited interaction possibilities. Look at Figure 3:

Each HTML page realizes one stateless transaction with the Web server, with very poor and very limited interaction possibilities.

One HTML document after another is simply downloaded from the Web server and interpreted by an HTML browser. Where does the whole interaction remain? You, as an HTML programmer, can typically only create a form on one page, let the user fill in the data and let him hit the submit button. The browser then takes values from the form fields, builds the HTTP request packet, and sends it over to the Web server. The server gets the request, processes it, and returns data in the format of another HTML document.

When the client submits a request, the server replies with a response. When the client submits another request, then server again replies with another response, having no idea about any previous mutual data exchange or communication. The whole concept is quite robust against communication failures and low-speed communication links, and this fact was perhaps quite important feature when the whole World Wide Web story started. Nowadays building client/server applications in such trivial environments can become very complicated and frustrating just due to these mentioned interaction limitations. In order to do some work and proceed from stage X to stage Y, a programmer must always refresh the whole page. Really not too much fun!

It became much more interesting for programmers when scripting capabilities were added to HTML browsers. In fact, all the fun we can now have with NWDir control (and of course with other embedded COM based objects) in HTML documents is allowed thanks to scripting power.

But what is scripting in an HTML browser? Scripting enables HTML applications to do some kind of a real job on the client side without the need to refresh or reload the whole page repeatedly. For example, scripting enables an application to check the type of the browser a user is running and react accordingly, set and store values in local variables, use conditional statements, run loops, validate user inputs and communicate with the user, instantiate and use COM component objects, and call applets, functions, and procedures. Sounds great, does not it?

Look at the Figure 4, which is a simplified graphical idea of the scripting in HTML application. The HTML browser contacts the Web server and downloads the default (home) HTML document. Because this document contains some scripts, these scripts can be processed when required (after being downloaded). Then browser downloads another HTML document, which again can contain scripting code. And the whole process continues.

Simplified graphical idea of the scripting in HTML application.

Scripting allows an HTML application to react to events like pressing a button or moving the mouse over a given object in a currently displayed HTML page. Validating user's input locally in scripts and processing locally some data allows eliminating frequent reloading of HTML pages.

Today two scripting languages are most popular -VBScript and JavaScript (also known lately as ECMAScript). Basically we can use any scripting language in our HTML code we like, as long as our HTML browser supports it. We can also use a combination of scripting languages in one HTML source code because they can perfectly coexist in the same HTML page.

In the sample code and discussions throughout this series I will focus on VBScripts only. If you already have experience with VB programming but not with VBScript, you will find VBScript pretty ease to understand. In case you have no experience with Visual Basic at all, you don't need to worry about that now. I believe you will find yourself soon familiar with VBScript when reading sample code in this series or later when creating your own code in VBScript. Even in case you are not a programmer, but by reading this article you are looking for an ASP/NDS solution, I am sure you will find that VBScript is a good tool and very easy to start with.

VBScript is a subset of the Microsoft's Visual Basic for Applications (VBA) language that is used in Visual Basic, Excel, Access, or Word. VBScript was intentionally designed to be fast, so for this reason (and in contrast to Visual Basic) it supports only one data type-Variant. For security reasons VBScript does not include functionality that directly accesses the underlying operation system, like file I/O or registry manipulation.

Important for our purpose is the fact that VBScript supports external objects, either provided by IE, or objects embedded into the HTML document through the <OBJECT< HTML tag or by using VBScript CreateObject() method.

Techniques discussed later are heavily dependent on Microsoft's Component Object Model (COM) technology and may be used without any change and without difficulties only with Microsoft's Internet Explorer (IE).

Adding the ActiveX control to an HTML Document

The Novell NWDir ActiveX control is a COM based component. It can be used in an HTML document in case Internet Explorer (IE) is used as the browser. As any other COM component, NWDir control can be added to HTML documents by using the <OBJECT< tag. This tag in its complexity can be composed from more than twenty different properties, but fortunately for us, there is no need to specify all of them. Here is the full syntax of this tag:

<OBJECT
   ACCESSKEY=key
   ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | 
   TEXTTOP | TOP
   CLASS=classname
   CLASSID=id
   CODE=filename
   CODEBASE=url[#version=a,b,c,d]
   CODETYPE=media-type
   DATA=url
   DATAFLD=colname
   DATASRC=#ID
   HEIGHT=n
   ID=value
   LANG=language
   LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT  | VBS 
   NAME=name
   STYLE=css1-properties
   TABINDEX=n
   TITLE=text
   TYPE=MIME-type
   WIDTH=n
   event = script
>

We will actively use only the following properties: ID, CLASSID and CODEBASE. Let's look at them closer; the best explanation is from the code snippet:

<OBJECT ID  = "NWDir1"
   CLASSID  = "CLSID:4F021AE3-9E98-11D0-A808-00C04FDCD94A"
   CODEBASE  = "http://www.novell.com/nds/controls/nwdir.ocx">
   <PARAM NAME = "FullName" VALUE="NDS:\\NDS_TREE\[Root]">
</OBJECT>

The identifier ID="NWDir1" specifies what will be the name of the instantiated object in our HTML document. From now on, when we want to call any method of this object or get any of its properties in our HTML code, we have to use this identifier.

CLASSID = "CLSID:4F021AE3-9E98-11D0-A808-00C04FDCD94A" specifies the globally unified identifier, which unambiguously defines this ActiveX component among all other components existing on the local system. The background processes need this identifier to be able to find required components in the system registry in order to load and instantiate the component into application memory.

It can easily happen that the component we want to use in our HTML code cannot be found in the computer registry simply because it does not exist on that PC. What to do then? Is our HTML application sentenced to fail? No, not necessarily. In such situations the next parameter - CODEBASE - can be of a help.

CODEBASE= "http://www.novell.com/nds/controls/nwdir.ocx" says, that the required component can be found on the specified Web site under the specified name. IE can then download and install this component "on-the-fly" in case the component was not found on the local system. (The link name we used in this sample does not exist in reality. It is your obligation as a programmer to specify a valid, existing path here. )

In case you have the impression that embedding controls into HTML pages this way (especially controls not yet installed on the local PC and requiring downloading from the remote side) can be dangerous for a computer security, then you are right. It is a significant security concern. Fortunately there are two options that can help to minimize security risks:

  1. You always have choice either to allow or to refuse such remote downloads. For the user's convenience there is a possibility of implementing a security warning in IE browser -IE warns before loading and installing the required component from the remote side (but only if IE properties are set accordingly).

  2. The component in question can be digitally signed, which presents a certain level of assurance and authenticity. This feature does not exclude possible misbehavior of downloaded component-it only informs you where this component came from.

If the component is digitally signed, and the browser's security properties set, the browser will pop up the following window with information about the component producer:

Security Warning.

As you can see, Novell's NWDir control is also digitally signed, so this way any end user who downloaded the HTML/NDS application and is in the process of downloading and installing NWDir control via IE browser can make himself a bit more sure and trust the component.

CODEBASE property parameters can also be used to install a newer version of the given component on the local machine.

There is an alternative way to add an ActiveX control into an HTML document. It can be done using VBScript's CreateObject() method:

Set NWDir1 = CreateObject("NWDirLib.NWDirCtrl.1")

The disadvantage of this later method is that it supposes the required ActiveX control is already installled on the client PC. It does not offer you an alternative to download and install the control "on-the-fly" from the remote Web site, as does the method which uses the "OBJECT" tag in case the control is missing on the client PC.

Who Am I?

This is our first HTML sample that uses the NWDir ActiveX control. It is in fact a kind of "Hello world" sample code. Here is how it looks like when downloaded into the IE window:

Who Am I HTML sample.

We can see two buttons in our IE window: the GetVersion button, which, when pressed, investigates the version of the locally installed NWDir ActiveX control, and the WhoAmI? button, which, when pressed, returns the full DS name of the local NetWare user.

We start our code with the standard HTML header:

<HTML>
<HEAD>
<TITLE>Who Am I sample code</TITLE>
</HEAD>

Next is the block with scripting code in VBScript. This block must be written within the paired <SCRIPT< tag and there should be specified in the beginning tag which scripting language will be used for scripting. This is important information for the browser, which has to handle and interpret the scripting code.

In fact, all jobs in this sample code are done in the scripting block. When the user presses either of the buttons on the form, OnClick() event is being fired. We catch with scripting procedures this event for both buttons. When the GetVersion button is pressed, we call NWDir1.AboutBox() method. In case WhoAmI? button is pressed, we call the internal VBScript msgbox procedure and pass NWDir1.LoginName property as a parameter into this procedure.

<SCRIPT LANGUAGE="VBScript">
   
Sub GetVersion_OnClick()
   call NWDir1.AboutBox()
End Sub
   
Sub WhoAmI_OnClick()  
   msgbox NWDir1.LoginName
End Sub
   
</SCRIPT>

Sometimes it is useful to embed the whole scripting block in comment tags <!-- and --<. This prevents browsers that do not understand scripting from seeing the scripting code and misinterpreting the whole HTML document:

<SCRIPT LANGUAGE="VBScript">
<!--
Sub GetVersion_OnClick()
   call NWDir1.AboutBox()
End Sub
Sub WhoAmI_OnClick()  
   msgbox NWDir1.LoginName
End Sub
-->
</SCRIPT>

In general, <SCRIPT< blocks can be put anywhere in the HTML document. They can be in the <HEAD< section or in the <BODY< section. They can also be outside of any section. It is a good practice to put them in the <HEAD< section. This way the scripting code is read and decoded before it is needed by any call from within the <BODY< section of the HTML document.

Here is the block with <OBJECT< tag which creates NWDir instance when the HTML document is loaded into the IE browser. By default I use in this sample code only the locally installed NWDir component. Commented out in this code snippet is the syntax which allows the remote component to be downloaded and installed. The full path to the component is http://rletos-1/nwdir.ocx.

<OBJECT CLASSID="CLSID:4F021AE3-9E98-11D0-A808-00C04FDCD94A"
ID="NWDir1" WIDTH=32 HEIGHT=32 >
<!-- Http link here for remote download and installation -->
<!--     CODEBASE="http://rletos-1/nwdir.ocx">  -->
</OBJECT>

Finally there must be a <BODY< part in our HTML which creates buttons and adds some text to the document:

<BODY BGCOLOR=#66CDAA>
<p>
<font face="Arial" size="+1" color="Red">
Who Am I sample code
</font>
<p>
To find out the version of installed NWDir control: <BR>
<INPUT NAME = "GetVersion" type="button" VALUE="Get Version">
<p>
To get full DS name of local NW user:<BR>
<INPUT NAME = "WhoAmI" type="button" VALUE="Who Am I ?">
<p>
</BODY>
</HTML>

Supposing we are already logged into the DS tree, here is the output from this HTML code when the WhoAmI? button has been pressed. We have used for the output one of the built-in VBScript standards - msgbox() method, which can take a string as a parameter and display it in a small output window on the screen. As you can see, the current user is logged as a user RLetos in the tree NOVELL_INC, and the user's full context is esc.dus.emea.novell:

VBScript.

Pressing the GetVersion button calls one of the basic NWDir methods called AboutBox().This method simply creates a small informational window on the screen and provides information about the NWDir control version used and a copyright notice:

About Novell Directory Control.

How would the code look if we wanted to instantiate our NWDir control into our scripting code without using the<OBJECT< tag? We would need to modify the scripting code by adding the following code into the <SCRIPT< block:

Dim NWDir1
Sub Window_OnLoad()
   Set NWDir1=CreateObject("NWDirLib.NWDirCtrl.1")
End Sub

The first line in this snippet declares global (in fact, page scope) variable NWDir1. Procedure OnLoad() is called by the IE browser whenever an HTML document is downloaded from the Web server. This procedure is usually used for initialization sequences etc. We use it here to instantiate our NWDir ActiveX control.

Conclusion

In the next installment we will discuss browsing the DS tree from an HTML page and getting DS object values from the DS tree.

* 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