AIIM DMware ODMA FAQ Q010103

Visual Basic Access to ODMA Functions

 Version 0.25 Last updated 2002-11-22-22:16 -0700 (pdt)
The latest version of this information is available on the AIIM DMware ODMA site.

Summary:

This response addresses questions about the usage of Visual Basic and component technology as a means for accessing and providing ODMA functionality.

There is presently (November, 2002) no public solution for general access to ODMA-integrated DMS systems from Visual Basic applications.  There is also no public solution for construction of DMS integration using Visual Basic.  

The ActiveODMA project is intended to make ODMA integration available to all platform COM-capable and scripting languages.  There has been negligible progress to date.

This FAQtip summarizes the known approaches to bridging the mismatch between ODMA and the Visual Basic programming model (and others like it).  Few available resources are identified.

1. Accessing ODMA Using Visual Basic

2. ODMA-Using Components

3. Direct ODMA Usage

4. ActiveX ODMA Interface

5. Building a DMS With Visual Basic

Contributors

Change History


Summary

There are periodic questions about the integration of Visual Basic applications with ODMA.  The first inquiries concerned being able to construct special purpose desktop fixtures that would access DMS integrations via ODMA.  Lately, there has been interest in using Visual Basic in creating a DMS integration itself.  

The appeal of Visual Basic (VB to its friends) is the existence of a large community of application developers who use VB as their only programming language.  In addition, there are DMS vendors who develop client- (and server-) side document-management systems either by using Visual Basic or by providing interfaces that encourage access from Visual Basic applications.

It is natural to ask how ODMA integration can be utilized in these VB-centric settings. 

Simply put, (1) the ODMA API is not compatible with direct use from Visual Basic and (2) the ODMA Connection Manager DMS integration model is not compatible with objects of the kind that can be constructed using Visual Basic.  

As unnatural as the fit between ODMA and Visual Basic happens to be, there are some who have achieved limited "impedance matching" between the two.  This is not something that fits the ordinary experience of Visual Basic developers.  Extraordinary effort is required and this may present testing, maintenance and general skill requirements that an organization must be prepared for.

Here's what VB developers need to know about the possibilities for ODMA usage.   Steps to simplify the situation are described.    

1. Accessing ODMA Using Visual Basic

1.1 Historical Perspective

In 1994 when ODMA was being developed, the choice of a C Language API was near-automatic.  This was the preferred means of development and integration by developers of Microsoft Windows-based desktop applications, most of whom had not yet adopted the 1992-introduced OLE (Object-Linking and Embedding) and COM (Component Object Model) technologies.  Many developers of desktop applications and of DMS technology were still wary of Microsoft's COM initiative and, even if they saw migration to COM/OLE as inevitable, current products didn't employ the technology.

Although use of COM as an integration model was not commonplace and some doubted its viability altogether, the ODMA developers did agree on COM interfacing techniques for DMS integration with the ODMA Connection Manager.  The ambition was also to support the same models on platforms beyond the Win16-Win32 "sweet spot," and it was thought that a constrained COM integration approach would ease transfer to Macintosh, Unix, and OS/2, among others.  

It was also felt that "pure COM" could not be used simply because the applications and existing services that were being offered for ODMA integration were implemented in a way that did not yet map naturally to the COM approach.  At the time, the migration from Win-16 applications to Win32 and NT was more in the forefront.

The "incompleteness" of ODMA COM support is revealed primarily in the way ODMA supports character data and uses storage for information delivered across ODMA interfaces.  The ODMA provisions were entirely appropriate for the candidate applications and DMS systems that were available at that time.  They are unnatural to the current COM (and emerging .NET) worlds.

Although Visual Basic has now emerged as an instrument of professional software development and an appealing avenue for application development, its concepts and natural idioms are not harmonious with the approach taken in arriving at the ODMA API.  The ODMA API is quite idiosyncratic compared with the consistency of COM automation-oriented languages, including Visual Basic.  ODMA presents a challenging impedance match for Visual Basic developers.

1.2 Requirements of the ODMA API

[establish the nomenclature, introduce basic principles involved.  Also identify the limitations here or in an end-section, so that people can confirm there understanding of why it doesn't work just the way things are.]

[include links to related FAQ about this.]

[establish which Visual Basics we are talking about]

2. ODMA-Using Components

see also:
4. ActiveX ODMA Interface

One way to obtain ODMA services from Visual Basic is to access an already-available Active X Component (an OCX) that is ODMA-aware.   For example, it is possible to use Microsoft Word component interfaces to initiate a Word session that will use ODMA to open a requested document and perform other operations.  Here is an example of this approach provided by Nancy Bobb:

Private Sub Command1_Click()
     Dim x As Object
     Set x = CreateObject("Word.Application")
     x.Visible = True
     x.Documents.Open FileName:= _
     "::ODMA\GRPWISE\FH09CADO.FH09CAPO.FH09CA_SUBJCA_LIBRARY:34035.1"
     End Sub

It is possible to support this same technique by introducing a special-purpose "application" that provides something like the Microsoft Word Object Model, or perhaps the Microsoft Office Binder Object Model.  This "application" would use ODMA to perform its accesses while exposing an object model usable by Visual Basic applications. 

 This case has not been explored.  

The advantage is that almost all ODMA DMS integrations are designed to support ODMA Accesses from Microsoft Office and matching that behavior in a pseudo-application component should be successful.  

The disadvantage is that the Word Object Model can be an unnatural fit and be inadequate with regard to ODMA functionality that the Word Object model does not accommodate.   Finally, the effort is probably as great as building an ODMA-specific OCX.

3. Direct ODMA Usage

There has been some success accessing ODMA directly using Visual Basic calls.  A sample of suitable VB (and VBA) declarations is found in the file VBODMA102.bas.  Documentation has not been provided.  The handling of ODMA string buffers and the ODMA use of 8-bit characters (not BSTRs) requires some care.  

A variation on this technique has been used to provide ODMA access to Borland Delphi applications.

4. ActiveX ODMA Interface

4.1 Experimental OCX Development: ODMAWrapper

An experimental implementation of an ODMA-compatible Active X Control was turned over in 1999.  The idea was to provide ODMA functionality to any application able to use an OLE control.

There is an archive of the available source code at ODMA-OCX-2.0.0-0 (261kB ZIP file).  This code has not been confirmed and a tested .DLL has never been provided.  There is no information about the development status, the completeness, or the reliability of the implementation.

Expertise with Microsoft VC++ and the Microsoft Foundation Class (MFC) Library is required for working with this implementation.

The ODMAWrapper software does provide a specimen mapping between ODMA methods and operations delivered to VB applications.  This is worthy of review in arriving at a public implementation of ActiveODMA solutions.

4.2 ActiveODMA Interfaces and Modules

[Add information about the development to be described more fully in the ActiveODMA section of the ODMA web site.]

5. Building a DMS with Visual Basic

[discusses limitations on using component technologies (e.g., VB 6.0, VBA, ...) to make a DMS.  Need for a wrapper to allow the ODMA Connection Manager to connect to a DMS that is integrated via implementation of components.  Link to the ActiveODMA section for more on potential approaches]


Contributors

Nancy Bobb
illustrated how ODMA-aware components, such as those of MS Word, can be used as an avenue to obtaining ODMA functions from a Visual Basic Application
Dennis Hamilton
initiated this FAQtip in support of ODMA Tech requests for material on usage with Visual Basic as well as other component-based technologies and scripting engines.
Simon Tomlinson
provided an example of Visual Basic definitions that are useful with ODMA.

Change History

version 0.25 2002-11-23
updated to reflect the initiation of ActiveODMA and also provide more content information.
version 0.21 2002-05-07
added the Visual Basic definitions that have been employed in some situations.  Then updated the file to version 1.02 after checking the source in Visual Basic 6.0.
version 0.15 2001-01-30
begins to add text on the first case, relaying through ODMA-using components
version 0.10 2001-01-17
is a place-holder and outline for a note to be reviewed and developed further.
   

created 2001-01-17-13:16 -0800 (pst) by orcmid
$$Author: Orcmid $
$$Date: 07-07-28 11:15 $
$$Revision: 9 $