AIIM DMware ODMA FAQ

FAQtip Q000600: WordPerfect-ODMA Troubleshooting

Version 0.70  Last updated 2000-09-19-14:52 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.

Summary:

This response addresses the question "How can I trouble-shoot WordPerfect operation with ODMA-based Document Management Systems?"

1. Reviewing WordPerfect Support Resources

2. Confirming Current ODMA Software

3. Configuring ODMA for WordPerfect

4. Logging WordPerfect-ODMA Operations

5. Interpreting WordPerfect Activity Logs

6. Trying Other Things

Contributors

Change History


Summary

For troubleshooting a WordPerfect-ODMA integration, follow these guidelines:

  1. Review Available WordPerfect Support Resources.
    This can lead you to new information about the ODMA-compliant software releases you are dealing with.  Others may have encountered difficulties and arrived at workarounds that you should know about.
  2. Have a Current ODMA Configuration.
    Before working through an integration, make sure you have the correct ODMA software installed.  Having multiple versions of the software installed can lead to inconsistent behavior.  Make sure you have the latest stable release of ODMA software and that it is properly installed.
  3. Configure ODMA for WordPerfect.
    Make sure that the ODMA configuration has WordPerfect be able to use ODMA the way you want.  You can prevent ODMA from being available to WordPerfect, you can specify a particular DMS for default use by WordPerfect, and you can specify a default DMS that is automatically used with any ODMA-aware application that is run.
  4. Log WordPerfect ODMA Activity
    WordPerfect for Windows provides activity logs.  Learn to activate these logs for use in confirming ODMA operation, and see what ODMA is reporting to WordPerfect.
  5. Interpret the WordPerfect Activity Logs
    Use the tutorials here, along with other reference material, to interpret the logs and determine the requests that WordPerfect is making via ODMA and the responses that are returned for those requests.
  6. Try Other Things
    Depending on what your investigations reveal, you may want to try other resources, including problem workarounds that others have found.

1. Reviewing WordPerfect Support Resources

see also: Q000601 WordPerfect Support Resources, for updated information

WordPerfect and Soft Solutions were the original promoters and sponsors of the Open Document Management API development effort.

WordPerfect has supported DMS integration via ODMA on Windows since the original introduction of ODMA 1.0.  

There are three kinds of support information available for current versions of WordPerfect: Direct, Peer-to-Peer, and Community:

It is important to check these and any other resources that you have.  Thoroughness matters.  Many problems are not what they first seem; details contributed as discussions continue are often critical to successful resolution of a problem.

2. Confirming Current ODMA Software

An important first step is ensuring that current ODMA software is installed on your computer.

The latest edition of software is that designed for the ODMA 2.0 Specification.  In general, it is always preferable to use versions of ODMA software designed for ODMA 2.0.  In addition to providing access to maximum functionality, there is special support for troubleshooting that is not available in earlier versions.

For troubleshooting recent versions of WordPerfect for Windows (starting with WPWin 8.0), there is no reason not to use the latest version of ODMA32.dll, version 2.0.0-1.

To ensure that you have the latest, and it is the most appropriate for your configuration, consult ODMA FAQtip Q000603: Latest ODMA Software.  This tip is updated any time there are important changes to the available software.

3. Configuring ODMA for WordPerfect

There are three ways to configure ODMA so that WordPerfect is (or is not) allowed to operate with ODMA: 

  1. Using a default DMS with WordPerfect, 
  2. Using a specific DMS with WordPerfect, 
  3. Using no DMS with WordPerfect.

Prerequisite:

3.1 Using a Default DMS

3.1.1 Confirming Default DMS
3.1.2 Enable WordPerfect ODMA Operation

Even though ODMA software is installed, WordPerfect for Windows will not automatically use ODMA unless a DMS has been assigned for use and WordPerfect for Windows has ODMA operation enabled.

Establishing a Default DMS will allow all ODMA-aware applications to be used with that DMS without any special installation operations being required.  All ODMA-aware applications for which no other DMS has been specified will use the established default as their default DMS.  When it is desirable to avoid ODMA-based operation of some applications, including WordPerfect for Windows, it is then desirable to operate without a default DMS.

see also: 3.2 Using No DMS

3.1.1 Confirming Default DMS

3.1.1.1 Identify Installed DMS Integrations
3.1.1.2 Identify Unique Default Integration

3.1.1.1 Identify Installed DMS Integrations

Using the Windows Registry editor, review the entries under registry key

HKEY_CLASSES_ROOT\ODMA32\

Under the ODMA32 key, there should be one key entry for each ODMA DMS that has a Win32 integration installed.  A DMS is installed if the DMS ID appears as a subkey entry and the subke has a default value that specifies a full path to the .dll file that implements the particular DMS integration.

If there is no ODMA32 key, there are no keys below it, or none of the keys have default values, it is necessary to install one or more Win32 DMS integrations before ODMA operations can be performed via WordPerfect for Windows.  

If you don't have a commercial DMS installed, you can test WordPerfect operation using the ODMASAMP DMS provided with the ODMA 2.0 SDK.  This permits rudimentary testing of operation even though full DMS functionality is not available.  It also allows determination of whether any problems appear to be DMS specific or not.

If you do not install ODMASAMP, you should install at least one Win32 integration for a commercial ODMA-compliant DMS that you have available.  

3.1.1.2 Identify Unique Default Integration

see also: ODMA 2.0 Specification section 5, Installing a DMS

At most one of the 

HKEY_CLASSES_ROOT\ODMA32\

subkeys may identify a global default DMS to be available to all ODMA-aware applications, including WordPerfect for Windows.  Although a default DMS is not required, it is common practice to have one.  You can establish any particular DMS as the default, and you can change the default at any time.

To specify the default DMS, you need to know the DMS ID.  This is the key that occurs just below the ODMA32-key level of the registry.  If you want to be sure which document management system goes with a DMS ID, look for FullName subkeys that provide plaintext descriptions of the product integrated with that DMS ID.  

In the following procedure, the ODMA 2.0 Sample DMS ODMASAMP, with FullName value "ODMA 2.0 Sample DMS (32 bit)" is used for purposes of example.  You can use any installed DMS as the default.

  1. If there is a DEFAULT subkey, and it is not for the DMS that you want as default, delete the DEFAULT subkey(s) that is (are) already there.  
  2. If a default is not already specified, create a DEFAULT subkey for global usage.  For example, to have the ODMA Sample DMS as the 32-bit default, create the key 

    HKEY_CLASSES_ROOT\ODMA32\ODMASAMP\DEFAULT\

    and make sure there is no other ODMA32 DMS ID key that has a DEFAULT subkey.  No value is required for the DEFAULT subkey.

  3. Confirm that the specified DMS is actually installed.  For example, the HKEY_CLASSES_ROOT\ODMA32\ODMASAMP\ key should have a default value that specifies the correct file-system location of the ODMASamp32.dll.  (Do not be surprised if this path is expressed in terms of Win16 8.3-format file-and-subdirectory names, the ones that are always available in addition to long file names on many Win32 file systems.)

3.1.2 Enable WordPerfect ODMA Operation

WordPerfect is normally configured to automatically use ODMA when a DMS is available for usage as the WordPerfect default.  Even when there is no default DMS, WordPerfect may attempt to use ODMA if it encounters an ODMA Document Id for a file to be used.  

If you have current ODMA software and a default ODMA DMS integration has been specified, confirm that WordPerfect is operating with ODMA:

  1. Initiate WordPerfect operation
  2. Specify menu item File | New to create a new document
  3. A DMS-specific file-creation dialog should occur.  This dialog will invite you to provide initial information about the document as it will exist in the DMS.
  4. There will be an option to force the file-system to be used by WordPerfect, even though a DMS is available.  Select that option.
  5. You should now have a new document to work on that has not been assigned to any DMS, and that you can save in the file system the same as when ODMA operation is not available.

If you do not see the above sequence, especially step (3), WordPerfect is not configured to use ODMA.

To make sure that WordPerfect is configured to use ODMA, you need to use the WordPerfect for Windows configuration options to specify enhanced file dialogs.  If your version of WordPerfect for Windows allows the use of ODMA to be controlled as part of that configuration dialog, make sure that ODMA usage is selected.

3.2 Using A Specific DMS

Whether or not a default DMS has been established, you can instruct ODMA to use a particular DMS for WordPerfect.  

This is described in the ODMA 2.0 Specification in section 5, following the discussion of setting the overall default.

The Application Id parameter value that WordPerfect uses for itself is "WordPerfect".

Create a registry key of

HKEY_CLASSES_ROOT\WordPerfect\ODMA32\

and set the default value to the name of the DMS integration (e.g., "ODMASAMP") that you want to force as the initial default for WordPerfect to use.

This application-specific default always takes precedence over any general default.

3.3 Using No DMS

When there is a specific or generic default DMS established for WordPerfect to use, WordPerfect will notice that ODMA is supported in the configuration you have.  It will then offer that DMS any time the operator requests creation of a new document or opening of an existing document.  If WordPerfect fails to obtain a default DMS, it will not do that, offering only its own file-system operations for creating new documents and opening existing documents.

However, if WordPerfect is give an ODMA Document Id, it may still attempt to operate with the DMS that is identified in that Document Id.  And a DMS may launch WordPerfect with that Document Id as a command-line parameter.  This is just by way of warning that you may see WordPerfect attempt to operate with a DMS different than any specified default, and also when no DMS is specified for WordPerfect.

There are a number of ways to specify that WordPerfect is not to use any ODMA DMS:

  1. Register a bogus DMS Id as the specific default for WordPerfect.  E.g., apply the procedure of section 3.2 and use a fictitious DMS Id like "ODMAFAKE".
  2. Have there be no generic default DMS for ODMA and assign a default DMS for every ODMA-aware application that you use except WordPerfect.
  3. Assign an ODMA 2.0-compliant DMS that supports an exclusion list and that rejects WordPerfect connections.
  4. Use configuration options of WordPerfect itself that causes it to avoid using ODMA.  If you cannot find WordPerfect configuration options that do precisely what you want, there are workarounds possible for manipulating WordPerfect's own Windows Registry settings.

4. Logging WordPerfect-ODMA Operations

Word Perfect for Windows versions 8 and 9 provide activity logs for all operations performed via the Open Document Management API (ODMA).  The logs can be used to confirm that WordPerfect and a DMS are properly installed and coordinating via ODMA.

4.1 Prerequisites

Willingness to Modify the Windows System Registry
 

WordPerfect Knowledge Base Article 12912 

4. Interpreting Logs of WordPerfect-ODMA Operations

4.2 Prerequisites

The ODMA 2.0 Specification for explanations of the operations summarized in the log entries.

A text editor or viewer (such as Windows Notepad or WordPerfect) for reviewing the log files that are produced.

WordPerfect Knowledge Base Article 12912 

 

5. Trying Other Things

Creating a Log from ODMA32

Workarounds for known problems


Contributors

Clay Gibney
provided a copy of the procedure for initiating WordPerfect activity logging (2000-06-06) and provided trouble-shooting information as part of working on an ODMA integration incident.
Dennis Hamilton
collected the contributed material and organized versions 0.50-0.70 for initial trial (2000-06-19 to 2000-09-19).

History

Version 0.70: Added Disabling of ODMA for WordPerfect
Tied in procedures for Disabling WordPerfect use of ODMA without crippling ODMA for other applications.
Version 0.66: Work through Default DMS Configuration
Expand the coverage of how to tie WordPerfect and a DMS together by controlling default DMS configurations.  This is tedious and deserves being separated out as a generic case anyhow, with just the WordPerfect-Unique information here.
Version 0.65: Connect Other FAQtips
FAQtips Q000601 and Q000603 are linked from this tip, and the section on Configuration of ODMA is expanded.
Version 0.60: Expanded Material
The location of support information, and the confirmation of the latest version of ODMA are separated out into separate FAQtips.  These will be cross-referenced from other problem work-around procedures.  Additional sections are introduced for covering other elements available in the configuration of WordPerfect for operation with ODMA (and vice versa).
Version 0.50: Initial Trial
The initial version is posted for trial use and confirmation by those who provided the original information and others interested in WordPerfect-ODMA troubleshooting.

created 2000-06-19-15:47 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 00-09-19 14:54 $
$$Revision: 14 $