DirXML™ on NetWare® Frequently-Asked-Questions (FAQ)

Contents


Where can I find DirXML documentation online?

http://developer.novell.com/dirxml/


What version of NetWare is required for DirXML to run?

The minimum requirements for DirXML 1.1 are NetWare 5.0 with current service packs, Java v1.1.7b, and NDS 8.6 with current service packs. Recommended requirements are NetWare 5.1 with current service packs, Java 1.2.2, and NDS 8.6 with current service packs.


Why don't the DirXML drivers auto-start?

This is normally caused by improper sequencing of SYS:\SYSTEM\AUTOEXEC.NCF commands, and the individual timing of the file server's boot process. Typically the SYS:\SYSTEM\AUTOEXEC.NCF file will have the following line: SEARCH ADD SYS:\JAVA\BIN following the mount all line. This line exists to allow the file server to find Java.nlm and other associated tools for the Java Virtual Machine (JVM). If the SEARCH ADD SYS:\JAVA\BIN is placed prior to the FILE SERVER NAME <ServerName> line, then the DirXML drivers should autostart at server boot time.

In other words, to fix the problem, simply move the SEARCH ADD SYS:\JAVA\BIN line to the top of the AUTOEXEC.NCF file, or at least prior to the FILE SERVER NAME <ServerName> line.

If the SEARCH ADD SYS:\JAVA\BIN command is not available to the booting file server when it needs to run Java.nlm, then DirXML.nlm cannot load and DirXML drivers cannot start. DIRXML.NLM will not load into memory, until JAVA.NLM has already been loaded into memory. When a file server boots, DS.NLM (NDS) is loaded, but before making the directory service available for usage, DS.NLM checks if DirXML should be loaded, and if so, attempts to load DIRXML.NLM. At this time, as DIRXML.NLM attempts to load, the server attempts to auto-load JAVA.NLM. If JAVA.NLM cannot be found due to a "missing" search path, then JAVA.NLM fails to load, DirXML fails to load, and DS.NLM continues its initialization process without DirXML.


Where are the DirXML event cache files stored on a NetWare server?

The DirXML event cache files are stored in the same location as the NDS data files (DIB set): in the SYS:\_NETWARE folder which is hidden on a NetWare file server.


Why did NetWare 5.1 Service Pack 2 break my DirXML setup (part A)?

After installing NetWare 5.1 Service Pack 2 (NW51SP2) on a server where DirXML has been installed, the DirXML Driver for eDirectory no longer works.

It is highly likely that the NetWare Service Pack has overwritten SYS:\SYSTEM\JSAS.NLM with an older version (02/11/2000) that does not provide some required SSL calls for the eDirectory driver. The oldest JSAS.NLM that is compatible with DirXML is dated 05/09/2000. Locate this file on your DirXML CD, and copy it to the SYS:\SYSTEM folder. JSAS.NLM has two associated .jar files that also have the same date. They are: nssl1.1_dom.jar and nssl1.1_exp.jar. DIRXML.NLM typically references the .jar files from the SYS:\SYSTEM\LIB folder.


Why did NetWare 5.1 Service Pack 2 break my DirXML 1.0 setup (part B)?

Running the NetWare 5.1 Service Pack 2 (NW51SP2) in conjunction with DirXML 1.0 prevents the DirXML drivers from loading.

NW51SP2 and the initial (FCS) release of DirXML 1.0 on NetWare are incompatible. With NW51SP2 installed, the DirXML engine cannot find "long-named" .jar files (or .zip files) located in the SYS:\SYSTEM\LIB directory. Thus, necessary files such as collections.jar, CommonDriverShim.jar, etc. that are typically located in the SYS:\SYSTEM\LIB directory, become invisible to DirXML. Hence, DIRXML.NLM will load, but cannot successfully load a driver. All .jar files located in the SYS:\SYSTEM\LIB directory with DOS formatted (8.3 format) names are still visible and available to DirXML.

This problem is normally manifest with an error message to the DSTRACE screen at driver start time. When attempting to start the NDSToNDS driver, the error message(s) displayed to the trace screen may be similar to the following:

DVRS: Novell JClient 1.0.19-1.0.19. Copyright 1999 Novell Inc. All Rights Reserved.
DVRS: Error: java.lang.NoClassDefFoundError: com/sun/java/util/collections/Comparable
DVRS: Error: at com.novell.nds.dirxml.engine.nwvrdi.main(Compiled Code)
DVRS: VRDI Initialization Error!

FIX: Update DirXML to the most recent version. The current version of DIRXML.NLM no longer has this problem. An appropriate fix was made available with the SP1 release of DirXML. If updating the DirXML to the most recent version is not an option, then a workaround is also available.

WORKAROUND: Modify the java classpath on the NetWare Server running DirXML. The java classpath can be modified to include each required "long-named" .jar file. Modifying the java.cfg file that is typically located in the SYS:\ETC directory of the NetWare Server is an easy way to appropriately update the java classpath. Once the java.cfg file has been modified, unload JAVA.NLM and reload JAVA.NLM so the new classpath will be "in effect." When JAVA.NLM is loaded, the java classpath can be viewed from the system console by typing the ENVSET command.

The java.cfg file could be modified in similar fashion to the following example, where the additions (the workaround) are emphasized. Remember all "long-named" .jar or .zip files that would normally be located in the SYS:\SYSTEM\LIB directory need to be appropriately referenced in the java classpath, or in other words, included in this java.cfg configuration file, for this workaround to be effective.

SYS:\ETC\JAVA.CFG:

JAVA_HOME=SYS:\JAVA
OSA_HOME=SYS:\JAVA
MGMT_HOME=SYS:\PUBLIC\MGMT
CLASSPATH=sys:\java\lib\classes.zip;sys:\java\classes;.
CLASSPATH=$CLASSPATH;SYS:\SYSTEM\LIB\collections.jar
CLASSPATH=$CLASSPATH;SYS:\SYSTEM\LIB\CommonDriverShim.jar
CLASSPATH=$CLASSPATH;SYS:\SYSTEM\LIB\NetscapeShim.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\swing.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\jgl3.1.0.jar
CLASSPATH=$CLASSPATH;$MGMT_HOME\ConsoleOne\1.2\help
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\servertop.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\jndi.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\njcl.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\vbjorb.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\vbjapp.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\vbjtools.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\lib\ucs.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWDir.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWSess.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWPrtQAdm.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWSockets.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWBind.jar
CLASSPATH=$CLASSPATH;$OSA_HOME\beans\NWVolAdm.jar


Can I use Java command line options to configure the Java Virtual Machine (JVM)?

JVM command line options or switches can be set using special DIRXML_JVM_* environment variables. These DirXML environment settings discussed here are on the NetWare platform only. DirXML on Win32 and on Unix has different environment variables (DHOST_JVM_*).

Any time DIRXML.NLM starts a driver it instantiates a JVM by calling the java class com.novell.dirxml.engine.nwvrdi (the DirXML engine java entry point on NetWare). To do so DIRXML.NLM builds an execution parameter string to be consumed by the Java NLM. This execution string has the following form:

java <DIRXML_JVM settings> -classpath <classpath built by DIRXML.NLM> com.novell.nds.dirxml.engine.nwvrdi -driverID <entryID> -fGetSchema <0 | 1>

DIRXML.NLM checks each of the above DIRXML_JVM_* variables and appropriately builds the DirXML JVM settings to be placed in the execution parameter string before launching a JVM instance for a driver.

The following options can be used on NetWare:

DIRXML_JVM_INITIAL_HEAP set to value in bytes of initial java heap size. Works with 1.1.x and 1.2.x.
Example: DIRXML_JVM_INITIAL_HEAP=4M
Example: DIRXML_JVM_INITIAL_HEAP=4096K
DIRXML_JVM_MAX_HEAP set to value in decimal bytes of maximum java heap size. Works with 1.1.x and 1.2.x.
Example: DIRXML_JVM_MAX_HEAP=36M
Example: DIRXML_JVM_MAX_HEAP=36864K
DIRXML_JVM_VIRTUAL_HEAP set to value in decimal bytes of virtual java heap size. Works with 1.1.x and 1.2.x.

Example: DIRXML_JVM_VIRTUAL_HEAP=36M
Example: DIRXML_JVM_VIRTUAL_HEAP=36864K
DIRXML_JVM_OPTIONS set to arguments for the 1.2 JVM.
Example: -Xnoagent -Xdebug -Xdebugport8080 -Xmx36M
Each option string is separated by whitespace. If an option string contains whitespace, it must be enclosed in double quotes.

DHOST_JVM_OPTIONS only works with 1.2.x.
DIRXML_JVM_C_STACK_SIZE set to value in decimal bytes of the java C process stack size.
Example: DIRXML_JVM_C_STACK_SIZE=128K (default)
Example: DIRXML_JVM_C_STACK_SIZE=256K


Why must DIRXML_JVM_ environment variables be placed in SYS:\ETC\JAVA.CFG?

To avoid unnecessary confusion. If you really want to hear the nuts and bolts of it, read on.

DirXML is not a CLIB dependent NLM. As such, it does not hold (or have access to) CLIB environment variables by default. DirXML obtains CLIB environment settings via an imported getEnv call which exists in JClient (actually the jclntR.nlm). When a CLIB dependent NLM loads, CLIB creates a copy of the current CLIB environment, for that NLM. Thus when jclntR.nlm loads, the current CLIB environment variables at that time will then be available to DIRXML.NLM. JAVA.NLM also gets a copy of the CLIB environment variables at load time, and maintains these environment variables, and even allows them to be managed using the ENVSET system console command. When JAVA.NLM is loaded, the initial java NLM environment variables are also set within (copied to) the separate CLIB environment. So when JAVA.NLM is loaded, all settings within the JAVA.CFG file are set within the java NLM environment as well as the CLIB NLM environment. In addition, any existing CLIB environment variables (prior to JAVA.NLM load time) are attached to the end of the java NLM environment variables. Thus, after JAVA.NLM is loaded, JAVA.NLM and CLIB.NLM have equivalent environment settings. Any java NLM enabled "envset" commands which are entered at the system console after JAVA.NLM load time are only placed within the java NLM environment and not mirrored in the CLIB environment. In a similar fashion any CLIB.NLM enabled "env" commands which are entered at the console command after JAVA.NLM is loaded are not mirrored to the JAVA.NLM environment.

When considering DIRXML.NLM, we are concerned about the CLIB NLM environment variables as they exist at jclntR.nlm load time. So any "env" commands that are entered at the system console after jclntR.nlm has loaded will never be picked up by DIRXML.NLM because jclntR.nlm already has its copy of the CLIB environment which it obtained at load time. Likewise, any JAVA.NLM ENVSET commands entered after jclntR.nlm has already been loaded, will not be available to DIRXML.NLM.

Because of the complicated nature of sharing NetWare environment variables, we recommend that all necessary DIRXML_JVM_* parameters be placed in the SYS:\ETC\JAVA.CFG file. In this way, they are guaranteed to be effective.


How do I get DirXML to display trace messages or error messages on NetWare?

Several trace mechanisms are available on NetWare.

  1. Let us first consider DSTRACE.NLM. DSTRACE can be used to display trace messages on the system console. Also trace messages can be logged to a file (DSTRACE.LOG) using DSTRACE. DSTRACE displays messages to a screen labeled DSTrace Console. Any system console screen label can be seen on the top of the file server screen when holding down the system console's ALT key. After loading DSTRACE.NLM, type DSTRACE to see the current settings of the NLM. An easy way to configure DSTRACE to display only DirXML trace messages is: DSTRACE -ALL +DXML +DVRS. If you would also like to display message tags and time stamps use the following: DSTRACE -ALL +DXML +DVRS +TAGS +TIME.
  2. Another method of displaying trace messages is to use the internal trace of DS.NLM. This internal trace method can be displayed to the system console screen by entering the following set command at the system console: set dstrace=on. Once the internal DSTRACE is turned on, a system console screen labeled Directory Services is available for view. Any system console screen label can be seen on the top of the screen when holding down the ALT key. To turn on DirXML trace messages for this trace screen enter: set dstrace=+DXML. To turn off DirXML trace messages for this trace screen enter: set dstrace=-DXML. To turn on DirXML driver trace messages for this trace screen enter: set dstrace=+DVRS. To turn off DirXML driver trace messages for this trace screen enter: set dstrace=-DVRS. To turn off the internal trace screen enter: set dstrace=off.
  3. Another method of displaying trace messages is to use the NDSiMon utility. This is a web management tool that can be used to view DSTRACE messages from any Web browser. These web services are integrated with NetWare management portal services, and can be found under the NDS Management DS Trace bullet.
  4. DIRXML.NLM also builds an error log: SYS:\SYSTEM\DIRXML.LOG. Only DirXML errors are stored in this file. This file will not grow larger that 500K.
  5. Each DriverSet object can have a trace file specified. To create (or modify) a trace file configuration from ConsoleOne, select a particular DriverSet object with your mouse, right click, select Properties, from the properties DialogBox select the Other tab, Add a new attribute (or modify the existing one) called DirXML-JavaTraceFile and enter the value of the log file name to be used (i.e. SYS:\SYSTEM\DRVSET1.LOG).
The amount of DirXML driver information that is displayed can be controlled by a DriverSet attribute. To create (or modify) a DirXML-DriverTraceLevel configuration from ConsoleOne, select a particular DriverSet object with your mouse, right click, select Properties, from the properties DialogBox select the Other tab, Add a new attribute (or modify the existing one) called DirXML-DriverTraceLevel and enter the value of 0,1,2,or 3, to control the verbosity. 0=min, 1=low, 2=medium, 3=high.


What causes a java.lang.ClassNotFoundException error message?

This problem can occur when the Java Virtual Machine (JVM) cannot locate a particular class that is necessary to run DirXML, or a DirXML driver. DirXML java code (including DirXML drivers) is typically located in the SYS:\SYSTEM\LIB directory. When located in this directory, this code must be in the form of a .jar or .zip file. Other code may be accessed by the JVM if it is appropriately referenced by the java classpath. The following steps are performed when DIRXML.NLM creates a classpath parameter to be passed to the JVM at driver launch time:

  1. DIRXML.NLM always puts the following files first (even if they don't exist):
  2. DIRXML.NLM then appends all files in the SYS:\SYSTEM\LIB directory with a .jar extension. These typically are SYS:\SYSTEM\LIB\nssl1.1_exp.jar, SYS:\SYSTEM\LIB\collections.jar, SYS:\SYSTEM\LIB\i18n.jar, SYS:\SYSTEM\LIB\CommonDriverShim.jar, and the appropriate driver .jar files and their dependent pieces (if any).
  3. DIRXML.NLM then appends all files in the SYS:\SYSTEM\LIB with a .zip extension.
  4. DIRXML.NLM lastly appends the current java classpath as it exists on the system at that moment.
Thus, to start a driver, DIRXML.NLM will build a string internally that may look like the following.

Java -Xverify:none -classpath SYS:\SYSTEM\LIB\dirxml.jar; SYS:\SYSTEM\LIB\jclient.jar; SYS:\SYSTEM\LIB\nxsl.jar; SYS:\SYSTEM\LIB\xp.jar; SYS:\SYSTEM\LIB\nssl1.1_exp.jar; SYS:\SYSTEM\LIB\collections.jar; SYS:\SYSTEM\LIB\i18n.jar; SYS:\SYSTEM\LIB\CommonDriverShim.jar; SYS:\SYSTEM\LIB\Nds2Nds.jar; $CLASSPATH com.novell.nds.dirxml.engine.nwvrdi -driverID 37240 -fGetSchema 0


What causes a java.lang.OutOfMemoryError error message?

When examining this error, the first three error lines in the DSTRACE log look similar to the following:

DirXML Log Event -------------------
Status = error
Message = java.lang.OutOfMemoryError:

These lines are then followed by the java stack trace of the methods requesting memory from the Java Virtual Machine (JVM).

To resolve this, increase the maximum memory that is available to the JVM by inserting or modifying the DIRXML_JVM_MAX_HEAP environment variable in the SYS:\ETC\JAVA.CFG file. Within the java architecture, each JVM has a limited amount of memory it can allocate from the operating system. This value can by used to prevent java from consuming all system memory resources. By default, this maximum memory limit for each NetWare 1.1.7b JVM is 16M (16M == 16 Megabytes == 16384K). By default, this maximum memory limit for each NetWare 1.2.2 JVM is 64M. If running Java 1.1.7b on NetWare, try inserting the following line into SYS:\ETC\JAVA.CFG: DIRXML_JVM_MAX_HEAP=32M. Or, if running Java 1.2.2 on NetWare, try inserting the following line into SYS:\ETC\JAVA.CFG: DIRXML_JVM_MAX_HEAP=128M. This will double the default maximum memory usage for each JVM. Remember to unload java, and then reload DirXML for the new values to take effect. If the problem still persists, increase the memory value until the problematic driver can acquire the memory it needs.

Note: each DirXML driver running on a NetWare server runs within a separate JVM.


What causes a "VRWriteCacheBlock: Unable to open cache file [FileName]. Err: failed, database not found (-734)" error?

This error may occur frequently with the DIRXML.LOG file. In this case the error indicates Unable to open cache file <DIRXML.LOG>. This error occurs when multiple processes are simultaneously attempting to log information to the DIRXML.LOG file. Only one process can write to DIRXML.LOG at a time, while the others processes wait. If a DirXML process (i.e. a driver) is denied writing to the DIRXML.LOG, this -734 error is sent to DSTRACE. The probability of this -734 error message occurring increases as more drivers simultaneously log information to the DIRXML.LOG file. Generally the error itself is not a concern, when associated with DIRXML.LOG. When multiple drivers are operating on a file server, this error message occasionally occurs, and should not cause alarm. If the problem is excessive, ensure the DIRXML.LOG file is not being held open by another application or editor, and can be freely accessed and written to by DirXML.

If the error occurs with a file name that has an extension of .TAO (i.e. 33252.TAO), then this is a serious error, and would be cause for concern. If this is the case, then DirXML is having trouble updating its cache files. Ensure appropriate disk space is available on the SYS volume of the file server. To recover from this problem it may be necessary to disable the driver with the problem cache file, causing the cache file to be deleted, and then re-enabling the driver. If the cache file cannot be deleted by the driver disable operation, it may be necessary to remove the cache file manually. Caution! Deleting a cache file is an extreme solution! Be ready to live with the consequences of such an action! Beware! Disabling drivers and deleting cache files causes ds events intended for a connecting application to be lost. After a cache file is lost or identified as corrupt, then DirXML will attempt to "resync" that cache file's driver/application. Even the "resync" operation does not guarantee restoration of "all" events that were once cached, and then lost.