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.
Contributors
Change History
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.
Connection Manager |
|||
ODMA 1.0 |
ODMA 1.5 |
ODMA 2.0 |
|
ODMA 1.0
|
ok | ok | ok |
ODMA 1.5
|
fail | ok | ok |
ODMA 2.0
|
fail | fail | ok |
- 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.
- 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
andODMATest
.
MultODMA
is a simple ODMA-aware document-editor application included in the ODMA 1.0 Development Kit. The two versions (Win16 and Win32) ofMultODMA.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) andODMATest32.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.
ODMA 16 Connection Manager |
|||
Application Bindings |
ODMA 1.0 |
ODMA 1.5 |
ODMA 2.0 |
|
ok | fail-1 | fail-1 |
ODMA 1.5
|
not tested | not tested | not tested |
|
fail-2 | fail-3 | ok |
- 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 inODMASAMP
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.
ODMA 32 Connection Manager |
|||
Application Bindings |
ODMA32 1.0 |
ODMA32 1.5 |
ODMA32 2.0 |
|
ok | ok | ok |
|
not tested | not tested | not tested |
|
fail-4 | fail-4 | ok |
- fail-4
ODMATest32
fails at startup, with an error message indicative of a problem withODMA32.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.
When an ODMA-aware application is developed, there are two questions to answer with regard to ODMA interoperability:
- level of API (i.e., functionality) to employ?
- 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.
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. ExtendedHelp | About ...
information is a good place, as is a separatereadme.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
(andodmacom.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 ofodma.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
- Dennis Hamilton
- ran into this situation while documenting use of ODMA 2.0 libraries and choosing the
odma.lib
andodma32.lib
files that maximize interoperability across levels of ODMA.
- 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 $