ODMA Incident Report

X000006: ODMQueryCapability Crash

Last updated 2001-03-17:48 -0800 (pst)
The latest version of this information is available on the AIIM DMware ODMA site.
Category: Functionality - Critical Incident ID: X000006
Priority: 9 - Urgent Status: Under Investigation
Component: ODMA32.dll 2.0.0
Repaired in: tbd
 Related information:
X000902: E_ODMVERSION neither Defined nor Implementable,
X000809: Down-level version Support Not Implemented,
X000808: ODMRegisterApp Filters version Incorrectly,
 Q000705: Changes Between ODMA Versions,
Q000703: ODMA-Aware Application and Connection-Manager Version Compatibility
ODMA 2.0 Specification section 2.19 ODMRegisterApp, and section 2.14 ODMQueryCapability.
ODMA 2.0 Specification Errata.
Assigned To: tbd
Reported By:
Dal Ghotra (1999-03-30)
Date Logged: 2000-08-11
Date Recorded: 2001-03-09		 Date Closed: none

Content

1. Incident Summary

2. Actions Toward Resolution

3. Working Around the Problem

4. Analysis

Contributors

1. Incident Summary (2001-03-10)

When an ODMA Application requests an operation that is defined by the level of ODMA supported by the Connection Manager implementation, but for a later version of ODMA than the DMS integration supports, it appears that the ODMA 2.0 Connection Manager can crash.

Why is this considered critical?

Middleware must not crash in predictable cases for which defensive measures are appropriate and well-defined.  

An ODMA-aware application can have this arise under innocent conditions.  A version-support expectation can be confounded when using a document whose ODMA Document ID is supplied indirectly and the document is managed by a DMS different than the default DMS for the application.

2. Actions Toward Resolution (2001-03-10)

The following actions are proposed:

  1. Record the existence of of the problem and establish an incident report as notification and as documentation of the problem to be confirmed.  [2001-03-10: Completed]
  2. Develop appropriate ODMA 2.0 Specification Errata entries for ODMQueryCapability (and all other non-ODMA-1.0 operations) to have it be clear what response can be expected when the DMS does not provide support for the non ODMA-1.0 operation.  Also, point out that ODMGetDMSInfo, the only precautionary avenue for an application, does not have sufficient provision for failure cases.
  3. Inspect the ODMA 2.0 Connection Manager implementation and identify the conditions under which the software fails to defend against version mismatches between application and DMS integration.
  4. Construct a repeatable demonstration of the problem, if needed to establish that the problem is in the Connection Manager and not in a DMS integration.
  5. Implement any needed correction in project P000902: ODMA Connection Manager Release 2.0.1.
  6. Evaluate the need for specific trouble-shooting procedures for situations in which version matching and confirmation of upward/downward compatibility is important.

3. Working Around the Problem

Colin O'Brien suggests that the function ODMGetDMSInfo, supported by all ODMA DMSs, be used to identify the version that is supported.  If the returned *pwVerNo value is at least 200, for example, then the operation ODMQueryCapability is safe to perform.

4. Analysis of Incident

4.1 Preliminary Investigation (2001-03-10)

The incident report has been taken at face value, along with the suggestions for a workaround.  Even though the workaround is effective, the additional actions for resolving this incident and providing appropriate ODMA Connection Manager support for inter-version interoperability will be pursued as part of further investigation.

This incident is important to resolve because it undermines the reliability of the ODMA Connection Manager as the key bridge to implementation of interoperability among different levels of ODMA implementation:  

  1. It is inappropriate for the ODMA 2.0 Connection Manager implementation to depend on all DMS integrations having full ODMA 2.0 support.  This nullifies the ODMA upward/downward compatibility assurance.  

  2. There are defined responses (i.e., ODM_E_FAIL and ODM_E_NOSUPPORT) for every case where a requested ODMA operation is not implemented.  These responses must be inserted by the Connection Manager when an ODMA operation not supportable by the DMS is requested.

  3. In the specific case of the ODMA 2.0 ODMQueryCapability operation, an ODMA 2.0 (or later) Connection Manager can be made to determine whether an identified function is even supportable with the interfaces offered by a given DMS, inserting an ODM_E_NOSUPPORT result when the function is clearly not supported. 

  4. If the ODMQueryCapability function parameter identifies a function this is supportable by the interfaces offered by a given DMS, but IODMDocMan2::QueryCapability is itself not supported, it is appropriate for the Connection Manager to insert an ODM_E_FAIL response. 

Contributors

Dal Ghotra
detected a Connection Manager failure in exercising ODMQueryInterface and reported the problem along with related questions about access to the DMS COM interfaces.
Dennis Hamilton
reviewed old ODMA Tech mail for untracked incidents, logged this incident (2000-08-11) and then recorded the incident (2001-03-09) as part of having all backlog recorded.  The response is an expansion on the original provided by Colin O'Brien.
Colin O'Brien
responded to Dal Ghotra with suggestion of a workaround involving 
 

created 2001-03-09-22:04 -0800 (pst) by orcmid
$$Author: Orcmid $
$$Date: 01-03-10 17:51 $
$$Revision: 4 $