visits to popular ODMA.info pages

Open Document Management API

Version 2.0

September 19, 1997

Copyright © 1997 AIIM International

HTML EDITION 2.0-3 Review Draft last updated 2001-09-04-12:49 -0700 (pdt)

For the latest information on ODMA and the ODMA Specifications, consult the ODMA section of the AIIM DMware Development Site.  Current locations of development sites can be found through AIIM DMware.  The current status of ODMA and its support, including current status of ODMA 2.0,  is reported in the ODMA Support section.

Specification History

1. Overview

1.1 Document IDs
1.2 Constants
1.3 Error Handling
1.4 Connections and the ODMA Connection Manager
1.5 Document Format Names
1.6 DMS or Native File System Dialogs - Which to Display First
1.7 Character Sets
1.8 Application Interfaces
1.9 Query Syntax
1.10 Query Examples

2. ODMA API

2.1 ODMActivate
2.2 ODMCloseDoc
2.3 ODMCloseDocEx
2.4 ODMGetAlternateContent
2.5 ODMGetDMS
2.6 ODMGetDMSCount
2.7 ODMGetDMSInfo
2.8 ODMGetDMSList
2.9 ODMGetDocInfo
2.10 ODMGetDocRelation
2.11 ODMGetLeadMoniker
2.12 ODMNewDoc
2.13 ODMOpenDoc
2.14 ODMQueryCapability
2.15 ODMQueryClose
2.16 ODMQueryExecute
2.17 ODMQueryGetResults
2.18 ODMQueryInterface
2.19 ODMRegisterApp
2.20 ODMSaveAs
2.21 ODMSaveAsEx
2.22 ODMSaveDoc
2.23 ODMSaveDocEx
2.24 ODMSelectDoc
2.25 ODMSelectDocEx
2.26 ODMSetAlternateContent
2.27 ODMSetDMS
2.28 ODMSetDocEvent
2.29 ODMSetDocInfo
2.30 ODMSetDocRelation
2.31 ODMUnRegisterApp

3. DMS Interface

3.1 ODMGetODMInterface
3.2 IODMDocMan Interface
3.3 IODMQuery Interface
3.4 IODMDocMan2 Interface

4. Binding to the API

5. Installing a DMS

6. Installing a Client Application

7. Connection Manager Trace Logging

Appendix A  - Document Attributes

Appendix B - Preferred Call Usage for Initial File Creation

Specification History

Version 1.0 - with small BHC-325 at the end of the document

Brad Clements, SoftSolutions. This is the original version.

 Version 1.0 - with small DM1\285 at the end of the document 

Mike Gardiner, Novell. This contains additional information for registering ODMA under Windows 95 and NT. It also adds a new table for document ID constants.

Version 1.0a

Rod Schiffman, Novell. Additional information on the ODMA spec background, usage of calls, suggestions on the use of document ID character sets and the addition of ODM_E_INUSE as a valid return code in ODMActivate.

Version 1.5

Jerry (Gerald) Willett, PC DOCS, Inc. Added the Query specification. This included the Query Syntax and Query Examples sections and the ODMQuery* functions and the IODMQuery COM interface. Also added a clarification to the expected behavior of an application when calling ODMSaveAs and an empty string is returned for lpszNewDocId.

Version 2.0

Bob St.Jean, Digital Equipment Corp. Added additional attributes and functions to improve ODMA support for popular Document Management System (DMS) features. These are mostly defined in a new IODMDocMan2 interface. Defined several items to help provide better out-of-the-box integration between desktop applications and DMS. Also added clarifications to the existing specification and arranged the functions alphabetically.

1. Overview

The original impetus for the Open Document Management API (ODMA) was the recognition that there was no standard method for a client application to integrate with a Document Management System (DMS). Each DMS vendor wrote separate integration code for each of the major client applications they supported. Applications that did not have integrations written for them by the DMS vendors would have to write and support a separate integration for each DMS that was supported. This required a complete matrix of integrations, each with its own set of bugs, limitations and reliability issues. It seemed obvious that a high level standard for connecting applications and document management systems was a natural fit.

A small group of application and DMS vendors started working together to create an API that would allow applications and document management systems to inter-operate through a single high level API. This implied the creation of a standard, however, the creation of a standard has many pitfalls. Probably the biggest problem is that a lot of work can be put into the creation of the standard, and nobody uses it.

The industry is filled with examples of standards that were obsolete by the time they made it through the standardization process. By the time some standards make it through the standardization process, they are so large and unwieldy they are almost impossible to implement and maintain. Company politics and hidden agendas of the participants can play as big a role in the adoption of a standard as trying to solve the problem in the first place. The industry is also full of proprietary API’s that claim to be standards, but are not. The initial group of vendors that met and formed the ODMA consortium wanted to avoid as many of these problems as possible.

The working rules of the ODMA consortium are fairly simple.

1. If the standard does not solve a problem it will not be used.
2. If the creation of the standard takes a long period of time, it does not solve the problem.
3. If the standard is difficult to implement, it does not solve the problem.
4. The standard must be vendor independent.
5. The standard must not try to solve all vendors’ problems, or it will be big, complex and take a long time to implement. This violates rules 1, 2 and 3 above.
6. It is the customers that lose if there is not a straightforward way to integrate applications that create documents and applications that manage documents.
7. Easy integration between applications and document management systems will grow the industry and increase sales for the entire marketplace.

It is difficult to express the importance the initial members of the consortium placed on wanting to create a useful API that is vendor and platform independent while still simple to implement. They recognized that they could solve 80 percent of the problem easily and were willing to live with having to solve another 10 percent over time and probably never being able to solve the final 10 percent.

The Open Document Management API (ODMA) is a standardized, high-level interface between desktop applications and document management systems (DMSs). Its purposes are:

1. To make DMS services available to users of desktop applications in a seamless manner so that these services appear to the user like extensions of the applications.
2. To reduce the application vendors burden of having to deal with multiple DMS vendors. By writing to ODMA, an application vendor has potentially integrated his application with all supporting DMSs.
3. To reduce the DMS vendors burden of integrating with multiple applications. By supporting ODMA a DMS vendor has potentially integrated with all applications that have written to ODMA.
4. To reduce effort and complexity needed to install and maintain DMSs.

ODMA specifies a set of interfaces that applications can use to initiate actions within a DMS. The API is intended to be relatively easy for application vendors to incorporate into updates of existing applications. It should not require major restructuring of an application to integrate it with ODMA. Note that this version of ODMA does not specify how DMSs may initiate actions within the applications.

The ODMA API is platform-independent. The associated data type definitions and binding information are platform-specific. Currently, most of the work has been done in Windows. It makes this document look Windows specific, but over time, the platform specific entries for other platforms will be added as they are defined.

1.1 Document IDs

Many of the ODMA functions accept or return a Document ID parameter. A document ID is a persistent, portable identifier for a document. It can be stored and used in a later session, and it can be passed across platforms via email or other processes.

A Document ID is a case insensitive, null-terminated string of printable characters. Although a document ID is case insensitive, an application should never change the case of a document ID. The format of a document ID is

The DMS_ID portion of a document ID will identify which DMS provided the ID. This information is primarily for the use of ODMA itself; applications using ODMA should not need to know which DMS provided a particular ID. The ODMA group members will coordinate these IDs to ensure their uniqueness. The maximum length of the DMS_ID portion of the document ID is specified by the constant ODM_DMSID_MAX. The DM_SPECIFIC_INFO portion of the ID will vary depending on which DMS built the ID. The total length of the document ID including the terminating Null character cannot exceed ODM_DOCID_MAX bytes.

ODMA-aware applications should be able to handle a document ID anywhere they handle an externally-generated document filename. For example, if the application allows a document filename to be passed as a command line argument then it should allow a document ID to be passed in the same way. If the application allows document filenames to be used in DDE commands then it should also support the use of document IDs in the same commands.

Although the technical definition of a document ID is a case insensitive, null-terminated strings of printable characters, there are some general rules that are more likely to make a DMS and ODMA application work better together. ODMA was designed so that it would be easy to add to an application without major modifications in code or structure. If a DMS passes a document ID that breaks fundamental rules of normal file and path names it will probably run into problems if it is passed in on a command line. Special characters like ^, [, ], |, *, -, >, < and ? are processed by the UNIX shell even before they are seen by the application. It is possible to pass these characters by using special escape sequences, but that places a burden on the DMS vendor to process the document ID before giving it to the ODMA application. Some operating systems require the application to handle the reverse process of interpreting and removing the escape characters. The application may be able to support the escape removal on the command line, but not if the document ID with escape characters is returned in a procedure call. In most cases, it is easier to generate a document ID that contains a fairly simple set of characters. The following table suggests characters it may be wise to avoid for different platforms.

 

Table 1-1.  Characters to Avoid in ODMA Document Ids

Platform	Characters to avoid
Windows 3.x	" ‘ < > * ? | and the space character
Windows 95	" ‘ < > * ? |
Other platforms to be defined

1.2 Constants

The following table lists the constants that are defined in the odma.h header.

Table 1-2.  Parameter Constants Defined by ODMA

CONSTANTS	Win 3.x	Win32	Mac	UNIX	Other
ODM_DOCID_MAX Maximum length of a document ID including the null-terminator.	80	255	255	255	255
ODM_FILENAME_MAX Maximum length of a path/filename returned by ODMA including the terminating Null character.	128	255	255	1024	255
ODM_API_VERSION The version of the ODMA API to which this header file corresponds. See ODMRegisterApp.	200	200	200	200	200
ODM_DMSID_MAX Maximum length of a DMS ID including the null-terminator.	9	9	9	9	9
ODM_APPID_MAX Maximum length of an Application ID including the null-terminator.	16	16	16	16	16
ODM_FORMAT_MAX Maximum length of a content format string including the null-terminator.	81	81	81	81	81
ODM_QUERYID_MAX Maximum length of a query ID string including the null-terminator.	255	255	255	255	255

1.3 Error Handling

Nearly all of the ODMA functions use the return value to indicate to the calling application whether the function succeeded, failed because the user canceled the operation, or failed for other reasons. The DMS is responsible for displaying informational error messages to the user where appropriate except when the ODM_SILENT flag is specified. The DMS must take care to return the appropriate error indication because applications may act differently depending on whether an ODMA call was canceled by the user or failed for other reasons. The calling application generally should not display error messages when an error value is returned from ODMA unless the ODM_SILENT flag was specified.

1.4 Connections and the ODMA Connection Manager

The ODMA connection manager is a small software module that sits between applications using ODMA and document management systems implementing ODMA. It manages the connections between these components and routes ODMA calls to the appropriate provider. A freely redistributable copy of the ODMA connection manager will be provided to any vendor wishing to implement or make use of the ODMA API. This is a place where it would be possible to provide mapping code that would allow ODMA to have truly platform independent document IDs, however, it currently only manages connections and does not touch document IDs.

1.5 Document Format Names

When new documents are registered with a DMS via ODMA and when an existing document's format is changed by an application, the application passes a document format name to ODMA. Document format names are null-terminated strings defining the format of a document's content. These strings have a maximum length defined by the ODM_FORMAT_MAX constant.

There are several places in ODMA where a content format name for a document can be specified or requested. The ODMNewDoc, ODMSaveAs and ODMSaveAsEx functions each have a lpszFormat parameter where a format can be specified. The ODMSaveAs also has a callback, which uses a format string. The ODM_CONTENTFORMAT attribute can be requested or set using the ODMGetDocInfo and ODMSetDocInfo functions.

The ODMA 1.0 specification did not attempt to standardize the format names used by DMS and application vendors. This was a significant limitation in some cases. The DMS would not know in advance what type of file was being created by the application. Also an application that saved an existing file back to the DMS using a different format would have no standard format name to give to the DMS. This model relied on both the DMS and the application being able to auto-detect all file formats.

ODMA 2.0 defines guidelines to standardize format names. This has become necessary due to vendors’ desire to have applications and DMSs more tightly integrated and because ODMA 2.0 introduces some new functions which require standardization in order to work. The new ODMGetAlternateContent and ODMSetAlternateContent functions require the DMS and application to have a standard way to identify file content. A new document attribute called ODM_ALTERNATE_RENDERINGS allows an application to find out if a DMS can provide a document in other formats and make a choice of which to use.

ODMA has defined the following guidelines to standardize how a DMS or application might specify a document’s content format:

1. MIME Content Type. If a file type does not have a MIME content type, then a file extension must be used.
2. File Extension (a.k.a. File Type). If a file extension is used the first character must be a dot. The file extension should be the one normally used to identify the document on the platform where the client application is running. Some platforms allow the file extension to contain more than three characters. ODMA does not define a maximum file extension length.
3. File Extension plus other identifying information. This other information may be useful in cases where a single file extension is used for different variations or versions of the file type. In this format the first character must be a dot, followed by the file extension, plus a single forward slash, plus a string containing the additional information.

Examples:

application/msword

• .doc
• .doc/MS Word 95 Document
• .doc/MS Word 97 Document

image/tiff

• .TIF
• .TIFF
• .TIF/Tagged Image File Format
• .TIF/Scanned TIFF

A DMS or application can use the Windows Registry or its own mapping capability to convert a file extension to a MIME code or vice versa. Note that some file extensions are used by more than one application, some file types have multiple valid file extensions, and that some MIME content types are used to define more than one file type within the same application. A DMS or application may have use whatever format name is most precise.

1.6 DMS or Native File System Dialogs - Which to Display First

ODMA imposes no rules on applications requiring them to always show the DMS dialogs first in response to filing commands such as File Open and File Save As. ODMA applications are encouraged to provide a user preference setting so the user can designate if the application’s native file system dialog or the DMS’s dialog is displayed first. Ideally the application may provide a push-button or some other control in its native file system dialog box to allow the user to quickly select the DMS dialog box.

If the application cannot provide one or more of the options described above then they have no choice but to always display the DMS dialog box in response to the File Open and File Save As commands. Each ODMA compliant DMS must provide a way for the user to select the native file system from dialogs displayed while processing the ODMSelectDoc, ODMSelectDocEx, ODMNewDoc, ODMSaveAs and ODMSaveAsEx functions. The DMS returns the ODM_E_APPSELECT status if the user elects to use the native file system. When this status is returned the application can display their dialog box. If the user wishes to return to the DMS dialog box they will have to cancel and re-do the file command.

1.7 Character Sets

All strings passed to or returned from ODMA functions should be null-terminated series of octets, in the standard character set of the system on where ODMA is being used. So for example, 8859-1 would be used on English Windows, Shift-JIS would be used on Japanese Windows, etc. The term "null-terminated" as used in this specification means terminated by the character set's natural Null character. For most character sets this means a single byte with the value 0x0.

If an application obtains an ODMA document ID on one platform and later uses it on another platform, the application is responsible for translating the ID to the character set being used on the second platform before using it there.

1.8 Application Interfaces

An ODMA-aware application can choose to communicate with the ODMA Connection Manager either through a traditional, function-oriented API or through Component Object Model (COM) interfaces. Prototypes and constants used for the function-oriented API are included in the odma.h header file. Prototypes, constants, and interface definitions for the COM interface are included in the odmacom.h header file.

After calling ODMRegisterApp, applications can obtain one or more COM interfaces to ODMA through the ODMQueryInterface function. The IODMDocMan interface provides an alternate entry point to most of the ODMA functions documented below. Other functions are defined in the IODMDocMan2 and IODMQuery interfaces. These interfaces and their interface IDs are defined in the odmacom.h header file.

Note that IODMDocMan::QueryInterface will only query the default DMS for the calling application. The application must call ODMQueryInterface in order to query other DMSs.

1.9 Query Syntax

The query syntax described here is used in the ODMQueryExecute function.

 

Table 1-3. ODMA Query Syntax

<query>	:: select <returned_list> <search_criteria>
<returned_list>	:: <returned_item> [, <returned_list>]
<returned_item>	:: ODM_DOCID :: ODM_NAME
<search_criteria>	:: <search_clause> :: <where_clause> :: <search_clause> <where_clause> :: <where_clause> <search_clause>
<search_clause>	:: search document contains <expression>
<expressioin>	:: (<expression>) :: [not] (<expression>) :: <term> [<operator> <expression>]
<term>	:: ‘<word>’ :: [not] ‘<word>’
<operator>	:: and :: or
<word>	is a user supplied word. If there is a single quote (’) inside this word, it needs to be represented with two consecutive single quotes (’’).
<where_clause>	:: where <condition_list>
<condition_list>	:: <condition> [<operator> <condition_list>]
<condition>	:: <attribute> <op>
‘<attribute_value>’<attribute>	:: ODM_FORMAT :: ODM_NAME :: ODM_AUTHOR :: ODM_TYPE :: ODM_DMS_DEFINED:<dms_attribute> :: * Any other document attribute listed in Appendix A
<op>	:: = :: != :: <> :: > :: < :: <= :: >=
<dms_attribute>	is a DMS specific attribute name.
<attribute_value>	is a user supplied value for ODM_NAME, etc. If there is a single quote (’) inside any of these names, it must be represented with two consecutive single quotes (’’).

1.10 Query Examples

2. ODMA API

The following section describes each function in the ODMA API that a typical application would use. The functions are listed in alphabetical order.

2.1 ODMActivate

ODMSTATUS ODMActivate( ODMHANDLE handle, WORD action, LPSTR lpszDocId)

This function causes the DMS to perform actions that do not require cooperation from the calling application. Control is returned to the calling application after the specified action has been completed, except where noted. A DMS is not required to support all of these actions.

Parameters:

Return value:

2.2 ODMCloseDoc

ODMSTATUS ODMCloseDoc( ODMHANDLE handle, LPSTR lpszDocId, DWORD active Time, DWORD pagesPrinted, LPVOID sessionData, WORD dataLen)

An application that has opened a document by calling ODMOpenDoc must call ODMCloseDoc when it is finished using the document. The application should not call this function until after it has closed the document, because the DMS may move the document or make it inaccessible as a result of this call. Note that this function will not cause the document to be saved into the DMS's persistent repository unless ODMSaveDoc has been called previously.

It is possible for a user to explicitly check-out/reserve a document using either ODMActivate or a command provided by the DMS. If a document was already reserved by the user before ODMOpenDoc was called, then when ODMCloseDoc is called it is recommended that the DMS keep the document reserved. The DMS should only check-in/unreserve the document in ODMCloseDoc if it first displays a dialog box confirming this with the user.

Parameters:

Return value:

2.3 ODMCloseDocEx

ODMSTATUS ODMCloseDocEx( ODMHANDLE handle, LPSTR lpszDocId, LPDWORD pdwFlags, DWORD activeTime, DWORD pagesPrinted, LPVOID sessionData, WORD dataLen)

ODMCloseDocEx is the same as ODMCloseDoc except it has a pwdFlags parameter. There is an ODM_SILENT flag to facilitate unattended document processing. Some DMSs display a user interface when closing a document. This flag allows the calling application to suppress this UI.

An application that has opened a document by calling ODMOpenDoc must call ODMCloseDoc or ODMCloseDocEx when it is finished using the document. The application should not call this function until after it has closed the document, because the DMS may move the document or make it inaccessible as a result of this call. Note that this function will not cause the document to be saved into the DMS's persistent repository unless ODMSaveDoc or ODMSaveDocEx has been called previously.

It is possible for a user to explicitly check-out/reserve a document using either ODMActivate or a command provided by the DMS. If a document was already reserved by the user before ODMOpenDoc was called, then when ODMCloseDocEx is called it is recommended that the DMS keep the document reserved. The DMS should only check-in/unreserve the document in ODMCloseDocEx if the ODM_SILENT flag is not set and it first displays a dialog box confirming this with the user.

Parameters:

Return value:

2.4 ODMGetAlternateContent

ODMSTATUS ODMGetAlternateContent ( ODMHANDLE handle, LPSTR lpszDocId, LPDWORD pdwFlags, LPSTR lpszFormat, LPSTR lpszDocLocation)

This function causes the DMS to return an alternate content file for the specified document. The format of the alternate content file should be one of the formats returned by the ODM_ALTERNATE_RENDERINGS item in a previous call to ODMGetDocInfo. The application is responsible for deleting the alternate content file when it is finished using it.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDocId - in -  A null-terminated document ID. This is typically obtained by a call to ODMSelectDoc, ODMSelectDocEx or ODMNewDoc. The specified document may or may not be open when this function is called. This document ID refers to the main document for which an alternate content file is being requested.

pdwFlags - in/out -  A pointer to a variable containing flags used on both input and output. On input, zero (0) or the following flag: ODM_SILENT - The DMS should not require user interaction while satisfying the call. If the call cannot be satisfied without user interaction then an error should be returned. ODMA 2.0 does not define any output flags at this time.

lpszFormat - in -  A null-terminated string containing the format name of the alternate format requested. The Document Format Names section has information on how file formats are identified in ODMA. Typically the calling application would have first obtained the alternate renderings the DMS has for the specified document then specified one in this parameter. This is done by requesting the ODM_ALTERNATE_RENDERINGS attribute in ODMGetDocInfo. However, the application is free to simply specify the MIME Content Type or File Extension for the format it needs. If the DMS cannot return the requested format, it will return the ODM_E_NOSUPPORT status.

lpszDocLocation - in/out -  A pointer to a buffer of at least ODM_FILENAME_MAX bytes in length, into which the DMS will write a null-terminated string containing a full path and file name of the alternate content file. If an error occurs then the contents of the buffer will be undefined. It is the responsibility of the calling application, not the DMS, to delete this file when it is finished with it.   Optionally the calling application can specify a file extension in this parameter for the DMS to use in the file specification it returns. If specified, the file extension should be preceded by a period. The DMS may choose to ignore this information and return a file specification containing a different file extension.

Return value:

2.5 ODMGetDMS

WORD ODMGetDMS( LPCSTR lpszAppId, LPSTR lpszDmsId )

This function provides an application a programmatic way to get its default DMS. The DMS ID of the current DMS for the application will be returned. This can be either the default DMS from the registry or a DMS previously set by the application using ODMSetDMS.

Parameters:

lpszAppId - in -  A pointer to a null-terminated string containing an Application ID.

lpszDmsId - out -  A pointer to a buffer to receive the DMS ID of the default DMS. This buffer must be at least ODM_DMSID_MAX bytes in length. If an error occurs the value in this buffer is undefined.

Returns value:

ODM_SUCCESS  if successful.

ODM_E_NODMS  if there is no default DMS registered.

ODM_E_REQARG  if either parameter is not specified.

2.6 ODMGetDMSCount

WORD ODMGetDMSCount( )

This is an informational function. It will count the number of DMSs currently registered on the system. This information can be used to determine the minimum size for the buffer in a call to ODMGetDMSList.

Parameters:

none.

Return value: 

The number of DMSs currently registered on the system.

2.7 ODMGetDMSInfo

ODMSTATUS ODMGetDMSInfo( ODMHANDLE handle, LPSTR lpszDmsId, LPWORD pwVerNo, LPDWORD pdwExtensions )

This function returns information to the application about the currently active DMS. The application if free to only request the information it needs.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDmsId - out -  If specified by the caller, this should be a pointer to a buffer of at least ODM_DMSID_MAX bytes in length. A null-terminated ID identifying the DMS is returned here. This is the same ID embedded in document IDs returned by this DMS.

pwVerNo - out -  If specified by the caller, this should be a pointer to a variable to receive a version number. The version of the ODMA API supported by this DMS is returned here.

pdwExtensions - out -  If specified by the caller, this should be a pointer to a variable to receive extension information. Indications of extensions to the base ODMA API that are supported by this DMS are returned here. If a DMS does not support any currently defined extensions, then 0 will be returned. The DMS will return flag values for all the extensions it supports. The currently defined ODMA extensions are:  ODM_EXT_WORKFLOW - The DMS supports the ODMA Workflow Extensions. ODM_EXT_QUERY - The DMS supports the Query Extensions defined in ODMA 1.5.

Return value:

ODM_SUCCESS  if successful.

ODM_E_HANDLE  if handle was invalid.

2.8 ODMGetDMSList

WORD ODMGetDMSList( LPSTR buffer, WORD buffer_size )

This function gets a list of the DMSs currently registered on the system.

Parameters:

buffer - out -  A pointer to a buffer which will receive a list of DMSs. The format of the list is a collection of Null terminated strings. The list is terminated by an empty string (i.e. "<id#1>\0<id#2>\0\0").

buffer_size - in -  Size of buffer . It must be at least ODMGetDMSCount() * ODM_DMSID_MAX + 1 bytes in length.

Return value: 

The number of DMSs returned in buffer.

2.9 ODMGetDocInfo

ODMSTATUS ODMGetDocInfo( ODMHANDLE handle, LPSTR lpszDocId, WORD item, LPSTR lpszData, WORD dataLen )

An application can use this function to obtain information about a document from the DMS. It is recommended that the DMS not display any user interface while processing this function.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDocId - in -  A null-terminated document ID. This is typically obtained by a call to ODMSelectDoc, ODMSelectDocEx or ODMNewDoc. The specified document may or may not be open when ODMGetDocInfo is called.

item - in -  A single Item Id. Refer to Appendix A for a complete list of Item Ids for document attributes which can be specified in this parameter. ODM_DMS_DEFINED - Can be used for DMS specific attributes not explicitly defined by ODMA. The lpszData parameter contains a DMS-specific indication of the data to be returned. Note that an application must know which DMS it is talking to and must understand the data indications supported by the DMS in order to use this item id.

lpszData - in/out -  On input, ignored if item is anything other than ODM_DMS_DEFINED. If item is ODM_DMS_DEFINED then lpszData contains an indication of the data to be returned. It is recommended that the DMS be able to recognize a null-terminated string containing one of its known attribute names. On output, the requested data is returned in the buffer pointed to by lpszData. The data is always null-terminated.

dataLen - in -  The length of the output buffer pointed to by lpszData. If the data to be returned is longer than dataLen it will be truncated. The DMS must return ODM_E_TRUNCATED when the requested data cannot be safely truncated; for example when an attribute containing a document ID or URL is returned. In these cases the application should recall the function supplying a larger buffer.

Return value:

ODM_SUCCESS  if successful.

ODM_E_DOCID  if the document ID is invalid or refers to a document that no longer exists.

ODM_E_OFFLINE  if the DMS cannot currently access the document because the user client is off-line.

ODM_E_TRUNCATED  if the application supplied buffer is too small to hold data that cannot be safely truncated. A DMS cannot truncate an ODM_URL attribute or any attribute containing an ODMA document ID.

ODM_E_ITEM  if item is invalid or unknown to this DMS.

ODM_E_NOSUPPORT  if the DMS does not support the function or does not support the specified document attribute.

ODM_E_HANDLE  if handle was invalid.

2.10 ODMGetDocRelation

ODMSTATUS ODMGetDocRelation( ODMHANDLE handle, LPSTR lpszDocId, LPDWORD pdwFlags, LPSTR lpszLinkedId, LPSTR lpszFormat, LPSTR lpszPreviousId )

An application can use this function to retrieve pointers to document versions linked to a particular document ID. This function would be used typically as part of retrieving a compound document. It could also be used when saving an updated component document, for the user to verify which compound documents will be impacted by any changes.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDocId - in -  A null-terminated document ID. This is typically obtained by a call to ODMSelectDoc or ODMNewDoc . The specified document may or may not be open when ODMGetDocRelation is called.

pdwFlags - in/out -  A pointer to a variable containing flags used on both input and output. On input, one or more of the following flags: ODM_REL_PARENT - Return the lpszLinkedId that is a parent of lpszDocId. ODM_REL_CHILD - Return the lpszLinkedId that is a child of lpszDocId. ODM_SILENT - The DMS should not require user interaction while satisfying the call. If the call cannot be satisfied without user interaction then an error should be returned. Upon return one or more of the following flags may be set by the DMS unless an error occurred: ODM_REL_NOTORDERED - The default is that the DMS maintains child links as an ordered list, and that it will use lpszPreviousId to select the appropriate lpszLinkedId to return. If it is returning them in no particular, logical, meaningful sequence, the DMS will return this value to warn the application. A DMS could maintain both ordered and unordered lists, an example of the former being a book with separate chapters, while the latter might be a collection such as attached to a workflow. ODM_REL_FIXED - The relationship is frozen between the particular document versions represented by lpszDocId and lpszLinkedId. This may also be used to signify that the application and/or the user want to retain control over updating the link, rather than have the DMS do it. ODM_REL_RELEASED - The link should be maintained to the Current or Released version of the child document. Released is available in some DMS to distinguish a version that has been approved for release. If the DMS does not distinguish between Released and Latest, then Latest is used. The value is called Released and not Current, to avoid confusion with the version that is already (currently) linked. ODM_REL_LATEST - The link should be maintained to the latest version of the child document.

lpszLinkedId - out -  A pointer to a buffer where the DMS will return the ID of the next document version that is linked to lpszDocId. This buffer must be at least ODM_DOCID_MAX bytes in length. If successful then a null-terminated document ID will be returned here. Otherwise the contents of the buffer will be undefined.

lpszFormat - in/out -  This is an optional parameter. If specified it must be a pointer to a buffer of at least ODM_FORMAT_MAX characters. This buffer contains a null-terminated string naming the file format of the rendition to be retrieved when the link is followed. Refer to the Document Format Names section for information on how file formats are identified in ODMA. This parameter allows the caller to identify the best format for the intended use of the main document. The requested format may or may not be the one established in ODMSetDocRelation and may or may not be the primary editing format. For instance, a graphic may be saved in several resolutions, one for on-line use and another for printing. On input, this is a hint to the DMS of the preferred format of the child to be retrieved. If the application does not provide a format it should set the buffer in lpszFormat to a zero length string. In this case the DMS should use the format established in ODMSetDocRelation or the primary format of the document. On output, the DMS should write the format name of the rendition returned. This may be the closest rendition format the DMS could find. If the DMS does not record rendition formats when relating documents, then it should return a zero length string in this buffer. If this parameter is Null, then the DMS should use the format established in ODMSetDocRelation or the primary format of the child document (the one used in ODMOpenDoc).

lpszPreviousId - in -  A null-terminated document ID. This is typically returned as lpszLinkedId on a previous call to ODMGetDocRelation. By making repeated calls to ODMGetDocRelation, the application obtains a logically ordered list of document ID's that make up a compound document. To get the first document in a list, provide a zero length, null-terminated document ID. Null should be passed if the application has no meaningful information to pass through this parameter.

Return value:

ODM_SUCCESS if successful.

ODM_E_NORELATION  if the specified document has no related parent or child.

ODM_E_NOMOREDATA  if the end of the list has been passed.

ODM_E_DOCID  if a document ID is invalid or refers to a document that no longer exists.

ODM_E_USERINT  if the ODM_SILENT flag was specified and the DMS could not satisfy the call without user interaction.

ODM_E_NOSUPPORT  if the DMS does not support the function.

ODM_E_INVARG  if the value specified in pdwFlags was invalid. On input either ODM_REL_PARENT or ODM_REL_CHILD must be set.

ODM_E_REQARG  if a required parameter (i.e. lpszLinkedId) is Null.

ODM_E_HANDLE  if handle was invalid.

ODM_E_FAIL  if the specified data was invalid or the DMS was unable to accept it for other reasons.

2.11 ODMGetLeadMoniker

ODMSTATUS ODMGetLeadMoniker( ODMHANDLE handle, LPSTR lpszDocId, LPMONIKER FAR *ppMoniker )

Applications that are OLE 2 servers typically form composite monikers for their OLE links by combining a file moniker representing the document with one or more item monikers representing a particular section of the document. This approach often does not work in environments where Document Management Systems are in use because the filename that the application sees is usually just temporary. This function lets the application obtain a leading moniker from the DMS that can be used in place of the file moniker.

This function will only be available on platforms supporting OLE 2. This function may not be supported by some DMSs; those DMSs will return ODM_E_FAIL. In this case the application should go ahead and use the file moniker as though ODMA were not present. Note that this function is prototyped in odmacom.h instead of odma.h, so that non-OLE-aware applications do not have to #include the OLE header files.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDocId - in -  An ODMA document ID.

ppMoniker - out -  A leading moniker for the specified document ID will be returned here if successful. Otherwise Null will be returned here.

Return value:

ODM_SUCCESS  if successful.

ODM_E_FAIL  if the DMS that created the specified document ID does not support OLE moniker building.

ODM_E_DOCID  if the document ID is invalid or refers to a document that no longer exists.

ODM_E_HANDLE  if handle is invalid.

2.12 ODMNewDoc

ODMSTATUS ODMNewDoc( ODMHANDLE handle, LPSTR lpszDocId, DWORD dwFlags, LPSTR lpszFormat, LPSTR lpszDocLocation )

This function causes the DMS to create a new document profile and return the document ID for the new document to the calling application. The DMS may create a temporary or pending document profile; it may not have actually created a document in its data store. If the DMS displays a dialog box for this function it should be task/application modal.

The document ID returned by the DMS in ODMNewDoc provides a document context for the application. This document ID must be used in subsequent ODMA function calls which are needed to complete the process of saving a new document into a DMS. If the user decides to cancel the operation or save the document to the native file system, then the application should call ODMCloseDoc or ODMCloseDocEx and throw the document ID away. The document ID returned by ODMNewDoc may be temporary so the application must be prepared for the possibility that the DMS will later override it in a call to ODMSaveAs, ODMSaveAsEx or ODMSaveDoc or ODMSaveDocEx.

The calling sequence for creating a new document, which isn’t based on another existing document, is as follows: ODMNewDoc, ODMSaveAs, ODMOpenDoc then ODMSaveDoc. Finally the document must be closed with ODMCloseDoc. The above sequence will likely involve user interaction with the DMS displaying one or more dialog boxes.

It is possible for an application to create a new document without any user interaction if the DMS supports it. To accomplish this the calling application should set the ODM_SILENT flag and use the following call sequence: ODMNewDoc, {ODMSetDocInfo}, ODMSaveAsEx, ODMOpenDoc, ODMSaveDocEx and ODMCloseDocEx.

Optionally, if the application wishes to pre-set some document attributes in the Save As dialog box it can call ODMSetDocInfo using the document ID from ODMNewDoc. This should be done before calling ODMSaveAs or ODMSaveAsEx. Example attributes the DMS might accept and perhaps show in its Save As dialog are ODM_NAME, ODM_AUTHOR, ODM_KEYWORDS and others. After ODMSaveAs is called, the application might wish to call ODMGetDocInfo to see if the user changed the value of any document attribute it is tracking.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

lpszDocId - out -  A pointer to a buffer where the DMS will return the ID of the new document. This buffer must be at least ODM_DOCID_MAX bytes in length. If successful then a null-terminated document ID will be returned here. Otherwise the contents of the buffer will be undefined.

dwFlags - in -  0 or a combination of 1 or more of the following values: ODM_SILENT - The DMS should not require user interaction while satisfying the call. If the call cannot be satisfied without user interaction then an error should be returned.

lpszFormat - in -  A null-terminated string naming the format of the new document's content. Refer to the Document Format Names section for information on how file formats are identified in ODMA. Note that this may be changed later via an ODMSaveAs call.

lpszDocLocation - in -  Normally DMSs select the location for a new document. But if the document already exists and is large or resides on read-only storage then the calling application can use this parameter to tell the DMS where the document is currently stored. This is a hint to the DMS that the document should be left in this location. Note that some DMSs may ignore this hint and move the document anyway. A DMS may ignore this parameter. The calling application should not directly access the document in this location following the call to ODMNewDoc; it should use ODMOpenDoc to obtain a location for subsequent access to the document. In most cases the application should pass Null in this parameter to allow the DMS to determine the document's storage location.

Return value:

ODM_SUCCESS  if successful.

ODM_E_CANCEL  if the user cancels the new document creation.

ODM_E_FAIL  if the DMS failed to create the new document.

ODM_E_USERINT  if the ODM_SILENT flag was specified and the DMS could not process the function without user interaction.

ODM_E_APPSELECT  if the user indicated that he wants to select the document's filename using the application's regular file selection facilities rather than using the DMS. The application should just display its regular selection dialog.

ODM_E_OFFLINE  if the DMS has no local data store and is off-line from its server; generally the caller should treat this the same as ODM_E_APPSELECT.

ODM_E_HANDLE  if handle was invalid.

2.13 ODMOpenDoc

ODMSTATUS ODMOpenDoc( ODMHANDLE handle, DWORD flags, LPSTR lpszDocId, LPSTR lpszDocLocation )

This function causes the DMS to make a document available to the application. It performs any necessary pre-processing (mapping network drives, checking security, etc.) and then returns to the application a temporary filename that can be used to access the document during the current session. Note that this function does not open the document file; it merely makes the file temporarily available to the calling application. The application can then open, read, write and close the file as needed.

If ODM_MODIFYMODE is requested, the DMS may refuse the request if the user has view-only rights (ODM_E_ACCESS) or if the document is currently checked-out (ODM_E_INUSE) to another user. It is recommended that the application retry the request specifying ODM_VIEWMODE in both cases so that the user can at least view the document and possibly save changes to a new document.

Applications are encouraged to give the user the same level of feedback if a DMS based document is opened for read-only access as they would for a document based in the platform’s native file system.

When the application is finished using a file which was opened with either ODM_MODIFYMODE or ODM_VIEWMODE it must call ODMCloseDoc or ODMCloseDocEx. When an application is finished using a file that was obtained with the ODM_REFCOPY option it does not have to call ODMCloseDoc or ODMCloseDocEx, however, it must delete the temporary file.

If an application has opened a document in ODM_VIEWMODE and wishes to switch to ODM_MODIFYMODE, it must first call ODMCloseDoc or ODMCloseDocEx then call ODMOpenDoc requesting ODM_MODIFYMODE. The same is true if the application wishes to switch from ODM_MODIFYMODE to ODM_VIEWMODE. The ODM_E_ALREADYOPENED error status is returned by the DMS if the application attempts to re-open a document that it has already opened in either of these two modes.

Parameters:

handle - in -  A handle obtained by a previous ODMRegisterApp call.

flags - in -  One or more of the following flags: ODM_MODIFYMODE - The DMS should make the document available in a modifiable mode. This mode is assumed if ODM_VIEWMODE or ODM_REFCOPY is not explicitly requested. ODM_VIEWMODE - The DMS should make the document available in a view-only mode. Any changes made to the document will not be transferred back to the document repository. If ODM_VIEWMODE and ODM_MODIFYMODE are both specified in the same call the ODM_E_INVARG error will be returned. ODM_REFCOPY - The DMS should make a read-only reference copy of the document available to the calling application. The DMS must return a different filespec in lpszDocLocation each time this function is called. It is invalid to specify ODM_REFCOPY with either ODM_VIEWMODE or ODM_MODIFYMODE. The calling application must delete any reference copy file obtained using this option and it should not call ODMCloseDoc or ODMCloseDocEx. ODM_SILENT - The DMS should not require user interaction while satisfying the call. If the call cannot be satisfied without user interaction then an error should be returned.

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

lpszDocLocation - out -  A pointer to a buffer of at least ODM_FILENAME_MAX bytes in length. The DMS will store in this buffer a null-terminated string indicating where the caller can access the document during the current session. Typically, this will be the full path/file name of the specified document, but some document formats may dictate another type of location such as a directory name. If an error occurs then the contents of the buffer will be undefined.

Return value:

ODM_SUCCESS  if successful.

ODM_E_ACCESS  if the user does not have the access rights requested (for example, modify mode was requested but the user only has view rights to the document).

ODM_E_INUSE  if the user is currently unable to access the document in modify mode because it is checked-out by another user. This differs from ODM_E_ACCESS in that it is expected that the user might be able to access the document in the specified mode at some point in the future.

ODM_E_DOCID  if the document ID is invalid or refers to a document that no longer exists.

ODM_E_OFFLINE  if the DMS cannot currently access the document because the user client is off-line.

ODM_E_ARCHIVED  if the DMS cannot currently supply the document content because it has been archived.

ODM_E_USERINT  if the ODM_SILENT flag was specified and the DMS could not make the specified document available without user interaction.

ODM_E_INVARG  if both ODM_OPENMODE and ODM_VIEWMODE have been specified or if either of those modes was specified with ODM_REFCOPY.

ODM_E_ALREADYOPENED  if the application attempts to reopen a document with ODM_MODIFYMODE or ODM_VIEWMODE that it has already opened with either of these modes. See below for one possible exception.

ODM_E_FAIL  if the DMS is unable to make the document accessible for any other reason.

ODM_E_HANDLE  if handle was invalid.

If the application attempts to open a document for ODM_VIEWMODE that it already has opened for ODM_VIEWMODE, then the DMS may either return the ODM_E_ALREADYOPNED error status or ODM_SUCCESS along with the previously returned temporary file specification. The DMS should not return ODM_S