ODMA Incident Report

X000900: Omission of 0 and ODM_NOERROR from ODMSTATUS

Last updated 2000-09-10-11:58 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.
Category: Functionality - Defect Incident ID: X000900
Priority: 5 - Important Status: Repair Pending
Component: Odma.h, version 2.0.0
Repaired in: tbd
Related information:
Q000705: Changes Between ODMA Versions
Q000703: ODMA-Aware Application and Connection Manager Version Compatibility
Q000704: ODMA-Compliant DMS Integration and Connection Manager Version Compatibility
X000002: Error Codes Missing in Odma.h
Assigned To: Dennis Hamilton Reported By: 
Dennis Hamilton (2000-09-09)
Date Opened: 2000-09-10 Date Closed: none

Summary (2000-09-10):

In the ODMA 1.0 Specification, ODMSTATUS value 0 is defined as the successful result.

In the ODMA 1.5 Specification, ODMSTATUS value 0 continues to be defined as the successful result for those operations preserved from ODMA 1.0.  In addition, ODMSTATUS value ODM_NOERROR is specified as the successful result for new operations introduced in ODMA 1.5.  In the Odma.h file for ODMA 1.5, ODM_NOERROR is correctly defined to 0, preserving downward compatibility and the usability of 0 as the status code for a successful operation.

In the ODMA 2.0 Specification, ODMSTATUS value ODM_SUCCESS is the only defined value for a successful result.  In the Odma.h version 2.0.0, ODM_SUCCESS is correctly defined to 0, preserving downward compatibility.  However, the value ODM_NOERROR is no longer defined in Odma.h, violating the downward compatibility commitment: An ODMA-1.5-compliant program will not compile successfully using version 2.0.0 of the Odma.h file.  

This is a problem for source-code reuse and rebuilding of source code with newer library files.  The binary forms of ODMA-1.5-compliant components will operate properly because only the symbolic name has changed, not the actual value used for successful results.

Actions (2000-09-10):

  1. The update of Odma.h 2.0.0 to version 2.0.1 will define ODM_NOERROR to be the same as ODM_SUCCESS and there will be appropriate cautionary remarks about these always having to have value 0.
  2. There will be no change to the documentation or the ODMA 2.0 Specification.  The steps taken to preserve downward compatibility will be documented with the ODMA 2.0 library files.
  3. As a matter of good practice, new and revised ODMA-compliant components should be programmed to confirm ODM_SUCCESS without depending on its value being known to be 0.  E.g., use

if (rc != ODM_SUCCESS) return rc;

rather than

if (rc) return rc;

Recommendations to this effect will be implicit in new examples and sample software, as well as in any programming tips and programmers guides that are developed.

Investigation (2000-09-09):

  1. The ODMA 1.0, ODMA 1.5, and OMDA 2.0 specifications were compared as part of producing Q000705 on changes between ODMA versions.  The use of 0 in pre-ODMA-2.0 specifications, and the introduction of ODM_NOERROR in ODMA 1.5 was noticed then.
  2. The ODMA 1.5 version of Odma.h was inspected to confirm that ODM_NOERROR is defined and is 0 for downward compatibility.
  3. The ODMA 2.0 header file, Odma.h version 2.0.0, was inspected to confirm that ODM_SUCCESS preserves downward compatibility with 0 but that ODM_NOERROR is no longer defined.

created 2000-09-10-11:58 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 00-09-10 13:12 $
$$Revision: 3 $