ODMA: Open Document Management API

Q000705 ODMA FAQtip
 Changes Between ODMA Versions
0.20 Review Draft

ODMA>faq>
2000>07>

Q000705c>
0.20 2010-08-29 20:13 -0700

The latest status on  ODMA 2.0 is always available on the Internet at

http://ODMA.info/support/odma20st.htm.

This document is designed to be used in the same file location as HTML edition 2.0-3 of the ODMA 2.0 Specification and the Errata for that edition.  Shortcuts in this document depend on proximity to a copy of the specification.  A convenient way to make sure all necessary materials are present is to download the complete ODMA 2.0 Documentation Files package.

Summary:

This response expands on the question "What Changed Between ODMA Versions?"

The question is addressed in terms of what an ODMA-aware application would see as different.  There is also attention to what an ODMA-compliant DMS will adapt to (or not) when agreeing to support a particular level of ODMA on behalf of a requesting application.

This information is intended primarily for developers of ODMA-compliant components.  It is also useful as background for troubleshooting and exploring interoperability questions.

Dennis E. Hamilton
AIIM DMware Technical Coordinator
Renton, Washington, 2000 August 29

1. Inter-Level Interoperability
2. Feature Introduction Levels
3. Analysis and Recommendations
4. Sources and Resources

Contributors
Revision History

1. Inter-Level Interoperability

see also:
Q000703 ODMA-Aware Application and Connection-Manager Version Compatibility
ODMA 2.0 Specification description of ODMRegisterApp version parameter

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 downward compatible.  Updates to the specification are intended to be defined so that any DMS integration developed to a newer version of the specification will operate successfully with any ODMA-aware application constructed in correct conformance with an earlier version of the specification. 

Nevertheless, there are revisions to ODMA that do alter the described behavior of interfaces defined under earlier version of the specification.  

This article summarizes when each API element is introduced and where any alterations to the behavior of earlier elements has been added.

2. Feature Introduction Levels

2.1 ODMA 1.0 Baseline
2.2 ODMA 1.5 Changes
2.3 ODMA 2.0 Changes

The following table lists the 31 ODMA 2.0 API operations and the single DMS initiation operation.   The version of ODMA that introduced a given operation is shown in the columns to the right, along with any changes that arose in subsequent ODMA versions.

Table 1.  Level of Individual ODMA Feature Introductions
API Operation ODMA 1.0? ODMA 1.5? ODMA 2.0?
ODMActivate IODMDocMan

unchanged

 ODM_NEWDOC action
ODM_CHECKOUT action
ODM_CANCELCHECKOUT action
ODM_CHECKIN action
ODM_SHOWHISTORY action
ODM_E_ACCESS
ODM_E_OFFLINE
ODM_E_ARCHIVED
ODM_E_NOSUPPORT
ODM_W_NOACTION
ODMCloseDoc IODMDocMan

unchanged

 ODM_E_FAIL
ODM_E_FILELOCKED
ODMCloseDocEx - -

IODMDocMan2
ODMGetAlternateContent - -

IODMDocMan2
ODMGetDMS

-

-

ODMA 2.0
ODMGetDMSCount

-

ODMA 1.5

unchanged
ODMGetDMSInfo IODMDocMan

unchanged

 ODM_EXT_QUERY *pdwExtensions
ODM_EXT_WORKFLOW *pdwExtensions
ODMGetDMSList

-

ODMA 1.5

unchanged
ODMGetDocInfo IODMDocMan

unchanged

 22 item values
ODM_E_OFFLINE
ODM_E_TRUNCATED
ODM_E_NOSUPPORT
ODMGetDocRelation

-

-

IODMDocMan2
ODMGetLeadMoniker IODMDocMan

unchanged

unchanged
ODMNewDoc IODMDocMan

unchanged

 ODM_E_OFFLINE
ODMOpenDoc IODMDocMan

unchanged

 ODM_REFCOPY flags
ODM_E_OFFLINE
ODM_E_ARCHIVED
ODM_E_INVARG
ODM_E_ALREADYOPENED
ODMQueryCapability

-

-

IODMDocMan2
ODMQueryClose

-

 IODMQuery ODM_E_HANDLE,
ODM_NOERROR replaced by ODM_SUCCESS
ODMQueryExecute

-

 IODMQuery queryId[] maximum changed from ODM_DOCID_MAX to ODM_QUERYID_MAX,
ODM_E_HANDLE,
ODM_NOERROR replaced by ODM_SUCCESS
ODMQueryGetResults

-

 IODMQuery lpszDocId[] and lpszDocName[] minimum sizes, 
ODM_E_HANDLE, ODM_E_REQARG, ODM_NOERROR replaced by ODM_SUCCESS
ODMQueryInterface

ODMA 1.0

unchanged

 E_ACCESS_DENIED
E_FAIL
ODMRegisterApp

ODMA 1.0

unchanged

 ODM_E_REFUSED
ODMSaveAs IODMDocMan

unchanged

 ODM_E_OFFLINE
ODMSaveAsEx

-

-

IODMDocMan2
ODMSaveDoc IODMDocMan

unchanged

 ODM_E_NOOPEN
ODMSaveDocEx

-

-

IODMDocMan2
ODMSelectDoc IODMDocMan

unchanged

 ODM_VIEWMODE *pdwFlag input
ODM_E_OFFLINE
ODM_E_FAIL
ODMSelectDocEx

-

-

IODMDocMan2
ODMSetAlternateContent

-

-

IODMDocMan2
ODMSetDMS

-

ODMA 1.5

 ODM_NOERROR replaced by ODM_SUCCESS
ODMSetDocEvent

-

-

IODMDocMan2
ODMSetDocInfo IODMDocMan

unchanged

 22 item values
ODM_E_ACCESS
ODM_E_OFFLINE
ODM_E_NOSUPPORT
ODMSetDocRelation

-

-

IODMDocMan2
ODMUnRegisterApp

ODMA 1.0

unchanged

unchanged
ODMGetODMInterface

ODMA 1.0

unchanged

 E_ACCESSDENIED, E_FAIL, E_ODM_VERSION

2.1 ODMA 1.0 Baseline

ODMA 1.0 introduced 11 DMS-supported operations, 3 Connection-Manager operations, and one integration operation between the Connection Manager and the DMS.

The 11 DMS-implemented operations are identified by IODMDocMan in the ODMA 1.0 column of Table 1.

2.1.1 ODMA 1.0 Connection Manager Operations

see also:
Q000901: Using COM

The ODMA 1.0 Connection Manager implements three operations directly:

The first two are responsible for establishing and discarding an ODMA session.  The third uses the Connection Manager to request any COM interface known to the application from the DMS integration identified in the request.

ODMRegisterApp operations require the application to specify the minimum version of ODMA that the application can accept for its functions.  The DMS integrations have no means for discovering that level nor the level of the Connection Manager that is being used.  It is the Connection Manager that must reconcile the ODMRegisterApp version parameter from the application with the versions supported by individual DMS integrations.

ODMQueryInterface is a means by which an application may dynamically discover additional features of a selected DMS using the Microsoft Component Object Model (COM).  These may be any of the COM interfaces defined for ODMA of any version.  These may also be proprietary or other interfaces that a DMS integration happens to make available and that the application is implemented to employ.  

Microsoft COM interfaces, properly specified and implemented, are inherently versioned.  There are no ODMA versioning concerns for use of the COM interfaces, and the Connection Manager allows any interfaces to be requested, whether the universally-supported IUnknown interface, the ODMA-defined ones, or any others that the application is able to identify.  The selected DMS will determine whether it supports the requested interface and will respond accordingly.  

ODMQueryInterface delivers an HRESULT code.  If ODMQueryInterface has invalid parameters or is unable to access a DMS integration, it will terminate the operation, returning an HRESULT of E_INVALIDARG.  If ODMQueryInterface has valid parameters and is able to access a DMS integration, the HRESULT will be produced by the DMS integration's implementation of IUnknown::QueryInterface.  The permissible results are those defined by the Microsoft COM specification and can be more than the E_NOINTERFACE case defined in the ODMA 1.0 Specification.    

2.1.2 ODMA 1.0 DMS-Implemented Operations

 

2.2 ODMA 1.5 Changes

 

2.3 ODMA 2.0 Changes

 

3. Analysis and Recommendations

[tbd following completion and review of Table 1]

4. Sources and Resources

ODMA (1995).
Open Document Management API Version 1.0a.  ODMA Coalition, AIIM International, December 18, 1995.  Available on the internet at <http://ODMA.info/downloads/odma10-2.htm>.
   
ODMA (1996).
Open Document Management API Version 1.5.  ODMA Coalition, AIIM International, October 29, 1996.  Available on the internet at <http://ODMA.info/downloads/odma15-2.htm>.
    
ODMA (1997).
Open Document Management API Version 2.0.  ODMA Coalition, AIIM International, September 19, 1997.  Available on the internet at <http://ODMA.info/downloads/#ODMA-20-Specification>.  On-line review edition 2.0-3 available at <http://ODMA.info/downloads/odma20-3.htm>.
   
ODMA (2000a).
ODMA Codes Missing in Odma.h.  ODMA Incident Report X000002.  2001-05-21 version available at <http://ODMA.info/support/X000002.htm>.
    
ODMA (2000b).
Omission of 0 and ODM_NOERROR from ODMSTATUS.  ODMA Incident Report X000900.  2000-09-10 version available at <http://ODMA.info/support/X000900.htm>.
    
ODMA (2001).
odma.h 2.0.0-1.  ODMA 2.0 Library Files.  2001-09-04 edition.  Available at <http://ODMA.info/downloads/odma200h.htm>.
     This is the definitive header file for defining the ODMA-specific symbols and API signatures as established with the release of the ODMA 2.0 SDK.
    
Contributors:
Dennis Hamilton
ran into this situation while reviewing the ODMA 2.0 Specification and documenting use of ODMA 2.0 libraries in a way that maximizes interoperability across levels of ODMA.  On noticing that there were changes to down-level interfaces in ODMA 2.0, a complete audit of the three specifications was conducted to establish exactly what changed and what the impacts are.
    
Revision History:
0.20: 2006-04-10-18:32 Preserve as Part of Refresh
The material is captured on a page of the new folio style, with later versions produced as part of standard version progression.  A Sources and Resources from another FAQtip is carried here just for later usefulness.  The comments from previous versions concerning companion material apply to the download version of this page that will transclude pages of this folio.
0.15: 2006-04-06-23:04 Correct Table
ODMSetDocInfo was adjusted to include ODM_E_ACCESS, discovered when preparing Q000702c.
0.10: 2000-09-10 (orcmid)
The running review draft 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.  This document is a companion to the ODMA 2.0 Errata and is organized to be downloaded as a package with that errata and the specification to which it applies.  There are direct shortcuts to those documents that this document depends on.
0.00 2006-04-06-13:33 Create Initial Placeholder
Introduce an initial placeholder for this new folio that serve as a target of links and include-page components until more content is developed.
Construction Zone (Hard Hat Area) You are navigating the
ODMA Interoperability Exchange.

created 2000-08-29-15:43-0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 10-08-29 20:13 $
$$Revision: 28 $