Q000702c: 0.27 ODMA Result Codes

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).

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`
`6(6)`	`ODM_E_APPSELECT`	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`
`7(7)`	`ODM_E_USERINT`	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`
`8(8)`	`ODM_E_HANDLE`	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`
`9(9)`	`ODM_E_ACCESS`	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`
`10(a)`	`ODM_E_INUSE`	2.0	`ODMGetAlternateContent`, `ODMSetAlternateContent`, `ODMSetDocRelation`
`11(b)`	`ODM_E_DOCID`	1.0	Invalid Document ID: `ODMOpenDoc`, `ODMSaveAs`, `ODMActivate`, `ODMGetDocInfo`, `ODMSetDocInfo`, `ODMGetLeadMoniker`
`11(b)`	`ODM_E_DOCID`	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`
`12(c)`	`ODM_E_OPENMODE`	2.0	`ODMSaveDocEx`
`13(d)`	`ODM_E_NOOPEN`	1.0	The specified document is not open: `ODMCloseDoc`
`13(d)`	`ODM_E_NOOPEN`	2.0	ODMSaveDoc (1.0 breaking), `ODMCloseDocEx`, `ODMSaveDocEx`
`14(e)`	`ODM_E_ITEM`	1.0	Invalid item specifier: `ODMActivate`, `ODMGetDocInfo`, `ODMSetDocInfo`
`14(e)`	`ODM_E_ITEM`	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`
`15(f)`	`ODM_E_OTHERAPP`	2.0	`ODMSelectDocEx`
`16(10)`	`ODM_E_NOMOREDATA`	1.5	No more data is available: `ODMQueryGetResults`
`16(10)`	`ODM_E_NOMOREDATA`	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`

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.

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.

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.

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 $

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

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