Amigo 32 Release Notes

The Amigo32 (win32) release is delivered as a zip file. Unzip (recursive) to install onto your machine (and preserve the original sub tree structure).

The sub tree is self contained and can be installed anywhere you choose. At this point the code is sufficiently configured to allow you to access the dmaSystemManager and its service registry interface. You cannot connect to the system object, nor any document space or other service (eg: the merged scope factory) at this point. To do so you must register the system object, and document spaces.

The quick and simple solution is to adapt the supplied "dmasvc.reg" to detail the services you want registered, and 'run dmasvc.reg'.

The more standard approach (ie: less Amigo specific) is to register services via the IdmaServiceRegistry interface. In the case of Amigo, a service once registered can be used immediately (no need to reboot, no need to restart the DMA application). You do however need write permission to the LOCAL_MACHINE\Software\ branch of the windows registry.

Note: the system manager and the system object maintain separate registries. You must first must register the system object(s) using the IdmaServiceRegistry interface of the system manager. You can then connect to the system object, and register document spaces. The document spaces must be registered using the IdmaServiceRegistry interface of the system object. The registries are located as follows:

"HKEY_LOCAL_MACHINE\Software\DMA\System Manager Service Registry 1.0"

2. Contents of the ZIP file

amigo32\bin\win32msc\debug // debug runtime .EXE's/.DLLs/.LIB directory
amigo32\bin\win32msc\release // non debug runtime .EXE's/.DLLs/.LIB directory
amigo32\dma\include // The DMA 1.0 header files
amigo32\src // source directory for Amigo32
amigo32\dmasvc.reg // sample registration file

The source directory contains a make file:

win32msc.mak // windows 32, make file for Microsoft VC. This has targets for all amigo components

The win32msc.mak make files is generated using Microsoft Developer's Workbench, are VC++ 4.2 and provides release & debug targets. All code was compiled pack(8) and all the DLLs uses dynamic linked runtime libraries, and exceptions disabled.

3. Verification of install

From a dos prompt inside the debug or release runtime directory, you should be able to invoke the testclnt.exe program. This program allows you to connect to the system manager. It should fail and exit on attempt to connect to the system object if no system object is registered.

Once the system object is registered the program can connect to the system object, but will fail on attempting to connect to a document space unless one or more document space is available, and correctly registered.. The debug version is a lot chattier than the release version, which tells you the basics.

You should also be able to make release & debug versions of any of the runtime modules using "nmake" or "Microsoft Developer Studio" on the supplied win32msc.mak file.

4. Moving the installed files

You can safely copy the content of the runtime directory (bin/debug or bin/release) elsewhere (e.g., DMA, DMATEST, DMADEMO), as you require so long as your service registrations are not invalidated (eg: if you give a full path name for the module location, and then move the module..!!!).

Typically I would not expect full pathnames to be registered. Provided the DLL is still on the search path of the executing process, the DLL will be found.

5. Integrating your own doc space

The document space must be registered with the system object. The data is recorded in the windows registry

The default document space is whichever document space is produced first by enumeration of the windows registry.

To update the registry using a REG file, modify the dmasvc.reg file per instructions inside the file (please save an original copy in case you chew it up and need a reference). At ConnectDocSpace, the service procedure will be passed the specified profile string and required GUIDs. If the client does not request a specific DocSpace (ie: a NULL guid), on a ConnectDocSpace, the first DocSpace encountered in the registry is invoked.

To update the list of document spaces programmatically use the IdmaServiceRegistry interface from the system object. You can either supply an explicit serviceID, or rely on the Amigo software to generate a GUID for you (it uses CoCreateGUID).

The test program connects to the default document space.

6. Compiling and running a client application

Client applications should include the DMA header files, and link with DMA10.LIB to access the Amigo32 System Manager module. Aside from making sure your services are properly registered, that's it.

*** NOTE: When all else fails, try the supplied testclnt.exe and see if the connection gets through to the docspace you are trying to use. Then see how your connection code deviates from the example and see if you can make it work by matching the clnttest for now.

7. Supported functionality (see Section 10 for features new to this release)

7.1 SystemManager

dmaConnectSystemManager - keeps a copy of the locale (but performs no validation). Supports UNICODE only.
IdmaSystemManager:

GetMalloc() - is implemented via the task allocator (CoGetMalloc) if no IMalloc was supplied at the dmaConnectSystemManager call.
ConnectSystem().
EnumerateSystems()

IUnknown

QueryInterface()
AddRef()
DeleteRef()

IdmaOIID

GetSystemId()
GetDocSpaceId()
GetGuid()
GetObjectIdText()

IdmaServiceRegistry

GetRegistryElement
FindNextRegistryElement
RegisterServiceElement
RemoveRegistryElement

Notes:

Use of a null pSystemId is not permitted (as per the DMA 1.0 specification).
The service registry for the system manager is stored at

7.2 System Object

IdmaSystem (Supports UNICODE only)

ConnectDocSpace()
EnumerateDocSpaces()
GetResultCodeDescription()
CreateScope() - Implemented if a ScopeFactory plug-in module is present.

IUnknown

QueryInterface()
AddRef()
DeleteRef()

IdmaOIID is implemented here.
IdmaProperties

GetPropValBooleanById()
GetPropValInteger32ById()
GetPropValStringById()
GetPropValIdById()

IdmaServiceRegistry

GetRegistryElement
FindNextRegistryElement
RegisterServiceElement
RemoveRegistryElement

Notes:

Use of a null pDocSpaceId is not supported (as per the DMA 1.0 specification).

7.3 Test DocSpace

There is no test document space provided with this build.

8. Code Structure - module organization

The only implemented interfaces and functions are within:

DMA10.LIB

Link with this to have access to dmaConnectSystemManager

DMA10.DLL

dmaConnectSystemManager (dll well-known entry point)
IdmaSystemManager

ConnectSystem
GetMalloc
EnumerateSystems

IUnknown (ALL methods)
IdmaOIID (ALL methods)
IdmaServiceRegistry (ALL methods)

DMASYS1.DLL

DMA_GetServiceObject (dll well-known entry point)
IdmaSystem

ConnectDocSpace
EnumerateDocSpaces
GetResultCodeDescription

IUnknown (ALL methods)
IdmaOIID (ALL methods)
IdmaProperties

GetPropValBooleanById()
GetPropValInteger32ById()
GetPropValStringById()
GetPropValIdById()

IdmaServiceRegistry (ALL methods)
IdmaScopeFactory (QueryInterface fails if no scope factory service is registered)

tstdocsp.dll

DMA_GetServiceObject (dll well-known entry point)
IUnknown (ALL)

9. Caveats

dmaConnectSystemManager

pEnvInfo (not validated, it's pointer is simply passed through the system)
pProfile (assumed NULL; ignored in this implementation)
pIMalloc (if NULL, CoGetMalloc is used as the default allocator; if non-NULL, there must be a valid IMalloc interface available via QueryInterface)
The DmaString located by pLocaleName is copied but not validated.

IdmaSystemManager::ConnectSystem

lCharSetEncodingID (must be DMA_CS_UNICODE for the supplied system object; anything else leads to DMARC_BAD_PARAMETER)

IdmaSystem::ConnectDocSpace

If the DocSpace ID is NULL then DMARC_BAD_PARAMETER is returned.

IdmaSystem::EnumerateDocSpaces

Only Document Spaces with the current character set encoding (UNICODE) can be instantiated and delivered through the enumerator.
**Warning: The enumerator does not have an IdmaProperties interface, though this is required by DMA 1.0

System Object IdmaProperties (supports only the following properties):

dmaProp_DisplayName
dmaProp_DescriptiveText
dmaProp_LocaleName
dmaProp_CreatePending
dmaProp_UpdatePending
dmaProp_DeletePending
dmaProp_CharacterSetEncoding
dmaProp_SystemOIIDPrefix
dmaProp_SystemId
**Warning: There is no dmaProp_ClassDescription. This is a violation of DMA 1.0
**Warning: Access to these properties is by id only. Access by index is not supported. This is a violation of DMA 1.0

IdmaSystem::GetResultCodeDescription

Delivers "en_US" messages, and ignores the locale.

IdmaServiceRegistry::RegisterServiceElement

Does not ensure the uniqueness of the svcObjId, svcType, charset tuple. The same service can be registrered multiple times.

10. Explicit Release Modifications & Bug Fixes (code level)

10.1 New to this release

uses the AIIM header files of 1/20/98 .
CallDmaGetServiceElementBySvcRegId supports verification that desired character encoding ID is supported by requested service
character encoding id added as a parameter to GetEntryProc.
GetStringAFromDmaId function enhanced to prevent purify warning messages generated by sprintf.
CdmaServiceRegistry constructor enhanced to accept character encoding id parameter. This class now retains this information as a public data member.
CdmEnumOfSvc constructor enhanced to accept a pointer to the environment info data. This class now retains this information as a private data member.
Removed hard-coded DMA_CS_UNICODE in ConnectSystem's call to CallDmaGetServiceElementBySvcObjId. This allows

10.2 Bug Fixes (code level)

Since Amigo A5:

IdmaServiceRegistry::GetNextObject employs a mutex to ensure the stability of the read, and correct forward advance of the enumerator.
fixed a bug whereby IdmaServiceRegistry::RegisterServiceElement did not return the registration Id.
dmaConnectSystemManager returns with an error if the character set requested is not UNICODE.
pLocaleName is copied on dmaConnectSystemManager, and ConnectSystem. Clients are no longer required to maintain this parameter value.
pLocaleName parameter on ConnectSystem and connectDocSpace is now passed down even if NULL. Per the DMA specification we should not substitute the parents locale when given a NULL.
CdmaSystemManager::GetMalloc returns DMARC_UNEXPECTED if no allocator is available. Previously this returned DMARC_NOT_IMPLEMENTED (really!).

Since Amigo B0.00:

fixed bug where ConnectDocSpace and ConnectSystem fail when service registration id is not the same as the service object id.
fixed bug whereby the service registration id was passed to the Dma_GetServiceObject call.
removed some bogus registry keys from dmasvc.reg

Since Amigo B0.01

fixed bug where CdmaSystem::QueryInterface fails when asked for IID_ScopeFactory.
DMA_CREATE_STRING was buggy in B0.01 DMA header file. The new headers fix the length field of the BSTR.

Since Amigo B0.02

uses the headers3.zip header files from \DMA\TechnicalCommittee\Editorial\spec100\New\headers3.zip.
the system manager lib file is now called DMA10.LIB
the source tree structure is changed
added version resources to the DLLs and test program.
changed the registry key used by the system manager and system object for their service registry data.
IdmaServiceRegistry no longer uses the serviceObjectId as the registryId.
IdmaServiceRegistry has tighter validation of what it will allow to be registered.
added #pragma message comments to hghlight the difference in status between the system manager and the other components.
error descriptions are now based on the description in the DMA specification (not the symbolic name).
error description code factored out of sysobj.cpp to better isolate this code as it would need localization.
uses the new string macros defined in dmastr.h
supports IdmaScopeFactory, and requests the new IdmaScopeFactory interface from the merged scope plug in
changed the source tree layout for simplicity
IdmxOIID is no longer available (changes to IdmaOIID make this obsolete).
made local source file data items and functions static where-ever possible to reduce global symbol litter
made code tighter with respect to unused but named arguments, and unused local variables.
added test code for DMA string macros