An AppWare Loadable Module for NetWare Directory Services

Articles and Tips: article

CARY ANDREWS
Software Engineer
NetWare Utilities ALM Development Team

BRUCE CUTLER
Software Engineer
NetWare Utilities ALM Development Team

01 Sep 1994

The NetWare Directory Services AppWare Loadable Module (NDS ALM) is a software component used in the development of applications in the Visual AppBuilder environment. It comprises a group of associated functions that provide high-level access to the services provided by NetWare 4 Directory Services (NDS). The NDS ALM makes it possible for you to write applications that access NDS without having to code directly to the NDS API's.

Introduction
NDS ALM Components
Using the NDS ALM
The Login Script Editor Project
Summary

Introduction

The NetWare Directory Services AppWare Loadable Module (NDS ALM) is a software component that is used by developers in the Visual AppBuilder (VAB) environment. This ALM provides access to the information stored in the NetWare Directory Services database.

It provides access to the NDS information by consolidating many of the NetWare Directory Services (NWDS) APIs into a set of high-level functions. These functions, when combined with other VAB functions, allow you to create NDS-aware applications without having to write a single line of code.

As with most other Visual AppBuilder components, the NDS ALM has objects and functions that store and manipulate data. The objects store the data read from or to be written to the Directory.

The functions are used to read data from the Directory, manipulate the data once it is available, or to supply data to be used in creating or modifying objects in the Directory.

Novell had these main goals in providing NDS access to application developers via the NDS ALM:

Speed
Flexibility
Ease of use

Speed

This ALM was developed to speed development efforts where NDS access was desired. By using the NDS ALM a developer can quickly access the objects found in the Directory without having to spend time figuring out how to use the APIs in the NetWare SDK.

Flexibility

Contained in the ALM are all the functions necessary to read, modify, and create nearly every type of object found in the NetWare Directory. An important feature is that the NDS ALM was written using the database dictionary, referred to as the schema.

In other words, the functions were written to be able to read the schema to determine what objects and properties are defined in the Directory.

This means that if the NDS database has been extended by adding new classes or new class properties, the ALM will still function properly and be able to see and handle the extensions to the Directory. No update of the NDS ALM will be required to handle changes to the schema. This gives you great flexibility.

Ease of use

The functions provide common NDS operations in simple, easy to understand building blocks. As with all the other Visual AppBuilder functions, these functions connect together through signals and flows which produce function chains that are executed when they are called.

Constructing, testing, and debugging these function chains is easy, because of the granularity of the functions and the inherent characteristics of the Visual AppBuilder environment.

NDS ALM Components

The NDS ALM is made up of object and functions. Consistent with other Visual AppBuilder ALM design, the NDS ALM objects store data, and the functions manipulate the stored data.

NW DS Objects

Two objects are included in the NDS ALM: the NW DS Data object, and the NW DS Query object. The NW DS Data object is used to store an NDS object's information. The NW DS Query object stores information used when reading from the Directory using one of the read or list functions.

Each of these objects has a dialog box that provides the developer with the ability to specify the amount of information used in these objects. You can display the dialog boxes by double-clicking on the object icon in the group where the original object was placed.

NW DS Data Object. The NW DS Data Object stores NDS object information. The fields associate Visual AppBuilder objects with the NDS values stored in this object (see Figure 1).

Figure 1: This is the NW DS Data box.

The following table shows the fields, the Visual AppBuilder object type for each field, and the value that is stored in that object.

Field	VAB Object Type	Value
Name	Text	The name of the NDS object.
Context	Text	The NDS contextwhere the object is located.
Effective Rights	Text	The effectiverights the user has to the object.
Subordinate Count	Number	The numberof subordinates this object has if it is a container.
Dereferenced Name	Text	The objectname of the dereferenced object if this objectwas accessed via an alias.
Alias Entry	Flag	An indicationof whether or not this object was accessed via an alias.
Container Entry	Flag	An indicationof whether or not this object is a container.

NW DS Query Object. This is where information specifying what objects, in which context, and which properties are going to be read, is stored. The fields are used to associate Visual AppBuilder objects for storage of the values kept in this object (see Figure 2).

Figure 2: This is the NW DS Query box.

The following table shows the field, the Visual AppBuilder object type for each field, and the value that is stored in that object.

Field	VAB Object Type	Value
Name	Text	The name of the NDS object.
Context	Text	The NDS contextwhere the object is located.
Class Filter	Text	The name ofan NDS class to be used as a filter. Onlyobjects of this type will be listed whenusing the List Subordinates function.
Subordinate Mask	Text	A text patternto be used as a mask.
Show Alias	Flag	An indicationof whether or not to show the alias object'sinformation instead of the dereferenced object'sinformation.
Get Effective Rights	Flag	An indicationof whether or not to read object and property rights.
List of Properties	List	A list of propertiesthat will be read in; all others will not be read.

NW DS Data Functions

The NDS ALM has one functional category, called NW DS Data. It contains 33 functions, logically divided into the following operational categories.

Read	Modify	Schema	Get Data	Set Data	Miscellaneous
List Subordinates	Create Object	List Classes	Get Class	Set Class	Clear Property
Object Exists?	Change Password	List Properties	Get Date/Time Property	Set Date/Time Property	Compare Properties
Read Object	Delete Object		Get Net Address Property	Set Net Address Property	Property Supported
Verify Password	Modify Object		Get Number Property	Set Number Property	Set New Context
Who Am I?	Move Object		Get Table Property	Set Table Property
Get Current Context	Rename Object		Get Text Property	Set Text Property
Get Current Tree			Get Time Property	Set Time Property

Using these functions, the developer has the ability to create applications that efficiently and reliably access NetWare Directory Services on any NetWare 4 server. These functions are, for the most part, much higher level than the NWDS APIs. Even so, they provide the "plumbing" to allow the developer to use his or her creative abilities to build any number of different applications that access the powerful NetWare Directory Services database.

Using the NDS ALM

In this section we're going to cover the basic principles of using the NDS ALM, by describing the parts of a sample application put together with Visual AppBuilder. The application is a login script editor that reads the logged-in user's login script, allows the user to edit it, and then allows the user to save it back to the network.

In this project we have four groups and one subroutine. The groups are called Data, Main, Update, and Exit. The subroutine is called Modify Login Script. Our discussion will focus on each of the groups and the subroutine individually.

Here is a summary of the steps necessary to read and modify a user's login script.

Center and open the window.
Clear the previous value of the login script.
Get the user's login name from the Who Am I? function.
Format the login name with a preceding dot so that we won't have to set the context in order to read the user's object.
Call the Read function to read the user's object from the Directory.
Get the login script property out of the NW DS Data object.
When the update button is pressed, check to see if the login script was changed.
If it was changed, call the Modify Login Script subroutine and put up a notification that the change was made.
When the user clicks on the Exit button and the login script was changed, give the user the option of saving the changes or exiting from the application.
Use the Modify Login Script subroutine to set the new login script property into the NW DS Data object and call the Modify Object function.

The Login Script Editor Project

The login script editor project contains only one subject and one window. We will take each of the subject's groups and subroutine individually and explain the function chains in each, listing each function, giving the name and purpose for it.

The Data Group

For this project's purposes we have grouped most of the data objects into one group. The objects are easy to find and check during debugging when grouped together. Of course, this works for small projects but may not be the best way to handle very large ones.

Figure 3 shows the Data Group.

Figure 3: This is the Data Group.

The following table explains our project's data group.

Object	Value
Data	(NW DS DataObject) We have edited this object and madethe following changes. The object's Namefield is associated with the Object Name text object. The Context field is associatedwith the Context text object.
Query	(NW DS QueryObject) We have edited this object and madethe following changes. The object's Namefield is associated with the Object Name text object. The Context field is associatedwith the Context text object. TheList of Properties field is associated withthe Property Filter list object.
Context	(Text Object)This is the context of the user.
Login Script	(Text Object)This is the user's login script.
Full Name	(Text Object)This is the user's full name returned from Who Am I?
Object Name	(Text Object)This is the full name preceded by a dot (.).
Property Filter	(List Object)This is the name of the property we are goingto read. It is set to "Login Script".This speeds up the read operation by tellingthe Read function to read only the LoginScript property for each user.
Changed	(Flag Object)This flag object will tell us when the loginscript has been changed.

The Main Group

The main group is shown in Figure 4.

Figure 4: This is the Main Group.

This group is active immediately at application startup. The functions and the actions that take place in each function chain are shown in the following tables.

Object	Description	Application Startup Flow
Application	(ApplicationObject) Controls application startup routines.

Center Window - centers the window. Sets the window attribute as initially not visible in the window layout editor.
Open Window - opens the window to show it centered on the screen.

Object	Description	Window OpenedFlow
Window	(Window Object)Controls the visual information for the application.

HourglassCursor - puts up an hourglass cursor on the screen.
Clear Flag - clears the Changed flag so that we know that the login script has not been changed.
Clear Text - clearsthe Login Script text object. This starts us out with a blank login script text object.
Who Am I? - accesses the network and returns the currently logged-in user's full name into Full Name
ConcatenateText - joins a dot (.) and Full Name together, with the dot in the first position, and places the result in Object Name. This is done so that the currently logged-inuser's object can be read from the proper context.
Read Object - reads the object specified by Query from DirectoryServices and puts the result into Data.
GetText Property - accesses Data and retrieves the login script value. The value is placed into Login Script.
ArrowCursor - turns the cursor back to an arrow.

Note: Due to space considerations we have not included any error flow checking in our examples. Our intent here is not to lessen the importance of proper error checking, but to show the main points of using the NDS ALM. It is important to the usability of an application always to do proper error flow checking and handling.

The Update Group

Figure 5 shows the Update Group.

Figure 5: This is the Update Group.

This group is used to set the Changed flag and to make modifications to the Directory. The functions and their actions that take place in each function chain are shown in the following tables.

Object	Description	Login Script Edited Flow
Login Script	(Text Object-alias from Data Group).

SetFlag - sets the Changed flag whenthe login script is edited.

Object	Description	Update Button Pressed Flow
Update	(Button Object)When the user clicks on this button, theobject calls the Modify Login Script subroutineto update the Directory with the changedlogin script.

FlagSet? - determines the state of the Changed flag. We look for the flag to be set indicating that the login script was changed.
ClearFlag - clears the Changed flag for the next iteration.
Call Subroutine -calls the Modify Login Script subroutine. We have determined that the login script was changed, so now our modification routine is called to update the login script in the Directory.
Notify Alert - we put up anotification that the update procedure iscomplete.

The Exit Group

The Exit Group is shown in Figure 6. Figure 6: This is the Exit Group.

This group holds the exit button and its associated function chain. The functions and their actions that take place in the function chain are shown in the following table.

Object	Description	Exit Button Pressed Flow
Exit	(Button Object)We will exit the application when the user clicks on this button.

FlagSet? - determines the state of the Changed flag. We look for the flag to be set indicating that the login script was changed.
Yes/No/Cancel- prompts the user by displaying a message stating that the login script has changed and asking them if they want to save it. Presents three choices: Yes, No, Cancel.
CallSubroutine - the user chose Yes, so we call the Modify Login Script subroutine to update the login script in the Directory.
Quit- exits the program if the login script had not changed. The user chooses whether or not to save the login script if it had changed.

The Modify Login Script Subroutine

The Modify Login Script subroutine is shown in Figure 7. Figure 7: This is the Modify Login Script Subroutine.

The functions of the Modify Login Script subroutine and the actions that take place in the function chain are shown in the following table.

Object	Description	Modify Login Script Called Flow
Modify Login Script	(SubroutineObject) This is a subroutine object. Itis used when the login script needs to bemodified. This subroutine is used in placeof having this function chain in multipleplaces.
Replace	(Flag Object)This object is used to determine whether or not to replace the login script property.

SetText Property - sets the new login scriptvalue into the Login Script property in Data, replacing what was previously there. The Replace flag instructs the function to replace the new value. This function operates on memory; the change has not beenmade to the network at this point.
Modify Object- writes the information contained in Data back to the network, updating the logged-in user's login script. This function actually changes the object in the Directory.

The Application Window

Figure 8 shows what our application looks like when it runs. Figure 8: This shows the Login Script Editor running.

Summary

The NDS ALM for Visual AppBuilder is a tool that consists of a powerful set of functions that provide the developer with direct access to the power of NetWare Directory Services. The NDS ALM offers the advantage to developers of accessing NDS without having to understand or use the NWDS APIs directly. What this means to the developer is increased speed in developing applications requiring NDS access, flexibility in being able to create applications that will always know the NDS schema, and ease of use in being able to access NDS from a set of high-level visual programming functions.

* 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.