Copyright ? 2000 AIIM International
Version 2.0.0-1 Review Draft Last updated 2001-01-11-08:28 -0800 (pst)

The Open Document Management API (ODMA) Coalition defined and developed libraries for building ODMA-compliant software products in conformance with the ODMA 2.0 Specification.

The ODMA 2.0 Library Files are those definition files needed to construct ODMA-aware applications and ODMA-compliant DMS integrations.  These files are also employed in the construction, maintenance, and porting of the ODMA 2.0 Connection Manager.  Along with the specification itself, these are the essential software files for ODMA 2.0 software-development projects.

 This information applies to Zip Package 2.0.0-1 of the ODMA 2.0 Library Files.  For later versions and current status, consult the ODMA 2.0 Library Files description page.

---

Content

1. Prerequisites

2. Obtaining ODMA 2.0 Library Files

3. ODMA 2.0 Library Content (package version 2.0.0-1)

3.1 Odma.h (version 2.0.0-1)

The basic ODMA 2.0 API definitions (C and C++) used by ODMA-aware applications

 

3.2 Odmacom.h (version 2.0.0-1)

The basic ODMA 2.0 COM Interface definitions for use by ODMA-aware COM clients, COM servers, and ODMA-compliant DMS integrations.

 

3.3 Odma.lib (version 2.0.0-1)

The Microsoft object library for binding a 16-bit (Windows 3.11 compatible) application to the 16-bit implementation of the ODMA Connection Manager, Odma.dll.

 

3.4 ODMA32.lib (version 2.0.0-1)

The Microsoft object library for binding a Win32 (Windows 95, Windows NT, or later) application to the 32-bit implementation of the ODMA Connection Manager, ODMA32.dll.

4. Using Odma.h

5. Using Odmacom.h

6. Using Odma.lib and ODMA32.lib

Change History

---

1. Prerequisites

1.1 Access-Viewing Requirements
1.2 Development-Tool Requirements

The ODMA 2.0 Library Files (edition 2.0.0-1) are designed specifically for development of ODMA-compliant software on the Microsoft Windows platform (Intel PC architecture).  The libraries are for use by programs developed in C/C++ Language and constructed using standard development tools (e.g., Microsoft Visual Studio) for the Windows platform.

The materials included in the ODMA 2.0 Library Files package may be informative and useful for other purposes as well.  There is no special effort to satisfy other applications, though.

To determine whether there are more-suitable materials for your purposes, please consult the latest information on the AIIM DMware ODMA site:

• ODMA 2.0 Status for the latest information on ODMA materials and the supported versions of ODMA
• ODMA Support for overall information for all versions, including any later than ODMA 2.0.
• ODMA Downloads for all materials available for download, including more-recent and alternative materials to the ODMA 2.0 Library Files.
• ODMA FAQ for responses to Frequently-Asked-Questions on ODMA trouble-shooting, development, and support beyond those included in the ODMA 2.0 Library Files package.

For more information on how ODMA 2.0 Library Files edition 2.0.0-1 materials are applied, it is also useful to review the following sections of this document:

• Section 3, ODMA 2.0 Library Content
  for information on the actual content (in Table 1) 
• Section 4, Using Odma.h
for prerequisites to consider when applying the ODMA API in C/C++ programs
• Section 5, Using Odmacom.h
  for prerequisites to consider when accessing or delivering Microsoft COM interfaces for ODMA in C/C++ programs
• Section 6, Using Odma.lib and ODMA32.lib
  for considerations in binding to the ODMA API, and the development tools needed for delivering 16-bit (Win16) and 32-bit (Win32) ODMA-compliant Intel-architecture components

1.1 Access-Viewing Requirements

To access and use the material, you require:

1. A web browser or HTML viewer that supports HTML 3.2, including tables.
2. A ZIP-archive decompression utility that will extract files from WinZIP-compatible archives.
3. An Internet connection and web browser for accessing the ODMA sites and downloading necessary materials.   

It is also important to have a current copy of the ODMA 2.0 specification and any errata compiled for it.

1.2 Development-Tool Requirements

To develop ODMA-compliant software using the ODMA 2.0 Library Files, you will need

1. A C/C++ compiler system for developing Win32 applications that can use Win32 interfaces and be bound to Win32 Dynamic Link Libraries (DLLs).  If you wish to construct a Win32 DMS integration, the programming-language system must support construction of Win32-compliant DLLs.
2. A C/C++ compiler system for developing 16-bit (Win16) applications that can use 16-bit Windows interfaces and be bound to 16-bit DLLs.  Current Microsoft tools do not support development for Win16.  It is necessary to obtain older development products from Microsoft or other sources if construction and maintenance of Win16 components is important.
3. A licensed set of Windows headers and Windows libraries, usually provided with the chosen programming-language system.

It is also important to review current issues, incident reports, and FAQ that may impact your development of ODMA-2.0-compliant components.

If you have not already done so, it is valuable to obtain the ODMA 2.0 Software Development Kit (SDK) for component samples and the ODMA 2.0 Connection Managers.   This and other material that may be of value can be located via the ODMA Downloads page.

2. Obtaining ODMA 2.0 Library Files

2.1 Identify Current Files
2.2 Download 2.0.0-1 Files
2.3 Extract Files for Development Use

2.1 Identify Current Files

This document applies to the original library files created for ODMA 2.0.  They are available on-line as ODMA 2.0 Library Files package version 2.0.0-1.  

Unless you have already done so, and are satisfied that the 2.0.0-1 files are what you want, you should check on the AIIM DMware ODMA site for the latest description of ODMA 2.0 Libraries.  That description of the current ODMA 2.0 library can be found on the AIIM DMware ODMA development site at URL

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

If there is more-recent material that is more-appropriate for your purposes, locate the instructions that apply to that material and employ them in place of this description.  Do not continue with these instructions.

If package version 2.0.0-1 is the available material that you elect to use, continue with these instructions.

2.2 Download 2.0.0-1 Files

ODMA 2.0 Library Files edition 2.0.0-1 is distributed in the Zip archive file odma200L-1.zip.  

Download the .zip file from the designated location.  Choose a suitable working destination, such as a place where you intend to extract the contents.  Rename the file as needed to satisfy requirements of your operating system.  It is valuable to choose locations and names that avoid confusion between this library package and any others that become available.

If you obtain the .zip file by other means, you can confirm that you have the correct package by reviewing the odma200L-1.zip Content in Table 1.

2.3 Extract Files for Development Use

The files incorporated in odma200L-1.zip are designed to be extracted together into a single file-system directory.  Using typical Zip-file extraction software, an Extract All operation to a chosen directory will deliver the entire content exactly as described in Table 1.

All documentation is in HTML format, and the package can be reviewed using the page odma20L.htm as the starting point.

Two kinds of files are provided for use with programming-language systems:

• C/C++ header files Odma.h and Odmacom.h
• development-system link library files Odma.lib and ODMA32.lib

 

3. ODMA 2.0 Library Content (package version 2.0.0-1)

Table 1.  odma200L-1.zip Content

Name	Size (bytes)	Time Stamp (local time)	Edition	Description
odma20L.htm	-	-	2.0.0-1	Description of the package, how to use it, and how to obtain later material.
Odma.h	11567	1998-04-09-12:31	2.0.0-1	ODMA 2.0 Definitions and Interfaces for C/C++ construction of ODMA-compliant software
Odmacom.h	5652	1998-01-16-17:07	2.0.0-1	ODMA 2.0 Definitions and Interfaces for C/C++ construction of ODMA-compliant software that provides or uses the ODMA-defined Microsoft COM interfaces.
Odma.lib	12288	1998-05-07-15:39	2.0.0-1	Library for binding ODMA 2.0-aware Win16 applications to the Win16 ODMA 2.0.0-1 Connection Manager
ODMA32.lib	18860	1998-05-07-13:10	2.0.0-1	Library for binding ODMA 2.0-aware Win32 applications to the Win32 ODMA 2.0.0-1 Connection Manager
odma200c.htm	9458	2000-08-19-16:56	2.0.0-1	HTML-viewable rendition of Odmacom.h
odma200h.htm	16071	2000-08-11-18:01	2.0.0-1	HTML-viewable rendition of Odma.h
Q000014.htm	-	-	-	Q000014: Creating ODMA Document IDs.  Using Document IDs with a DMS Integration
Q000703.htm	25576	2000-09-11-12:57	0.13	Q000703: ODMA-Aware Application and Connection-Manager Version Compatibility.  Information on choosing the proper version of definitions and libraries
Q000706.htm	36819	2000-09-11-13:30	0.14	Q000706: ODMA Version-Interoperability Configuration.  Information on setting up the ODMA SDKs for testing with all versions of ODMA Connection Managers and samples
Q000901.htm	-	-	-	Q000901: Using COM.  Information on the way that Microsoft COM is applied for ODMA and on using COM with ODMA.
Q001201.htm	-	-	-	Q001201: Versions to Develop For.

3.1 Odma.h (version 2.0.0-1)

3.1.1 Format
3.1.2 Symbols
3.1.3 Dependencies
see also, 4. Using Odma.h

Odma.h 2.0.0-1 is the original file of ODMA 2.0 definitions for creating ODMA-compliant programs in the C and C++ languages.   The file is required for any ODMA-compliant component that depends on or integrates with an ODMA 2.0 Connection Manager.  Odma.h is also employed in construction of the ODMA 2.0 Connection Managers.

Odma.h 2.0.0 depends on the Microsoft Windows Win16 and Win32 platforms and their definitions.  The file is not designed for use on any other platform.

For more information on appropriate usage of odma.h, see section 4, Using Odma.h.

3.1.1 Format

Odma.h 2.0.0-1 is a 11,567-byte file with timestamp of 1998-04-09-12:31.  The file is encoded in the ISO 8859-1 Latin 1 Character-Set, best displayed using Windows ANSI code page 1252.  There are tab (HT) characters in the file, with line separations using carriage-return/line-feed (CR/LF) pairs.

The first seven lines of the file contain the following identifying information:

/* odma.h - Definitions, prototypes, etc. for Open Document Managment API
     (ODMA) version 2.0.

     COPYRIGHT (C) 1994, 1995
     AIIM International
     All Right Reserved
*/

3.1.2 Symbols

The file defines and uses the C/C++ pre-processor symbol ODMA_H to avoid duplicate processing of the Odma.h definitions.

All definitions of C/C++ types, preprocessor symbols, and function prototypes use symbols beginning with the three-character prefix "ODM."  No other form of symbol is introduced by processing of Odma.h.

3.1.3 Dependencies

The file depends implicitly on other headers files of the Microsoft Windows platform.   The definitions in Microsoft header file <wtypes.h> (and others introduced by wtypes.h as needed) are sufficient. 

If	#include <wtypes.h>
or	#include <windows.h>
precede	#include "Odma.h"

then this dependency is satisfied.  If <wtypes.h> is not part of the Microsoft platform-specific materials, or if it fails on the platform you are compiling for, use <windows.h> instead.  

Odma.h adjusts for platform dependencies depending on six preprocessor symbols: WIN32, _WINDOWS_, _MSDOS, unix, _UNIX, and __cplusplus.

3.2 Odmacom.h (version 2.0.0-1)

3.2.1 Format
3.2.2 Symbols
3.2.3 Dependencies
see also, 5. Using Odmacom.h

Odmacom.h 2.0.0-1 is the original form of ODMA 2.0 definitions for creating COM-dependent ODMA components in C and C++.  Odmacom.h 2.0.0 is required by ODMA-aware applications that use ODMA 2.0-specified COM interfaces.  The file is also required for programs that supply the ODMA 2.0-defined COM interfaces.  Odmacom.h is employed in the construction of the ODMA 2.0 Connection Managers.

Odmacom.h 2.0.0 depends on the Microsoft Windows Win16 and Win32 platforms and their definitions.  The file is not designed for use on any other platform.

For more information on appropriate usage of Odmacom.h, see section 5, Using Odmacom.h.

3.2.1 Format

Odmacom.h 2.0.0-1 is a 5,652-byte file with timestamp of 1998-01-16-17:07.  The file is encoded in the ISO 8859-1 Latin 1 Character-Set, best displayed using Windows ANSI code page 1252.  There are tab (HT) characters in the file, with line separations using carriage-return/line-feed (CR/LF) pairs.

The first seven lines of the file contain the following identifying information:

/* odmacom.h - Component Object Model related definitions, macros, etc. for
   ODMA version 2.0.

    COPYRIGHT (C) 1994, 1995
    AIIM International
    All Rights Reserved
*/

3.2.2 Symbols

see also: Q000705: Changes Between ODMA Versions

Odmacom.h defines and uses the C/C++ pre-processor symbol ODMACOM_H to avoid duplicate processing of the Odmacom.h definitions.

All Odmacom.h definitions of ODMA-specific C/C++ types, preprocessor symbols, interface classes, structures, constant values, and function prototypes employ symbols beginning with the following prefixes:

IODM
IID_ODM
LPODM
ODM

When used in C++ programs, odmacom.h defines a number of C++ class methods as part of COM interface definitions (Table 2).  These methods can conflict with method names used in other C++ class definitions (e.g., ones from the Microsoft Foundation Classes), especially when multiple inheritance is employed.  This is a consideration when constructing C++ classes that offer or inherit ODMA-defined COM interfaces.

3.2.3 Dependencies

Odmacom.h depends implicitly on other header files of the Microsoft Windows platform.   The definitions from Microsoft header file <wtypes.h> (and others introduced by wtypes.h as needed) are sufficient.  

then this dependency is satisfied.  If <wtypes.h> is not part of the Microsoft platform-specific materials, or if it fails on the platform you are compiling for, use <windows.h>.

The file depends explicitly on inclusion of "odma.h" for its correct processing, and checks for the pre-processor symbol ODMA_H to avoid duplicate inclusion of Odma.h.   

Odmacom.h depends on the following files provided for Microsoft Windows platforms: <objbase.h> (Win32), <memory.h> (not Win32), <compobj.h> (not Win32), <ole2.h> (all), and <moniker.h> (all).  

Five preprocessor symbols are used to coordinate the processing of definitions:  WIN32, _OBJBASE_H_, __COMPOBJ_H_, _OLE2_H_, and __cplusplus.  The preprocessor symbol INTERFACE is undefined and redefined as part of the use of Windows-platform interface-definition macros employed in the processing of Odmacom.h interface definitions.

3.3 Odma.lib (version 2.0.0-1)

3.3.1 Format
3.3.2 Symbols
3.3.3 Dependencies
see also, 6. Using Odma.lib and ODMA32.lib

ODMA-aware applications that operate on the 16-bit Windows (Win16) platform must be bound to Odma.dll, the Connection Manager for Win16.  This binding can occur dynamically or statically.  When binding is done statically, Odma.lib is used as part of linking the application program or component.

Odma.lib version 2.0.0 is the Win16 object library file to use for static binding to the ODMA 2.0 Connection Manager for Win16, Odma.dll version 2.0.0.  The library is not useful for binding to earlier versions of the Win16 Connection Manager.

For more information on usage of Odma.lib, see section 6, Using Odma.lib and ODMA32.lib.

3.3.1 Format

Odma.lib 2.0.0-1 is a 12,288-byte file with timestamp of 1998-05-07-15:39.  The file is encoded in the Microsoft development tools MSLIBR format.

Inprise Turbo Dump 5.0.16.6 recognizes the file.  Inspection of the TDUMP report yields two kinds of information:

1. A large number of ODMA Connection Manager 2.0.0 internal function names are visible in Odma.lib as C++ names.
2. The public, documented API entries are identified, in agreement with the ordinally-numbered list given in section 3.3.2, Symbols.  In MSLIBR files, the exported names are always fully-capitalized (e.g., ODMREGISTERAPP for ODMRegisterApp).

3.3.2 Symbols

The following definitions are provided by Odma.lib 2.0.0:

LIBRARY         ODMA
DESCRIPTION     'ODMA 2.0 Connection Manager 16-Bit'
CODE            MOVEABLE DISCARDABLE
DATA            MOVEABLE SINGLE

HEAPSIZE        16392

EXPORTS
    ODMRegisterApp         @2
    ODMUnRegisterApp       @3
    ODMSelectDoc           @4
    ODMOpenDoc             @5
    ODMSaveDoc             @6
    ODMCloseDoc            @7
    ODMNewDoc              @8
    ODMSaveAs              @9
    ODMActivate            @10
    ODMGetDocInfo          @11
    ODMSetDocInfo          @12
    ODMGetDMSInfo          @13
    ODMQueryInterface      @14
    ODMGetLeadMoniker      @15
	
    ODMQueryExecute        @16
    ODMQueryGetResults     @17
    ODMQueryClose          @18
	
    ODMGetDMSCount         @19
    ODMGetDMSList          @20
    ODMGetDMS              @21
    ODMSetDMS              @22

    ODMCloseDocEx          @23
    ODMSaveAsEx            @24
    ODMSaveDocEx           @25
    ODMSelectDocEx         @26
    ODMQueryCapability     @27
    ODMSetDocEvent         @28
    ODMGetAlternateContent @29
    ODMSetAlternateContent @30
    ODMGetDocRelation      @31
    ODMSetDocRelation      @32

3.3.3 Dependencies

Odma.lib version 2.0.0 does not depend on the presence of any other libraries in providing access to the 16-bit (Win16) ODMA 2.0 Connection Manager.

3.4 ODMA32.lib (version 2.0.0-1)

3.4.1 Format
3.4.2 Symbols
3.4.3 Dependencies
see also, 6. Using Odma.lib and ODMA32.lib

ODMA-aware applications that operate on the 32-bit Windows (Win32) platform must be bound to ODMA32.dll, the Connection Manager for Win32.  This binding can occur dynamically or statically.  When binding is done statically, ODMA32.lib is used when linking the application program or component.

ODMA32.lib version 2.0.0 is the Win32 object library file to use for static binding to the ODMA 2.0 Connection Manager for Win32, ODMA32.dll version 2.0.0.  The library is not useful for binding to earlier versions of the Win32 Connection Manager.

For more information on usage of ODMA32.lib, see section 6, Using Odma.lib and ODMA32.lib.

3.4.1 Format

ODMA32.lib 2.0.0-1 is a 18,860-byte file with timestamp of 1998-05-07-13:10.  The file is encoded in Microsoft Common Object Format File (COFF) binary Library format.  

Library Information:

time date stamp: 1998-05-07-02:10:13
machine: i386
linker version: 5.10
operating system version: 4.00

3.4.2 Symbols

The following definitions are provided by ODMA32.lib 2.0.0:

LIBRARY         ODMA32
DESCRIPTION     'ODMA 2.0 Connection Manager 32-Bit'
CODE            MOVEABLE DISCARDABLE
DATA            MOVEABLE SINGLE

HEAPSIZE        16392

EXPORTS
    ODMRegisterApp         @2
    ODMUnRegisterApp       @3
    ODMSelectDoc           @4
    ODMOpenDoc             @5
    ODMSaveDoc             @6
    ODMCloseDoc            @7
    ODMNewDoc              @8
    ODMSaveAs              @9
    ODMActivate            @10
    ODMGetDocInfo          @11
    ODMSetDocInfo          @12
    ODMGetDMSInfo          @13
    ODMQueryInterface      @14
    ODMGetLeadMoniker      @15
	
    ODMQueryExecute        @16
    ODMQueryGetResults     @17
    ODMQueryClose          @18
	
    ODMGetDMSCount         @19
    ODMGetDMSList          @20
    ODMGetDMS              @21
    ODMSetDMS              @22

    ODMCloseDocEx          @23
    ODMSaveAsEx            @24
    ODMSaveDocEx           @25
    ODMSelectDocEx         @26
    ODMQueryCapability     @27
    ODMSetDocEvent         @28
    ODMGetAlternateContent @29
    ODMSetAlternateContent @30
    ODMGetDocRelation      @31
    ODMSetDocRelation      @32

3.4.3 Dependencies

ODMA32.lib version 2.0.0 does not depend on the presence of any other libraries in providing static binding to the 32-bit (Win32) ODMA 2.0 Connection Manager.

4. Using Odma.h

• Who uses Odma.h?
• What level of Interoperability is desired?
• Using the appropriate ODMA Version
• Incorporating Odma.h into programs.
• Watching out for the dependencies.
• Tips on Usage

5. Using Odmacom.h

see also:

Q00901: Using COM

• Who uses Odmacom.h?
• What level of Interoperability is desired?
• Using the appropriate ODMA Version
• Incorporating Odma.h into programs.
• Important Precautions
• Tips on Usage
• Confirming ODMA Operation

6. Using Odma.lib and ODMA32.lib

• Who Uses Odma.lib and ODMA32.lib
• Win16 and Win32 considerations
• Choosing Type of Binding 
• Using the Correct Library for Platform, Binding, and ODMA Version
• Important Precautions
• Tips on Usage
• Confirming ODMA Operation

---

Change History

version 2.0.0-1 Initial Packaging of Materials (orcmid)

The basic materials, Odma.h, Odmacom.h, Odma.lib, and ODMA32.lib are zipped "as is" along with this accompanying odma20L.htm (package 2.0.0-1) description.  HTML versions of the definition files are provided in the browser-viewable pages  odma200h.htm and odma200c.htm.  Supplemental notes that support effective use of the libraries are also provided: Q000703.htm, Q000706.htm, Q000014.htm, Q000901.htm, and Q001201.htm.

created 2000-07-11-15:36 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 05-02-03 16:13 $
$$Revision: 15 $