Integration Guide for IBM Rational Rhapsody and IBM Rational ClearCase on Windows

IBM® Rational® Rhapsody provides a model-driven development (MDD) environment for real-time or embedded systems engineering and software development. IBM® Rational® ClearCase is the industry-leading solution for highly sophisticated software configuration management. The scope of this tutorial is to enable IBM Rational Rhapsody users to set-up, configure, and use the IBM Rational Rhapsody - IBM Rational ClearCase integration.

Patrick Schneider (pschneider@de.ibm.com), Certified IT Specialist, IBM Deutschland GmbH

Photo of Patrick SchneiderDr. Patrick Schneider is a Certified IT Specialist at IBM. He brings with him over 14 years of experience in Software Change and Release Management. Patrick joined IBM in 2003 with the acquisition of Rational Software. He gained experience in many different projects throughout different industries as consultant and trainer. He mainly supports customers in their use of the Rational Change and Release Management processes and products, such as Rational Team Concert, Rational ClearCase, Rational ClearQuest and Rational Build Forge.



Patrick Weber (patrick.weber@de.ibm.com), IT Specialist, IBM Deutschland GmbH

Photo of Patrick WeberPatrick Weber is an IT Specialist at IBM. He has more than 11 years of experience in developing embedded systems especially in the automotive domain where he was working as a developer, system integrator and architect. Patrick joined IBM in 2008 with the acquisition of Telelogic. Today he works as a technical sales representative and trainer supporting customers to integrate the model driven development solutions Rational Rhapsody in their existing landscape.



Martin Stockl (martin.stockl@de.ibm.com), IT Specialist, IBM Deutschland GmbH

Photo of Martin StocklMartin Stockl is an IT Specialist at IBM. He has more than twenty years of experience in the area of embedded real-time software development and ten years of experience in the area of model driven development based on UML. Martin joined IBM in 2008 with the acquisition of Telelogic. He works as a consultant and trainer and is experienced in supporting customers with the integration of MDD with Rhapsody into their existing environment including requirements management tools, configuration management tools, compiler, real-time operating systems and debugger.



31 August 2010

Also available in Chinese

Overview

Scope

The scope of this integration guide is to enable IBM Rational Rhapsody users to set-up, configure and use the IBM Rational Rhapsody - IBM Rational ClearCase integration. It provides detailed information about the configuration properties inside Rhapsody including sample property files. This guide also describes the creation and usage of a new IBM Rational ClearCase element type together with its type manager. The two available integration modes are presented and a sample usage scenario is shown.

The reader should be familiar with IBM Rational Rhapsody and should have basic knowledge of IBM Rational ClearCase.

Introduction

The IBM Rational Rhapsody solution is a model-driven development (MDD) environment for real-time or embedded systems engineering, software development and testing, based on UML and SysML. The Rational Rhapsody solution enables embedded systems engineers and software developers to improve productivity, quality and communication by

  • abstracting complex designs graphically, by automating the software development process and assisting in finding defects early through continual testing — to aid in reducing costs.
  • automating the software development process and assisting in finding defects early through continual testing — to aid in reducing costs.
  • assisting in finding defects early through continual testing — to aid in reducing costs.

IBM Rational ClearCase offers complete software configuration management. An industry-leading solution that provides sophisticated version control, workspace management, parallel development support and build auditing to improve productivity.

  • Light-weight feature-rich clients allow you to work locally or remotely
  • Flexible out-of-the-box usage model based on proven best practices increases team productivity and efficiency
  • Wide-range of supported environments and cross-platform support connects diverse teams
  • Transparent real-time access to files and directories virtually anywhere in your organization
  • Scales to any size team from small workgroups to distributed enterprise teams to support evolving organizational needs
  • Integration with leading IDEs allows you to work in your preferred environment
  • Sophisticated branching and graphical merge tools enable concurrent access to files and efficient use of time

The combination of IBM Rational Rhapsody and IBM Rational ClearCase offers a powerful solution of model driven development in a collaborative development environment. It enables collaborative editing and sharing of data (models) within or between teams from simple to complex environments, such as geographically distributed teams. The models are kept in a secure repository (VOB) which offers history, traceability, roll-back, metadata and many more advantages. For the end user the integration represents a minimal overhead since the functionality is provided directly in the Rhapsody user interface.


Configuration items and integration types

ClearCase Basics

Versioned Object Base (VOB)

A VOB is a permanent, read-only data repository. It stores anything that can be represented as a file or a directory and also ClearCase specific data such as labels, branches, etc.

Files and directories in ClearCase VOBs are called elements. An element consists of a set of versions, organized into a version tree. Each version represents one revision of a file under source control.

ClearCase View (config spec)

A ClearCase view is a workspace that provides users access to versions of elements in VOBs. It enables users to work in parallel. A view's configuration specification (config spec) is a filter mechanism (a set of ordered rules) used to select at most one version of each element. It determines which version of each element is visible in the view. All started views are by default visible under the 'M:\' drive. A view can be mapped to any other available drive.

The default config spec, which is for simple serial development, looks as follows:

element * CHECKEDOUT
element * /main/LATEST

ClearCase branches

Branches enable parallel development. They allow different projects and/or users to use the same sources at the same time. In a parallel development environment, you will most likely work on element branches other than /main. The view config spec needs to be changed to select the correct branches and versions.

A sample config spec for working on a different branch than main:

element * CHECKEDOUT
element * /main/mybranch/LATEST

Rhapsody Basics

A Rhapsody Unit is a file system representation of modeling elements such as projects, packages, use case diagrams, object model diagrams, components, etc.

Each unit has a specific extension depending on its type:

Table 1. Unit types and corresponding file extension
TypeFile Extension
Project .rpy
Packages / profiles .sbs
Object model diagrams .omd
Structure diagrams .std
Sequence diagrams .msc
Components .cmp
Use case diagrams .ucd
Classes, actors & use cases .cls
Collaboration diagrams .clb
Component diagrams .ctd
Deployment diagrams .dpd
Panel diagrams .pld
Controlled files any extension

By default components, controlled files, profiles, and packages are units whereas diagrams, classes, actors and use cases are no units. It is possible to convert diagrams, classes, etc. into units so that these elements are represented on the file system in separate files. Those newly created units can then be added to source control.

In Rhapsody you can create units as follows:

Go to the Rhapsody browser, right-click on the model element and select 'Create Unit'.

Figure 1. Rhapsody Units
Check box and detail listing

Each Rhapsody unit corresponds to a ClearCase element. If parallel work on the model elements in such a package (unit file / ClearCase element) is required, following steps can be taken:

  • Increase the unit granularity by either reorganizing the model elements of a package into smaller sub-packages or by creating unit files for some of the model elements (e.g. classes). This approach will increase the number of ClearCase elements, while decreasing their individual size. Checking in or out a whole package with all nested model elements (descendants) can take more time for big models.
  • Keep the Rhapsody model organization as is and create a branch for the corresponding element in ClearCase. This leads to parallel access to multiple versions of the same model element(s). This approach will increase the number of versions and branches of the model element. It requires a Diff/Merge session after the changes to the parallel branches have been completed. The resulting additional version contains the changes of all involved branches

In practice you may use a combination of those two approaches depending on your business needs.

Batch mode versus SCC mode

Rational Rhapsody supports CM tools, including Rational ClearCase, in either of two main modes - Batch and SCC.

Remark: Batch Mode is available on Windows and Linux whereas SCC mode is available on Windows only.

Batch mode is the traditional method of interacting with CM tools that do not conform to the SCC standard. In this mode, Rational Rhapsody has a custom set of properties for each tool that launches tool-specific commands for the CM operations.

SCC mode is an alternative method of interacting with CM tools that conform to the SCC standard. In SCC mode, one set of properties can be enough to interface with dozens of SCC-compliant CM tools, without further customization. You interact directly with the GUI elements for the CM tool to perform SCC-supported operations. Return status information, or error information in the case of failure, comes directly from the CM tool. In this way, you have more direct CM tool interaction and receive more meaningful feedback on CM operations.

Each of those integration modes has advantages and disadvantages. To help you decide which mode might be best for your situation, this integration guide provides you with information about these differences. It also shows you how to configure the different modes along with a wide range of properties for each mode. In order to decide whether you should use batch mode or SCC mode, see [1].

Remark: If you want to use Rational ClearCase UCM (Unified Change Management) then SCC mode is the preferred option. However, you can still use UCM in batch mode on Linux and Windows if you set the so called UCM activities directly within ClearCase.


Configuring the integration

Configuring Rational ClearCase for Windows

This section describes how ClearCase should be configured to smoothly integrate with Rhapsody. We are going to use a so called ClearCase type manager in association with a new ClearCase element type (e.g. rhp_file). This offers the advantage that the Rational Rhapsody DiffMerge tool can be launched directly from the Rational ClearCase version tree tool. This makes it easy to merge a unit from one branch to another and draw the hyperlink arrow as a single operation.

Case sensitivity

Make sure ClearCase MVFS (MultiVersionFileSystem) is set to case insensitive and case preserving.

  1. Open the 'HomeBase' under 'Start->Programs->IBM Rational ClearCase'.
  2. Select the 'Administration' tab and click on the 'Control Panel'.
Figure 2. ClearCase Home Base
Control Panel
  1. Select the 'MVFS' tab and make sure that the 'Case Insensitive MVFS' and 'Case Preserving' options are checked. Please keep in mind that after changing these settings you have to reboot your machine!
Figure 3: ClearCase MVFS Properties
Check boxes and detail listing

Remark: Rational Rhapsody does not support Rational ClearCase snapshot views.

Create a new Type Manager

Open the map file located in the mgrs directory (e.g. C:\Program Files\ibm\RationalSDLC\ClearCase\lib\mgrs) and add the following to the end of the file:

Listing 1: Map File
_rhp    construct_version           ..\..\bin\tfdmgr.exe
_rhp    create_branch               ..\..\bin\tfdmgr.exe
_rhp    create_element              ..\..\bin\tfdmgr.exe
_rhp    create_version              ..\..\bin\tfdmgr.exe
_rhp    delete_branches_versions    ..\..\bin\tfdmgr.exe
_rhp    compare    HKEY_LOCAL_MACHINE\SOFTWARE\Telelogic\Rhapsody\DiffMerge\Install Path
_rhp    xcompare   HKEY_LOCAL_MACHINE\SOFTWARE\Telelogic\Rhapsody\DiffMerge\Install Path
_rhp    merge      HKEY_LOCAL_MACHINE\SOFTWARE\Telelogic\Rhapsody\DiffMerge\Install Path
_rhp    xmerge     HKEY_LOCAL_MACHINE\SOFTWARE\Telelogic\Rhapsody\DiffMerge\Install Path
_rhp    annotate                    ..\..\bin\tfdmgr.exe
_rhp    get_cont_info               ..\..\bin\tfdmgr.exe

Create a new Magic file

Create a new magic file called 'cc.magic' in the ClearCase magic directory (e.g. C:\Program Files\ibm\RationalSDLC\ClearCase\config\magic) with the following content:

Listing 2: Magic File
# Rhapsody file types
rhp_file : -name "*.rpy";
rhp_file : -name "*.sbs";
rhp_file : -name "*.cls";
rhp_file : -name "*.omd";
rhp_file : -name "*.cmp";
rhp_file : -name "*.ctd";
rhp_file : -name "*.clb";
rhp_file : -name "*.ucd";
rhp_file : -name "*.msc";
rhp_file : -name "*.std";
rhp_file : -name "*.dpd";
rhp_file : -name "*.fil";
rhp_file : -name "*.fol";
rhp_file : -name "*.pld";

Create a new element type

  1. Open the 'Home Base' under 'Start->Programs->IBM Rational ClearCase'.
  2. Select the 'VOBs' tab and click on 'Type Explorer'.
Figure 4. Open ClearCase Type Explorer
Explorer with action buttons
  1. Select the appropriate VOB (here 'rhpdemo') and click 'OK'.
Figure 5. Select ClearCase VOB
List
  1. Open the 'element type' explorer.
Figure 6. Element Type Explorer
Type listing
  1. Right-click inside the 'element type' explorer and select 'Create'.
Figure 7. Element Types
Context menu
  1. Enter a name and a description to the new 'element type' and click 'OK'.
Figure 8. Create new Element Type
Type Details
  1. Select the tab 'Type Manager'.
  2. Select the 'Supertype' text_file.
  3. Check the property 'Override type manager' and enter as type '_rhp'.
  4. Click 'OK'.
Figure 9. Element Supertype
Type manager details and checkboxes
  1. Inside the 'element type' you will now have a new type called 'rhp_file'.
Figure 10. New Rhapsody Element Type
Type overview

Configuring Rhapsody on Windows

Rhapsody properties allow customization of the integration to ClearCase. Those properties are discussed in detail in chapter "Batch mode" and "SCC mode". Either you set those properties in the Rhapsody project or you load them using a property files. We provide sample property files for each integration mode (see chapter "Setup files for user installations"). In the first case the properties are only valid within the concerned project whereas in the second case the properties are loaded when starting Rhapsody and valid for all projects.

Batch mode

  1. Make sure that the VOB is mounted.
  2. Open your 'ClearCase Explorer'.
Figure 11. Open ClearCase Explorer
Start menu
  1. If the VOB is not mounted, right-click on the view, clickon 'Mount VOB's…
  2. elect the appropriate VOB and click on 'Mount'.
Figure 12. Mount VOB
List and checkbox
  1. Create a new project in the view/VOB
Figure 13. Create New Rhapsody Project
Folder explorer
  1. Add the project root directory to source control
    1. Open 'ClearCase Explorer', right-click the project root directory and select 'Add to Source Control …'
Figure 14. Add to Source Control
Context menu

Note:
Add only the project root directory to source code control. All other relevant files and directories (Rhapsody units) will be handled directly by Rhapsody.

  1. Enter a comment, set checkmark to 'Checkout after adding to source control' and hit 'OK'.
Figure 15. Enter Comment
Checkboxes and comment
  1. Setting properties inside the Rhapsody project. You don't need to perform those steps if you choose to load the included property files. Nevertheless you get an explanation of each used property in the following.

    Note:Changing the model structure within Rhapsody has consequences on CM system level. In order to make Rhapsody users aware of such consequences, we chose for several properties the value 'UserConfirmation'. We expect the user to accept/confirm by selecting 'Yes' in the dialog windows. Selecting 'No' can lead to inconsistencies which must be resolved manually. An alternate solution would be selecting 'Automatic' and let Rhapsody trigger the required CM commands.

The following screenshot represents some of the properties to be modified. Even though the properties displayed are marked as overwritten they represent the default values. It is not intended to be used as reference but simply for illustration purpose.

Figure 16. Rhapsody Configuration Management Properties
Project properties list

The following list shows all properties with changed values:

  • PathInProjectList -> Relative

    When a project is added to a project list, the path to the project is added to the project list file (.rpl). The property PathInProjectList can be used to specify whether an absolute or relative path should be used when the project is added to a project list. The possible values for the property are 'Absolute' and 'Relative'. In order to be independent from a ClearCase view set this property to 'Relative'.

  • ReferenceUnitPath -> Relative

    The ReferenceUnitPath property defines how to save a reference unit path. The property can be set to 'Absolute' or 'Relative' to specify whether units that are added to the model by reference to use an absolute path or by the relative path. If the property is set to 'Relative', then newly added referenced units contain a path relative to the project directory. In order to be independent from a ClearCase view set this property to 'Relative'.

  • AddMember -> $OMROOT/etc/Executer.exe" "cleartool checkout -reserved -nc \"$UnitDirPath\" ; cleartool mkelem -nc \"$UnitPath\" ; cleartool checkin -nc \"$UnitDirPath\"

    The AddMember property specifies the command used to add an item to the archive.

    In this case, the argument to the command to run the Executer ($OMROOT/etc/Executer.exe) consists of a list of three executable commands:

    cleartool checkout -reserved -nc $rhpdirectory
    cleartool mkelem -nc $unit
    cleartool checkin -nc $rhpdirectory
    • The first command, cleartool checkout -reserved -nc, is defined within ClearCase to check out an item.
    • The second command, cleartool mkelem -nc $unit, creates an element corresponding to the specifications inside the .magic file (see chapter "Configuring Rational ClearCase for Windows") and assigns this element to the variable $unit, which represents the unit of collaboration. This is the only command which needs to be changed.
    • The third command, cleartool checkin -nc $rhpdirectory, checks the unit in the _rpy directory into the archive.
  • AddMember_WithoutCheckOutCheckInDirectory -> cleartool mkelem -nc "$UnitPath"

    This property allows an item to be added to the archive without having to check out the parent directory and check it back in after the item has been added. The use of this property allows you to check out and check in the parent directory separately. The element gets created taking into account the specification of the .magic file (see chapter "Configuring Rational ClearCase for Windows").

  • AddToArchiveAfterCreateUnitActivation -> UserConfirmation

    When you create an element in a Rhapsody project that is not a unit by default (an actor, or class, for example), you can opt to create a unit from that element. When you do so, and this property is enabled, the new unit is automatically added as a unit in ClearCase.

    The possible values are as follows:

    • Disabled - No units are archived
    • UserConfirmation - prompts the user for confirmation before archiving the unit.
    • Automatic - automatically archives the unit without asking the user.
  • CheckIn -> $OMROOT/etc/ SensitiveCheckin.bat $UnitPath $log

    The CheckIn property specifies the command used to check an item into the archive using the main Configuration Items window.

    By default, ClearCase does not allow you to check in an unmodified version of an item. Rhapsody includes a script, SensitiveCheckin.bat, that checks whether a checked-out version of an item is different from the previous version, and then performs the checkin. If the item has not been changed, the script automatically performs an 'uncheckout' operation for that item.

  • DeleteActivation -> UserConfirmation

    The DeleteActivation property is a Boolean value that specifies whether deletion of units from the Rational Rhapsody model will trigger a delete command in the archive.

    The possible values are as follows:

    • Disable - Disable the trigger.
    • UserConfirmation - Prompt the user for confirmation before performing the deletion.
    • Automatic - Automatically trigger the delete command in the archive when a unit is deleted in Rational Rhapsody.
  • MoveActivation -> UserConfirmation

    The MoveActivation property is a Boolean value that specifies whether moving units in the Rational Rhapsody model (in a way that changes the unit file location) will trigger a rename command in the archive.

    The possible values are as follows:

    • Disable - Disable this functionality.
    • UserConfirmation - Prompt the user for confirmation before renaming the elements in the archive.
    • Automatic - Automatically rename elements whenever units are moved in the Rational Rhapsody model.
  • RenameActivation -> UserConfirmation

    The RenameActivation property is a Boolean value that specifies whether renaming units in the Rational Rhapsody model triggers a rename command in the archive.

    The possible values are as follows:

    • Disable - Disable the Rename functionality.
    • UserConfirmation - Prompt the user for confirmation before renaming the elements from the archive.
    • Automatic - Automatically rename the element units that are renamed in the Rational Rhapsody model.
  • StoreInSeparateDirectoryActivation -> UserConfirmation

    The StoreInSeparateDirectoryActivation property affects how an existing package is converted. The following conditions apply with this property:

    • Enable this property by selecting UserConfirmation or Automatic from the drop-down list.
      Resulting behaviour with Automatic or when selecting 'Yes' in user confirmation dialog:
      • When an existing flat package is converted to a package as a directory, the directory is created on the configuration management side and the children of this package are moved to this directory.
      • When an existing package as a directory is converted to a flat package, the directory is removed on the configuration management side and the children of this package are removed as well.
      Disable this property by selecting Disable.
      Resulting behaviour with Disable or when selecting 'No' in user confirmation dialog:
      • When an existing flat package is converted to a package as a directory inside of Rhapsody, the directory is not created on the configuration management side and the children of this package are not moved to this directory.
      • When an existing package as a directory is converted to a flat package inside of Rhapsody, the directory is not removed on the configuration management side and the children of this package are not removed.
      • In both cases the logical structure will not correspond to the file system structure in ClearCase. This inconsistency must be resolved manually.
  • CMTool -> ClearCase

    The CMTool property specifies which configuration management tool you are using. Valid properties for each CM tool are predefined in metaclasses of the same name. When evaluating property strings that reference other properties, Rational Rhapsody looks only within the same metaclass.

  • General:DefaultLockReserveOnCheckOut -> Checked

    The property DefaultLockReserveOnCheckOut provides a default lock or reserved value during a Checkout operation in Batchmode. Checking this box means that whenever a checkout operation is performed it is locked or reserved.

  • General:Model:AutoSynchronize -> Checked

    The AutoSynchronize property is a Boolean value that determines whether Rational Rhapsody will run synchronization.When this property is Checked, each time Rhapsody gets the focus Rational Rhapsody will run the synchronize functionality. The started synchronize can be a synchronization with the files on the file system, view, or CM archive depending on the environment.

  • ConfigurationManagement:ClearCase:CheckOut -> cleartool checkout -nc $mode $LabelPart

    The CheckOut property specifies the command used to check an item out of the archive using the main Configuration Items dialog. This command references the LabelPart property and the $mode.

  • ConfigurationManagement:ClearCase:LabelPart -> ( $label ? -version "$UnitPath@@\$label" : "$UnitPath")

    The LabelPart property specifies how to embed a revision label. This expression uses the (Exp1 ? Exp2 : Exp3) construct. If you entered a label in the Revision/Label field in the Check In or Check Out window, $label is True and LabelPart evaluates to -version "$UnitPath@@\$label", where $UnitPath and $label are replaced by their respective values. Otherwise, $label is False and LabelPart evaluates to $UnitPath.

  • ConfigurationManagement:General:UseUnitTimeStamps -> Checked

    The UseUnitTimeStamps property allows the user to determine whether or not to use unit time stamps.

  • General:Model:DefaultDirectoryScheme -> PackageAsDirectory

    The DefaultDirectoryScheme property is used by the hierarchical repository functionality. This property is available only at the project level, but activates or deactivates the Save in Subdirectory check box on the Unit Information for Package window. The possible values are as follows:

    • Flat - All units are stored in the project _rpy directory
    • PackageAsDirectory - New packages (and their descendants) are nested in a separate directory, no more than one level below the parent. The package subdirectory has the same name as the package it contains.
  • ConfigurationManagement:ClearCase:MakeCMShadowDirActivation -> UserConfirmation

    The MakeCMShadowDirActivation property controls whether new directories created by a save in Rational Rhapsody are elements in ClearCase. The possible values are as follows:

    • Disable - Disable this functionality.
    • UserConfirmation - Prompt the user for confirmation before creating the elements.
    • Automatic - Automatically create elements whenever new directories are created by a save in Rational Rhapsody.

    If you set this property to Automatic, every new package that is added to archive will create a new CM directory, including branches.

Connect to archive

The 'Connect to Archive' operation connects the project in your workspace to a CM archive. In addition, it permanently sets properties associated with the archive to be referenced internally whenever the project needs to communicate with the CM tool. You need to perform this operation only once for the lifetime of the project. A connect operation also triggers actions that should be performed before any other CM
operation.

  1. Select 'File -> Configuration Items…' in order to open the following dialog window and select 'Connect to Archive':
Figure 17. Rhapsody Connect to Archive
Menu and list
  1. Hit'OK'.
Figure 18. Confirm Connection
Confirmation

This will save the content of the project subdirectory into a newly created subdirectory with extension '.orig' and create an empty directory element with the original name of the project subdirectory.

Note:If you receive an error message like 'cleartool: Error: Can't modify directory "M:\rhpdemo_view\rhpdemo\root\SampleProject" because it is not checked out.', then do the following:

  1. Rename the projects subdirectory with '.orig' extension to its initial name, e.g. 'SampleProject_rpy.orig' to 'SampleProject_rpy'.
  2. Checkout the project root directory with help of ClearCase or Windows Explorer.
  3. In order to now add the Rhapsody unit files to ClearCase, change the view in 'Configuration Items' window to hierarchical, select the top-level element and hit 'Add to Archive'.
Figure 19. Add to Archive
Menu and list
  1. Select 'Yes' when asked to add descendants.
Figure 20. Add Descendants to Archive
Confirmation
  1. You can verify in ClearCase which items have been added to source control. The green checkmark indicates that the elements are checked out (writeable):
Figure 21. Verification of Files added to Source Control
Folder explorer

Note:
Files which are not relevant to maintain the model content are kept as 'View-private File' in the user's workspace and must not be added to source control.

SCC mode

  1. Make sure that the VOB is mounted.
    1. Open your 'ClearCase Explorer'.
Figure 22. Open ClearCase Explorer
Start menu
  1. If VOB is not mounted, right-click on the view, click on 'Mount VOB…', select the appropriate VOB and click on 'Mount':
Figure 23. Mount VOB
List and checkbox
  1. Create a new project in the view/VOB
Figure 24. Create New Rhapsody Project
Folder explorer
  1. Add the project root directory to source control.
    1. Open ClearCase Explorer, right-click the project root directory and select 'Add to Source Control …'
Figure 25. Add to Source Control
Context menu

Note:
Add only the project root directory to source code control. All other relevant files and directories (Rhapsody units) will be handled directly by Rhapsody.

  1. Enter a comment and hit 'OK' (do not select the 'Checkout after adding to source control' option).
Figure 26. Enter Comment
Checkboxes and comment

Setting properties in Rhapsody

Note:
Changing the model structure within Rhapsody has consequences on CM system level. In order to make Rhapsody users aware of such consequences, we chose for several properties the value 'UserConfirmation'. We expect the user to accept/confirm by selecting 'Yes' in the dialog windows. Selecting 'No' can lead to inconsistencies which must be resolved manually.An alternate solution would be selecting 'Automatic' and let Rhapsody trigger the required CM commands.

The following screenshot represents some of the properties to be modified. Even though the properties displayed are marked as overwritten they represent the default values. It is not intended to be used as reference but simply for illustration purpose.

Figure 27. Rhapsody Configuration Management Properties
Project properties list

The following list shows all properties with changed values:

  • PathInProjectList -> Relative

    When a project is added to a project list, the path to the project is added to the project list file (.rpl). The property PathInProjectList can be used to specify whether an absolute or relative path should be used when the project is added to a project list. The possible values for the property are 'Absolute' and 'Relative'. In order to be independent from a ClearCase view set this property to 'Relative'.

  • ReferenceUnitPath -> Relative

    The ReferenceUnitPath property defines how to save a reference unit path. The property can be set to 'Absolute' or 'Relative' to specify whether units that are added to the model by reference to use an absolute path or by the relative path. If the property is set to 'Relative', then newly added referenced units contain a path relative to the project directory. In order to be independent from a ClearCase view set this property to 'Relative'.

  • DefaultLockReserveOnCheckOut -> Checked

    The property DefaultLockReserveOnCheckOut provides a default lock or reserved value during a Checkout operation in Batchmode. Checking this box means that whenever a checkout operation is performed it is locked or reserved.

  • UseSCCtool -> Yes

    The UseSCCtool property specifies whether the standard SCC interface between Rhapsody and your CM tool is used. Note that when you use the SCC interface, all of the batch mode command properties are unused.

  • AuxProjPath

    The AuxProjPath property is a string that identifies the SCC provider, in this case ClearCase. Do not change this property. Removing the property value will disconnect the link between the Rational Rhapsody project and the SCC project.

    If you remove this value, you must also remove the ProjName property.

  • DeleteActivation -> UserConfirmation

    The DeleteActivation property is a Boolean value that specifies whether deletion of units from the Rational Rhapsody model will trigger a delete command in the archive.

    The possible values are as follows:

    • Disable - Disable the trigger.
    • UserConfirmation - Prompt the user for confirmation before performing the deletion.
    • Automatic - Automatically trigger the delete command in the archive when a unit is deleted in Rational Rhapsody.
  • MoveActivation -> UserConfirmation

    The MoveActivation property is a Boolean value that specifies whether moving units in the Rational Rhapsody model (in a way that changes the unit file location) will trigger a rename command in the archive.

    The possible values are as follows:

    • Disable - Disable this functionality.
    • UserConfirmation - Prompt the user for confirmation before renaming the elements in the archive.
    • Automatic - Automatically rename elements whenever units are moved in the Rational Rhapsody model.
  • ProjName

    The ProjName property is a string that identifies the SCC project name, in this case ClearCase. Do not change this property. Removing the property value will disconnect the link between the Rational Rhapsody project and the SCC project.

    If you remove this value, you must also remove the AuxProjPath property.

  • RenameActivation -> UserConfirmation

    The RenameActivation property is a Boolean value that specifies whether renaming units in the Rational Rhapsody model will trigger a rename command in the archive.

    The possible values are as follows:

    • Disable - Disable this functionality.
    • UserConfirmation - Prompt the user for confirmation before deleting the elements from the archive.
    • Automatic - Automatically delete the element units that are renamed in the Rational Rhapsody model.
  • ShowCMStatus -> Checked

    The property ShowCMStatus is a boolean property that determines whether or not Rational Rhapsody displays the CM status of project units. This property is set at the project level.

  • StoreInSeparateDirectoryActivation -> UserConfirmation

    The StoreInSeparateDirectoryActivation property affects how an existing package is converted. The following conditions apply with this property only if the SCC tool is ClearCase:

    • Enable this property by selecting UserConfirmation or Automatic from the drop-down list.
      Resulting behaviour with Automatic or when selecting 'Yes' in user confirmation dialog:
      • When an existing flat package is converted to a package as a directory, the directory is created on the configuration management side and the children of this package are moved to this directory.
      • When an existing package as a directory is converted to a flat package, the directory is removed on the configuration management side and the children of this package are removed as well.
    • Disable this property by selecting Disable.
      Resulting behaviour with Disable or when selecting 'No' in user confirmation dialog:
      • When an existing flat package is converted to a package as a directory inside of Rhapsody, the directory is not created on the configuration management side and the children of this package are not moved to this directory.
      • When an existing package as a directory is converted to a flat package inside of Rhapsody, the directory is not removed on the configuration management side and the children of this package are not removed.
      • In both cases the logical structure will not correspond to the file system structure in ClearCase. This inconsistency must be resolved manually.
  • General:Model:AutoSynchronize -> Checked

    The AutoSynchronize property is a Boolean value that determines whether Rational Rhapsody will run synchronization. When this property is Checked, each time Rhapsody gets the focus Rational Rhapsody will run the synchronize functionality. The started synchronize can be a synchronization with the files on the file system, view, or CM archive depending on the environment.

  • ConfigurationManagement:General:UseUnitTimeStamps -> Checked

    The UseUnitTimeStamps property allows the user to determine whether or not to use unit time stamps.

  • General:Model:DefaultDirectoryScheme -> PackageAsDirectory

    The DefaultDirectoryScheme property is used by the hierarchical repository functionality. This property is available only at the project level, but activates or deactivates the Save in Subdirectory check box on the Unit Information for Package window. The possible values are as follows:

    • Flat - All units are stored in the project _rpy directory
    • PackageAsDirectory - New packages (and their descendants) are nested in a separate directory, no more than one level below the parent. The package subdirectory has the same name as the package it contains.
  • ConfigurationManagement:SCC:AddNewUnitsToArchiveDuringCheckin -> Checked

    This property controls whether new subunits that may have been added to a checked out unit are automatically added to your CM archive during checkin if the parent unit is checked in with descendants. When this property is set to Checked, new subunits that were added to a checked out unit are automatically added to your CM archive during checkin if the parent unit is checked in with descendants.

Connect to archive

The Connect to Archive operation connects the project in your workspace to a CM archive. In addition, it permanently sets properties associated with the archive to be referenced internally whenever the project needs to communicate with the CM tool. You need to perform this operation only once for the lifetime of the project.
A Connect operation also triggers actions that should be performed before any other CM operation.

  1. Select 'File -> Configuration Items…' in order to open the following dialog window and select 'Connect to Archive'.
Figure 28. Rhapsody Connect to Archive
Menu and list
  1. Hit 'OK'.
Figure 29. Confirm Connection
Confirmation
  1. This will populate the SCC properties 'AuxProjPath' and 'ProjName' as shown below. Unlike in batch mode, this will not put anything under source code control.
Figure 30. Configured SCC Settings
Project configuration list
  1. In order to add Rhapsody unit files to ClearCase change the view in 'Configuration Items' window to hierarchical, select the top-level element and hit 'Add to Archive'.
Figure 31. Add to Archive
Menu and list
  1. Check the 'Include Descendants' option, enter a comment and hit 'OK'.
Figure 32. Add Descendants to Archive
Checkbox and comment
  1. Click 'OK' in the confirmation dialog.
Figure 33. Confirmation Window
Confirmation
  1. You can check in ClearCase the items added to source control.
Figure 34. Verification of Files added to Source Control
Folder explorer

Note:
Files which are not relevant to maintain the model content are kept as 'View-private File' in the user's workspace and must not be added to source control.

DiffMerge tool

The Rational Rhapsody DiffMerge tool supports team collaboration by showing the design changes between revisions and merging units as needed. It performs a full comparison
including graphical elements, text and code differences.

External difference/merge textual tool

For some attributes, the space provided in the Attributes pane is insufficient to view them properly (for example, a multi-line box). In such cases, you can launch an external textual diff tool.

  1. Set ClearCase ClearDiff and ClearDiffMrg as your external difference/merge textual tool.

Note: If you used the provided Rhapsody property files (see chapter "Setup files for user installations"), you don't need to perform the below-mentioned configuration steps.

  1. Open the Rhapsody DiffMerge tool from the 'Configuration Items' window
Figure 35. Open Rhapsody DiffMerge Tool
Menu and list
  1. In the DiffMerge tool select 'View -> Preferences…'
Figure 36. Open DiffMerge Preferences
Context menu
  1. In DiffMerge Preferences, expand the TextDiffMerge category and set the properties as shown below.
Figure 37. Set DiffMerge Properties
Properties list

The preferences will be stored in the Rhapsody installation directory in the file named diffmerge.ini

Description of 'TextDiffMerge' preferences

  • BaseAwareAutoMergeInvocation -> cleardiff -out $output -base $sourceBase -abo -qui $source1 $source2

    Specifies how to launch the external textual DiffMerge tool supporting base-aware (three-unit) detection of triviality of textual difference and three-unit automatic merging.

  • BaseAwareAutoMergeableAttributes -> ItsBody

    Specifies a list of attribute names, which contain text values and are allowed to merge automatically. The value of attribute can be also 'All' (meaning all attribute can be textually merged) and 'None' (meaning no automatic textual merge should be done). The default value, 'ItsBody', determines that only the implementation for the methods or/and operations will be merged automatically when possible.

  • BaseAwareDiffInvocation -> cleardiffmrg -base $sourceBase $source1 $source2

    Specifies how to launch the external textual DiffMerge tool supporting a base-aware comparison in Base Aware Diff mode.

  • BaseAwareDiffMergeInvocation -> $BaseAwareDiffInvocation -out $output

    Specifies how to launch the external textual DiffMerge tool supporting base-aware comparison and merging in Base Aware Merge mode.

  • BaseAwareTextDiffMergeEnabled -> TRUE

    Determines whether a base-aware (three-unit) textual DiffMerge tool is available to be launched.

  • DiffInvocation -> cleardiffmrg $source1 $source2

    Specifies how to launch the external textual DiffMerge tool in Diff mode.

  • DiffMergeInvocation -> $DiffInvocation -out $output

    Specifies how to launch the external textual DiffMerge tool in the Merge mode.

  • MergeOutput -> $temp\out.txt

    Specifies the text file path and name that the merging result will be written to.

Setup files for user installations

Inside Rhapsody there are many properties that allow customization of the tool and the generated code. Properties can be set once and for all by modifying the site.prp file in the Rhapsody\Share\Properties directory.

In our case we create two files site_RCC_Batch.prp and site_RCC_SCCI.prp and copy them to Rhapsody\Share\Properties directory. Either one is included to the site.prp file depending on which mode is used.

Example for include statement of site_RCC_Batch.prp and site_RCC_SCCI.prp file inside site.prp file.

Include "site_RCC_Batch.prp"
Include "site_RCC_SCCI.prp"

A sample site_RCC_Batch.prp file is shown below and is available in the Download section:

Figure 38. Contents of "site_RCC_Batch.prp" file
Contents of 'site_RCC_Batch.prp' file

Note: This file is available in the Download section.

A sample site_RCC_SCCI.prp file is shown below and is available in the Download section:

Figure 39. Contents of "site_RCC_SCCI.prp" file
Contents of 'site_RCC_SCCI.prp' file

Note: This file is available in the Download section.

Additional topics

  • Code generation performance improvements

    If you notice that performance is reduced, you might need to change the location of the temporary files. To change the location for temporary files, change the following entry in the Rhapsody.ini file, as follows:

    [CodeGen]
    TemporaryFilesDirectory = <the temporary code 
    generation files directory (for example, C:\TEMP)>

    When the entry is not present, temporary files are created in the project directory where the .rpy file is stored. By changing the location to a directory outside of a Rational ClearCase VOB domain, code generation performance improves.

  • Evil twins issue

In Rational ClearCase, you should avoid using the same name for different elements. This type of situation creates what is called "evil twins." For an explanation and guidance about the evil twins issue in the Rational ClearCase environment, see the technote titled "About Evil Twins" on the IBM website.


Verify the integration - Sample scenario for SCC mode

The following steps represent a sample scenario using SCC mode. The site_RCC_SCCI.prp file was used for this scenario and the project has already been added to source control (see chapter "SCC mode"). It is an introduction to working with Rhapsody under ClearCase version control. To simulate parallel development a branch is created and we show how to merge the changes from the branch back to main branch.

Basic Steps

  1. Check out the project. If you know what parts of the model you are going to change, you can also selectively check-out the specific units. In our case we check-out all units and perform an undo check-out of the units that don't change.
Figure 40. Check Out Project
Context Menu
  1. Check the 'Descendants' check-box
Figure 41. Check Out with Descendants
Check box and comment
  1. In order to make the object model diagram 'Model1' part of the target package, move it to the 'Default' package. On the file level basis this means that the data of the object model diagram is moved from the SampleProject.sbs to the Default.sbs file. This simplifies the way of working under source control, since from now on you only need to check-out the default package for content and model changes.
Figure 42. Change Data on Project Level
Model explorer
  1. We performed some additional changes by adding a class including an attribute and an operation with implementation.
Figure 43. Perform Additional Changes
Editor
  1. Check-in the project with descendants and enter a comment.
Figure 44. Check In the Project
Context menu
  1. Since not all units have been changed ClearCase notifies you that it won't check-in versions which are not different from their predecessors. Even though that is flagged as an error message it is merely a notification meaning that you either perform an undo check-out or an identical check-in operation. The Rhapsody ClearCase integration supports all the operations. Select 'OK'.
Figure 45. Expected Error Message
Error message
  1. Thanks to the autosynchronize property you get notified that some units changed. In this case the change consists in the check-in operation meaning that checked-in files are now read-only. Make sure to re-load the selected items to synchronize the status of the model with the status of the files in the repository. Select all changed files and press 'Load Selected Items' button.
Figure 46. List of Modified Files
Menu and list
  1. Select 'OK' in the check-in dialog.
Figure 47. Confirmation Window
Confirmation
  1. Because of the error we got earlier with regards to the identical check-in operation for some specific files we get the following error that the complete check-in process did not succeed as expected. Again this is a notification and we are going to deal with files which are not checked-in in the next step. Click 'OK'.
Figure 48. Error Window
Error message
  1. Now we are dealing with the files which haven't been checked-in by performing an undo check-out operation. Since the content has not changed we don't need to create new versions of those files. Right click on the default component and select 'Undo Checkout' under the 'Configuration Management' entry.
Figure 49. Undo Checkout
Context menu
  1. Click 'OK'.
Figure 50. Undo Check Out Confirmation
Confirmation

Working with branches / parallel development

  1. In order to enable parallel development, branches need to be created in ClearCase. In our example we already had created a branch type named 'devbranch'. We also created a second view named 'rhp_branch_view' to work on this branch. The config spec of this view is shown below.
Figure 51. Config Spec for Parallel Development
Properties list of view
  1. A second user would open the project in the second view 'rhp_branch_view'. In Rhapsody, open the checked-in project in the path corresponding to the branch view.
Figure 52. Open Rhapsody Project
Explorer with folder structure
  1. Rhapsody is aware that the project is under source control and suggests loading the status of the project.
Figure 53. Confirmation Window
Confirmation
  1. Check-out the project with descendants and perform some changes.
Figure 54. Perform Additional Changes
Editor
  1. Then check-in the project with descendants and perform 'undo check-out' where appropriate (see chapter "Basic Steps"). Close the branched 'SampleProject' in Rhapsody.
  2. The ClearCase version tree is a powerful tool to visual parallel development. If you
    1. open the ClearCase explorer, right-click on the Default.sbs file and select 'Version Tree' you can see the branch you just created.
Figure 55. ClearCase Version Tree
Version tree representation
  1. Now we continue working on the mainline (here: version main/3). Therefore we re-open the Rhapsody project in the original view.
Figure 56. Reopen Original Rhapsody Project
Explorer with folder structure
  1. Check-out the project with descendants and perform some additional changes.
Figure 57. Perform Changes inside Implementation
Editor
  1. Check-in the SampleProject. Now the version tree looks as follows:
Figure 58. Version Tree after Checkin
Version tree representation

Performing a merge with Rhapsody DiffMerge

  1. In order to propagate the changes from the branch to the mainline, a merge operation needs to be invoked. Open the history browser as following:
Figure 59. Open History Browser
Context menu
  1. Select the tools menu and open the version tree.
Figure 60. Open Version Tree
Version tree representation
  1. Perform the merge from the branch to the mainline. Right-click the version on the branch 'devbranch' and select 'Merge to…'
Figure 61. Initiate Merge
Context menu
  1. Click on the mainline version to select it as merge target visualized by the target icon.
Figure 62. Select Merge Target
Selection
  1. Select 'Merge the element graphically' and click on 'OK'.
Figure 63. Merge Element Graphically
Check boxes and comment
  1. Select 'Yes' in the information pop-up window.
Figure 64. Confirmation Window
Confirmation
  1. Enter a comment and hit 'OK'.
Figure 65. Checkout Confirmation
Check boxes and comment
  1. The Rhapsody DiffMerge utility will open. In order to inspect all changes please select 'No' in the pop-up dialog.
Figure 66. Inspect All Changes
List of changes
  1. Hit 'OK'.
Figure 67. Confirmation Window
Confirmation
  1. The base-aware merge window opens and shows the differences.
Figure 68. DiffMerge View
List of changes
  1. You may open the 'Merge Text' utility by right-clicking on the difference shown.
Figure 69. Open Merge Text Tool
Context menu
  1. The ClearCase DiffMerge window opens (as specified in the properties file site_RCC_SCCI.prp).
Figure 70. ClearCase DiffMerge Utlitity
Editor
  1. Resolve your merge points by selecting the appropriate contributor(s) (1, 2 or 3).
Figure 71. Merge Content
Editor
  1. Save the result and exit the ClearCase DiffMerge window. Save and exit the result in the Rhapsody DiffMerge utility.
  2. Select 'Yes' in the merge confirmation pop-up.
Figure 72. Close DiffMerge Utlitility
Version tree representation
  1. If you wish to finalize the merge operation you may check-in the merged version by right-clicking on the merge result and selecting 'Check In…'. Alternatively you may check-in at a later stage.
Figure 73. Checkin Merge Result
Context menu
  1. Your merge is displayed in the version tree browser as follows:
Figure 74. Version Tree of Merge Result
Version tree representation
  1. Change the focus to Rhapsody and load the merge result.
Figure 75. Load the Merge Results in Rhapsody
Result list
  1. Rhapsody will show the changes introduced by the merge.
Figure 76. Show Merge Result in Rhapsody
Editor

Summary

IBM Rational ClearCase and IBM Rational Rhapsody are now configured to support all common tasks in a seamless workflow. If any of the integration verification steps fails, please go back to chapter 'Configuring the integration' and check your setup.

As a next step users should work through the IBM Rational Rhapsody Team Collaboration Guide in order to learn how to organize a model in Rhapsody and how to perform parallel development in order to get the most out of this tool integration for a team of developers.

Rhapsody users should be aware that there are still scenarios beyond the scope of this integration which require usage of the ClearCase Explorer. For example, removing units from a ClearCase VOB that are no longer needed or that were inadvertently created.

In addition to keeping Rhapsody models under 'source control', it is possible to automate the production process by invoking Rhapsody via its command line within IBM Rational ClearMake. This can be used to generate C/C++/Java code from the model during the build process.


References

The following documents were used in references or as other sources of information:

  1. IBM Rational Rhapsody Team Collaboration Guide V7.5 (inside the Rhapsody installation)
  2. IBM® Rational® ClearCase® 7.X and Telelogic® Rhapsody®
  3. About Rhapsody
  4. About ClearCase

Downloads

DescriptionNameSize
Sample site_RCC_Batch.prp file (zipped)site_RCC_Batch.zip722KB
Sample site_RCC_SCCI.prp file (zipped)site_RCC_SCCI.zip576KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=512583
ArticleTitle=Integration Guide for IBM Rational Rhapsody and IBM Rational ClearCase on Windows
publish-date=08312010