The Novell Controls for ActiveX and Visual Basic: Creating Directory Entries
Articles and Tips: article
Software Engineer
Novell DeveloperNet University
01 Jan 2000
Shows how to create new entries in the NDS directory. Using this article as a guide, a Visual Basic programmer will be able to use the Session and Directory controls to create organization, organizational unit, and user entries in an NDS directory, add fields to the new entries, and set the values of the fields. This is the sixth article in a series on Novell Directory Services (NDS) programming, using the Novell Controls for ActiveX and Visual Basic.
- Introduction
- Creating Directory Entries
- Example Program: CreateEntry
- CreateEntryForm
- Still Want More?
Introduction
This article is the sixth installment in a series on Novell Directory Services (NDS) programming, using the Novell Controls for ActiveX and Visual Basic. So far, we've talked about setting up your development environment, logging in to a directory, reading and searching NDS field values, and writing data values to NDS fields. This article tells how to create new entries in the NDS directory.
|
Objective |
Using this lesson as a guide, a Visual Basic programmer will be able to use the Session and Directory controls to create organization, organizational unit, and user entries in an NDS directory, add fields to the new entries, and set the values of the fields. |
|
Prerequisites |
Entry-level Visual Basic programming skills, a DeveloperNet subscription (Electronic Level subscription available free at http://developer.novell.com), successful completion of SearchField task in previous article. |
|
Required Items |
See "Required Setup." |
|
Optional Items |
None. |
|
Required Setup |
A NetWare 4 or 5 server, a Win32 workstation (Windows 95/98/NT) with installed software: the appropriate Novell Client for the operating system, Microsoft Visual Basic or Visual Studio, and the Novell Controls for ActiveX. |
|
Development Environment |
The procedures discussed in this article were tested using a 200 MHZ Pentium-based workstation with 64 MB RAM, running Windows NT 4.0, a NetWare 5.0 file server, the NetWare Client for NT 4.60, Microsoft Visual Studio 6.0, and the Novell Controls for ActiveX 1/25/99. |
A previous article in this series ("The Novell Controls for ActiveX and Visual Basic: Searching NDS Field Values,
" Novell Developer Notes, October 1999) introduced you to the structures that comprise the NDS directory: fields, entries, and layouts. If you missed that article or need a review, you can find that article on the DeveloperNet Web site, http://support.novell.com/techcenter/articles/dnd19991001.html.
Creating Directory Entries
There are four steps to creating a new NDS directory entry:
Declare an object of type NWEntry.
Dim newEntry As NWEntry
Create an object of the type you want to create and give it a common name
Set newEntry = NWDir1.Entries.Add("User", "Laura")Assign values to the entry's mandatory fields and any optional fields you want to set. For example, for a User entry, the Surname field is mandatory. If you do not set the Surname field, the entry will not be added to the directory.
Call newEntry.SetFieldValue("Surname","Petrie")Update the entry in the directory. The new entry is not added to the directory until you call its Update method.
Call newEntry.Update
Example Program: CreateEntry
CreateEntry allows you to create and delete organization, organizational unit, and user entries, based on descriptions contained in a text file.
Each line in the text file contains the specification for one directory entry. Fields within the directory entry are separated by tilde (~) characters.
The specification for an organization entry begins with the keyword "ORGANIZATION," followed by the name of the organization:
ORGANIZATION~VerySmallCompany
CreateEntry will create the organization entry at the root of the selected directory.
The specification for an organizational unit entry begins with "OU" and has the full path for the organizational unit to be created:
OU~VerySmallCompany\Marketing
The specified path must be valid, that is, the organization entry must exist before you can put any organizational units in it.
The specification for a user entry begins with "USER," followed by the full name of the user, the user's surname, title, and phone number:
USER~VerySmallCompany\George Smith~Smith~President~555-1212
The title and phone number fields can be empty, but the tilde field separators are required. There must be a string in the surname field.
CreateEntry is a valuable utility (or at least the beginning of one) for creating and populating a directory to be used for testing NDS utilities. For example, when CreateEntry reads the following input file, it will create an organization entry named "VerySmallCompany," three organizational unit entries named "Marketing," "Engineering," and "Accounting," and 11 user entries in the containers that comprise the organization.
ORGANIZATION~VerySmallCompany OU~VerySmallCompany\Marketing OU~VerySmallCompany\Engineering OU~VerySmallCompany\Accounting USER~VerySmallCompany\George Smith~Smith~President~555-1212 USER~VerySmallCompany\Veronica Smith~Smith~Marketing VP~555-6318 USER~VerySmallCompany\Jedd Smith~Smith~Engineering VP~555-6051 USER~VerySmallCompany\Samuel Smith~Smith~Accounting VP~555-3694 USER~VerySmallCompany\Emma Jones~Jones~President's Secretary~555-3056 USER~VerySmallCompany\Marketing\Peter Smith~Smith~Inbound Mktg Dir~555-8562 USER~VerySmallCompany\Marketing\Jeanne Smith~Smith~OutBound Mktg Dir~555-3054 USER~VerySmallCompany\Marketing\Sharon Jones~Jones~Mktg Admin~555-2066 USER~VerySmallCompany\Engineering\David Smith~Smith~Eng Dev Dir~555-6521 USER~VerySmallCompany\Engineering\Tom Smith~Smith~Test Eng Dir~555-2054 USER~VerySmallCompany\Engineering\Tammy Jones~Jones~Eng Admin~555-1254
Figure 1: CreateEntry. s
To build the CreateEntry program:
Start Visual Basic and create a new "Standard EXE" project.
Add the Novell Directory and Session controls to your project:
Open the Components dialog by selecting "Components" from the Project menu, or by right-clicking the Toolbox and selecting "Components" from the pop-up menu.
Scroll down the list of components and check the boxes next to "Novell Directory Control" and "Novell Session Control."
Click "OK."
CreateEntry consists of three forms and one code module. As mentioned earlier, two of the forms can be copied from the ReadField program.
ConnectionsForm, LoginForm, and Module1
The previous article in this series, "The Novell Controls for ActiveX and Visual Basic: Searching NDS Field Values
" (October 1999), had instructions for designing and writing the associated code for two forms, ConnectionsForm and LoginForm, and one code module, Module1. You will need to make one small change to each of the two forms, so you should create a new directory for the SearchField program and copy ConnectionsForm.frm, LoginForm.frm, and Module1.bas to this new directory.
After copying the files, do the following:
Add Module1 to the project by selecting "Add Module" from the Project menu, clicking on the "Existing" tab, and selecting the Module1.bas file that you just copied.
Add the forms to the project by selecting "Add Form" from the Project menu, clicking on the "Existing" tab, and selecting the ConnectionsForm.frm and LoginForm.frm files that you just copied.
For each form, double-click anywhere on the form to open the associated code and change the line of code that says
SearchFieldForm.Show
CreateEntryForm.Show
Make ConnectionsForm the project's startup form by opening the project's property sheet from the Project menu, then selecting "ConnectionsForm" from the Startup Object drop-down menu.
CreateEntryForm
1. After the user has selected the directory that CreateEntry is to operate on, CreateEntryForm loads. To create CreateEntryForm, add a new form to your project by selecting "Add Form" from the Project menu and clicking the "Open" button with the "Form" icon selected. Resize the form and add the components and associated attributes as shown in Figure"2.
Figure 2: Components and Attributes placed on CreateEntry Form.
CreateEntryForm doesn't have any list or combo box controls, so there are no lists of items that need to be built when the form loads. So all the Form_Load subroutine has to do is set the program's default context to the root of the tree the user selected, either from ConnectionsForm or LoginForm:
Private Sub Form_Load()
'Set context to root of the tree the user has selected
NWSess1.DefaultFullName = "NDS:\\" + DefaultTree + "\[Root]"
NWDir1.FullName = NWSess1.DefaultFullName
End Sub
Notice that a string with the form:
NDS:\\<Tree Name<\[Root]
(including the square brackets around "Root," and where "Tree Name"is the name of the directory) is the full name of the root of the specified directory.
There are two buttons on CreateEntryForm. The first is named ExitBtn, and ends the program when the user clicks on it. To enter the code for ExitBtn, double-click on it and enter an End statement in the button's Click subroutine, as shown below:
Private Sub ExitBtn_Click()
End
End Sub
CreateEntryForm's other button initiates the process in which the user selects a script file and the program parses and creates (or deletes) the entries specified in the file.
Private Sub SelectBtn_Click()
Dim lineStr As String
Dim fs As Object
Dim scriptFile As Object
'use the Windows common open dialog
CommonDialogCtrl.ShowOpen
'switch to hourglass cursor (parsing the file can take minutes)
CreateEntryForm.MousePointer = vbHourglass
'open the file, parse it, close it
Set fs = CreateObject("Scripting.FileSystemObject")
Set scriptFile = fs.OpenTextFile(CommonDialogCtrl.FileName, 1, 0)
Call ParseScriptFile(scriptFile)
scriptFile.Close
'and go back to the default cursor
CreateEntryForm.MousePointer = vbDefault
End Sub
ParseScriptFile is the procedure that parses the script file. It reads a line from the script file and checks the directive at the beginning of the line to see if the line contains a specification for an organization, organizational unit, or user entry. The procedure then either creates or deletes the specified entry, depending on the setting of the CreateDeleteOpt radio buttons. As entries are created or deleted, the procedure displays a message in the MessageText text box. ParseScriptFile does minimal error checking, and if it encounters a line that it doesn't recognize, it simple displays an error message and terminates.
Private Sub ParseScriptFile(scriptFile As Object)
Dim tempStr As String
Dim contextStr As String, nameStr As String, surnameStr As String,
titleStr As String, phoneStr As String
Do While Not scriptFile.AtEndOfStream
On Error GoTo FileError
'read a line from the script file
lineStr = scriptFile.ReadLine
'is it an Organization?
If Left$(lineStr, 13) = "ORGANIZATION~" Then
nameStr = Mid$(lineStr, 14, Len(lineStr) - 13)
If CreateDeleteOpt(0).Value Then
'Create option button was selected
DisplayLine ("Creating Organization: " + nameStr)
If (CreateOrganization(nameStr) = False) Then
DisplayLine
("*** Error creating organization. Script file line:")
DisplayLine (lineStr)
End If
Else
'Delete option button was selected
On Error GoTo DeleteError
DisplayLine ("Deleting Organization: " + nameStr)
NWDir1.Entries.Remove (nameStr)
End If
'is it an OU?
ElseIf Left$(lineStr, 3) = "OU~" Then
nameStr = Mid$(lineStr, 4, Len(lineStr) - 3)
If CreateDeleteOpt(0).Value Then
DisplayLine ("Creating OU: " + nameStr)
If (CreateOU(nameStr) = False) Then
DisplayLine ("*** Error creating OU. Script file line:")
DisplayLine (lineStr)
End If
Else
'is it a User?
ElseIf Left$(lineStr, 5) = "USER~" Then
'copy to temporary string, strip off USER~
tempStr = Right$(lineStr, Len(lineStr) - 5)
'copy name to nameStr, then strip it off
nameStr = Left$(tempStr, InStr(1, tempStr, "~", vbTextCompare))
tempStr = Right$(tempStr, Len(tempStr) - Len(nameStr))
nameStr = Left$(nameStr, Len(nameStr) - 1)
'copy surname to surnameStr, then strip it off
surnameStr = Left$(tempStr,
InStr(1, tempStr, "~", vbTextCompare))
tempStr = Right$(tempStr, Len(tempStr) - Len(surnameStr))
surnameStr = Left$(surnameStr, Len(surnameStr) - 1)
'copy title to titleStr, then strip it off
titleStr = Left$(tempStr, InStr(1, tempStr, "~", vbTextCompare))
tempStr = Right$(tempStr, Len(tempStr) - Len(titleStr))
titleStr = Left$(titleStr, Len(titleStr) - 1)
'phone is everything left, copy it to phoneStr
phoneStr = tempStr
If CreateDeleteOpt(0).Value Then
DisplayLine ("Creating User: " + nameStr)
If (CreateUser(nameStr, surnameStr, titleStr, phoneStr)
= False) Then
DisplayLine
("*** Error creating user. Script file line:")
DisplayLine (lineStr)
End If
Else
On Error GoTo DeleteError
DisplayLine ("Deleting User: " + nameStr)
NWDir1.Entries.Remove (nameStr)
End If
'are we at the end of the file?
ElseIf Left$(lineStr, 4) = "END~" Then
DisplayLine ("End of entry specifications")
'there's something I don't recognize on this line
Else
DisplayLine ("*** Error parsing line:")
DisplayLine (lineStr)
End If
Loop
Exit Sub
DeleteError:
DisplayLine ("*** Error deleting object: " + nameStr)
Resume Next
FileError:
DisplayLine ("*** Error parsing script file, aborting")
End Sub
DisplayLine is the procedure ParseScriptFile uses to display information and error messages in the MessageText text box.
Private Sub DisplayLine(line As String)
MessageTxt.Text = MessageTxt.Text + line + vbCrLf
End Sub
As ParseScriptFile reads messages for creating organization, organizational unit, and user entries, it calls the CreateOrganization, CreateOU, and CreateUser procedures (respectively) to create the appropriate NDS entries. The code for these procedures is shown below.
Private Function CreateOrganization(name As String) As Boolean
Dim newEntry As NWEntry
On Error GoTo AddError
Set newEntry = NWDir1.Entries.Add("Organization", name)
newEntry.Update
CreateOrganization = True
Exit Function
AddError:
newEntry.Abort
CreateOrganization = False
End Function
Note that after these procedures create a new entry, they must call the entry's Update method to add the new entry to the directory. If an error occurs during creation of the entry, the procedure calls the entry's Abort method, to assure that the entry's resources are deallocated.
Private Function CreateOU(name As String) As Boolean
Dim newEntry As NWEntry
On Error GoTo AddError
Set newEntry = NWDir1.Entries.Add("Organizational Unit", name)
newEntry.Update
CreateOU = True
Exit Function
AddError:
newEntry.Abort
CreateOU = False
End Function
Unlike the CreateOrganization and CreateOU procedures, that simply create an entry of the proper type and with the specified name, CreateUser must also set the surname, title, and phone fields for the user entry after creating them.
Private Function CreateUser(name As String, surname As String, title As String,
phone As String) As Boolean
Dim newEntry As NWEntry
On Error GoTo AddError
Set newEntry = NWDir1.Entries.Add("User", name)
'set attributes for the new User
If (newEntry.SetFieldValue("Surname", surname) = True) And
(newEntry.SetFieldValue("Title", title) = True) And
(newEntry.SetFieldValue("Telephone Number", phone) = True) Then
DisplayLine (" Surname = " + surname)
DisplayLine (" Title = " + title)
DisplayLine (" Phone = " + phone)
newEntry.Update
CreateUser = True
Else
newEntry.Abort
CreateUser = False
End If
Exit Function
AddError:
newEntry.Abort
CreateUser = False
End Function
Still Want More?
The next article in this series will show how to work with stream fields. Streams are binary data with no prescribed syntax. Stream attributes are usually used to store large data objects, like login scripts or images. Because the data in a stream field is unformatted, stream fields can be used to store any type of data that pertains to an NDS entry.
The example program that accompanies the next article will be a simple modification of the CreateEntry program in this article, with an added feature that it can add a login script when creating a user entry.
* 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.