ODMA: Open Document Management API

Q000702 ODMA FAQtip
Interpreting ODMA Logs
ODMA Result Codes

ODMA>faq>
2000>07>

Q000702c>
0.27 2010-08-29 20:13 -0700


1. Result Codes
    1.1 Implemented Result Codes
    1.2 Unimplemented Result Codes
2. Breaking Changes
    2.1 Breaking Condition
    2.2 Breakable Condition
3. Sources and Resources

1. Result Codes

The following values are defined for the ODMSTATUS returned from most API functions.  Not all values are applicable to every operation. 

In addition, some values added in ODMA 2.0, if implemented by a DMS, will be seen as invalid/unknown responses by ODMA 1.5 and ODMA 1.0 applications.  These breaking and breakable changes are discussed further below (section 2).

1.1 Implemented Result Codes

The following result codes are the ones that have been defined with values in the official versions of the odma.h header file.

Log Value ODMSTATUS Symbol ODMA
Version

Explanation

0(0) 0 1.0 Operation completed successfully.
ODM_NO_ERROR 1.5
ODM_SUCCESS 2.0
1(1) ODM_E_FAIL 1.0 The operation failed: ODMOpenDoc, ODMSaveDoc, ODMNewDoc, ODMSaveAs, ODMActivate, ODMSetDocInfo, ODMGetLeadMoniker
1.5 ODMQueryExecute, ODMQueryGetResults, ODMQueryClose
2.0 ODMCloseDoc (1.0 breaking), ODMSelectDoc (1.0 breaking), ODMCloseDocEx, ODMGetAlternateContent, ODMGetDocRelation, ODMQueryCapability, ODMSaveAsEx, ODMSaveDocEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation
2(2) ODM_E_CANCEL 1.0 Action was cancelled at user request: ODMSelectDoc, ODMNewDoc, ODMSaveAs, ODMActivate
1.5 ODMQueryExecute
2.0 ODMSaveAsEx, ODMSaveDocEx, ODMSelectDocEx
3(3) ODM_E_NODMS 1.0 DMS not registered: ODMRegisterApp
1.5 ODMSetDMS
2.0 ODMGetDMS, ODMQueryCapability
4(4) ODM_E_CANTINIT 1.0 DMS failed to initialize: ODMRegisterApp
5(5) ODM_E_VERSION 1.0 DMS doesn't support requested version of ODMA: ODMRegisterApp
6(6) ODM_E_APPSELECT 1.0 DMS reports that Application should select file: ODMSelectDoc, ODMNewDoc, ODMSaveAs
2.0 ODMSaveAsEx, ODMSelectDocEx
7(7) ODM_E_USERINT 1.0 Operation can't be performed without an user interaction that was not allowed in the request: ODMSelectDoc, ODMOpenDoc, ODMNewDoc
2.0 ODMCloseDocEx, ODMGetAlternateContent, ODMGetDocRelation, ODMQueryCapability, ODMSaveAsEx, ODMSaveDocEx, ODMSelectDocEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation
8(8) ODM_E_HANDLE 1.0 Invalid ODMHANDLE parameter in the request: ODMSelectDoc, ODMNewDoc, ODMOpenDoc, ODMSaveDoc, ODMCloseDoc, ODMSaveAs, ODMActivate, ODMGetDocInfo, ODMSetDocInfo, ODMGetDMSInfo, ODMGetLeadMoniker
2.0 ODMQueryClose (1.5 breaking), ODMQueryExecute (1.5 breaking), ODMQueryGetResults (1.5 breaking), ODMCloseDocEx, ODMGetAlternateContent, ODMGetDocRelation, ODMQueryCapability, ODMSaveAsEx, ODMSaveDocEx, ODMSelectDocEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation
9(9) ODM_E_ACCESS 1.0 Insufficient access rights for request: ODMOpenDoc
2.0 ODMActivate (1.0 breakable), ODMSetDocInfo (1.0 breakable), ODMGetAlternateContent, ODMSetAlternateContent, ODMSetDocRelation
10(a) ODM_E_INUSE 1.0 Document in use and not accessible in the specified mode: ODMOpenDoc, ODMActivate
2.0 ODMGetAlternateContent, ODMSetAlternateContent, ODMSetDocRelation
11(b) ODM_E_DOCID 1.0 Invalid Document ID: ODMOpenDoc, ODMSaveAs, ODMActivate, ODMGetDocInfo, ODMSetDocInfo, ODMGetLeadMoniker
2.0 ODMGetAlternateContent, ODMGetDocRelation, ODMSaveAsEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation
12(c) ODM_E_OPENMODE 1.0 Requested action is incompatible with mode of access to document: ODMSaveDoc
2.0 ODMSaveDocEx
13(d) ODM_E_NOOPEN 1.0 The specified document is not open: ODMCloseDoc
2.0 ODMSaveDoc (1.0 breaking), ODMCloseDocEx, ODMSaveDocEx
14(e) ODM_E_ITEM 1.0 Invalid item specifier: ODMActivate, ODMGetDocInfo, ODMSetDocInfo
2.0 ODMQueryCapability, ODMSetDocEvent
15(f) ODM_E_OTHERAPP 1.0 Selected document was for another application and none is returned for this application (treat as ODM_E_Cancel): ODMSelectDoc
2.0 ODMSelectDocEx
16(10) ODM_E_NOMOREDATA 1.5 No more data is available: ODMQueryGetResults
2.0 ODMGetDocRelation
17(11) ODM_E_PARTIALSUCCESS 1.5 Not all queried DMSs succeeded: ODMQueryExecute
18(12) ODM_E_REQARG 2.0 Required parameter not specified (i.e., is NULL): ODMQueryGetResults (1.5 breaking), ODMGetAlternateContent, ODMGetDMS, ODMGetDocRelation, ODMQueryCapability, ODMSelectDocEx, ODMSetDocEvent, ODMSetDocRelation
19(13) ODM_E_NOSUPPORT 2.0 DMS does not support requested action: ODMActivate (1.0 breakable), ODMGetDocInfo (1.0 breakable), ODMSetDocInfo (1.0 breakable), ODMGetAlternateContent, ODMGetDocRelation, ODMQueryCapability, ODMSelectDocEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation
20(14) ODM_E_TRUNCATED 2.0 Supplied buffer too small for result that cannot be truncated: ODMGetDocInfo (1.0 breakable), ODMSelectDocEx
21(15) ODM_E_INVARG 2.0 An argument value is invalid: ODMOpenDoc (1.0 breaking), ODMGetAlternateContent, ODMGetDocRelation, ODMQueryCapability, ODMSaveDocEx, ODMSelectDocEx, ODMSetAlternateContent
22(16) ODM_E_OFFLINE 2.0 Cannot access because DMS storage or service is offline/disconnected: ODMActivate (1.0 breakable), ODMGetDocInfo (1.0 breakable), ODMNewDoc (1.0 breaking), ODMOpenDoc (1.0 breaking), ODMSaveAs (1.0 breaking), ODMSelectDoc (1.0 breaking), ODMSetDocInfo (1.0 breakable), ODMGetAlternateContent, ODMSaveAsEx, ODMSaveDocEx, ODMSelectDocEx, ODMSetAlternateContent, ODMSetDocEvent, ODMSetDocRelation

1.2 Unimplemented Result Codes

There are a number of ODMSTATUS symbols defined in the ODMA 2.0 Specification that are not to be found in the standard odma.h header files.  There were agreed values and it is possible that they may appear on an ODMA log for a DMS integration that implements the result cases.  For additional information and recommendations about these codes, see (ODMA 2000a).

Log Value ODMSTATUS Symbol ODMA
Version

Explanation

23(17) ODM_E_ARCHIVED 2.0 Cannot access document because it is archived: ODMActivate (1.0 breakable), ODMOpenDoc (1.0 breaking),  ODMGetAlternateContent, ODMSetAlternateContent
24(18) ODM_E_ALREADYOPENED 2.0 The document is already opened and was not opened again: ODMOpenDoc (1.0 breaking)
25(19) ODM_E_FILELOCKED 2.0 Application document still open/locked and DMS can't access it: ODMCloseDoc (1.0 breaking), ODMCloseDocEx
26(1a) ODM_E_REFUSED 2.0 DMS Refused for this application: ODMRegisterApp (1.0 breaking)
27(1b) ODM_W_NOACTION 2.0 No action needed to achieve result: ODMActivate (1.0 breakable), ODMSetDocRelation
28(1c) ODM_E_NORELATION 2.0 Document has no related parent or child: ODMGetDocRelation, ODMSetDocRelation

2. Breaking Changes

The ODMA Specifications require and promise down-level compatibility from later versions of the specification.  Nevertheless, the ODMA 2.0 Specification contained a number of breaking changes in the API, including in the addition of ODMSTATUS values to ODMA 1.0 and ODMA 1.5 operations (ODMA 2000b).

In the above tables, there are two categories of possible breakage: breaking and breakable.

2.1 Breaking Condition

If an ODMSTATUS value in this category is returned for a particular ODMA operation, it will break the interface agreement for an earlier version of ODMA. 

The occurrence of such a result will not be recognized by an ODMA-aware application that implements an earlier version of ODMA.  In this case, the response is unpredictable. 

If the ODMA-aware application was not programmed to detect unexpected values of ODMSTATUS, it is possible that the application will fail or behave in unexpected ways.

Because an ODMA-compliant DMS integration has no means for determining the version of ODMA on which an application depends, it is recommended that these cases not be implemented in ODMA 2.0 DMS integrations.

In reviewing logs for resolution of unexpected behavior, it is important to review the logged ODMSTATUS values to see if a breaking value has been returned.

2.2 Breakable Condition

In some cases, the functions of certain ODMA 1.0 operations have been extended in ODMA 2.0.  These functions will only be requested by ODMA-aware applications that rely on ODMA 2.0 capabilities.

However, the ODMA 2.0 specification also introduces additional ODMSTATUS values that will not be recognized by ODMA-aware applications built to earlier versions of the specification.

When one of the additional (breakable) ODMSTATUS values is returned for a function that is only defined for ODMA 2.0, there is no difficulty.  Any application requesting that ODMA 2.0 functionality must be programmed to expect all of the possible ODMA 2.0 ODMSTATUS values for the operation.

When an additional ODMSTATUS value is returned for a function that is defined for earlier versions of the API, that action is a breaking condition and should be treated as such (section 2.1).

3. 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).
Changes Between ODMA Versions.  ODMA FAQtip Q000705.  2006-04-10 version 0.20 review draft available at <http://ODMA.info/faq/2000/07/Q000705c.htm>.
    
ODMA (2000c).
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.
    

Revision History:
0.27 2006-05-10-18:07 Update Cross-References
Refer to the 0.20 version of Q000705 as (ODMA 2000b).  Use the new folio location that will now be permanent.
0.26 2006-04-06-08:52 Make cleanups
Table formatting is corrected and ODMSelectDocEx is added into the ODM_E_APPSELECT case.
0.25 2006-04-05-22:54 Create Review Draft
The material is complete enough for careful review and for reference in incident analyses that are underway.
0.00 2006-04-04-17:01 Create Initial Placeholder
Introduce an initial placeholder 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 2006-04-04-17:01 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 10-08-29 20:13 $
$$Revision: 22 $