ODMA Incident Report

X000002: ODMA Codes Missing in Odma.h

Last updated 2001-05-21-17:31 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.
Category: Functionality - Defect Incident ID: X000002
Priority: 5 - Important Status: Workaround Under Development
Component: Odma.h 2.0.0
Repaired in: tbd
 Related information:
X000009: Incorrect ODMOpenDoc ODM_REFCOPY Flag
X000301: Constant Definitions Managed Improperly
Q000705: Changes Between ODMA Versions,
Q000703: ODMA-Aware Application and Connection-Manager Version Compatibility,
Errata 2.0: ODMA Version 2.0 Errata,
P000702: ODMA Library Release 2.0.1 project
Assigned To: tbd
Reported By:
Raja Sekhar (1998-07-17)
Bob St. Jean (1998-09-08)
Michael D. Smith (1999-04-16)
Dal Ghotra (1999-08-16)
Evgeny Rex (2001-05-09)
Viktor Yuzyuk (2001-05-15)
Date Reported: 1998-07-17
Date Logged: 2000-08-11
Date Opened: 2001-05-11		 Date Closed: none

Content

1. Incident Summary

2. Actions Toward Resolution

3. Working Around the Problem

4. Analysis

Contributors

1. Incident Summary (2001-05-21)

In the original ODMA 2.0 Library header file Odma.h, the values for a number of flags and result codes are not defined:

Table 1-1.  Missing Values for ODMSTATUS Codes
ODMSTATUS Correct Value Comments
ODM_NOERROR 0      Define this code to preserve down-level compatibility with ODMA 1.5 Definitions.
ODM_E_ALREADYOPENED 24      1. Do not use these result codes with any operation defined prior to ODMA 2.0.  See Q000705: Changes Between ODMA Versions.  These codes are not expected by pre-ODMA 2.0 applications, and failures may be provoked if they are returned.
     2. Do not define these result codes until it is established how to safely return these codes to only those applications that are prepared for them.
ODM_E_ARCHIVED 23
ODM_E_FILELOCKED 25
ODM_W_NOACTION 27      1. An application developed without this definition may fail or behave as if the requested operation failed.  
     2. Do not define this code.  Return ODM_SUCCESS instead.
ODM_E_NORELATION 28  
ODM_E_REFUSED 26      Do not define.  Do not use.  The ODMA 2.0 Connection Manager implementation of  ODMRegisterApp never returns this ODMSTATUS value.

 

Table 1-2.  Missing/Corrected Values for ODMOpenDoc and ODMSelectDocEx flag
ODMOpenDoc/ODMSelectDocEx flag values Correct Value Comments
ODM_REFCOPY 4 Value of 3 is incorrect.  
ODM_TEMPLATE 8  

 

Table 1-3.  Values for Get/Set Relation *pdwflag
ODMGetRelation/ODMSetRelation *pdwflag values Correct Value Comments
ODM_REL_CHILD 1  
ODM_REL_PARENT 2  
ODM_REL_NONE 4  
ODM_REL_NOTORDERED 8  
ODM_REL_FIXED 32  
ODM_REL_RELEASED 64  
ODM_REL_LATEST 128  

 

Table 1-4.  Values for ODMSetDocEvent event
ODMSetDocEvent event values Correct Value Comments
ODM_EVENT_PRINTED 1  
ODM_EVENT_POSTED 2  
ODM_EVENT_SENT 3  
ODM_EVENT_FAXED 4  
ODM_EVENT_ROUTED 5  
ODM_EVENT_COPIED 6  
ODM_EVENT_CONVERTED 7  
ODM_EVENT_DMSDEFINED 8  

 

Table 1-5.  Values for ODMGetODMInterface and ODMQueryInterface HRESULT
HRESULT Correct Value Comments
S_OK 0L      1. These values are defined by standard Windows libraries when odmacom.h is properly included into a program.  Do not define these values directly.
     2. These are but a small selection of possible COM HRESULT codes that can be delivered to applications whether or not returned directly by ODMA DMS implementations. 
     3. Apart from S_OK and E_NOINTERFACE, applications should treat all others as if E_UNEXPECTED.
E_NOINTERFACE 0x80004002L
E_FAIL 0x80004005L
E_UNEXPECTED 0x8000FFFFL
E_ACCESSDENIED 0x80070005L      1. Do not return these  values from an implementation of ODMQueryInterface or ODMGetODMInterface.  
     2. Although these are defined by some standard Windows libraries, there is no use made of them by the ODMA 2.0 Connection Manager.
E_INVALIDARG 0x80070057L
E_ODM_VERSION n/a There is no valid HRESULT with this name.  Do not implement.

2. Actions Toward Resolution (2001-05-21)

The following actions are proposed:

  1. Leave odma.h 2.0.0-1 intact.
  2. Create a supplemental .h file that can be added by #include following the inclusion of odma.h.
  3. The supplemental .h file will define only those codes that are safe to introduce unannounced at this point. 
  4. For the codes that are useful but that introduce compatibility problems, it is recommended that they be abandoned for now and reintroduced with a maintenance release of the specification, the ODMA Connection Manager, and the ODMA libraries.
  5. The introduction of more codes will be accomplished in a way that preserves operation of all ODMA-aware applications implemented with the current ODMA 2.0, 1.5, or 1.0 versions of odma.h and the pre-ODMA 2.0 ODMA Specifications.

3. Working Around the Problem (2001-05-21)

[When the supplemental .h file is available, it will be made available here.]

4. Analysis of Incident (2001-05-21)

[The discussion of history and problems introduced by the additional ODMA 2.0 codes is a bit complex.  We will save this until a decent workaround is available]

Contributors

Dennis Hamilton
reviewed the archive of ODMA Tech mail for unresolved incidents, logging this one (2000-08-11) and later opening it for resolution (2001-05-11) as more people began to notice the deficiency.  Dennis provided analysis of the compatibility issues and the workaround approach.
Bob St. Jean
confirmed that there are omissions and provided an unofficial version of odma.h with his corrections.

created 2001-05-11-08:17 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 04-11-18 14:16 $
$$Revision: 5 $