Q060601
ODMA
FAQtip
Confirming
ODMA-Aware Connection
Procedure 0.10 (review draft)
0.10 2010-08-29 -20:13 -0700
|
|
Q060601
ODMA
FAQtip |
0.10 2010-08-29 -20:13 -0700 |
- Latest version: The latest version of this FAQtip is available on the Internet at
<http://ODMA.info/faq/2006/06/Q060601b.htm>.- This version: Procedure 0.10 <http://ODMA.info/faq/2006/06/Q060601c.htm>. Consult that page for the latest status and for the most-recent electronic copies of the material.
{author note: This is a provisional draft for early review. There is missing information. It is also likely that this material will eventually be refactored, with some material extracted into a common place where it will serve multiple procedures.}
This procedure is for testing and troubleshooting the automatic connection between ODMA-aware desktop applications and the ODMA Connection Manager. Confirming end-to-end connection between the application to the ODMA Connection Manager and is the first stage in verifying that an application has been configured properly for ODMA.
1. Purpose
2. Scenario
3. Prerequisites
3.1 Platform
3.2 Administrative Authorization
3.3 Initial Conditions
4. Setup
4.1 Have No Default DMS
4.2 Start the ODMA32 Log
5. Confirmation Steps
5.1 Clear the Log
5.2 Start the Application
5.3 Request Opening of a Document
5.4 Confirm Absence of ODMA-Related Dialogs
5.5 Cancel Operation and Close Application
6. Checking the ODMA Log
6.1 Preserve Any Log
6.2 Inspect the Log
6.3 Confirm Logging If In Doubt
7. Next Steps
7.1 Restore the ODMA Configuration
7.2 If Confirmation Succeeded
7.3 If Confirmation Failed
8. Resources
{tbd: A little more about when this procedure would be used. Paraphrase the Summary on the folio cover page.
This procedure can also be used to learn the ODMA Application ID that an application program is using.}
Suggest also using this procedure as a way to become familiar with ODMA troubleshooting
This procedure can also be undertaken with an application that is known to be working with ODMA. That can be done to confirm that the procedure works and also demonstrate what a successful results look like.
{tbd: Diagram of the path to the Connection Manager and Back. An Input-Process Output organized on the pattern of a UML interaction-sequence diagram (Fowler & Scott, p.103}
3.1.1 Microsoft Windows 2000 and later versions are assumed for the conduct of this procedure. The procedure and examples are all based on using Windows XP Professional SP2 (Media Center Edition 2005). Variations in appearance of examples and incidental details will be observed with earlier and later versions of Microsoft Windows.
3.1.2 This procedure is specific to native Win32 desktop applications, x86-compatible processors, and the ODMA 2.0 Connection Manager, ODMA32.dll. No ODMA Connection Manager is supplied for native operation on 64-bit versions of Windows.
3.1.3 This procedure also applies to versions of Windows 98. The desktop application must be supported on those versions. The authorization conditions and use of separate administrator and limited-user accounts do not apply (3.2). The Windows registry can be modified by any Windows 98 user and no special permissions are required.
3.1.4 Duplicate the essential configuration. An application that is confirmed to connect on one platform may fail to connect on a different Microsoft Windows version. If there is apparent difficulty obtaining an ODMA connection from an application, this procedure should be carried out on an identical configuration and preferably on the same computer.
3.2.1 You must be comfortable carrying out simple Administrator functions. You must have an administrative account on the platform to be used, or else an administrator must perform the following functions for you.
3.2.2 The confirmation itself can be carried out entirely in a limited user account (strongly recommended). This duplicates what should be the normal account type for operating an office-desktop application with ODMA.
3.2.3 Registry settings must be adjusted to set up the confirmation procedure. This can be accomplished by using an administrative account
- (a) to backup the registry in case it is damaged or corrupted by later modifications
- (b) to access the registry for modifications
- (c) optionally, to changing the permissions on the ODMA-important portions of the registry so they can be adjusted using the limited account during testing and troubleshooting
3.2.4 An administrative account is required for software installation. This applies to installation of the ODMA Connection manager (e.g., by installing the ODMA SDK) if it is not already installed. It will usually apply to installation of the application to be confirmed. It is recommended that installations be performed by elevating the limited account to administrator capability just long enough to carry out the installs and initial configuration of the application.
3.3.1 The desktop application has been installed and is confirmed to be working normally in the absence of any ODMA installation. Note: An ODMA-aware desktop application is expected to operate normally if there is no ODMA Connection Manager installed or if there is no default DMS available for use with the particular application. If there is any suspicion that the application is malfunctioning in the presence of ODMA, the ODMA Connection Manager should be removed and operation of the application confirmed. {tbd: link to information on how to do this safely and then restore ODMA in an appropriate manner.}
3.3.2 The ODMA Connection Manager is installed. It is recommended that the ODMA 2.0 SDK be used. This will provide the correct Connection Manager version and also set up other tools that are valuable for troubleshooting. This installation is safe to make even when the ODMA Connection Manager is already installed.
3.3.3 There need not be any ODMA-compliant Document Management System installed. This confirmation procedure works easiest if there are none. Default use of any ODMA DMS will be disabled as part of the setup, then restored afterwards.
4.1.1 ODMA Connection Fails Without a Default DMS. When there is no default DMS available for use with an ODMA-aware application, the ODMA Connection Manager will reject the application's ODMRegisterApp request. In this procedure we want that to happen. This procedure confirms that registration is rejected and tests whether the application behaves appropriately in the face of that condition.
4.1.2 ODMA Checks for Application Default DMS First. The ODMA Connection manager will use the ODMA Application ID to check the Windows Registry for an entry with that key under HKEY_LOCAL_MACHINE\Software|Classes. If there is specification of a default ODMA32 DMS under that key, that DMS will be used. For this procedure, there should not be any application default DMS entry. If there is one, it can be temporarily disabled. It can then be restored following the procedure. {tbd: picture of an application default DMS entry and renaming of the key to prevent it being recognized.}
4.1.3 ODMA Checks for a Global Default DMS Next. If there is no specific default DMS for the application, the ODMA Connection manager checks the list of registered ODMA32 DMS integrations under HKEY_CLASSES_ROOT\ODMA32. If there is an entry with a DEFAULT subkey, that DMS will be used. For this procedure, there should not be any global default DMS entry. If there is one, it can be temporarily disabled. It can then be restored following the procedure. {tbd: picture of a global default DMS entry and renaming of the key to prevent it being recognized.}
4.2.1 The ODMA 2.0 Connection Managers will provide a log of all requests received by ODMA. The log includes the name of the request, the parameters of the request, and the results, if any, returned through ODMA back to the requesting application. The production of logs is controlled by registry keys added beneath the HKEY_CLASSES_ROOT\ODMA32.ConnectionManager key (fig. 4-1). Unless logging is already set up, you will need to modify the registry (cf. section 3.2):
|
|
4.2.2 Create Logging key under ODMA32.ConnectionManager. If it is not already present, add the Logging key. No value is required.
4.2.3 Create Enabled sub-key under the Logging key. If it is not already present, add the Enabled sub-key. No value is required. If there is a disabled Enabled key (such as one name Enabled.off), simply rename it back to Enabled.
4.2.4 Create File sub-key under the Logging key. If it is not already present, add the File sub-key. A valid absolute path and file name is required. The file should be in a location that is both writeable and readable under the limited account used to perform this confirmation.
4.2.5 Considerations for Location of Log File. It is important that the directory for the log file be eligible for limited-account use in creating, reading, and deleting log files. It is also useful to choose a location that has no spaces in the full path name.
4.2.6 Other Options for Log File Entries. There is an optional Options sub-key that can be added under the Logging key. The value, if any is a comma-separated list of tokens. The only token that is meaningful for the ODMA 2.0 Connection Manager is NEWLOG. When that token is present in the value of an Options sub-key, any existing log is deleted each time the Connection Manager is loaded and initiated by an application. In all other cases when logging is enabled, new log entries will be appended to any existing ones. It is recommended that there be no options when using this procedure. This will prevent loss of the log in the case that the ODMA Connection Manager is initiated more than once for some reason.
If there is already a log file at the log location, either delete it or rename it. Renaming it, perhaps to include a timestamp in the name, preserves any existing log while making sure there is no log file already present at the start of the application. It is useful to keep the directory that receives logs open so that the creation of the log file can be observed.
Simply start the application to be confirmed. Double click on an icon, select it in Start | All Programs, or take any other action that will initiate the ODMA-aware application.
5.3.1 An ODMA-aware application might not connect to the ODMA Connection Manager until it is clear that a document operation is to be performed. This can be as late as requesting a dialog for opening a file (e.g., a File | Open ... menu selection) or as requesting that a newly-created document be saved (e.g., a File | Save As ... menu selection).
5.3.2 Initiate an operation (e.g., a File/Document Open dialog) of the application where an existing document is to be accessed.
5.4.1 No ODMA-related Dialogs should occur. There should be no offer from any sort of DMS to select a document. There should be no error messages of any kind.
5.4.2 The application should provide its normal, default dialog for accessing a document (e.g., from a location in the Windows file system).
5.4.3 If there are any unusual behaviors, including failure to be offered any dialog at all, make note of that fact.
It is not necessary to perform any useful operations. The dialog that opened, if any, should be closed/cancelled. Then close the application.
6.1.1 If no log is recorded at all, the application is not connecting to the ODMA Connection Manager.
6.1.2 If there is a log file, rename it (e.g., from ODMA32.log to ODMA32-2006-06-17-1827.log or any other name that helps keep test logs organized and associated with related projects and notes.)
If a log has been produced, the application reached the ODMRegisterApp entry point of the ODMA Connection Manager. The log entry should have the following form (159 byte .txt file):
ODMRegisterApp Input parameters: version=100(64) << Version of ODMA API expected by the application lpszAppId=MS Word; << ;-followed ODMA Application ID for the application dwEnvData=458964(700d4) Output parameters: odmHandle=0(0) << No ODMA session handle created (NULL handle returned) Return value=3(3) << ODMSTATUS value ODM_E_NODMS
6.3.1 If no log was produced and there is any doubt whether the ODMA 2.0 Connection Manager is producing a log, repeat this confirmation with an ODMA-aware application (such as Microsoft Word or the ODMA Test application from the ODMA SDK) that is known to connect properly.
6.3.2 If you are unable to produce a log for a known ODMA-aware application, verify that you have the ODMA 2.0 Connection Manager installed. There should be no other ODMA32.dll files, especially in directories along with application software.
7.1.1 If there were any default DMS settings that were disabled as part of the setup (section 4.1), those default settings should now be restored in the registry.
7.1.2 If it is undesirable to continue capturing logs (section 4.2), disable logging by either deleting the Enabled key or renaming it to a different value such as Enabled.off.
If this confirmation procedure succeeds, perform further tests using the existing setup for logging and any test DMS for operation. The test DMS can be setup as an application-specific default, using the ODMA Application ID found in the log that was produced (section 6.2).
7.3.1 If the confirmation procedure fails, any troubleshooting and further analysis will depend on the nature of the application and the support available for it. There is no generic advice that applies.
7.3.2 Sometimes, there is specific information on individual ODMA-aware applications. Consult the notes column of the registry of ODMA-aware applications.
{tbd: Also attributions and acknowledgments - possibly below the line.}
|
You are
navigating the ODMA Interoperability Exchange. |
created 2006-06-14-13:42 -0700 (pdt) by
orcmid |
