IBM Support

How to change the XML Diff/Merge Type Manager

Question & Answer


Question

How do you reconfigure the default IBM Rational ClearCase XML type manager to use a third party application to address UTF8 and other issues when using ClearCase diff merge tools?

Cause

Note: There were enhancements in ClearCase 7.1 that introduced UTF support. Refer to the What's New section of the IBM Rational ClearCase Release Notes under the topic of Unicode Transformation Format (UTF) Support for further information.


Problem #1

When two different versions of an XML file have lines inserted into the same place, attempts to diff or merge to the base contributor results in an add-add conflict. This conflict in turn causes the xmldiffmrg tool to only allow the contributors from the base to be selected. A workaround is to use the text file diff merge (see Problem #2).

Example:



Note: Options 2 and 3 do not set the changes for those contributors. Only Option 1 reflects the selected change.



Note: A similar problem occurs for delete-delete and modify-modify conflicts as well.


Problem #2

The algorithm used by xmldiffmrg is different than the text diff merge (cleardiffmrg). Currently xmldiffmrg parses one file at a time. Parsing the file builds a tree and then uses a bottom-up approach to compare the tree to look for xml differences. The xmldiffmrg does not consider two different versions of the file with lines inserted into the same place (as seen in the example above) as a difference; however the text diff tool will.

Example: Contributor 2 and 3 were selected as the result of using cleardiffmrg.



This work-around is acceptable in most cases, however, problems arise when the XML file uses UTF8 or other unicode types in the file. (See Problem #3.)


Problem #3

Using the text diff/merge tool as a workaround may solve the contributor issue, however, the text diff/merge tool does not work correctly with UTF8 character sets. So if your XML projects/files are configured to use UTF8 (or any type of Uni-Code) the text diff merge tool will not handle these files properly.


With all of these issues, how can you configure ClearCase to successfully diff and merge XML files?

Answer

Change the type manager that is managing your XML file types to use a third party XML Diff and Merge solution. KDiff3 is the XML diff/merge of choice selected in this example.

Note: For additional information about creating and modifying a type manager refer to About the Rational ClearCase Type Manager white paper.










About KDiff3 (http://KDiff3.sourceforge.net/#news)

  • KDiff3 compares and merges two or three text input files or directories
  • KDiff3 shows the differences line by line and character by character
  • KDiff3 provides an automatic merge-facility
  • KDiff3 has an editor for comfortable solving of merge-conflicts
  • KDiff3 supports Unicode, UTF-8 and other file encodings
    • KDiff3 handles UTF8, windows-1251, windows-1252, ISO_8859-15, and some Japanese encodings.
    • Encoding auto detection for Unicode files with byte order mark "BOM" at the file start
  • KDiff3 prints differences
  • KDiff3 provides excellent performance results on large files.



Configuring Native ClearCase to use KDiff3

Note: Implement these instructions on every client that needs to diff and or merge XML files using this method.
  1. Download and install KDiff3 from SourceForge
    (http://sourceforge.net/project/showfiles.php?group_id=58666)

  2. Open the Type Manager map file with a text editor.

    Note: The map file is in the ccase-home-dir/lib/mgrs directory.

    Windows: C:\Program Files\Rational\ClearCase\lib\mgrs

    Review the ClearCase Command Reference Guide on the topic of type_manager (cleartool man type_manager) for more information.

  3. For any type manager that uses xmldiffmrg, replace the xmldiffmrg executable with the path to KDiff3.

    What needs to be changed in the map file?

    merge/compare -- CLI merge/compare
    xcompare/xmerge -- GUI compare/merge

    Example:

    _xml2       compare          ..\..\..\..\KDiff3\KDiff3.exe
    _xml2       xcompare         ..\..\..\..\KDiff3\KDiff3.exe
    _xml2       merge            ..\..\..\..\KDiff3\KDiff3.exe
    _xml2       xmerge           ..\..\..\..\KDiff3\KDiff3.exe

    Note: The mapfile uses a relative path from its current location to find the executable. In this example, KDiff3 was installed to the default directory on Windows (C:\Program Files\KDiff3) thus the relative path defined in the map file reflects as such.

  4. Stop and Restart ClearCase



KDiff3 Version 0.9.92 installation

KDiff3 version 0.9.92 introduced changes in it’s installer that provides an option to turn on ClearCase integration so as to set KDiff3 as the comparison and merge tool for ClearCase.

Here are the steps to select the ClearCase integration option:
  1. Install Kdiff3-0.9.92
  2. During the installation the following options are presented.



  3. Select the “Integrations” component and then ClearCase

    The following ClearCase-related changes will be made automatically during the install:
    • A backup of the ClearCase type manager map file is created in the ClearCase installation directory (by default: C:\Program Files\Rational\ClearCase\lib\mgrs) named map.preKDiff3Install

    • The following lines in the map file are modified to reference the KDiff3 tool:

      • text_file_delta
        text_file_delta
        whole_copy
        whole_copy
        z_text_file_delta
        z_text_file_delta
        z_whole_copy
        z_whole_copy
        _xml
        _xml
        _xml2
        _xml2
        _rftdef
        _rftmap
        _rftvp
        _xtools
      xcompare
      xmerge
      xcompare
      xmerge
      xcompare
      xmerge
      xcompare
      xmerge
      xcompare
      xmerge
      xcompare
      xmerge
      xcompare
      xcompare
      xcompare
      xcompare
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe
      C:\Program Files\KDiff3\kdiff3.exe


      Note:
      For XML merge and compare options it is only necessary to update the xml lines in the map file. If you do not want to use the KDiff3 tool for all the type managers listed above, revert to the backup copy of the map file that was previously created and modify only the _xml2 lines as noted in the previous section. Always keep a backup copy of the original map file.

      The changes to the map file explained above apply to the ClearCase Native clients only. Although the ClearCase Integration option can be selected during a KDiff3 version 0.9.92 install on a CCRC client, there is no local map file to update, thus you should follow the CCRC instructions listed below.



Configuring the ClearCase Remote Client (CCRC) to use KDiff3
  • Change directories to the CCRC installation location > plugins > com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver>

    Where <os> is the name of the operating system bits used and <ccrc ver> is the latest version of the CCRC update applied on the client.

    On Windows
    CCRC 7.1
      Default: C:\Program Files\IBM\IMShared\plugins

    CCRC 7.0 Default: C:\Program Files\IBM\Rational\ClearCase\CCRC\plugins\

    Example:
    com.ibm.rational.clearcase.compare_merge.win32x86_7.0.1.CU02

  • Copy the KDiff3 executable from its installation path to the com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver> directory

  • Rename the ccrc_xmldiffmrg.exe to ccrc_xmldiffmrg_orig.exe

  • Rename KDiff3.exe to ccrc_xmldiffmrg.exe

  • Close and reopen CCRC

Note: Replacing the CCRC diffmerge utility as explained above with KDiff3 version 0.9.92 may result in a KDiff3 usage error. Refer to the known issues section below.



Known Issues

Native ClearCase Issue:

When updating ClearCase (patch, iFix, FixPack), the map file will be overwritten with every client update. As a result, a copy of this file must be maintained outside of the ClearCase directory and replaced after each update.


CCRC Issue:
  • When updating CCRC, the plug-in directory com.ibm.rational.clearcase.compare_merge.<os>_<ccrc ver> will change. The steps above will need to be run again in the new plug-in directory.

    Note: You can control when the updates occur by preventing CCRC from looking for updates automatically. Click Window > Preferences > Install/Update > Automatic Updates and disable automatic updates.



    Once this is done, you can control when to look for, download and install CCRC updates.

    Note: To obtain updates, click Help > Software Updates > Find and Install.
  • Using KDiff3 version 0.9.92 as a CCRC diffmerge tool may cause the following usage error during a compare operation. Dismiss this error by clicking the "Ignore" button which will allow the compare to proceed.

    KDiff3-Usage

    i  Unknown option: -xcompare
    If KDiff3 should ignore this option, run KDiff3 normally and edit
    the "Command line options to ignore" in the "Integration Settings".


    KDiff3-Usage when starting via commandline:
    - Comparing 2 files  kdiff3 file 1 file2
    - Merging 2 files         kdiff3 file 1 file2 -o outputfile
    ....
    If you start without arguments, then a dialog will appear
    where you can select your files via a filebrowser.




  • To eliminate this issue in future merges:
    1. select Settings -> Configure Kdiff3
    2. Move to the integration tab
    3. Add ";-xcompare" to the "Command-line options to ignore" box. The page should look similar to the following:





DISCLAIMER:
All references made to third party applications in this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

After installing and configuring KDiff3 (or 3rd party application of your choice) to work as the type manager for XML files, attempts to diff or merge XML files from native ClearCase or CCRC will result in a clean diff and merge. Results will be as expected.

KDiff3 screen capture:


[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Type Manager","Platform":[{"code":"PF033","label":"Windows"}],"Version":"9.0;8.0.1;8.0;7.1.2;7.1.1;7.1;7.0.1;7.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
29 September 2018

UID

swg21256807