For the latest information on ODMA and the ODMA Specifications, consult the ODMA section of the AIIM DMware Clearinghouse at
http://DMware.info/. The latest status on ODMA 2.0 is always available on the Internet at
http://ODMA.info/support/odma20st.htm.This information is also part of ODMA 2.0 Library Files edition 2.0-1. For later editions and current status, consult the ODMA 2.0 Library Files description page.
ODMA employs the Microsoft Component Object Model (COM) for dynamic connection of DMS integrations to applications via the ODMA Connection Manager.
This document provides references and background information on the use of COM as part of developing ODMA Components.
This information is provided for developers and integrators who need to understand when and where Microsoft COM must be used in the integration of document-management services for access from ODMA-aware applications. We also review where COM is not usable, and where COM may be used to increase the flexibility by which an application exploits the availability of services via ODMA.
Content
Sketch:
Give a thumbnail sketch of how to find out enough about COM to work with ODMA, whether or not any further use of COM is intended. Include how to find supporting information, updates, examples and samples, etc.
- [COM Spec]
- Microsoft Corporation and Digital Equipment Corporation. The Component Object Model Specification. Microsoft Corporation (Redmond, WA: 1992-1995). Version 0.9, October 24, 1995.
This specification is available in the Microsoft Developer Network (MSDN) Library as recently as the July 2000 distribution. It can also be accessed via MSDN On-Line. There is a copy on the CD-ROM supplement to [Inside COM].
The specification is available on-line. There is an on-line HTML version and two downloadable versions consisting of Microsoft Word 6.0 Master Documents with individual chapters. A Word 6.0 version is required in order to have the footnotes and bibliography. [An interesting sideline to the downloadable versions is that they provide clean demonstrations of successful Word Master Document usage, an interesting challenge for document-management systems. --dh:]
For the purposes of ODMA, the important chapters of the specification are those on the basic model and use of the binary interface standard for COM. If ODMA is used in a COM environment, more of the specification applies, but not because of anything that ODMA depends on.- [Inside COM]
- Rogerson, Dale. Inside COM: Microsoft's Component Object Model. Microsoft Press (Redmond, WA: 1997). ISBN 1-57231-349-8. pbk with CD-ROM.
Chapters 1-4 take a leisurely tour of the interface and execution model for COM. This is the part that applies most directly to use of the ODMA COM interfaces. The treatment of aggregation in Chapter 8 is also important, especially for developers of DMS integrations. ODMA avoids use of COM Servers and the COM Class Factory mechanisms: There is no direct dependence on the COM APIs and the COM System Control Manager (SCM) -- COM's run-time -- at all. The same effect is achieved by a small, self-contained scheme implemented in the ODMA Connection Manager. Higher-level COM techniques remain available and useful: they simply don't arise directly in ODMA integration so far.- [Effective COM]
- Box, Don., Brown, Keith., Ewald, Tim., Sells, Chris. Effective COM: 50 Ways to Improve your COM and MTS-based Applications. Addison-Wesley (Reading, MA: 1999). ISBN 0-201-37968-6.
A compendium of tips and practices based on experience creating successful COM objects. For work with ODMA, the section on Interfaces (guidelines 6-16) and Implementations (guidelines 18-28) are the most useful and could be well-applied in future maintenance of ODMA SDK components and of the ODMA Connection Manager.
- [Inside OLE]
- Brockschmidt, Kraig. Inside OLE. ed.2. Microsoft Press (Redmond, WA: 1995). ISBN 1-55615-843-2. pbk with two disks.
This book is available in the Microsoft Developer Network (MSDN) Library as recently as the July 2000 distribution.
The book can also be found on MSDN Online.
OLE is a widely-known application of COM. There is much in this treatment that is inapplicable in the ODMA application of COM, although OLE facilities are certainly available to be used in applications that are also using COM for ODMA operations. The early material on pure COM aspects of OLE are applicable, though [Inside COM] provides a cleanly-separated view of the same basic COM elements. OLE applies to electronic documents, and the OLE model of documents is important to document-management, even though not addressed by ODMA (apart from a smidgen of support via ODMA'sODMGetLeadMonikeroperation).
Inside OLE is well-respected and, because of its inclusion in the MSDN Library, readily available.
- [MSDN Lib]
- Microsoft Corporation. Available by subscription.
- [MSDN Magazine]
- MSDN Magazine. Published monthly by Miller Freeman, Inc. ISSN 1528-4859.
Formerly the Microsoft Systems Journal (MSJ) and the Microsoft Internet Development (MIND) publications, this periodical provides timely material of importance to application developers and independent software vendors who target Microsoft platforms. The content is also available on-line and materials are sometimes included in MSDN On-Line and the MSDN Library.- [MSDN On-Line]
- Microsoft Corporation. Published on the web.
- [8Lessons]
- Prosise, Jeff. Eight Lessons from the COM School of Hard Knocks. Wicked Code column. MSDN Magazine 15, 11 (November 2000), 149-157.
There are a number of critical areas to pay attention to when ODMA COM interfaces are used from a full-up COM client or when delivered by an implementation that also operates as a COM client and/or COM server. These lessons apply to proper initialization of COM, passing (and using) interface pointers between threads, impact of the apartment models, and watching out for some DCOM gotchas. There are also tips on sharing object instances, if you must.
Sketch:
A short discussion of how COM is used by ODMA, and the limited use that is made of it. A diagram or two will be very helpful.
Basically in-process linkages via the DMS-integration
.dllfile, with everything accomplished via theODMGetODMInterfaceentry to the.dll.
- We will emphasize that the implementation of the DMS COM object may use more COM capabilities that ODMA requires.
- ODMA has no direct way to take advantage of that.
- It can still be useful
- Details about DMS use of COM are deferred to the appropriate section.
Point out that ODMA is designed so that a desktop application need not have any COM dependency in it at all, but that there are advantages to using COM as part of ODMA usage. The details are in section 4.
Finally indicate how, with one important exception, the use of COM for dynamically connecting DMS integrations to desktop applications is entirely handled by the ODMA Connection Manager.
This also means that a DMS integration must support the
.dlland COM interfaces required of it by ODMA. It can provide more, and applications can be designed to discover and exploit that, but the key thing is satisfying the COM requirement set down by ODMA.
Sketch:
ODMA Connection Manager is not available as a COM Server
DMS Integrations are not required to be available as COM Servers either
There are neither IDispatch nor Dual interfaces defined by or supported by ODMA, so there is no availability to scripting engines (VBScript, JScript, Python, etc.). There is also no convenient availability to Visual Basic or VBA. There is also no convenient way to build ODMA-compliant components using these technologies.
Even though ODMA Uses COM, it is not an application of COM (like OLE) where there is support in special application-development systems (MFC, Visual Basic, etc.)
This also means that standard utilities and tools for working with COM objects are useless with ODMA.
There are also characteristics of ODMA that make it difficult to extend the reach of ODMA via COM.
Sketch:
When it is useful for an ODMA-Aware Application to use COM for ODMA operations.
To ensure inter-version interoperability with any connection manager and DMS combination
To provide for more adaptability to the capability of the assigned default DMS.
To operate with special-purpose interfaces supplied by known DMS integrations that are valuable beyond the ODMA-defined interfaces (e.g., in a custom desktop application that is built to take advantage of special DMS cases).
Include guidelines of when to keep using the ODMA API when it is not know which DMS is the appropriate one to honor a given request.
Sketch:
OK, now you have to use COM. How much of it do you have to use and what do you have to be careful about.
Satisfy the interface requirements
Watch the object life cycle
Be very careful about aggregation support in
ODMGetODMInterfaceBe defensive
Don't mess with the contract
Be very cautious around deviations that have crept in between different ODMA versions
(See "Changes Between ODMA Versions.")Handle character sets and code pages as carefully as you can.
Be very careful with output parameters and when storing material into data areas of the application
Dennis E. Hamilton
AIIM DMware Technical Coordinator
Renton, Washington
September 13, 2000
- Version 0.10: Interim Drafts (orcmid)
- Collect key references and begin adding decorations on exactly how COM is used and usable in the context of ODMA..
created 2000-09-13-12:23 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 07-07-28 11:14 $
$$Revision: 9 $