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.