Novell is now a part of Micro Focus

Novell Directory Services Q & A

Articles and Tips: article

Developer Support Engineer
Developer Support

01 Jul 1997

Q & A

Q. I am using Novell's Directory Services (NDS) Event Services. I realize that NDS Event Services are services that allow NLM applications to request notification of specific NDS events. I also realize that these services will allow NLM applications to register one or more functions that will be called a s callbacks when specific events occur. What are the actual Application Programming Interfaces (APIs) that are available for doing these Event Services?

A. The following APIs are some of the more important functions that can be used for registering NDS Events:



Registers a function to be used as a callback when a specific NDS event occurs.


Unregisters a callback that has been registered to be called when a specific NDS event occurs.


Converts the object names returned in the DSEEntryInfo structure to a form that is consistent with the NWDS... functions.


Retrieves the local ID of a specified Schema attribute.


Retrieves the local ID for the specified object class.


Retrieves the name of the Schema object class that is associated with the supplied local ID.


Retrieves the local ID for the specified Directory object.


Retrieves the name of the Directory object that is associated with the supplied local ID.

Q. Along these same lines, I have never programmed using Novell's NDS Event Services. Since I know the required NLMs ship with the Novell SDK Release 9 and later, what are the steps are required to use NDS Event Services?

A. The following steps are a high-level perspective of the steps that an NDS event-monitoring application will take:

  1. Before registering for any events, the NLM application should use the appropriate helper functions to determine the IDs for the desired objects, object classes and attributes that will be monitored.

  2. The NLM application calls NWDSERegisterForEvent to register a function that will be used as a callback when a specific event occurs. The application calls NWDSERegisterForEvent for each event it wants to monitor.

  3. When the specified event occurs, such as the creation of an object, the callback is called and given data about the event.

  4. The callback determines if it wants to use the data. If it does, it either immediately processes the data, or makes a local copy of the data and stores the local copy. Then the callback returns.

  5. If the callback has saved a local copy of the data so it can be processed by another thread, the processing thread processes the event's data.

  6. When the NLM application no longer wants information about an event, it uses NWDSEUnRegisterForEvent to remove its callbacks from the notification lists. The application must call NWDSEUnRegistereForEvent for each event for which it has registered.

Q. What are some of the NDS Events that I can monitor from my NLM application?

A. The list of events that can be monitored are as follows:



Creation of a new Directory object.


Deletion of an existing Directory object.


Renaming of an existing Directory object.


This is the second of two events reported for a move operation. This event specifies the deletion of a Directory object from its original location in the Directory tress. (See DSE_MOVE_DEST_ENTRY.)


Addition of a value to an object attribute.


Deletion of a value from an object attribute.


Closing of a Stream attribute


Deletion of an attribute. This generates DSE_DELETE_VALUE events for values associated with the attribute. The DSE_DELETE_VALUE events occur after the DSE_DETELE_ATTRIBUTE event.


Setting of the bindery context on the server.


Creation of a bindery object.


Deletion of a bindery object.


This is the first of two events reported for a move operation. This event specifies the placement of the Directory object into its new location in the Directory tree. (See DSE_MOVE_SOURCE_ENTRY.) This generates DSE_ADD_VALUE events for all of the values associated with the object.


Deletion of an unused external reference.


Occurrence of an NDS Trace event.


Remote server, where request was destined, is down.


Request could not be completed due to NCP timeout.


A remote connection has been cleared.

Q. Since all of NDS's request data is carried out in Unicode format, I have had to useNWLocalToUnicode and NWUnicodeToLocalto work with the data I receive from calling NDS Event Services APIs. I have noticed that NWLocalToUnicodeand NWUnicodeToLocalare documented in Novell's SDK Release 11 as having a seventh parameter called allowNoMapFlag. allowNoMapFlagis documented as being able to be set to two values. It specifies whether to use the map character. You can pass in either USE_NOMAP_CHARor DONT_USE_NOMAP_CHAR. What I am seeing is that regardless of which flag I pass in, the value is always set to USE_NOMAP_CHAR. What is happening?

A. The seventh parameter for NWLocalToUnicode and NWUnicodeToLocal should never have been published. This was an oversight on Novell's part. The history about this is as follows: a Novell Engineer needed specific functionality for the NetWare Operating System. He modified the internal procedures that NWLocalToUnicodeand NWUnicodeToLocal call to include the seventh parameter for the NetWare Operating System's exclusive use. This seventh parameter governs what happens when an error occurs during the conversion of a Unicode string to ASCII and vice-versa. The flag allows either an error to be returned (DONT_USE_NOMAP_CHAR) or no error to be returned and a special character to be placed, in the string, where the error was encountered (USE_NOMAP_CHAR). This functionality was intended for internal Novell use only.

Novell's Cross-Platform libraries convert the internal seven parameters of NWLocalToUnicodeand NWUnicodeToLocal to the original six parameters via a macro found in UNICODE.H:

#define NWLocalToUnicode(P1,P2,P3,P4,P5,P6) NWLocalToUnicode(P1,P2,P3,P4,P5,P6, 1)
#define NWUnicodeToLocal(P1,P2,P3,P4,P5,P6) NWUnicodeToLocal(P1,P2,P3,P4,P5,P6, 1)

This macro hard-codes the seventh parameter to 1 causing the USE_NOMAP_CHAR flag to be used all the time.

Note: The Novell SDK documentation will be fixed to reflect these changes.

* Originally published in Novell AppNotes


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