Open Document Management API

Version 2.0 Errata

Errata 2.0-1 Review Draft last updated 2001-05-20-10:49 -0700 (pdt)

All errata to the ODMA 2.0 Specification 
compiled since January 1, 2000.

For the latest information on ODMA and the ODMA Specifications, consult the ODMA section of the AIIM DMware Clearinghouse at http://www.infonuovo.com/dmware.  The latest edition of the ODMA 2.0 Specification is always available on the Internet at

http://www.infonuovo.com/odma/downloads/odma20.htm.

This information is also part of ODMA 2.0 Documentation Files edition 2.0-1.  For later editions and current status, consult the ODMA 2.0 Documentation Files description page.

This document is designed to be used in the same file location as HTML edition 2.0-3.  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.

Item

STATUS Errata, Concerns, and Clarifications

1.12 on case insensitivity of Document IDs

2000-07-09
tbd

The case insensitivity of Document IDs has implications on the use of DMS IDs in registry entries and on the formatting of other DocId information that might also appear in registries, profile files, and other material.  There is no assurance that two separate occurrences of a DMS ID, for example, will be in the same single case.  Software that examines and compares DMS IDs should take this into account.

1.13 on DMS IDs

2000-07-09
tbd

The statement "The ODMA group members will coordinate these IDs to ensure their uniqueness." is inaccurate.  There is no formal coordination mechanism and there is no longer an "ODMA group."  The new AIIM DMware clearinghouse will provide a registry for ODMA DMS IDs.  Contribution of already-used DMS IDs and reservations of DMS IDs is and will continue to be entirely voluntary.

1.15 on using simple characters in Document IDs 2000-07-09
tbd
There are more concerns than just avoiding characters that are used in local console and script command lines.  Because Document IDs are transferred in the code page of the application, DMS implementations must account for transfer of Document IDs in data and documents (especially e-mail messages and workflow objects) to systems where different code pages may have to be used. To ensure interoperability, it is valuable for DMS implementations to stick to a subset of ISO 646 printable characters that avoids the listed characters and any others having special significance in URLs, for example.
1.15 grammar 2000-08-03
tbd
The phrase "Although the technical definition of a document ID is a case insensitive, null-terminated strings of printable characters, ..." is perhaps best read "Although the technical definition of a document ID is as a case insensitive, null-terminated string of printable characters, ...".
1.3 Error Handling non-failure cases 2000-07-09
tbd
There are also "warning responses" that do not indicate failures.  ODM_W_NOACTION indicates a benign condition, for example.
1.3 Error Handling down/up-level considerations 2000-07-09
tbd
The negotiation of an ODMA version during ODMRegisterApp also has implications for the result codes that an ODMA requester is prepared to deal with.  Assume that a later-version DMS will not deliver any result codes other than those documented for the level requested by the application.  The implications of the ODMA Specifications are that users of the API will never encounter result codes other than those documented in the specification for the negotiated version.  This has not been made explicit, and there is also no statement about any prospects for unexpected ODMSTATUS values.  
   For example, the result code ODM_E_INVARG introduced with ODMA 2.0 was also made a possible ODMSTATUS from the ODMA 1.0 function ODMOpenDoc.  This can be a big surprise for an ODMA-aware application developed to an earlier version of the ODMA Specification.  Likewise, an ODMA 2.0-aware application is not assured to see the ODMA 2.0-expected error-reporting behavior for ODMOpenDoc when it happens to be operating with an ODMA 1.0-compliant DMS. 
1.52 Where Document Format is specified 2000-07-09
tbd
Document format is specifiable in ODMGetAlternateContent, ODMGetDocRelation, ODMNewDoc, ODMSaveAs, ODMSaveAsEx, ODMSetAlternateContent, ODMSetDocRelation, and ODMSelectDocEx.  Both ODMSaveAs and ODMSaveAsEx provide for format-specification via callback procedure.  The document attributes ODM_ALTERNATE_RENDITIONS and ODM_CONTENT_FORMAT use document format identifications which are potentially accessible by ODMGetDocInfo and ODMSetDocInfo.
1.72 on Character Set Conversion 2000-07-09
tbd
Although an application may be sharing Document Ids with itself on different platforms, in the general case the application will not be able to determine the destination application or platform on which an exported Document Id will be used.  This is also not a question that users will be able to answer.  It is important to employ character sets in a way that Document Ids are likely to be transportable via some neutral, simple character set, such as a subset of ISO 646 printable characters that occur in almost all ISO-standardized character codes.
1.8 Application Interfaces section statement on using COM 2000-11-01
tbd
The first paragraph is misleading.  The C Language API and the COM interfaces are not operationally equivalent.  The C Language API defined by odma.h is supported by the ODMA Connection Manager.  Except for the ODMQueryInterface operation, all interfaces defined in odmacom.h are those supplied by DMS-integration modules and are not operations or interfaces supplied by the ODMA Connection Manager.  Although the COM operations are related to (a subset of) the C API operations, and are similarly-named, they are not the same operations.
1.83 on using COM Query Interface 2000-07-09
tbd
The use of IODMDocMan::QueryInterface is not limited to the default DMS.  The operation will query for an available interface from whatever DMS supplied the IODMDocMan interface (or other COM interface) being used.  To have interfaces to multiple DMS integrations, use ODMQueryInterface to obtain one COM interface to start with (e.g., IUnknown, the always-supported interface) for each DMS of interest.
1.9 Use of quotes in Query Syntax <term> and <condition> forms 2000-07-10
tbd
The syntax forms given in the table use balanced quotations, ... , which are code-page specific characters. This may be a word-processor "smart"-quotes artifact and not the actual syntax.  The single-quote character, ', is probably intended in the rules for <term> and <condition> and in the explanations for creating single quotes in <word> and <attribute_value> texts.  This needs to be confirmed against the ODMA 1.5 specification and any actual implementations. 
1.9 Query Syntax <expression> misspelled 2000-07-10
tbd
The rule name <expressioin> should be <expression>
1.9 Query Syntax <condition> and <attribute> rules are malformed 2000-07-10
tbd
The correct rule for <condition> is 

<condition> :: <attribute> <op> <attribute_value>

and the <attribute_value> element should be deleted from the front of the <attribute> rule.

1.9 Query Syntax formalism not defined 2000-07-10
tbd
There is neither reference nor definition of the particular syntactic-definition notation employed in this section.  Rules for admissible and required white space and for case sensitivity are omitted.
1.9 Query Syntax character-set requirements 2000-07-10
tbd
For an application to be able to create query formulae, it must be operating in a code page that includes this character set:

0 1 2 3 4 5 6 7 8 9
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
= < ! > ( ) ' _
+ - : \ , / .
and at least the space character

including characters required for attribute values that are ODMA Document IDs, date-time values, format names, and lists of keywords.  This is another condition requiring consistent availability of a simple character set that is translatable among all acceptable code pages.

1.10 Query Examples use of quotation characters 2000-07-10
tbd
The examples all employ balanced quotations, ... , which are code-page specific characters. This may be a word-processor "smart"-quotes artifact and not the actual syntax.  The single-quote character, ', is probably intended, as noticed for the Query Syntax also. This needs to be confirmed against the ODMA 1.5 specification and any available implementations. 
Description of lpszDocId parameters:
2.1 ODMActivate,
2.2 ODMCloseDoc,
2.3 ODMCloseDocEx,
2.4 ODMGetAlternateContent,
2.9 ODMGetDocInfo,
2.10 ODMGetDocRelation,
2.11 ODMGetLeadMoniker,
2.13 ODMOpenDoc,
2.20 ODMSaveAs,
2.21 ODMSaveAsEx,
2.22 ODMSaveDoc,
2.23 ODMSaveDocEx,
2.26 ODMSetAlternateContent,
2.28 ODMSetDocEvent,
2.29 ODMSetDocInfo,
2.30 ODMSetDocRelation
2000-06-30
tbd
(Description of lpszDocId for 2.18 ODMQueryInterface is addressed separately.)

The description of lpszDocId in many of the sections overlooks the fact that the parameter is a pointer to the first byte of a document ID.  It is *lpszDocId (better yet, lpszDocId[]) that carries the document ID.  Accomplished C/C++ programmers will completely overlook this careless language, automatically understanding what is meant.  People who do not use C/C++ and who want to understand these interfaces are supported by more rigorous ways of speaking.  It is recommended that the use of a pointer and the use of pointed-to material always be clearly differentiated.

Definitions such as

lpszDocId - in
A null-terminated document ID. This is typically obtained by a call to ODMSelectDoc, ODMSelectDocEx or ODMNewDoc

are perhaps better expressed as 

lpszDocId - in
Pointer to the beginning of a null-terminated document ID. lpszDocId[] is typically obtained by a call to ODMSelectDoc, ODMSelectDocEx or ODMNewDoc
Failure to Find a DMS:
2.1 ODMActivate,
2.2 ODMCloseDoc,
2.3 ODMCloseDocEx,
2.4 ODMGetAlternateContent,
2.9 ODMGetDocInfo,
2.10 ODMGetDocRelation,
2.11 ODMGetLeadMoniker,
2.13 ODMOpenDoc,
2.18 ODMQueryInterface,
2.20 ODMSaveAs,
2.21 ODMSaveAsEx,
2.22 ODMSaveDoc,
2.23 ODMSaveDocEx,
2.26 ODMSetAlternateContent,
2.28 ODMSetDocEvent,
2.29 ODMSetDocInfo,
2.30 ODMSetDocRelation
2000-08-03
tbd
All API (not COM) requests that take an lpszDocId parameter must be routed to a DMS that is able to work with the identified document.  The specification does not address this case: What is the response if the lpszDocId[] Document ID string is improperly formed or the DMS ID is for a DMS that can't be found or connected?

It would appear that the only possible responses, depending on the operation, is one of ODM_E_DOCID and ODM_E_FAIL.  For ODMQueryInterface, the prospects are E_INVALIDARG and E_FAIL.

Inspection of the ODMA 2.0.0 versions of ODMA Connection Managers confirms that these are indeed the possible responses.  If the particular operation has only one of ODM_E_DOCID and ODM_E_FAIL as a valid ODMSTATUS value, then the one permitted value is used.  Otherwise, either response is possible and the implementations have ways of producing both.

2.2 ODMCloseDoc activeTime parameter 2000-06-28
tbd
In the function prototype for ODMCLoseDoc, the activeTime parameter is incorrectly shown as active Time, with a space in the name.  
2.31 ODMCloseDocEx pdwFlags misspelling 2000-06-28
tbd
In the first paragraph, pdwFlags is misspelled as pwdFlags.
2.5 ODMGetDMS Result Value 2000-06-29
tbd
In the function prototype for ODMGetDMS, the result value is incorrectly shown as having type WORD, but the result values are all ODMSTATUS values.  In odma.h, ODMSTATUS is specified in the declaration for ODMGetDMS.  Applications should be sure to place any result from this function into a value of type ODMSTATUS, not type WORD.
2.5 ODMGetDMS introduction of LPCSTR 2000-07-11
tbd
In the function prototype for ODMGetDMS, the parameter type LPCSTR is introduced for the first time.  The Microsoft wtypes.h definition to const char* is a contract that the provided character string will not be altered in any way by action of the function.  This extremely-valuable provision is under-used for the ODMA 2.0 API.  Everywhere that an LPSTR is specified for an in-parameter, the LPCSTR type is preferable and could have been safely specified.  This provides additional diagnostic protection and operating predictability when building ODMA-compliant products.
2.5 ODMGetDMS usage of Returns Value 2000-07-11
tbd
The list of return values for ODMGetDMS is titled "Returns Value" instead of "Return Value" as used in all other function descriptions.
 2.71 ODMGetDMSInfo typo 2000-06-30
tbd
The last sentence of the first paragraph, "The application if free to ..." should begin "The application is free to ..."
2.8 ODMGetDMSList nomenclature 2000-06-30
tbd
This section speaks of returning DMSs.  DMS Ids are returned.
2.81 ODMGetDMSList platform functionality 2000-08-03
tbd
This function does not necessarily return a DMS Id for every DMS "currently registered on the system."  It returns a DMS Id for each registered DMS that is available to the requesting application via an ODMGetDMS request.  For example, a Win32 application will receive a list of DMS Ids for which there are registered Win32 DMS Integrations;  DMS Ids for which there are only Win16 DMS Integrations are not returned to a Win32 application.  (See specification section 5, Installing a DMS.)
2.10 ODMGetDocRelation and 2.30 ODMSetDocRelation ODMSTATUS value ODM_E_NOSUPPORT 2000-10-17
see Q001000: DocRelation Usage
The ODM_E_NOSUPPORT status is ambiguous between the function not being supported and the requested operation not being supported.
2.10 ODMGetDocRelation pdwFlags 2000-06-30
tbd
This is a pointer to the flags parameter.  It is more appropriate to refer to *pdwFlags as providing the input Flag option, *pdwFlags as providing any output values.
2.10 ODMGetDocRelation ODM_E_REQARG status 2000-06-30
repaired in 2.0-3
This entry was collapsed into the preceding entry for ODM_E_INVARG.  It has been separated into a free-standing Return Value entry in edition 2.0-3.
2.10 ODMGetDocRelation *pdwFlags output values 2000-06-30
tbd
The *pdwFlags output settings ODM_REL_FIXED, ODM_REL_RELEASED, and ODM_REL_LATEST are described as if inputs rather than outputs.  It is not clear to whom these are to be understood as instructions, and what is meant by specifying them back to the application.
2.10 ODMGetDocRelation *pdwFlags output value ODM_REL_RELEASED 2000-06-30
tbd
The wording for this case is very difficult to understand.
2.11 ODMGetLeadMoniker *ppMoniker output value 2000-06-30
tbd
It is in *ppMoniker where an interface pointer for the lead moniker's IMonitor interface will be returned.  Note that the application is responsible for releasing this interface.  

Generally, this function is underspecified and much more information is required before it is clear how the Moniker can be used.

     
2.16 ODMQueryExecute ODMSTATUS value ODM_E_PARTIALSUCCESS mis-identified 2000-09-20
tbd
ODM_E_PARTIALSUCCESS should be identified as ODM_W_PARTIALSUCCESS because there is a result produced in queryId[].  A warning indication, not a failure result, is appropriate.  See incident reports X000301 and X000903.
     
2.18 ODMQueryInterface description of lpszDocId 2000-08-03
tbd
As for a number of other functions, the lpszDocId parameter is spoken of as being the document ID instead of a pointer to the document ID.  The description of ODMQueryInterface is a perfect illustration of the confusion that this makes possible: It is the pointer that may be Null, even though there are also null strings to consider.

The description

lpszDocId - in
An ODMA document ID or Null. If Null then the application's default DMS is queried for the interface. Otherwise the DMS that created this document ID is queried.

is more rigorous when put in the form

lpszDocId - in
Pointer to the beginning of an ODMA document ID or Null. If Null then the application's default DMS is queried for the interface. Otherwise the DMS specified in the lpszDocId[] document ID is queried for a COM interface.

2.19 ODMRegisterApp ODMSTATUS values

2000-10-30
tbd
In accordance with incident report X001001, these result codes are ill-defined.  More-appropriate definition of the failure cases is
ODM_E_NODMS 
ODMA has no default DMS for this application
ODM_E_CANTINIT 
ODMA initialization failed
ODM_E_VERSION 
ODMA configurationdoes not support the requested version of the API
ODM_E_REFUSED 
(deprecated)
Operation with the available default DMS has been refused by the DMS.  This should be treated the same as ODM_E_NODMS.
     

3.1 ODMGetODMInterface HRESULT E_ODM_VERSION

2000-09-10
tbd
In accordance with incident report X000902, this result code is not possible to produce and is not implemented.  It should simply be stricken from the specification.

 

   

B.12 on when documents are saved into a DMS

2000-07-09
tbd

The statement "ODMSaveDoc is the only ODMA function that actually saves a document into a DMS." is no longer true.  ODMSaveDocEx also saves a document..  And the use of the new operations ODMSetAlternateContent and ODMSetDocRelation introduce further implications about whether a document exists in the DMS, whether or not it has any document file in the default format there too.

Formal management of ODMA support began in May 2000.  Capturing and publicizing errata to the ODMA 2.0 specification starts with HTML Edition 2.0-3 published in August 2000.  Some errata involve incident reports which are the basis for troubleshooting and amendments to the specification, to the ODMA software, and to ODMA usage practices.

This document is a companion to Edition 2.0-3 of the ODMA 2.0 Specification, web page odma20-3.htm.  It can be downloaded to the same location as a copy of odma20-3.htm and reviewed by browser there without needing any Internet connection.  All references to portions of odma20-3.htm will make use of the local copy and operate correctly.


Errata 2.0-1 Initial Errata Compilation Intermediate Review Draft
Initial errata collected while making final web version of HTML edition 2.0-3 of the ODMA 2.0 specification.

created 2000-07-09-15:45 -0700 (pd) by orcmid
$$Author: Orcmid $
$$Date: 02-11-22 15:33 $
$$Revision: 17 $