Documentum Web Development Kit Troubleshooting Guide

for Windows NT, Windows 2000, Solaris, and HP-UX

Version 4.2.1 July 2001

DOC3-WDKUNIX42-0401

*DOC3-WDKUNIX42-0401*

Copyright © 2001 Documentum, Inc. 6801 Koll Center Parkway Pleasanton, CA 94566 All Rights Reserved.

Documentum®, Documentum 4i™, Docbase™, Documentum eContent Server™, Documentum Server®, Documentum Desktop Client™, Documentum Intranet Client™, Documentum WebPublisher™, Documentum ftpIntegrator™, Documentum RightSite®, Documentum Administrator™, Documentum Developer Studio™, Documentum Web Development Kit™, Documentum Web Gear™, Documentum WebCache™, Documentum ContentCaster™, AutoRender Pro™, Documentum iTeam™, Documentum Reporting Gateway™, Documentum Content Personalization Services™, Documentum Site Delivery Services™, Documentum Content Authentication Services™, Documentum Dynamic Content Assembler™, Documentum DocControl Manager™, Documentum Corrective Action Manager™, Documentum eConnector™ for BEA WebLogic® (BEA and WebLogic are registered trademarks of BEA Systems), Documentum eConnector™ for JDBC, Documentum eConnector™ for CAD, Documentum eConnector™ for SAP™ (SAP is a trademark of SAP AG), Documentum eConnector™ for Lotus Notes® (Lotus Notes is a registered trademark of Lotus Development Corporation), DocInput™, Documentum DocViewer™, GMPharma™, Virtual Document Manager™, Docbasic®, Documentum WorkSpace®, Documentum SmartSpace®, and Documentum ViewSpace® are trademarks or registered trademarks of Documentum, Inc. in the United States and throughout the world. All other company and product names are used for identification purposes only and may be trademarks of their respective owners.

Overview

Overview The Documentum® Web Development Kit (WDK) Troubleshooting Guide provides information on troubleshooting the installation and deployment of the WDK 4.2 sample applications. This information is not found in the online help. This guide does not include information on troubleshooting problems during the development of WDK-based applications. Some tips are provided in the online help for debugging and error-handling.. This document covers the following topics: ■ “Overview” on page 1 ❒ “Obtaining the most recent product version” on page 1 ❒ “Using the correct documentation” on page 2 ❒ “WDK documentation” on page 2 ■ “Installation Problems” on page 3 ■ “Deployment Problems” on page 4 ❒ “Application does not launch” on page 4 ❒ “Application launches, but frames have error messages” on page 7 ❒ “No connection to eContent server or Internet” on page 9 ❒ “wdkSpace works, then stops working” on page 11 ❒ “Custom application errors” on page 14 ■ “Using WDK Documentation” on page 16 ❒ “Online help” on page 16 ❒ “Bug lists and documentation online” on page 17

Obtaining the most recent product version To ensure that you install the most recent version of this product, we recommend that you visit the Documentum FTP site and review the product versions available for your platform.

Troubleshooting WDK-based Applications

1

Overview

Using the correct documentation You should ensure that the documentation you use matches the product version you are installing. Server installation guides typically have two digits, so that a 4.2 installation guide applies to all 4.2.x releases. Release notes typically have the same version number as the product, and can have from 2 to 4 digits. For example, to install server 3.1.7.1, use the 3.1 installation guide for your platform plus the 3.1.7.1 release notes for your platform.

WDK documentation WDK documentation includes the following resources. To install them, choose the custom option in the installer and select the documentation: ■ WDK Online Help: JavaHelp format. See “Online help” on page 16 for

instructions on launching the help. ■ WDK API Reference: Javadoc format. The API reference is installed in

/docs/api. ■ Documentum Web Development Kit Installation and Release Notes: This

document (PDF format). This document is installed in / docs. ■ Documentum Web Development Kit Tutorial: Tutorial in PDF format,

installed in /docs. Sample code: WDK_Tutorial_ 42_Files.tar.gz (Unix) or WDK_Tutorial_ 42_Files.zip (Windows) ■ Migrating to WDK 4.2: Guide in PDF format, installed in

/docs. ■ Internationalizing and Localizing WDK-based Applications Guide in PDF

format, installed in /docs. ■ Sample code for online help module Extending WDK Models and Views:

In the Unsupported directory of the WDK FTP site, ExtendingWDK42_source.tar.gz (Unix) or ExtendingWDK42_source.zip (Windows)

2

Troubleshooting WDK-based Applications

Installation Problems

Installation Problems This section describes the problems that can arise during installation. Make sure that you have properly installed and configured your web server and JSP server and that you can browse to a sample JSP page on your server before installing and deploying WDK. WDK is installed on a development host. You may deploy the sample application or your WDK-based application to an application server on the development machine, or you may deploy to a separate server. In a production environment, you will probably develop on a separate machine and deploy to your app server. When you install WDK and deploy your WDK-based application to an app server on the same machine, do not confuse the roles of the client and server. Each will have content transfer directories, which you can change in the config.xml file. Many server error messages will display in the client browser, and the error message may or may not include a stack trace, which is helpful in debugging. Other server errors will be written to the server and WDK logs, so inspect these logs for information when you encounter unexpected server behavior.

(Solaris) Installer may hang or core dump if insufficient memory for installation There must be sufficient free disk space and free memory to run the installer. A memory allocation of 65 MB to Java cmd is sufficient. Use the ps command to view process memory usage during installation.

(Solaris) tar checksum error when you untar wdkSpace42delta.tar.gz The Solaris tar utility cannot handle long path names in archives. Use the more robust GNU tar utility (GNUtar1.1.3), which can be found at http:// www.ibiblio.org/pub/packages/solaris/sparc. The limitation of the name to 100 bytes is described in the tar man page at http://cluster.ats.ucla.edu:8080/ docs/man/tar.html

Troubleshooting WDK-based Applications

3

Deployment Problems

(Solaris) Installer will not run in a telnet window The installer must run in the server console or in an X-window client because it presents dialogs for navigation on the Unix host.

Deployment Problems Problems during deployment are caused by setup errors, environment errors, or Docbase connection errors. The errors below are grouped by symptom: ■ If the application does not start, go to “Application does not launch” on

page 4. ■ If the application starts but the frames do not fill properly, go to

“Application launches, but frames have error messages” on page 7. ■ If the application launches, but operations fail, go to “No connection to

eContent server or Internet” on page 9. ■ If the application works, but then stops working, go to “wdkSpace works,

then stops working” on page 11.

Application does not launch (JRun/IIS) Error message in browser: "There is no server on port XX of IIS" Check your Windows NT services to make sure the IIS server is running.

(Jrun/IIS) Error message in browser: “Access denied” You must set up anonymous access for the IIS server.

4

Troubleshooting WDK-based Applications

Deployment Problems

(JRun) Error message in browser: "Could not connect to JRun Server" or “JRun exited abnormally” Cause: Your network cannot resolve the URL to the DTD in web.xml. Open the file web.xml (for example, C:\tomcat3.2.2\webapps\shme\WEBINF\web.xml) and change the following two lines: Change to Change "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd" to "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"

(JRun) Error message in browser: "Could not connect to JRun Connector Proxy" The JRun server is not running. Restart the JRun default server, or the JRun server on which you have deployed your application.

(JRun) Cannot run multiple instances of the WDK sample application wdkSpace on the same JRun application server You see the error “Folder tree failed”. WDK does not support multiple instance of Documentum applications in the same server instance.

java.lang.IllegalArgumentException: Path name is mandatory! There are several possible causes for this error message: 1. You have redeployed your application. If the application has changed, the files that were generated by a previous deployment of the application can contain invalid path information. Solution: Deleted all files generated for your application by the JSP server and redeploy. Alternatively, you can redeploy in a separate directory. You must restart your server to clear the native libraries from memory. On Windows, the native libraries may remain loaded in memory even when the server is stopped, so you must reboot the server host.

Troubleshooting WDK-based Applications

5

Deployment Problems

2. You have tried to access WDK JSPs without installing them in a web application. WDK JSP pages require the root alias for the web app, which they get from the request.ServletContext() call.

RightSite or WDK application won’t work on same server To use WDK and RightSite on the same server, you must use the RightSite Administrator to set the value of the RightSite configuration variable DW_NORMALIZE_URL to FALSE. For detailed information on using RightSite Administrator and setting configuration variables, see the Documentum RightSite Reference Manual.

(JRun) Cannot connect to JRun This error can be caused by one of the following scenarios: 1. You did not stop the IIS web server when you set up the JRun connects to IIS. Stop the IIS process (“net stop iisadmin /y” in a command window) before you start the connector wizard. Then restart IIS.

.war file not initialized Error message in browser (Weblogic server): The error Unknown occurred for the following reason: wdkSpace42.war: not initialized

Cause (one of the following): 1. No alias for the application in the Java command line in the start script. Solution: See the Release Notes and Installation Guide for further information on deployment. 2. No .war file present in the /config directory (Weblogic 6). Solution: Weblogic retains alias information for applications in the domain config.xml file even when the application is no longer present. See the Weblogic documentation for information on removing and redeploying applications.

6

Troubleshooting WDK-based Applications

Deployment Problems

java.lang.ClassCircularityError thrown with first WDK JSP page This problem is seen with Weblogic servers prior to version 5.1 Service Pack 8. Upgrade to SP8.

Error message in browser: “Access denied” Your HTTP or JSP server is not properly configured.

NullPointerException from DwWDK.bind( ) This error is caused by curly braces in XML configuration files, which are not permitted by the XML parser. The name value of a section element cannot be contained within curly braces.

Application launches, but frames have error messages Multi-docbase tree and contents pages failed The first pages of the wdkSpace app may fail to load for several reasons.

Missing or bad path to dmcl.ini The error message will be one of the following: “Multi-Docbase Tree failed” or “Docbases Contents Failed”. For example:

Cause: Your dmcl.ini file is missing, or the path to it is not specified correctly in your application server. Troubleshooting WDK-based Applications

7

Deployment Problems

Solution: See the release notes and installation guide for WDK for full instructions. You must restart the application server after fixing the path.

Missing or bad path to DMCL native libraries The native libraries should exist on the JSP server host. Each JSP server has a means of specifying native libraries to be called when the application is initialized. The error message :

8

Troubleshooting WDK-based Applications

Deployment Problems

No connection to eContent server or Internet

Cause: Intranet or Extranet connection down, Docbroker down, or Internet connection down. Solution: Check connections.

wdkSpace launches, but operations fail Applet download fails in Internet Explorer On login, the browser displays “Installing Documentum Content Transfer Applet”, then “This application will not function properly without the Content Transfer Applet.” The application then displays Install and Exit buttons, but install fails. Cause: (one of the following) 1. Cookies are not enabled in the IE browser. Solution: Enable cookies. 2. The applet directory does not have write access (typical location for IE is C:\\WINNT\Downloaded Program Files). Solution: Change access on the applet directory. 3. See the next item, Browser hangs on login

Troubleshooting WDK-based Applications

9

Deployment Problems

Browser hangs on login or displays error message: java.lang.InstantiationException: com/documentum/wc/applet/ contentxfer/DwContentXferUtilApplet Cause: You tried to connect to a WDK 1.X-based application after connecting to a WDK 4.2-based app. Solution: You need to apply the WDK 1.0.1 patch. The patch can be obtained at the following URL: ftp://ftp.documentum.com/patches/Web/ WebDevelopmentKit/

IE browser reports that WDK applets are damaged If you connect to a newer version of WDK, the new content transfer applets will download and the IE browser will report that the applets are damaged, but they are not. This is due to a Microsoft VM bug. See http:// support.microsoft.com/support and search on “damaged status display”.

(JRun) Content transfer fails The error message: The view operation failed occurred for the following reason com.documentum.wc.env.DwContentXferException: An error occurred on the server: java.util.zip.ZipException: error in opening zip file Cause: The JRun internal server may be listening on the same port as the default server for your WDK application. By default, the JRun internal server runs on port 8000. However, if it is set to listen on port 8100, it must be changed so that it doesn’t conflict with the application server. Solution: Turn off the JRun internal server in the JRun administrator console.

Docbase does not appear in the list of available Docbases The Docbase is either down or it does not project to the Docbroker named in your dmcl.ini file.

10

Troubleshooting WDK-based Applications

Deployment Problems

Could not connect to Docbase (error message) Solution: Weblogic: Make sure your server has a dmcl.ini file or docbroker specification in the Weblogic start script and that the Docbroker name is valid. See the WDK Release Notes and Installation Guide. (Unix) Make sure the weblogic administrator does not have a different environment setting for the DOCUMENTUM or DMCL_CONFIG variables. User settings will override the path that is specified in the Weblogic start script. To check the Weblogic administrator’s settings, enter: env

(Netscape) Error message in browser: “Your browser currently has smart update disabled” Cause: The WDK content transfer applets require Netscape smart update. Solution: Enable this feature in the Netscape browser settings.

wdkSpace works, then stops working (JRun) Application server hangs Cause: You have exceeded the number of connections for your license. Check the most recent WDK log file in the application WEB-INF/log folder. You will see a log item for each active docbase session, for example: ...createDwDocbaseSession(), there are now 2 active docbase sessions

The last entry will read: [id=...], connect(), connected

Solution: WDK is certified on the Enterprise Edition of JRun. Upgrade to that version of JRun.

No sessions available (error message in browser) Cause: You have run out of Docbase sessions.

Troubleshooting WDK-based Applications

11

Deployment Problems

Solution: Increase the maximum number of Docbase sessions in the IIS server dmcl.ini file. The default, when max_session_count is not specified, is 10 connections. This setting governs the number of connections to all Docbases by the HTTP server. For example: [DMAPI_CONFIGURATION] max_session_count = 1000

Menu disappears or XML parser error is reported Cause: If you have modified a WDK XML config file, and the file contains XML syntax errors, the menu may disappear or the page that it configures will report an XML parser error. Solution: You can test your configuration files in IE 5. When you open an XML file in the browser, it will display any syntax errors.

(Netscape) Can’t import files Cause: Netscape requires a mapped drive for file access. Solution: To import files using Netscape browsers, you must map a network drive and then select the file for import.

Browser times out even if the operation is still executing on the server Cause: Timeout behavior is built into the browser. This is not the same timeout that is controlled by the JSP server. A user’s JSP session will not time out while an operation is executing. Solution: No known workaround. WDK cannot control browser timeout behavior.

Lists of object types, base and extended permissions, users, groups, formats, templates, and configuration elements do not reflect changes to Docbase or WDK config files Cause: These objects are cached at the application level for performance reasons.

12

Troubleshooting WDK-based Applications

Deployment Problems

Solution: There are three approaches to this scoping issue. 1. You can create these objects with session scope rather than application scope. Performance will suffer. 2. When changes to these objects occur (new object type, new permission sets, new users or groups, formats, templates, or config file changes) you can restart the application server to clear the DwApplication cache. 3. You can clear the cache using the WDK administrator page in the sample application wdkSpace. This sample application can be found in the Unsupported directory on the WDK FTP site.

(Netscape) Browser cannot display more than 4 or 5 folder levels in the Docbase tree Cause: The tree view is displayed within HTML tables. The Netscape browser has a limitation in displaying deeply nested tables. When the user opens the 4th or 5th level, the refresh takes much longer and consumes all of the CPU on the client machine. Solution: Limit levels of Docbase folder hierarchy to four or less.

Action Canceled message flashes when user clicks a link before page has fully loaded The user sees an Action Canceled page in the frame that is loading, although the frame eventually loads properly. Cause: This is a known browser limitation. Solution: No known workaround. WDK cannot control this browser behavior.

Checkin attempt from wrong PC generates bad error message If the user attempts to check in an object from a different PC than the PC on which the The checkin operation failed Cause: com.documentum.wc.applet.registry.DwRegKeyException: Invalid key

Troubleshooting WDK-based Applications

13

Deployment Problems

Solution: Users must check in documents from the PC on which they were checked out.

Applets are installed more than once WDK Content transfer applets are installed on the client at login. The message “Installing applets” is displayed for the following occasions: 1. The first time the user logs in to the WDK server, the server downloads the applets to the client and writes a cookie with the server name and applet version. 2. If the user connects to a different server, that server displays the same message, checks the applet version, and writes a cookie with the new server name and applet version. 3. If the server has a newer version of the applets than the version on the client, the server downloads the newer version and writes a new cookie.

Custom application errors It is impossible to anticipate all of the errors you might make in your custom application. Following are a few errors we have encountered that may help you avoid error.

Properties Form Failed: error reading current docbase object attributes Cause: You have specified an attribute in the properties config file that does not apply to the object type. Solution: You must create a separate properties config file for each object type in your Docbase if you wish to display and set attributes specific to the object type. If you are connecting to multiple Docbases that do not have the same set of object types, you must create config files directories for each Docbase. See the online help for further instructions.

14

Troubleshooting WDK-based Applications

Deployment Problems

java.lang.NullPointerException Error stack trace: java.lang.NullPointerException at com.documentum.wc.env.DwPageContext.acquireSession Cause: You application did not specify the required Session initialization data in config.xml. Solution: See the online help for more information. Search on config.xml

Operation fails intermittently Cause: One cause of intermittent failures is that your Docbase model or view requires a locked Docbase session. Your bean or class should not perform a query in the constructor. Solution: The safest practice, if you need a synchronized session, is to lock the Docbase session before instantiating your class or before the jsp:useBean tag.

com.ms.packagemanager.PackageManagerException: Package not found Cause: You have called a WDK class from within your unsigned applet class, or you tried to call a WDK server class from within your applet. Applet classes can only call client-side classes. Solution: Sign your applets with a digital signature.

com.ms.security.SecurityException -- cannot access File Cause: You have added an unsigned custom applet or modified a WDK applet jar file without signing it. Solution: You must sign all applets that are not supplied by WDK.

WDK classes don’t work when called from custom pages Cause: You created WDK objects outside the WDK namespace. What doesn’t work: doc1 = new DwDocbaseObject( );

Troubleshooting WDK-based Applications

15

Using WDK Documentation

Solution: Creat e the object using DwPageSet, for example: DwDocbaseObject myModel = (DwDocbaseObject) pageSet.create(“myModel”,”com.documentum.wc.widget.docbase .DwDocbaseObject”); myModel.init ( objectId );

javax.servlet.ServletException: DwCommandDispatcher.service java.lang.NullPointerException at com.documentum.wc.env.jsp.DwJSPWebApplication.getRealPath Cause: You created DwJSPPageContext with the deprecated construction: DwJSPPageContext( request, response) and then used the object in a page that requires the context path (request.getContextPath). Solution: Do not use request.getContextPath on a page with this constructor, or use the non-deprecated constructor.

Using WDK Documentation Online help If you choose to install the Help options during installation, the WDK installer copies the following files to your local file system: ■ JavaHelp files in //docs/JavaHelp/

To launch the JavaHelp, enter:

./wdkhelp ■ The Javadoc API reference (HTML format) in

//docs/api/ To launch the API reference, open the file index.html in your browser of choice. ■ Five PDF files in//docs/: ❒ Installation and release notes ❒ Migration guide (from WDK 1.0.1)

16

Troubleshooting WDK-based Applications

Using WDK Documentation

❒ Tutorial ❒ Troubleshooting guide (this document) ❒ Customization guide

Bug lists and documentation online Customers with a software support agreement can read our product documentation and, after commercial release of a product, view lists of fixed bugs on our Technical Support web pages. To view this information you must apply for access to the Technical Support area. ➤

To apply for access:

1.

In your browser, open http://www.documentum.com/

2.

Choose the Customer Service ➤ Technical Support link.

3.

Click the Request Access link.

4.

Complete the form and submit it. Documentum will respond to your request within two business days.

➤

To view a document:

1.

In your browser, open http://www.documentum.com/

2.

Choose the Customer Service ➤ Support Logon link.

3.

Log on to the Technical Support site.

4.

In the left pane, click Documentation.

5.

To list documents, select a sorting method in the List Documentation By field, and click List.

6.

Click the name of the document you wish to view.

Troubleshooting WDK-based Applications

17

Using WDK Documentation

18

Troubleshooting WDK-based Applications