AIIM DMware ODMA FAQ

Q000703: ODMA-Aware Application and Connection-Manager Version Compatibility

Version 0.13  Last updated 2000-09-11-12:51 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.

Summary:

This response expands on the question "What ODMA-level applications are compatible with the different ODMA Connection Manager versions?"

This information is intended primarily for developers.  It is also useful to integrators and information-technology staff concerned with maintaining interoperable ODMA configurations.

1. Intended Down-Level Interoperability

2. Experimental Results

3. Recommended Approach

4. Troubleshooting Considerations

Contributors

Change History

1. Intended Down-Level Interoperability

The evolution from ODMA 1.0 through ODMA 1.5 to ODMA 2.0 has been with the requirement that all versions of the API are upward compatible.  Updates to the specification are intended to preserve operation of ODMA-compliant products produced in compliance with earlier versions of the specification. 

Does this compatibility include "plug-and-play" interoperability among ODMA-compliant products that were physically constructed using different versions of ODMA software libraries?  

Yes.

Requiring ODMA-aware applications to be updated and re-released each time there's a new ODMA connection manager is an unacceptable configuration and integration burden.  It is imperative that ODMA-aware applications developed with earlier (down-level) versions of ODMA operate without change when later (up-level) versions of the ODMA connection manager are installed on the same computer software platform.  

The only exceptions should be for resolution of ODMA-related defects in specific versions of the libraries and Connection Manager and/or in the ODMA-aware applications.  Because interoperability-decreasing repairs are so disruptive of down-level interoperability, stability is often given preference to loss of interoperability except when there is a critical defect that is damaging to predictable, stable operation and the reliable preservation of the work of users.

Satisfying this requirement has the following implications:

• A correctly-built ODMA-compliant DMS integration will operate with any version of the ODMA Connection Manager supplied for the same platform (e.g., Win32).
• A correctly-built ODMA Connection Manager will operate properly with DMS integrations that are compliant with earlier, later, or the same version of specification and platform (e.g., Win16) as the Connection Manager.
• A correctly-built ODMA Connection Manager will operate properly when accessed by applications built with .lib files for the same or earlier versions of the ODMA Connection Manager on the same platform.
• The quality with which up-level DMA-aware applications accommodate down-level ODMA Connection Managers depends on the ingenuity with which coherent behavior is incorporated into the application's design.  (See section 3, Recommended Approach.)

The expected situation is illustrated in Table 1.

fail

The application will usually fail on start-up as the result of not being able to find support for all of the API in the Connection Manager that is present.  System responses are typically inscrutable.  A serious user-centric application would be arranged to bind dynamically and degrade functionality rather than fail to operate in ways that undermine the confidence of users in the application. 

Application Bindings

If an application binds to a level of library that is more than required (e.g., the Application is constructed to use a lower level of ODMA function than the level for which the library is designed), opportunities to fit into more configurations of ODMA are lost for no reason.  See section 3, Recommended Approach.

2. Experimental Results

see also:

Q000706: ODMA Version-Interoperability Configuration

SDKs for ODMA 1.0, 1.5 and 2.0 were installed in a single configuration for easily testing and troubleshooting inter-level interoperability.

Two test applications were chosen from the releases of ODMA:  MultODMA and ODMATest. 

 MultODMA is a simple ODMA-aware document-editor application included in the ODMA 1.0 Development Kit.  The two versions (Win16 and Win32) of MultODMA.exe are constructed using the ODMA 1.0 libraries.

ODMATest is a modified ODMA-aware document-editor application that also allows the ODMA 2.0 settings to be explored.  ODMATest.exe (Win16) and ODMATest32.exe (Win32) are constructed using ODMA 2.0 libraries.

The ODMA 2.0 Sample DMS Integration, ODMASAMP, was used in all tests.  The ODMA 2.0 version was used because the interoperability of DMS integrations with different connection managers is not in doubt.  That interoperability was also confirmed in this experiment.

These applications and the DMS were chosen because they are simple, available to anyone, and fully available for inspection and further experimentation. 

2.1 Interoperability Among Versions of Win16 Components

fail-1

MultODMA fails to detect the ODMA connection manager or DMS and operates as a stand-alone file-based application instead.

fail-2

ODMATest crashes with a General Protection Fault on startup.

fail-3

ODMATest fails inscrutably: Open and Save menu selections result in no operations and no menus, neither file-system nor DMS based.

ok

Documents are correctly created in the single document collection shared between the Win16 and Win32 ODMASAMP DMS integrations.  Documents created in ODMASAMP by all successful applications (Win16 or Win32) are accessible, whether using the same or different version of ODMA Connection Manager.  A high level of interoperability is achieved.

These initial results suggest that it is not possible to easily achieve the desired level of interoperability with the ODMA Win16 libraries and Connection Managers.

There is no deeper analysis of underlying cause at this point.  The situation is being investigated as a defect.

2.2 Interoperability Among Versions of Win32 Components

fail-4

ODMATest32 fails at startup, with an error message indicative of a problem with ODMA32.DLL.  This is still an inscrutable failure, but with enough distinctness that a trouble-shooting procedure can help.

These initial results suggest that it is definitely possible to achieve a high level of interoperability with the ODMA Win32 libraries and Connection Managers.

Deeper analysis may reveal subtle effects that are not apparent in this crude test using basic ODMA-aware fixtures.

3. Recommended Approach

When an ODMA-aware application is developed, there are two questions to answer with regard to ODMA interoperability: 

1. level of API (i.e., functionality) to employ?
2. version of API libraries (i.e., release level) to employ?

The easiest way to stay within a particular level of ODMA functionality is to use the version of odma.h that corresponds to that level (1.0, 1.5, or 2.0).  

The easiest, most-interoperable way to compile the application for distribution is by using the lowest version of ODMA .lib file for which linking succeeds.

The easiest way to insure the widest support for interoperability and functionality of Win32 applications is simply to install the ODMA 2.0 level Connection Manager, odma32.dll.  

For any new implementations of ODMA-aware applications, using the Win32 software platform is clearly preferable, provided that all intended DMS integrations have Win32 versions.   

For integration on Win16, pray that all of the DMS-aware applications are bound to the same library and install that version of the Win16 ODMA Connection Manager.  The Win32 and Win16 Connection Managers do not have to be at the same level to interoperate correctly.  However, logging functions are not provided in Odma.dll releases prior to version 2.0.0.  

4. Troubleshooting Considerations

Developers of ODMA-aware applications need to document the behavior of their application with different versions of ODMA Connection Managers.  If a specific Connection Manager is needed, spell it out.  Be aware that operation with other Connection Managers will be attempted at some point, probably inadvertently as a side-effect of DMS installation or upgrade.  It is important to have troubleshooting procedures that make it easy to confirm when it is a binding and Connection Manager version mismatch that accounts for a failure of the ODMA-aware application to operate.

There is no easy way to determine which ODMA .lib was used, if any, for the static binding of an ODMA-aware application.  It is important to know this for trouble-shooting of application problems.  It would be helpful if such dependency information were built into material included with the application, where it can always be found by a technician or an user engaged in a customer-support call.  Extended Help | About ... information is a good place, as is a separate readme.txt file that can be read even when the application fails to start.

Likewise, it can be very important to know the version of odma.h (and odmacom.h if applicable) that is used in the construction of an ODMA-aware application.  Inter-version interoperability failures may arise as the result of defects or other bit rot in different editions of odma.h.  Knowing the version of library that is used will help to isolate such cases when troubleshooting.

Dennis E. Hamilton
AIIM DMware Technical Coordinator
Renton, Washington, 2000 July 24

---

Contributors

Dennis Hamilton

ran into this situation while documenting use of ODMA 2.0 libraries and choosing the odma.lib and odma32.lib files that maximize interoperability across levels of ODMA.

History

Version 0.13: 2000-09-11 (orcmid)

adjusted to reflect upgrade of Q000703a to Q000706.

Version 0.12: 2000-07-29 (orcmid)

Moved to odma/downloads area for ease in packaging with library materials and cross-referencing with that material via simple shortcuts.  Stitch the material together so that users can employ this tip as part of a library download.  Tweak and correct some typos.

Version 0.11: 2000-07-28 (orcmid)

Correct one layout problem and an incorrect shortcut.  Tweak the title.

Version 0.10: 2000-07-26 (orcmid)

The initial version is created to capture the results of experiments with down-level application interoperability.  It provides a starting point for deeper analysis of possible barriers to full inter-level interoperability.

created 2000-07-24-15:30 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 00-09-11 13:04 $
$$Revision: 8 $