ODMA FAQtip

Q000901: Using COM

Version 0.10  Interim Draft Last updated 2002-11-22-14:14 -0800 (pst)
The latest version of this information is available at the AIIM DMware ODMA site.

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

1. COM Resources

2. How ODMA Uses COM

3. Limitations of ODMA COM Support

4. COM for ODMA-Aware Applications

5. COM for ODMA-Compliant DMS Integration


1. COM Resources

1.1 Specifications and Guides
1.2 Reference Libraries

     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.

1.1 Specifications and Guides

[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, ChrisEffective 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's ODMGetLeadMoniker operation).
     Inside OLE is well-respected and, because of its inclusion in the MSDN Library, readily available.
 

1.2 Reference Libraries

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

1.3 Articles and Other Materials

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

2. How ODMA Uses COM

     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 .dll file, with everything accomplished via the ODMGetODMInterface entry to the .dll.

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 .dll and 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.

3. Limitations of ODMA's COM Support

     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.

4. COM for ODMA-Aware Applications

     Sketch:

When it is useful for an ODMA-Aware Application to use COM for ODMA operations.

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.

5. COM for ODMA-Compliant DMS Integration

     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.

 

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 $