File Name: dmimapper_readme.txt last updated March 28, 2002 Licensed Materials - Property of IBM 09N6996 (C) Copyright IBM Corp. 1999, 2001 All Rights Reserved US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. DMI Support Utility CONTENTS -------- 1.0 Overview 2.0 Change History 3.0 Installation and Setup Instructions 4.0 Limitations and Known Problems 5.0 Unattended Mode 6.0 Web Sites and Support Phone Number 7.0 Trademarks and Notices 8.0 Disclaimer 1.0 Overview ------------- The DMI Support Utility is used to install support for the Desktop Management Interface (DMI). The DMI is a vendor-neutral interface for collecting and manipulating network management information. The Desktop Management Task Force, Inc. (DMTF) develops and maintains DMI specifications. Adding this DMI support option to the IBM Director product provides support for the DMI browser, inventory, resource monitoring, and event management tasks. To provide DMI data, managed systems must be running under Windows ME, Windows 98, Windows 2000, Windows NT 4.0, or Windows XP Professional edition. DMI support must be added after IBM Director 3.1 is installed. When the managed system is restarted, it is enabled for DMI operations. 2.0 Change History -------------------- New with 1.1.16.108: This version fixes a problem setting property values in provider-supplied (vs. WMI database-resident) class instances. The problem was traced to the use of WBEM_FLAG_UPDATE_ONLY in the flag to the IWbemServices::PutInstance method. This flag value was replaced with WBEM_FLAG_CREATE_OR_UPDATE. New with 1.1.16.107: No changes to the mapper binary beyond those necessary to change the version and no changes to mapping definitions. This version fixes a problem with uninstalling the mapper and Service Provider when the target system originally had a mapper/SP installation from pre-WIinstaller technology, and had been updated with a WI-based mapper/SP install. In this scenario, several files, directories, Registry and SCM entries were left behind when the WI-based installation was uninstalled. This version uses an aggressive uninstall method that removes all files and directories up to and including the directory specified by the Win32DmiPath environment variable. New with 1.1.16.106: No changes to the mapper binary beyond those necessary to change the version. This release includes the SmartDMI(tm) Secure Service Provider v2.75, which fixes an issue preventing the SNMP Service on Windows 2000 and XP from shutting down correctly when the SmartDMI(tm) To SNMP Mapper is installed. New with 1.1.16.105: No changes to the mapper binary beyond those necessary to change the version. This version brings all mapped DMTF Groups up to the latest group version, based on the DMTF Master.Mif Version Number : 011008 New with 1.1.16.104: No changes to the mapper binary beyond those necessary to change the version. This version brings the mapped DMTF|Processor|xxx group up to date to use v 015. Earlier mapper versions used v 009, as required by WfM spec. New with 1.1.16.103: No changes to the mapper code beyond those necessary to change the version, and no changes to mapping definitions in this release. This release includes the SmartDMI(tm) Secure Service Provider v2.74. This Service Provider release fixes a buffer overrun problem in the secure RPC communication initialization. New with 1.1.16.102: IBM Defect 14201 has been resolved in this release, by turning off registration for all intrinsic events for CIM_VoltageSensor, per IBM request and agreement. Logging for Intrinsic events has been enhanced to provide the instance path of the object related to the event. New with 1.1.16.101: IBM Defect #8285 has been resolved in this release. The mapper no longer instruments the ComponentID group of any mapped component that was not developed by STEI. New with 1.1.16.100: The mapper now has the capability to count associations between classes and return the count as the DMI value, rather than retrieving a specific CIM property value. 3.0 Installation and Setup Instructions ----------------------------------------- *NOTE: Administrator privilege is required for installation. *NOTE: If you downloaded the DMI Support Utility from the Website substitute the filename setup.exe with dmimapper.exe in this document. 3.1 This is applicable with the following Director component levels: Director Server 3.1 Director Agent 3.1 Director Extensions 3.1 3.2 This applies to the following operating systems: Windows 2000 Professional Windows 2000 Server and Advanced Server Windows NT 4.0 Server and Workstation Windows 98 (including Second Edition) 3.3 Primary Installation Before installation, IBM Director 3.1 must be installed. The WMI core must be installed and operating before this installation package is invoked. To install the SmartCIM(tm) To DMI Mapper with the SmartDMI(tm) Secure Service Provider, run the Setup.exe installation program and follow the instructions on screen. 4.0 Limitations ------------------------------- 4.1 Known issues - Windows 98 systems with a msiexec.exe version earlier than 1.20 must install version 1.20 before the dmimapper.exe can be installed. The version 1.20 of the Windows Installer service can be found on Microsoft's site or by extracting the dmimapper.exe to temporary location and launching the instmsia.exe in the mapper\files folder. - Log strings are currently stored in a DLL, but in a form that does not readily support translation. These log strings have been analyzed, and do not provide any meaningful end-user information. These strings should not be translated. - (Ref #948) On rare occasions, an exception may be thrown if WMI or the DMI Service Provider is stopped before the mapper is stopped. No pattern to these exceptions has been detected. Logic has been included in to avoid this situation. Since this logic was added, the exceptions have not been observed. - (Ref #959) On Windows 95, a defect in DCOM95 prevents the system from shutting down cleanly if the mapper is active. To avoid this problem, install DCOM for Windows 95, version 1.2 or later, available from Microsoft. - (Ref #959) On Windows 98, a defect in DCOM prevents the system from shutting down cleanly if the mapper is active. To avoid this problem install Windows 98 Second Edition or later, available from Microsoft. - (Ref #976) When using the mapper with the WBEM SDK v1.0 (Build 525) and accessing data provided by the Win32 Provider, exceptions have been observed when shutting the mapper down. This behavior has not been observed when using WMI Build 520, or when accessing data that is not provided by the Win32 Provider. No evidence has been obtained to date that indicates this is a mapper problem. - (Ref #917) When running the mapper under Windows 98, the Discovery phase of operation for a given data set has been observed to be longer in general than when running under Windows 95 or Windows NT. - When running the mapper under the version of WMI distributed with Windows NT 5.0 Beta 2 (Build 575), the WMI GetObject function sometimes fails to return. This has been observed both at Discovery time and during normal Get/Set operations. No evidence has been obtained to date that indicates this is a mapper problem. - When running the mapper under Windows 95 or Windows 98, inconsistencies in system responses have been observed. These inconsistencies manifest primarily as apparent system 'hangs', or failure to respond to keyboard or mouse commands. This behavior has also been observed on test systems that are not executing the mapper. No firm identification of the source of this behavior had been made at the time this document was published. 4.2 Behavioral Considerations - (Ref #780) The mapper does not allow SETs to WMI key properties. Therefore, even if a DMI Attribute that is mapped to a WMI key property has Read-Write access, SETs to this attribute will return a DMIERR_ILLEGAL_TO_SET error. - (Ref #783) DMI Octet Strings are not translated in any way by the mapper, either for ISO/Unicode or language. Therefore, WMI strings that are mapped to DMI Octet Strings may have an apparent extra byte for each character. This may be demonstrated by creating a WMI string value and initializing it in a MOF file. Then map this string to a DMI Octet String and view the result with DCTS. - (Ref #799) The mapper supports most cross-data type mappings; for instance mapping a signed 16-bit WMI value to an unsigned DMI 32-bit value. The following cross-data type mappings are NOT supported: WMI DATETIME <===> Any DMI data type except DATE WMI Bool <===> Any DMI data type except Integer DMI OctetString <===> Any WMI data type except BSTR - (Ref #824) The mapper does not allow SETs to DMI Attributes that are Borrowed or Manufactured. - (Ref #897) The mapper does not track WMI Class modification events. If a Group View class is modified and recompiled while the mapper is running, the new mapping information will not take effect until the next time the mapper is started. - (Ref #900,901,902) DMI does not allow multiple rows in a single table to be identified with the same key list values. Given the nature of mapping data from a CIM style schema to DMI, it is possible that this 'non unique' row situation may occur. The mapper includes logic to alleviate this situation, in particular, the mapper ensures that a DMI MA will not encounter an apparently infinite table while performing a table walk using the DmiGetMultiple command. However, it is possible for random row accesses to be directed to a row different than the one actually intended. In most cases, the first row in the table with the appropriate keylist is the one accessed. Avoid duplicate keylists for DMI rows whenever possible. The ManufactureDmiKey qualifier can assist this. - (Ref #941) In order to maximize throughput, the mapper stores DMI Keylist values in an internal database. If a DmiSetAttribute to a DMI key is followed immediately by a DmiGetAttribute to the same key, it is possible the old value will be returned. This is due to WMI modification event latency. Waiting a few tens of milliseconds after the SET to perform the GET should suffice to ensure that the modification event has been received and processed. - (Ref #905) When mapping data from multiple WMI source classes into a single DMI group, all instances of the WMI classes must be associated appropriately. For all such associations in all namespaces, the mapper requires the Associator class to be derived from the CIM_Dependency class. - (Ref #954) All numeric DMI data types are integers of one form or another. All UnitTranslation qualifier expressions are truncated, not rounded, during division. - (Ref #950) When operating under stress, that is, many requests for data in a short amount of time, including simultaneously, WMI sometimes returns a generic error when attempting to get a property value. The mapper returns a 'Value Unknown' status code to the DMI Service Provider in this case. This situation is beyond the control of the mapper. Slowing the rate of requests and retrying will generally result in successful operations. - (Ref #951) When a DMI Group is constructed from two or more WMI source classes, the mapper watches for creation of instances of the PrimarySourceClass and instances of associations between the source classes, and deletion of instances of source classes (not associations). For such groups, if an instance of a source class is deleted, the corresponding row in the DMI group is removed. Then if the source class instance is re-created with no changes to associations, the row will not be re-mapped until the mapper restarts. If the association is re-created, the row is mapped immediately. - (Ref #955) Target data overflow detection, when using the UnitTranslation qualifier, is limited to checks of the final bit count. Therefore, for example, if a translation calculation results in a value that is 32 bits all 1, the value is interpreted as a very large Counter32, or a negative 1 Integer32. It is the responsibility of the implementor to verify that UnitTranslation expressions are valid in all cases. - (Ref #957) UnitTranslation expressions may include data from other classes than the target class. However, all classes used must reside in the same namespace as the target class (the class specified in the ViewSource qualifier). - (Ref #966) WMI classes used in UnitTranslation expressions but not in ViewSource qualifier values are not watched for any form of WMI event. - (Ref #973) DMI requires that accesses to instrumentation for any given single component be serialized by the DMI Service Provider. The mapper enforces another level of serialization because it is a single piece of instrumentation that may be servicing multiple DMI components. It is therefore possible for multiple requests to be submitted to the mapper simultaneously. To prevent system race conditions, if a particular request takes a long time to service (this is determined by the WMI instrumentation), a request that is waiting will time out after a few seconds and return an error code to the Service Provider. The SP in turn returns this error to the Management Application. MAs that receive this error should retry the request until it succeeds, or another, fatal error code is returned. 5.0 Unattended Mode -------------------- The user can extract the files and launch the ibmsetup.exe in the mapper folder with the "-s" parameter. 6.0 WEB Sites and Support Phone Number --------------------------------------- 6.1 IBM Support Web Site: http://www.pc.ibm.com/support 6.2 IBM Netfinity Systems Management Web Site: http://www.pc.ibm.com/ww/netfinity/systems_management/index.html 6.3 IBM Enterprise Support page for electronic support: http://www.pc.ibm.com/ww/solutions/enterprise/support/index.html 6.4 IBM Marketing Netfinity Web Site: http://www.pc.ibm.com/netfinity 6.5 If you have any questions about this update, or problems applying the update go to the following Help Center World Telephone Numbers URL: http://www.pc.ibm.com/qtechinfo/YAST-3P2QLY.html. 7.0 Trademarks and Notices ---------------------------- 7.1 The following terms and product names are trademarks of the IBM Corporation or Tivoli Systemsin the United States or other countries or both: AIX, IBM, Netfinity, Netfinity Director, Universal Manageability Services, Tivoli IT Director, and Tivoli Management Environment. Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation. SCO UnixWare 7 (c) Copyright of Santa Cruz Operation. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited. Java and Hot Java are trademarks of Sun Microsystems, Inc. SmartCIM(tm) is a trademark of Smart Technology Enablers, Inc. Other company, product, and service names may be trademarks or service marks of others. All other brand or product names are trademarks or registered trademarks of their respective holders. 8.0 Disclaimer ---------------- 8.1 THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS. 8.2 Note to Government Users Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.